feat(ui): ui-shell header with tool links, mobile side nav, Youreka logo

- header: Carbon ui-shell (cds-header) with the Youreka logo (from
  idid-enterprise-portal), Image Cropper / Fingerprint Agent nav items
  (aria-current on the active tool), the agent status tag on the wizard,
  and the operator chip + Sign out on desktop
- mobile: cds-side-nav (logo above the items, both tools, a divider, then
  Sign out) toggled by the ui-shell menu button; account actions move out
  of the header below 1056px, the nav is hidden at desktop widths
- the header is built once in server.js (appHeader) and injected into the
  landing, both tools and error pages — no per-page duplication
- removed my duplicate menu-button toggle: ui-shell coordinates the menu
  button and side nav itself (the duplicate cancelled it out)
- fixes: 'cds-header' was hidden by a selector-list typo
  (cds-header, cds-side-nav:not(:defined)); the collapsed side nav no
  longer captures taps

Tools banner logo asset added (public/assets/youreka-logo.png).

tools/public/assets/cropper/app.js

@@ -54,10 +54,6 @@ Vue.config.ignoredElements = [/^cds-/];
     },
 
     computed: {
-      initials: function () {
-        var n = (this.session && (this.session.firstName || this.session.phone)) || '?';
-        return n.slice(0, 2).toUpperCase();
-      },
       canReview: function () {
         if (this.busy.review) return false;
         if (this.accepted) return true;

tools/public/assets/cropper/index.html

@@ -12,6 +12,7 @@
   <script src="https://cdn.jsdelivr.net/npm/vue-croppa@1.3.8/dist/vue-croppa.min.js"></script>
   <script src="https://unpkg.com/axios/dist/axios.min.js"></script>
   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/vue-croppa@1.3.8/dist/vue-croppa.min.css">
+  <script type="module" src="https://1.www.s81c.com/common/carbon/web-components/version/v2.50.0/ui-shell.min.js"></script>
   <script type="module" src="https://1.www.s81c.com/common/carbon/web-components/version/v2.50.0/button.min.js"></script>
   <script type="module" src="https://1.www.s81c.com/common/carbon/web-components/version/v2.50.0/notification.min.js"></script>
   <script type="module" src="https://1.www.s81c.com/common/carbon/web-components/version/v2.50.0/tag.min.js"></script>
@@ -23,23 +24,7 @@
 </head>
 <body class="app">
 <div id="app">
-  <nav class="nav">
+  <!--app-header-->
-    <div class="container">
-      <a class="brand" href="/">
-        <span class="brand-mark">
-          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M6 2v14a2 2 0 0 0 2 2h14"/><path d="M18 22V8a2 2 0 0 0-2-2H2"/></svg>
-        </span>
-        YOUreka <small>Tools</small>
-      </a>
-      <div class="nav-right" v-cloak v-if="session">
-        <span class="user-chip">
-          <span class="avatar">{{ initials }}</span>
-          {{ session.firstName || session.phone }}
-        </span>
-        <a class="linklike" href="/auth/logout">Sign out</a>
-      </div>
-    </div>
-  </nav>
 
   <main class="container" v-cloak v-if="session">
     <div class="page-head">

tools/public/assets/fp/app.js

@@ -41,10 +41,6 @@ Vue.config.ignoredElements = [/^cds-/];
     },
 
     computed: {
-      initials: function () {
-        var n = (this.session && (this.session.firstName || this.session.phone)) || '?';
-        return n.slice(0, 2).toUpperCase();
-      },
       maxStage: function () { return MAX_STAGE; },
       bothCaptured: function () {
         return this.fingers['right-thumb'].status === 'done' &&
@@ -139,17 +135,27 @@ Vue.config.ignoredElements = [/^cds-/];
         });
       },
 
+      /** The agent status tag lives in the server-rendered header. */
+      renderAgentTag: function () {
+        var el = document.getElementById('agent-status');
+        if (!el) return;
+        el.textContent = this.agent.connected ? 'Agent connected' : 'Agent offline';
+        el.setAttribute('type', this.agent.connected ? 'green' : 'red');
+        el.setAttribute('title', this.agent.version ? 'fpagent ' + this.agent.version : '');
+      },
+
       connectAgent: function () {
         var self = this;
         this.socket = io(this.session.agentUrl, { reconnectionDelayMax: 5000 });
 
-        this.socket.on('connect', function () { self.agent.connected = true; });
+        this.socket.on('connect', function () { self.agent.connected = true; self.renderAgentTag(); });
-        this.socket.on('disconnect', function () { self.agent.connected = false; });
+        this.socket.on('disconnect', function () { self.agent.connected = false; self.renderAgentTag(); });
-        this.socket.on('connect_error', function () { self.agent.connected = false; });
+        this.socket.on('connect_error', function () { self.agent.connected = false; self.renderAgentTag(); });
 
         this.socket.on('agent-hello', function (data) {
           self.agent.version = (data && data.version) || '';
           self.agent.captureAgentId = (data && data.captureAgentId) || '';
+          self.renderAgentTag();
         });
 
         this.socket.on('fprint-enroll-status', function (data) {

tools/public/assets/fp/index.html

@@ -9,6 +9,7 @@
   <link rel="stylesheet" href="/assets/style.css">
   <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><rect width='24' height='24' rx='4' fill='%230f62fe'/><path d='M12 5a6 6 0 0 0-6 6c0 2.6.8 4.1 1.5 5.2' fill='none' stroke='white' stroke-width='1.6' stroke-linecap='round'/><path d='M15.5 19a7.5 7.5 0 0 0 3-9.7A6 6 0 0 0 7.1 7.9' fill='none' stroke='white' stroke-width='1.6' stroke-linecap='round'/><path d='M9.5 18.5a5.5 5.5 0 0 1-.8-7.6 3.8 3.8 0 0 1 7.2 1.5 4.3 4.3 0 0 1-3.4 4.6' fill='none' stroke='white' stroke-width='1.6' stroke-linecap='round'/></svg>">
   <script src="https://cdn.socket.io/4.4.0/socket.io.min.js" integrity="sha384-1fOn6VtTq3PWwfsOrk45LnYcGosJwzMHv+Xh/Jx5303FVOXzEnw0EpLv30mtjmlj" crossorigin="anonymous"></script>
+  <script type="module" src="https://1.www.s81c.com/common/carbon/web-components/version/v2.50.0/ui-shell.min.js"></script>
   <script type="module" src="https://1.www.s81c.com/common/carbon/web-components/version/v2.50.0/button.min.js"></script>
   <script type="module" src="https://1.www.s81c.com/common/carbon/web-components/version/v2.50.0/notification.min.js"></script>
   <script type="module" src="https://1.www.s81c.com/common/carbon/web-components/version/v2.50.0/progress-bar.min.js"></script>
@@ -16,25 +17,7 @@
 </head>
 <body class="app">
 <div id="app">
-  <nav class="nav">
+  <!--app-header-->
-    <div class="container">
-      <a class="brand" href="/">
-        <span class="brand-mark">
-          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 2a8 8 0 0 0-8 8c0 3.5 1 5.5 2 7"/><path d="M16 21a10 10 0 0 0 4-13 8 8 0 0 0-15.7-1"/><path d="M8 21a8 8 0 0 1-1-11 5 5 0 0 1 9.7 1.4A6 6 0 0 1 12 17"/><path d="M12 21a4 4 0 0 0 4-4 4 4 0 0 0-1.2-2.9"/></svg>
-        </span>
-        YOUreka <small>Tools</small>
-      </a>
-      <div class="nav-right" v-cloak v-if="session">
-        <cds-tag v-bind:type="agent.connected ? 'green' : 'red'"
-                 v-bind:title="agent.version ? 'fpagent ' + agent.version : ''">{{ agent.connected ? 'Agent connected' : 'Agent offline' }}</cds-tag>
-        <span class="user-chip">
-          <span class="avatar">{{ initials }}</span>
-          {{ session.firstName || session.phone }}
-        </span>
-        <a class="linklike" href="/auth/logout">Sign out</a>
-      </div>
-    </div>
-  </nav>
 
   <main class="container" v-cloak v-if="session">
     <div class="page-head">

tools/public/assets/style.css

@@ -26,33 +26,33 @@ cds-toast:not(:defined), cds-toast-item:not(:defined), cds-progress-bar:not(:def
    a real box so grid columns and click targets work correctly. */
 cds-tile, cds-clickable-tile { display: block; }
 
-/* ── header (Carbon ui-shell look) ──────────────────────────────────────── */
+/* ── header + side nav (Carbon ui-shell) ────────────────────────────────── */
-.nav {
+cds-header:not(:defined), cds-side-nav:not(:defined) { visibility: hidden; }
-  background: #161616;
+.brand-logo { display: inline-flex; align-items: center; justify-content: center; border: 1px solid var(--cds-border-subtle, #e0e0e0); border-radius: 4px; padding: 2px; margin-right: 0.5rem; }
-  height: 48px;
+.brand-logo img { display: block; }
-  padding: 0;
+.brand-suffix { color: var(--cds-text-secondary, #525252); font-weight: 400; }
+.header-right { margin-left: auto; display: flex; align-items: center; gap: 1rem; padding-right: 1rem; }
+.header-agent { margin-left: 1rem; }
+/* mobile: account actions live in the side nav, not the header */
+@media (max-width: 1055px) {
+  .header-right, .header-agent { display: none; }
 }
-.nav .container { display: flex; align-items: center; justify-content: space-between; gap: 1rem; height: 100%; max-width: none; padding: 0 1rem; }
+/* collapsed side nav must never swallow taps meant for the header */
-.brand { display: inline-flex; align-items: center; gap: 0.6rem; font-weight: 600; color: #f4f4f4; font-size: 14px; }
+cds-side-nav { pointer-events: none; }
-.brand:hover { color: #f4f4f4; }
+cds-side-nav[expanded] { pointer-events: auto; }
-.brand small { color: #c6c6c6; font-weight: 400; }
+/* the side nav is a mobile affordance — desktop uses the header nav */
-.brand-mark {
+@media (min-width: 1056px) {
-  width: 28px; height: 28px; border-radius: 4px;
+  cds-side-nav { display: none; }
-  background: #0f62fe; color: #fff;
-  display: inline-flex; align-items: center; justify-content: center;
-  flex: 0 0 auto;
-}
-.brand-mark svg { width: 16px; height: 16px; }
-.nav-right { display: flex; align-items: center; gap: 1rem; flex-wrap: wrap; }
-.nav-right .linklike { color: #c6c6c6; font-size: 13px; padding: 0.4rem 0.6rem; }
-.nav-right .linklike:hover { color: #f4f4f4; background: #353535; }
-.user-chip { display: inline-flex; align-items: center; gap: 0.45rem; color: #c6c6c6; font-size: 13px; }
-.user-chip .avatar {
-  width: 26px; height: 26px; border-radius: 50%;
-  background: #0f62fe; color: #fff;
-  display: inline-flex; align-items: center; justify-content: center;
-  font-size: 11px; font-weight: 700;
 }
+.user-chip { display: inline-flex; align-items: center; gap: 0.45rem; color: var(--cds-text-primary, #161616); font-size: 13px; }
+.user-chip .avatar { width: 26px; height: 26px; border-radius: 50%; background: #0f62fe; color: #fff; display: inline-flex; align-items: center; justify-content: center; font-size: 11px; font-weight: 700; }
+.linklike { background: none; border: none; padding: 0; color: var(--cds-link-primary, #0f62fe); font-weight: 400; cursor: pointer; font-size: 13px; font-family: inherit; }
+.linklike:hover { color: var(--cds-link-primary-hover, #0043ce); text-decoration: underline; }
+.linklike[disabled] { color: var(--cds-text-disabled, #c6c6c6); cursor: default; }
+
+/* logo above the mobile side-nav items */
+.side-nav-brand { display: flex; align-items: center; gap: 0.75rem; padding: 1rem; color: var(--cds-text-primary, #161616); font-weight: 600; font-size: 14px; border-bottom: 1px solid var(--cds-border-subtle, #e0e0e0); }
+.side-nav-brand img { border: 1px solid var(--cds-border-subtle, #e0e0e0); border-radius: 6px; padding: 2px; display: block; }
 
 /* ── layout ─────────────────────────────────────────────────────────────── */
 .container { width: 100%; max-width: 1136px; margin: 0 auto; padding: 0 1.5rem; }
@@ -127,8 +127,6 @@ textarea.form-control { height: auto; padding: 0.6rem 0.75rem; }
 .btn-danger-ghost { background: transparent; border: none; color: var(--cds-button-danger-primary, #da1e28); }
 .btn[disabled], .btn.disabled { opacity: 0.5; pointer-events: none; }
 .btn-block { display: flex; width: 100%; align-items: center; justify-content: center; }
-.linklike { background: none; border: none; padding: 0; color: var(--cds-link, #0f62fe); font-weight: 400; cursor: pointer; font-size: 13px; font-family: inherit; }
-.linklike[disabled] { color: var(--cds-text-disabled, #c6c6c6); cursor: default; }
 
 /* cds-button inside flex rows */
 cds-button { min-width: 0; }

tools/public/index.html

@@ -8,23 +8,15 @@
   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@carbon/styles@1.69.0/css/styles.min.css">
   <link rel="stylesheet" href="/assets/style.css">
   <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><rect width='24' height='24' rx='4' fill='%230f62fe'/><path d='M12 5a6 6 0 0 0-6 6c0 2.6.8 4.1 1.5 5.2' fill='none' stroke='white' stroke-width='1.6' stroke-linecap='round'/><path d='M15.5 19a7.5 7.5 0 0 0 3-9.7A6 6 0 0 0 7.1 7.9' fill='none' stroke='white' stroke-width='1.6' stroke-linecap='round'/><path d='M9.5 18.5a5.5 5.5 0 0 1-.8-7.6 3.8 3.8 0 0 1 7.2 1.5 4.3 4.3 0 0 1-3.4 4.6' fill='none' stroke='white' stroke-width='1.6' stroke-linecap='round'/></svg>">
+  <script type="module" src="https://1.www.s81c.com/common/carbon/web-components/version/v2.50.0/ui-shell.min.js"></script>
   <script type="module" src="https://1.www.s81c.com/common/carbon/web-components/version/v2.50.0/tile.min.js"></script>
+  <script type="module" src="https://1.www.s81c.com/common/carbon/web-components/version/v2.50.0/tag.min.js"></script>
   <style>
     cds-tile:not(:defined), cds-clickable-tile:not(:defined) { visibility: hidden; }
   </style>
 </head>
 <body class="app">
-  <nav class="nav">
+  <!--app-header-->
-    <div class="container">
-      <a class="brand" href="/">
-        <span class="brand-mark">
-          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 2a8 8 0 0 0-8 8c0 3.5 1 5.5 2 7"/><path d="M16 21a10 10 0 0 0 4-13 8 8 0 0 0-15.7-1"/><path d="M8 21a8 8 0 0 1-1-11 5 5 0 0 1 9.7 1.4A6 6 0 0 1 12 17"/><path d="M12 21a4 4 0 0 0 4-4 4 4 0 0 0-1.2-2.9"/></svg>
-        </span>
-        YOUreka <small>Tools</small>
-      </a>
-      <div class="nav-right"><!--session-nav--></div>
-    </div>
-  </nav>
 
   <main class="container">
     <div class="hero">

tools/server.js

@@ -75,19 +75,7 @@ function errorPage(res, status, title, message, actions = {}) {
   <link rel="stylesheet" href="/assets/style.css">
 </head>
 <body class="app">
-  <nav class="nav">
+  ${appHeader(null, null)}
-    <div class="container">
-      <a class="brand" href="/">
-        <span class="brand-mark">
-          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 2a8 8 0 0 0-8 8c0 3.5 1 5.5 2 7"/><path d="M16 21a10 10 0 0 0 4-13 8 8 0 0 0-15.7-1"/><path d="M8 21a8 8 0 0 1-1-11 5 5 0 0 1 9.7 1.4A6 6 0 0 1 12 17"/><path d="M12 21a4 4 0 0 0 4-4 4 4 0 0 0-1.2-2.9"/></svg>
-        </span>
-        YOUreka <small>Tools</small>
-      </a>
-      <div class="nav-right">
-        <a class="linklike" href="/auth/logout">Sign out</a>
-      </div>
-    </div>
-  </nav>
   <main class="container narrow center-v">
     <div class="card message-card">
       <div class="message-icon error">${ICONS[icon] || ICONS.alert}</div>
@@ -118,6 +106,50 @@ function esc(value) {
     .replace(/'/g, '&#39;');
 };
 
+/**
+ * The application header and mobile side nav (Carbon ui-shell), shared by
+ * every page. `session` is present when the operator is signed in; `active`
+ * marks the current tool. Rendered server-side so pages need no client
+ * session fetch and hold a single header definition.
+ */
+const appHeader = (session, active) => {
+  const toolLink = (href, label, key) =>
+    `<cds-header-nav-item href="${href}"${key === active ? ' aria-current="page"' : ''}>${label}</cds-header-nav-item>`;
+  const sideLink = (href, label, key) =>
+    `<cds-side-nav-link href="${href}"${key === active ? ' aria-current="page"' : ''}>${label}</cds-side-nav-link>`;
+  const name = session ? (session.firstName || session.phone || '') : '';
+  const right = session
+    ? `<span class="user-chip"><span class="avatar">${esc(name.trim().slice(0, 2).toUpperCase())}</span>${esc(name)}</span>
+       <a class="linklike" href="/auth/logout">Sign out</a>`
+    : '<a class="linklike" href="/auth/login">Sign in</a>';
+  return `
+<cds-header aria-label="YOUreka Tools">
+  <cds-header-menu-button button-label-active="Close menu" button-label-inactive="Open menu" id="header-menu-button"></cds-header-menu-button>
+  <cds-header-name href="/">
+    <span class="brand-logo"><img src="/assets/youreka-logo.png" alt="" width="20" height="20"></span>YOUreka<span class="brand-suffix"> Tools</span>
+  </cds-header-name>
+  <cds-header-nav>
+    ${toolLink('/cropper', 'Image Cropper', 'cropper')}
+    ${toolLink('/fingerprint', 'Fingerprint Agent', 'fingerprint')}
+  </cds-header-nav>
+  ${active === 'fingerprint' ? '<cds-tag id="agent-status" type="red" class="header-agent">Agent offline</cds-tag>' : ''}
+  <div class="header-right">${right}</div>
+</cds-header>
+<cds-side-nav aria-label="Tools" id="side-nav">
+  <div class="side-nav-brand">
+    <img src="/assets/youreka-logo.png" alt="YOUreka" width="40" height="40">
+    <span>YOUreka Tools</span>
+  </div>
+  <cds-side-nav-items>
+    ${sideLink('/cropper', 'Image Cropper', 'cropper')}
+    ${sideLink('/fingerprint', 'Fingerprint Agent', 'fingerprint')}
+    <cds-side-nav-divider></cds-side-nav-divider>
+    <cds-side-nav-link href="/auth/logout">Sign out</cds-side-nav-link>
+  </cds-side-nav-items>
+</cds-side-nav>
+`;
+};
+
 // ── app factory ──────────────────────────────────────────────────────────────
 export function createApp(overrides = {}) {
   const cfg = {
@@ -300,7 +332,7 @@ export function createApp(overrides = {}) {
    * client never has to fetch it (and never flashes a loading state).
    * Per-user content — must not be cached.
    */
-  const renderPage = (res, file, session) => {
+  const renderPage = (res, file, session, active) => {
     fs.readFile(path.join(__dirname, 'public', 'assets', file), 'utf8', (error, html) => {
       if (error) return errorPage(res, 500, 'Something went wrong', 'The page could not be loaded.');
       const data = session
@@ -310,21 +342,24 @@ export function createApp(overrides = {}) {
         .set('Cache-Control', 'no-store')
         .set('Vary', 'Cookie')
         .type('html')
-        .send(html.replace('</head>', `  <script>window.__SESSION__ = ${data};</script>\n</head>`));
+        .send(
+          html
+            .replace('<!--app-header-->', appHeader(session, active))
+            .replace('</head>', `  <script>window.__SESSION__ = ${data};</script>\n</head>`)
+        );
     });
   };
 
+
+
   app.get('/', (req, res, next) => {
     fs.readFile(path.join(__dirname, 'public', 'index.html'), 'utf8', (error, html) => {
       if (error) return next(error);
-      const nav = req.session
-        ? `<span class="user-chip"><span class="avatar">${esc((req.session.firstName || req.session.phone || '?').trim().slice(0, 2).toUpperCase())}</span>${esc(req.session.firstName || req.session.phone || '')}</span><a class="linklike" href="/auth/logout">Sign out</a>`
-        : '<a class="linklike" href="/auth/login">Sign in</a>';
       res
         .set('Cache-Control', 'no-store')
         .set('Vary', 'Cookie')
         .type('html')
-        .send(html.replace('<!--session-nav-->', nav));
+        .send(html.replace('<!--app-header-->', appHeader(req.session, null)));
     });
   });
 
@@ -363,7 +398,7 @@ export function createApp(overrides = {}) {
   // ── wizard page (session required) ────────────────────────────────────────
   app.get('/fingerprint', requirePage, async (req, res, next) => {
     try {
-      renderPage(res, 'fp/index.html', await sessionPayload(req, { withDomains: true }));
+      renderPage(res, 'fp/index.html', await sessionPayload(req, { withDomains: true }), 'fingerprint');
     } catch (e) {
       next(e);
     }
@@ -399,11 +434,12 @@ export function createApp(overrides = {}) {
     next();
   };
   app.get('/cropper', requirePage, pageCropGate, (req, res, next) => {
-    renderPage(res, 'cropper/index.html', {
+    renderPage(
-      phone: req.session.phone,
+      res,
-      firstName: req.session.firstName,
+      'cropper/index.html',
-      lastName: req.session.lastName,
+      { phone: req.session.phone, firstName: req.session.firstName, lastName: req.session.lastName },
-    });
+      'cropper'
+    );
   });
   const cropperClients = cfg.cropperClients !== undefined ? cfg.cropperClients : buildCropperClients();
   if (cropperClients) {

tools/test/server.test.js

@@ -317,7 +317,15 @@ test('landing header is server-rendered for the session', async () => {
   try {
     const anon = await (await fetch(`${base}/`)).text();
     assert.match(anon, /href="\/auth\/login">Sign in</);
-    assert.ok(!anon.includes('<!--session-nav-->'), 'marker is replaced');
+    assert.ok(!anon.includes('<!--app-header-->'), 'header marker is replaced');
+    // tools live in the header nav and in the mobile side nav
+    assert.match(anon, /cds-header-nav-item href="\/cropper"/);
+    assert.match(anon, /cds-header-nav-item href="\/fingerprint"/);
+    assert.match(anon, /cds-side-nav-link href="\/cropper"/);
+    assert.match(anon, /cds-side-nav-divider/);
+    assert.match(anon, /cds-side-nav-link href="\/auth\/logout"/);
+    assert.match(anon, /youreka-logo\.png/);
+    assert.match(anon, /header-menu-button/);
 
     const cookies = await login(base);
     const authed = await (await fetch(`${base}/`, { headers: { cookie: cookies } })).text();