@fikar-ai/design 1.5.0 → 1.6.0

package/README.md

@@ -435,7 +435,7 @@ Since 1.2.0 the launcher can also use the shared behaviour, the same way as the
 - Plain HTML and Jinja: add `data-fk-menu` to the root, or call `launcher(apps, data_fk_menu=true)`. `shell.js` then opens it on a click or Enter, closes it on Escape (focus returns to the button), on a press outside and on choosing a link, and moves between the links with the arrow keys, Home and End. The recipe file itself has no attribute, because it is the markup a page that wires the launcher itself already copies. The shell recipes carry it.
 - The current app has `.current` and `aria-current="page"`, and its tile is the primary colour. The apps come from the page, and nothing is fetched.
 - Each tile is a 36px `.launcher-tile` with a 20px glyph over the app name, and the name may wrap to two lines. The hint is not shown. The panel carries `.launcher-apps`, which is what makes it a grid; every grid rule is scoped to that class, so the search results, the user menu and the theme menu, which reuse `.launcher-panel` and `.launcher-item`, keep their look, and a host whose copy of the markup has no `.launcher-apps` keeps the old list.
-- The package owns the glyphs, keyed by app id: `chat`, `platform`, `crs`, `dictionary`, `cost-calculator`, `super-admin` and `account`. They are lucide 0.469 SVG files in `brand/apps/<id>.svg` (24px frame, 1.5 stroke, `currentColor`). An id the package does not know shows the first letter of the app name in the same tile. The Jinja `launcher` macro and the React component need the app `id` for this; an item without one shows the letter.
+- The package owns the glyphs, keyed by app id: `chat`, `platform`, `crs`, `dictionary`, `pii`, `cost-calculator`, `super-admin` and `account`. They are lucide 0.469 SVG files in `brand/apps/<id>.svg` (24px frame, 1.5 stroke, `currentColor`). An id the package does not know shows the first letter of the app name in the same tile. The Jinja `launcher` macro and the React component need the app `id` for this; an item without one shows the letter.
 - `react/src/app-icons.ts` and the icon map in `templates/jinja/launcher.html` are generated from those files by `node scripts/build-app-icons.mjs`. Change an SVG, run the script and commit the result; a test fails when they differ.
 - React: `AppLauncher` renders the recipe and owns its behaviour, so it does not render `data-fk-menu`.
 
@@ -1309,6 +1309,351 @@ Docs imports only the raw ramp and aliases Infima to it. Do **not** delete the d
 
 Docusaurus toggles `[data-theme='dark']`, not `.dark`, so docs keeps its own dark block (it already references `--fk-*`).
 
+## Plain-JS apps (`esm/`)
+
+Apps with no bundler (the dictionary, PII and crs services) sign in, renew the session, theme the page and
+build the app launcher with the same five scripts. They used to each carry a copy; the package now ships
+one, as plain ES modules under `esm/` with no build step. Every module takes its collaborators as options
+(storage, fetch, crypto, location, timers), so `node --test` runs them with no browser.
+
+```
+@fikar-ai/design/esm/oidc.js  auth.js  theme.js  launcher.js  dom.js  app-icons.js
+```
+
+| Module | Exports |
+|---|---|
+| `oidc.js` | `createOidc({ storagePrefix, authUrl, clientId, redirectUri, postLogoutRedirectUri })` returning `{ beginSignIn(returnTo), completeSignIn(callbackUrl), signOutUrl(), accountUrl() }`. Also `base64url`, `codeChallenge`, `decodeJwtPayload`. Authorization code flow with PKCE (S256); the three endpoints are built from `authUrl`. |
+| `auth.js` | `createAuth({ storagePrefix, getAuthUrl, onSessionCleared })` returning the session object (`token`, `setSession`, `clearSession`, `trySso`, `authedFetch`, `armRenewal`, `clearRenewal`, `refreshInFlight`, `generation`). Also `parseJwtClaims`, `decodeJwtExpMs`, `decodeJwtEmail`, `computeDelayMs`. Single-flight cookie refresh and proactive renewal. |
+| `theme.js` | `createTheme({ storagePrefix, storage, root, matchMedia, onChange })` returning `{ get, set, apply, resolved }`. Also `themeKey(prefix)`, `normalizeTheme`, `resolveTheme`, `THEMES`. |
+| `launcher.js` | `launcherItems(apps, currentId)` returns the launcher panel's markup (one `<a class="launcher-item">` per app, the current one marked), or `''` for an empty list. Names and URLs are escaped. |
+| `dom.js` | `h(tag, props, ...children)`, `fill(node, ...children)`, `clear(node)`, `renderable(children)`. Text goes in as text nodes, never as markup. |
+| `app-icons.js` | `APP_ICONS`, the inner markup of each `brand/apps/*.svg` glyph keyed by app id. Generated by `scripts/build-app-icons.mjs`; `launcher.js` imports it as `./app-icons.js`, so the files must sit in one directory. |
+
+### storagePrefix
+
+`storagePrefix` is required by `createAuth`, `createOidc` and `createTheme` (each throws without it). It is
+the only per-app setting in these modules. One app name gives three keys:
+
+| Key | Holds |
+|---|---|
+| `${storagePrefix}.token` | the access token (`auth.js`) |
+| `${storagePrefix}.oidc.pending` | the PKCE verifier, state and nonce between redirect and callback (`oidc.js`, `sessionStorage`) |
+| `${storagePrefix}-theme` | the theme choice (`theme.js`, `localStorage`); `themeKey(prefix)` returns it |
+
+Use the app's client id as the prefix (`dictionary`, `pii`, `crs`), which keeps the existing keys, so nobody
+is signed out by the move. The page's inline first-paint script reads `localStorage.getItem('<prefix>-theme')`
+before any module has run, so it repeats the literal key.
+
+### Recipe: a new plain-JS app
+
+1. Copy `scripts/fetch-design.sh` below into the app, pin `DESIGN_VERSION`, and run it. It writes
+   `static/design/` and `static/design/design.lock.json`.
+2. Build `static/index.html` from the recipes. The three menus carry `data-fk-menu`, so `shell.js` opens and
+   closes them and the app wires none by hand. The shell markup is `recipes/shell.html`, the launcher is
+   `recipes/launcher.html`, the theme menu `recipes/theme-menu.html`, the user menu `recipes/user-menu.html`.
+3. Write `static/js/app.js` with the glue below.
+4. Register the client with the provider (client id = the prefix, redirect URI `<origin>/auth/callback`,
+   post-logout URI `<origin>/`) and have the service answer `/auth/callback` with the same `index.html`.
+   The page also needs `GET /config` returning `{ "auth_url": "..." }`.
+
+`static/index.html`, reduced to what the modules need:
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>My app</title>
+<link rel="stylesheet" href="/static/design/tokens.css">
+<link rel="stylesheet" href="/static/design/components.css">
+<script>
+  // First paint: same key as createTheme({ storagePrefix: 'myapp' }) writes.
+  (function () {
+    try {
+      var stored = localStorage.getItem('myapp-theme');
+      var theme = stored === 'light' || stored === 'dark' ? stored : 'system';
+      var dark = theme === 'dark' || (theme === 'system' && matchMedia('(prefers-color-scheme: dark)').matches);
+      document.documentElement.classList.toggle('dark', dark);
+      document.documentElement.setAttribute('data-theme', theme);
+    } catch (_) {}
+  })();
+</script>
+</head>
+<body>
+<div id="authError" class="overlay-screen" hidden>
+  <p id="authError-message"></p>
+  <button id="authError-retry" type="button">Try again</button>
+  <button id="authError-signout" type="button">Sign out</button>
+</div>
+<div id="noAccess" class="overlay-screen" hidden>
+  <p id="noAccess-signed-in" hidden></p>
+  <a id="noAccess-account" href="/">Account settings</a>
+  <button id="noAccess-switch" type="button">Switch account</button>
+</div>
+
+<!-- recipes/shell.html goes here. In its topbar cluster:
+       recipes/launcher.html   with id="launcher" (hidden) and its panel id="launcher-panel"
+       recipes/theme-menu.html with id="thememenu"
+       recipes/user-menu.html  with ids usermenu-btn, usermenu-avatar, usermenu-email, account, logout
+     each wrapper keeps its data-fk-menu attribute. -->
+
+<script src="/static/design/shell.js"></script>
+<script type="module" src="/static/js/app.js"></script>
+</body>
+</html>
+```
+
+`static/js/app.js`, the glue the dictionary and PII apps share. Everything app-specific is the prefix, the
+client id, the launcher id and the screens at the end.
+
+```js
+import { createAuth, decodeJwtEmail } from '/static/design/auth.js';
+import { createOidc } from '/static/design/oidc.js';
+import { launcherItems } from '/static/design/launcher.js';
+import { createTheme } from '/static/design/theme.js';
+
+const APP = 'myapp'; // storagePrefix, client id and launcher id
+const $ = (id) => document.getElementById(id);
+
+let config = null;
+async function getAuthUrl() {
+  if (!config) config = await (await fetch('/config')).json();
+  return config.auth_url;
+}
+
+let oidc = null;
+// Two races to guard: onSessionCleared firing mid-redirect, and a session the
+// service rejects bouncing through the provider (which still has its own
+// session) into an unbroken redirect loop.
+let redirecting = false;
+let justSignedIn = false;
+
+function showAuthError(message) {
+  $('authError-message').textContent = message;
+  $('authError').hidden = false;
+}
+
+function startSignIn(returnTo) {
+  if (redirecting || !oidc) return;
+  if (justSignedIn) {
+    showAuthError('Signed in, but the session was rejected. Sign out and try again.');
+    return;
+  }
+  redirecting = true;
+  oidc.beginSignIn(returnTo);
+}
+
+const auth = createAuth({
+  storagePrefix: APP,
+  getAuthUrl,
+  onSessionCleared: () => startSignIn(location.pathname + location.search),
+});
+const token = auth.token;
+
+function switchAccount() {
+  // Set before clearSession() so its sign-in callback no-ops instead of racing
+  // the redirect to the provider's end-session page.
+  redirecting = true;
+  auth.clearSession();
+  location.assign(oidc.signOutUrl());
+}
+$('authError-retry').addEventListener('click', () => { $('authError').hidden = true; oidc.beginSignIn('/'); });
+$('authError-signout').addEventListener('click', () => location.assign(oidc.signOutUrl()));
+$('logout').addEventListener('click', switchAccount);
+$('noAccess-switch').addEventListener('click', switchAccount);
+
+// Theme: the local choice paints at once; the account's choice arrives with /me.
+const thememenuEl = $('thememenu');
+const theme = createTheme({
+  storagePrefix: APP,
+  storage: localStorage,
+  root: document.documentElement,
+  matchMedia: window.matchMedia.bind(window),
+  onChange: () => {
+    for (const b of thememenuEl.querySelectorAll('[data-value]')) {
+      const on = b.dataset.value === theme.get();
+      b.classList.toggle('current', on);
+      b.setAttribute('aria-checked', String(on));
+    }
+  },
+});
+thememenuEl.addEventListener('fk-theme-change', async (e) => {
+  theme.set(e.detail.value);
+  if (!token()) return;
+  try {
+    await auth.authedFetch(`${await getAuthUrl()}/api/auth/me`, {
+      method: 'PATCH', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ theme: theme.get() }),
+    });
+  } catch { /* the local choice stands */ }
+});
+theme.apply();
+
+// Identity and launcher: the provider returns only the apps this account may open.
+async function syncLauncher() {
+  if (!token()) return;
+  const email = decodeJwtEmail(token());
+  $('usermenu-email').textContent = email || '';
+  const initial = email ? email[0].toUpperCase() : '?';
+  $('usermenu-avatar').textContent = initial;
+  $('usermenu-btn').dataset.initials = initial;
+  try {
+    const authUrl = await getAuthUrl();
+    const [appsRes, meRes] = await Promise.all([
+      auth.authedFetch(`${authUrl}/api/auth/me/apps`),
+      auth.authedFetch(`${authUrl}/api/auth/me`),
+    ]);
+    if (appsRes.ok) {
+      const apps = await appsRes.json();
+      $('launcher-panel').innerHTML = launcherItems(apps, APP);
+      $('launcher').hidden = apps.length === 0;
+    }
+    if (meRes.ok) {
+      const me = await meRes.json();
+      if (me.preferences && me.preferences.theme) theme.set(me.preferences.theme);
+    }
+  } catch { /* the launcher is not worth an error state */ }
+}
+
+function startApp() {
+  // The first accepted response proves the service took the token, which is
+  // when the redirect-loop guard can stand down.
+  const authedFetch = async (...args) => {
+    const res = await auth.authedFetch(...args);
+    if (res.ok) justSignedIn = false;
+    return res;
+  };
+  // ... build the app's screens with `authedFetch` ...
+  syncLauncher();
+}
+
+async function init() {
+  try {
+    await getAuthUrl();
+  } catch {
+    showAuthError('Cannot reach the service. Try reloading the page.');
+    return;
+  }
+  oidc = createOidc({
+    storagePrefix: APP,
+    authUrl: config.auth_url,
+    clientId: APP,
+    redirectUri: `${location.origin}/auth/callback`,
+    postLogoutRedirectUri: `${location.origin}/`,
+  });
+  $('account').href = oidc.accountUrl();
+
+  if (location.pathname === '/auth/callback') {
+    try {
+      const { accessToken, returnTo } = await oidc.completeSignIn(location.href);
+      justSignedIn = true;
+      auth.setSession(accessToken);
+      history.replaceState(null, '', returnTo);
+      startApp();
+    } catch (e) {
+      showAuthError(e.message || 'Sign-in failed');
+    }
+    return;
+  }
+  if (token()) {
+    auth.armRenewal();
+    startApp();
+    return;
+  }
+  // No refresh-cookie auto-login: the provider session behind /authorize gives
+  // the silent re-entry and keeps each app's refresh family attached to a
+  // session the account settings can list.
+  startSignIn(location.pathname + location.search + location.hash);
+}
+
+init();
+```
+
+The dictionary and PII apps also revalidate the session when the tab regains focus (a sign-out elsewhere
+clears the shared cookie) and show the `noAccess` overlay when the token lacks what the screen needs
+(`showNoAccess` sets `noAccess-signed-in` and points `noAccess-account` at `oidc.accountUrl()`). Both are
+about 30 lines and identical in the two apps, so copy them from `services/dictionary/static/js/app.js`
+(`revalidateSession`, `showNoAccess`) when the app wants them. They are left out of `esm/` because they
+reach into the page's DOM and the crs explorer wires them inline in `ui.html`.
+
+`scripts/fetch-design.sh`:
+
+```bash
+#!/usr/bin/env bash
+# Pull the pinned @fikar-ai/design release into static/design.
+#
+# The page links the design system's CSS and runs its shell.js and esm/ modules, so the files
+# live in this repo. This script is the only sanctioned way to update them, and a test fails when
+# a committed file drifts from design.lock.json. Bump DESIGN_VERSION, run this, commit the result.
+set -euo pipefail
+
+# The release must ship esm/ (the first one after 1.5.0).
+DESIGN_VERSION="${DESIGN_VERSION:?set DESIGN_VERSION to an @fikar-ai/design release that ships esm/}"
+HERE="$(cd "$(dirname "$0")/.." && pwd)"
+DEST="${DEST:-$HERE/static/design}"
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+
+(cd "$TMP" && npm pack "@fikar-ai/design@${DESIGN_VERSION}" --silent >/dev/null && tar xzf fikar-ai-design-*.tgz)
+
+FILES="tokens.css components.css shell.js brand/fikar-logo.svg brand/fikar-logo-reversed.svg"
+ESM_FILES="esm/oidc.js esm/auth.js esm/theme.js esm/dom.js esm/launcher.js esm/app-icons.js"
+NOTE="Vendored verbatim from @fikar-ai/design@${DESIGN_VERSION} by scripts/fetch-design.sh; do not edit."
+
+mkdir -p "$DEST"
+for f in $FILES $ESM_FILES; do
+  out="$DEST/$(basename "$f")"
+  case "$f" in
+    *.svg)
+      # An XML comment must come after the XML declaration, when there is one.
+      python3 - "$TMP/package/$f" "$out" "$NOTE" <<'PY'
+import pathlib, re, sys
+src, out, note = pathlib.Path(sys.argv[1]), pathlib.Path(sys.argv[2]), sys.argv[3]
+text = src.read_text()
+decl = re.match(r"\s*<\?xml[^>]*\?>\s*", text)
+head = decl.group(0) if decl else ""
+out.write_text(f"{head}<!-- {note} -->\n{text[len(head):]}")
+PY
+      ;;
+    *)
+      { echo "/* $NOTE */"; cat "$TMP/package/$f"; } > "$out"
+      ;;
+  esac
+done
+
+# The favicon set is copied byte for byte: the .ico and .png files are binary and a manifest
+# cannot carry a comment. Serve it at the site root.
+rm -rf "$DEST/favicon"
+mkdir -p "$DEST/favicon"
+cp "$TMP"/package/brand/favicon/* "$DEST/favicon/"
+
+python3 - "$DEST" "$DESIGN_VERSION" $(for f in $FILES $ESM_FILES; do basename "$f"; done) <<'PY'
+import hashlib, json, pathlib, sys
+dest, version, names = pathlib.Path(sys.argv[1]), sys.argv[2], sys.argv[3:]
+digest = lambda p: hashlib.sha256(p.read_bytes()).hexdigest()
+lock = {
+    "package": "@fikar-ai/design",
+    "version": version,
+    "sha256": {n: digest(dest / n) for n in names},
+    "favicon_sha256": {p.name: digest(p) for p in sorted((dest / "favicon").iterdir())},
+}
+(dest / "design.lock.json").write_text(json.dumps(lock, indent=2) + "\n")
+print(f"vendored @fikar-ai/design@{version}: {', '.join(names)}")
+PY
+```
+
+The `brand/apps/` glyphs are not vendored any more. `app-icons.js` carries them, already generated.
+
+A guard test in the app repo keeps the vendored files honest. It reads `design.lock.json`, hashes each file
+under `static/design/` (and each file in `favicon/`) and fails when one differs, when a file on disk is not
+in the lock, or when the `@fikar-ai/design@<version>` named in a file's first line is not the lock's version.
+The dictionary's `tests/test_design_vendoring.py` is the working example (pytest); a Node version is a
+dozen lines with `node:crypto`.
+
+Vendored modules run unchanged under `node --test`, so the app's own tests import them from
+`static/design/` and inject fakes. Keep the app's tests for its own code only; the modules' tests live in
+this package (`test/esm-*.test.mjs`).
+
 ## Tokens
 
 - Ramp is `--fk-*` (e.g. `--fk-blue600`, `--fk-n200`). Compose with `hsl()`: `hsl(var(--fk-blue600) / 0.5)`.

package/brand/apps/pii.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+  <path d="M20 13c0 5-3.5 7.5-7.66 8.95a1 1 0 0 1-.67-.01C7.5 20.5 4 18 4 13V6a1 1 0 0 1 1-1c2 0 4.5-1.2 6.24-2.72a1.17 1.17 0 0 1 1.52 0C14.51 3.81 17 5 19 5a1 1 0 0 1 1 1z"/>
+  <path d="m9 12 2 2 4-4"/>
+</svg>

package/esm/app-icons.js

@@ -0,0 +1,12 @@
+// Generated by scripts/build-app-icons.mjs from brand/apps/*.svg. Do not edit; change the SVG and run the script.
+// The inner markup of each app's launcher glyph, keyed by app id. Each is drawn in the shared 24px, 1.5 stroke frame.
+export const APP_ICONS = {
+  "account": "<circle cx=\"12\" cy=\"8\" r=\"5\"/><path d=\"M20 21a8 8 0 0 0-16 0\"/>",
+  "chat": "<path d=\"M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z\"/>",
+  "cost-calculator": "<rect width=\"16\" height=\"20\" x=\"4\" y=\"2\" rx=\"2\"/><line x1=\"8\" x2=\"16\" y1=\"6\" y2=\"6\"/><line x1=\"16\" x2=\"16\" y1=\"14\" y2=\"18\"/><path d=\"M16 10h.01\"/><path d=\"M12 10h.01\"/><path d=\"M8 10h.01\"/><path d=\"M12 14h.01\"/><path d=\"M8 14h.01\"/><path d=\"M12 18h.01\"/><path d=\"M8 18h.01\"/>",
+  "crs": "<circle cx=\"12\" cy=\"4.5\" r=\"2.5\"/><path d=\"m10.2 6.3-3.9 3.9\"/><circle cx=\"4.5\" cy=\"12\" r=\"2.5\"/><path d=\"M7 12h10\"/><circle cx=\"19.5\" cy=\"12\" r=\"2.5\"/><path d=\"m13.8 17.7 3.9-3.9\"/><circle cx=\"12\" cy=\"19.5\" r=\"2.5\"/>",
+  "dictionary": "<path d=\"M4 19.5v-15A2.5 2.5 0 0 1 6.5 2H19a1 1 0 0 1 1 1v18a1 1 0 0 1-1 1H6.5a1 1 0 0 1 0-5H20\"/><path d=\"m8 13 4-7 4 7\"/><path d=\"M9.1 11h5.7\"/>",
+  "pii": "<path d=\"M20 13c0 5-3.5 7.5-7.66 8.95a1 1 0 0 1-.67-.01C7.5 20.5 4 18 4 13V6a1 1 0 0 1 1-1c2 0 4.5-1.2 6.24-2.72a1.17 1.17 0 0 1 1.52 0C14.51 3.81 17 5 19 5a1 1 0 0 1 1 1z\"/><path d=\"m9 12 2 2 4-4\"/>",
+  "platform": "<line x1=\"21\" x2=\"14\" y1=\"4\" y2=\"4\"/><line x1=\"10\" x2=\"3\" y1=\"4\" y2=\"4\"/><line x1=\"21\" x2=\"12\" y1=\"12\" y2=\"12\"/><line x1=\"8\" x2=\"3\" y1=\"12\" y2=\"12\"/><line x1=\"21\" x2=\"16\" y1=\"20\" y2=\"20\"/><line x1=\"12\" x2=\"3\" y1=\"20\" y2=\"20\"/><line x1=\"14\" x2=\"14\" y1=\"2\" y2=\"6\"/><line x1=\"8\" x2=\"8\" y1=\"10\" y2=\"14\"/><line x1=\"16\" x2=\"16\" y1=\"18\" y2=\"22\"/>",
+  "super-admin": "<path d=\"M6 22V4a2 2 0 0 1 2-2h8a2 2 0 0 1 2 2v18Z\"/><path d=\"M6 12H4a2 2 0 0 0-2 2v6a2 2 0 0 0 2 2h2\"/><path d=\"M18 9h2a2 2 0 0 1 2 2v9a2 2 0 0 1-2 2h-2\"/><path d=\"M10 6h4\"/><path d=\"M10 10h4\"/><path d=\"M10 14h4\"/><path d=\"M10 18h4\"/>",
+};

package/esm/auth.js

@@ -0,0 +1,240 @@
+// Auth state machine for a plain-JS FIKAR app: the shared single-flight cookie
+// refresh, the authGeneration guard, and the proactive access-token renewal
+// timer. Shared by the dictionary, PII and crs apps (KAN-385).
+//
+// Kept free of the DOM, with every dependency injected, so node --test can run
+// it (test/esm-auth.test.mjs in @fikar-ai/design). The page wires the login
+// redirect and sign-out into the object createAuth() returns. The access token
+// is stored under `${storagePrefix}.token`.
+
+// 90s margin absorbs clock skew and the refresh call's own latency; the
+// jitter (redrawn on every arm) staggers tabs that share the same stored
+// token so several tabs don't rotate the shared .fikar.ai cookie at once.
+const MARGIN_MS = 90_000;
+const JITTER_MAX_MS = 45_000;
+
+/** Dependency-free JWT payload decode, no signature check: every caller here
+ * already holds a token the server accepted on some prior request, so this
+ * is just reading claims back out of it, not trusting it as a credential.
+ * Returns null for anything that isn't a three-segment JWT with a JSON
+ * payload, rather than throwing, since both callers below treat "can't read
+ * this claim" as a normal case (an unrecognized token, a claim the server
+ * didn't set) and not an error. */
+export function parseJwtClaims(token) {
+  if (typeof token !== 'string') return null;
+  const parts = token.split('.');
+  if (parts.length !== 3) return null;
+  try {
+    return JSON.parse(base64UrlDecode(parts[1]));
+  } catch {
+    return null;
+  }
+}
+
+/** The `exp` claim (seconds since epoch), in milliseconds. Needed to arm the
+ * renewal timer, and the token lifetime differs per environment (15 or 60
+ * minutes), so it must come from the token itself rather than a hardcoded
+ * constant. Exported for direct testing. */
+export function decodeJwtExpMs(token) {
+  const payload = parseJwtClaims(token);
+  return typeof payload?.exp === 'number' ? payload.exp * 1000 : null;
+}
+
+/** The `email` claim the user service puts on every access token (KAN-255):
+ * used only for the "Signed in as ..." line on the no-access screen, so a
+ * token that doesn't decode or carries no email claim just means that line
+ * is omitted, not an error. Exported for direct testing. */
+export function decodeJwtEmail(token) {
+  const payload = parseJwtClaims(token);
+  return typeof payload?.email === 'string' ? payload.email : null;
+}
+
+function base64UrlDecode(segment) {
+  const base64 = segment.replace(/-/g, '+').replace(/_/g, '/');
+  const padded = base64.padEnd(base64.length + ((4 - (base64.length % 4)) % 4), '=');
+  const binary = atob(padded);
+  // atob yields a binary string; re-decode as UTF-8 so multi-byte claim
+  // values don't get mangled.
+  const bytes = Uint8Array.from(binary, c => c.charCodeAt(0));
+  return new TextDecoder().decode(bytes);
+}
+
+/** Pure so jitter/margin math can be asserted directly. Exported for tests. */
+export function computeDelayMs(expiresAtMs, now, jitterMs) {
+  return Math.max(0, expiresAtMs - MARGIN_MS - jitterMs - now);
+}
+
+/**
+ * Builds the auth object ui.html holds for its lifetime. Dependencies are
+ * injected (storage, fetch, timers, randomness, the clock, the document) so
+ * tests can run this with no DOM, no real network and no real delays.
+ *
+ * `documentImpl` defaults to the real `document` when one exists (the
+ * `typeof` guard keeps that default from throwing in Node, where no global
+ * `document` is declared) and is only used to listen for `visibilitychange`
+ * (KAN-238); pass an object with `addEventListener`/`visibilityState` to
+ * drive that from a test, or `undefined` to skip wiring it up at all.
+ */
+export function createAuth({
+  storagePrefix,
+  storage = localStorage,
+  fetchImpl = fetch,
+  getAuthUrl,
+  onSessionCleared,
+  now = Date.now,
+  random = Math.random,
+  setTimeoutImpl = setTimeout,
+  clearTimeoutImpl = clearTimeout,
+  documentImpl = typeof document === 'undefined' ? undefined : document,
+} = {}) {
+  if (typeof storagePrefix !== 'string' || !storagePrefix) throw new Error('storagePrefix is required');
+  // Shares one cookie rotation across startup, the proactive timer, and
+  // concurrent expired requests.
+  let refreshPromise = null;
+  let authGeneration = 0;
+  let timerId = null;
+
+  const TOKEN_KEY = `${storagePrefix}.token`;
+  const token = () => storage.getItem(TOKEN_KEY);
+
+  function clearRenewal() {
+    if (timerId !== null) {
+      clearTimeoutImpl(timerId);
+      timerId = null;
+    }
+  }
+
+  /** (Re)arms the proactive renewal timer off the stored token's own `exp`.
+   * A no-op (no stored token, or one with no decodable exp) just clears any
+   * timer already scheduled. */
+  function armRenewal() {
+    clearRenewal();
+    const current = token();
+    if (!current) return;
+    const expiresAtMs = decodeJwtExpMs(current);
+    if (expiresAtMs === null) return;
+    const jitterMs = random() * JITTER_MAX_MS;
+    const delay = computeDelayMs(expiresAtMs, now(), jitterMs);
+    const generation = authGeneration;
+    timerId = setTimeoutImpl(() => {
+      timerId = null;
+      // A logout (or another generation-bumping event) between arming and
+      // firing must not let a stale timer touch the new session.
+      if (generation !== authGeneration) return;
+      // Shares trySso()'s single-flight guard with the reactive 401 path in
+      // authedFetch(), so a timer firing mid-refresh just waits on it. A
+      // proactive failure is silent by design: no login form, token left
+      // alone, the reactive path in authedFetch() is the fallback.
+      void trySso();
+    }, delay);
+  }
+
+  function clearSession() {
+    authGeneration++;
+    clearRenewal();
+    storage.removeItem(TOKEN_KEY);
+    onSessionCleared?.();
+  }
+
+  /** Stores a freshly issued access token (login) and arms the timer for it. */
+  function setSession(accessToken) {
+    authGeneration++;
+    storage.setItem(TOKEN_KEY, accessToken);
+    armRenewal();
+  }
+
+  function trySso() {
+    if (refreshPromise) return refreshPromise;
+    const generation = authGeneration;
+    refreshPromise = (async () => {
+      try {
+        const res = await fetchImpl(`${await getAuthUrl()}/api/auth/refresh`, {
+          method: 'POST',
+          credentials: 'include',
+        });
+        if (!res.ok) return false;
+        const data = await res.json();
+        if (generation !== authGeneration || !data.access_token) return false;
+        storage.setItem(TOKEN_KEY, data.access_token);
+        armRenewal();
+        return true;
+      } catch {
+        return false;
+      }
+    })().finally(() => { refreshPromise = null; });
+    return refreshPromise;
+  }
+
+  /** True when the stored token cannot carry a request without a refresh
+   * first: no token at all, or one that has already passed `exp` or sits
+   * inside the same MARGIN_MS the renewal timer uses. A token that decodes
+   * to no `exp` claim (never issued by the real user-service, but a stand-in
+   * some tests use) is left alone here and handled by the existing 401 path
+   * instead, since there is nothing to preflight-check about it. */
+  function needsPreflightRefresh() {
+    const current = token();
+    if (!current) return true;
+    const expiresAtMs = decodeJwtExpMs(current);
+    if (expiresAtMs === null) return false;
+    return expiresAtMs - MARGIN_MS <= now();
+  }
+
+  async function authedFetch(url, init = {}) {
+    // `init` lets a caller PATCH (the theme, KAN-294); the bearer header is
+    // always ours, whatever the caller passed.
+    const withAuth = (bearer) => ({ ...init, headers: { ...(init.headers || {}), Authorization: `Bearer ${bearer}` } });
+    const generation = authGeneration;
+    // Pre-flight (KAN-238): a token that is already expired, or due to
+    // expire within the renewal margin, is refreshed silently before the
+    // request goes out, instead of sending it, getting a 401, and refreshing
+    // reactively. This is what makes a laptop wake silent: the overdue
+    // renewal timer and the app's first request both want a refresh, and
+    // trySso()'s single-flight guard collapses them into one. A failed
+    // refresh here (dead cookie) falls straight through to the unchanged
+    // 401 handling below.
+    if (needsPreflightRefresh()) {
+      await trySso();
+      if (generation !== authGeneration) throw new Error('session changed');
+    }
+    const sentToken = token();
+    let res = await fetchImpl(url, withAuth(sentToken));
+    if (generation !== authGeneration) throw new Error('session changed');
+    if (res.status === 401) {
+      // A late 401 may arrive after another request already refreshed. Reuse
+      // that token instead of rotating the shared cookie for a second time.
+      if (token() && (token() !== sentToken || await trySso())) {
+        if (generation !== authGeneration) throw new Error('session changed');
+        res = await fetchImpl(url, withAuth(token()));
+        if (generation !== authGeneration) throw new Error('session changed');
+        if (res.status !== 401) return res;
+      }
+      if (generation === authGeneration) clearSession();
+      throw new Error('unauthorized');
+    }
+    return res;
+  }
+
+  // Re-arm on wake (KAN-238): a setTimeout cannot fire while the machine is
+  // asleep, so the armed timer is stale the moment the tab becomes visible
+  // again. Re-arming off the stored token here (an expired token arms with
+  // delay 0, see computeDelayMs) puts the next renewal on a correct footing
+  // even if this races the pre-flight check in authedFetch(); both paths
+  // share trySso()'s single-flight guard.
+  if (documentImpl?.addEventListener) {
+    documentImpl.addEventListener('visibilitychange', () => {
+      if (documentImpl.visibilityState === 'visible') armRenewal();
+    });
+  }
+
+  return {
+    token,
+    setSession,
+    clearSession,
+    trySso,
+    authedFetch,
+    armRenewal,
+    clearRenewal,
+    refreshInFlight: () => refreshPromise,
+    generation: () => authGeneration,
+  };
+}

package/esm/dom.js

@@ -0,0 +1,39 @@
+// A tiny element builder. Shared by the plain-JS apps (KAN-385). Text goes in as text nodes, never as markup, so a
+// name or definition typed by a person cannot inject HTML into the page.
+
+/** Children worth rendering: nested lists flattened, and the false, null and
+ * undefined that `cond && el` leaves behind dropped. Native append() would
+ * write those as the text "false" or "null". */
+export function renderable(children) {
+  return children.flat(Infinity).filter((c) => c !== undefined && c !== null && c !== false);
+}
+
+/** h('button', { class: 'btn', onclick: fn, disabled: true }, 'Save', child) */
+export function h(tag, props = {}, ...children) {
+  const node = document.createElement(tag);
+  for (const [key, value] of Object.entries(props || {})) {
+    if (value === undefined || value === null || value === false) continue;
+    if (key.startsWith('on') && typeof value === 'function') node.addEventListener(key.slice(2), value);
+    else if (key === 'class') node.className = value;
+    else if (key === 'value') node.value = value;
+    else if (value === true) node.setAttribute(key, '');
+    else node.setAttribute(key, String(value));
+  }
+  for (const child of renderable(children)) {
+    node.append(child instanceof Node ? child : document.createTextNode(String(child)));
+  }
+  return node;
+}
+
+export function clear(node) {
+  node.replaceChildren();
+  return node;
+}
+
+/** Replace a node's children; use this instead of clear(node).append(...) for
+ * any list that can hold `cond && el`. */
+export function fill(node, ...children) {
+  node.replaceChildren();
+  for (const child of renderable(children)) node.append(child instanceof Node ? child : document.createTextNode(String(child)));
+  return node;
+}

package/esm/launcher.js

@@ -0,0 +1,44 @@
+// The app launcher's panel markup from the provider's list, kept out of the
+// page so it can be tested with node --test. Shared by the dictionary, PII and
+// crs apps (KAN-385). The open/close behaviour is
+// shell.js's, through data-fk-menu.
+
+import { APP_ICONS } from './app-icons.js';
+
+function escapeHtml(value) {
+  return String(value)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+// The glyph for a known app id (the body comes from the vendored package, so it
+// is markup we trust); an unknown id shows the first letter of its name.
+function tile(app) {
+  const body = APP_ICONS[app.id];
+  if (body) {
+    return (
+      '<svg class="app-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"' +
+      ` stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${body}</svg>`
+    );
+  }
+  return escapeHtml(String(app.name || '').trim().charAt(0).toUpperCase());
+}
+
+/** One <a class="launcher-item"> per app, the current one marked. The list
+ * arrives already filtered and ordered by the provider; nothing is reordered
+ * or dropped here. Returns '' for an empty list, which the caller treats as
+ * "no launcher". */
+export function launcherItems(apps, currentId) {
+  return (apps || [])
+    .map((app) => {
+      const current = app.id === currentId;
+      return (
+        `<a class="launcher-item${current ? ' current' : ''}" role="menuitem"` +
+        ` href="${escapeHtml(app.url)}"${current ? ' aria-current="page"' : ''}>` +
+        `<span class="launcher-tile" aria-hidden="true">${tile(app)}</span>${escapeHtml(app.name)}</a>`
+      );
+    })
+    .join('');
+}

package/esm/oidc.js

@@ -0,0 +1,163 @@
+// OIDC authorization-code + PKCE flow for a plain-JS FIKAR app, against the
+// user service acting as the provider. Shared by the dictionary, PII and crs
+// apps (KAN-385).
+//
+// The three endpoints this app needs never move independently of the provider,
+// so they are built from authUrl rather than fetched from discovery, saving a
+// round trip before the redirect. Dependencies are injected so node --test
+// runs it with no browser (test/esm-oidc.test.mjs in @fikar-ai/design). The
+// pending sign-in is stored under `${storagePrefix}.oidc.pending`.
+
+const VERIFIER_BYTES = 64;
+
+/** Bytes -> base64url, no padding. Used for both the PKCE verifier and the
+ * S256 challenge. Exported for direct testing. */
+export function base64url(bytes) {
+  let binary = '';
+  for (const b of bytes) binary += String.fromCharCode(b);
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+/** RFC 7636 S256: base64url(SHA-256(ascii(verifier))). Exported so the RFC
+ * appendix B test vector can be checked directly against this function. */
+export async function codeChallenge(verifier, cryptoImpl) {
+  const bytes = new TextEncoder().encode(verifier);
+  const digest = await cryptoImpl.subtle.digest('SHA-256', bytes);
+  return base64url(new Uint8Array(digest));
+}
+
+/** Decodes a JWT's payload segment with no signature check. Safe here only
+ * because the id_token was read straight off the token endpoint's response
+ * body over TLS, not handed to us by a third party the way a redirect
+ * parameter would be; nothing forwards this token or trusts it beyond the
+ * nonce/aud/iss checks completeSignIn() makes right after decoding it.
+ * Exported for direct testing. */
+export function decodeJwtPayload(idToken) {
+  const parts = idToken.split('.');
+  if (parts.length !== 3) throw new Error('malformed id_token');
+  const base64 = parts[1].replace(/-/g, '+').replace(/_/g, '/');
+  const padded = base64.padEnd(base64.length + ((4 - (base64.length % 4)) % 4), '=');
+  const binary = atob(padded);
+  const bytes = Uint8Array.from(binary, c => c.charCodeAt(0));
+  return JSON.parse(new TextDecoder().decode(bytes));
+}
+
+function randomString(cryptoImpl, byteLength) {
+  const bytes = new Uint8Array(byteLength);
+  cryptoImpl.getRandomValues(bytes);
+  return base64url(bytes);
+}
+
+/** A same-origin path only: '/x' is fine, '//evil.example/x' and an absolute
+ * URL are not. Guards against an open redirect via a crafted returnTo. */
+function isSameOriginPath(value) {
+  return typeof value === 'string' && value.startsWith('/') && !value.startsWith('//');
+}
+
+/**
+ * Builds the OIDC client ui.html holds for its lifetime. Dependencies are
+ * injected (fetch, storage, crypto, location) so tests can drive this with
+ * no browser and no real network.
+ */
+export function createOidc({
+  storagePrefix,
+  authUrl,
+  clientId,
+  redirectUri,
+  postLogoutRedirectUri,
+  fetchImpl = fetch,
+  storage = typeof sessionStorage === 'undefined' ? undefined : sessionStorage,
+  cryptoImpl = globalThis.crypto,
+  locationImpl = typeof window === 'undefined' ? undefined : window.location,
+} = {}) {
+  if (typeof storagePrefix !== 'string' || !storagePrefix) throw new Error('storagePrefix is required');
+  const PENDING_KEY = `${storagePrefix}.oidc.pending`;
+  const issuer = authUrl.replace(/\/$/, '');
+  const authorizeEndpoint = `${issuer}/authorize`;
+  const tokenEndpoint = `${issuer}/token`;
+  const endSessionEndpoint = `${issuer}/end-session`;
+
+  async function beginSignIn(returnTo) {
+    const verifier = randomString(cryptoImpl, VERIFIER_BYTES);
+    const challenge = await codeChallenge(verifier, cryptoImpl);
+    const state = randomString(cryptoImpl, 32);
+    const nonce = randomString(cryptoImpl, 32);
+    storage.setItem(PENDING_KEY, JSON.stringify({ verifier, state, nonce, returnTo }));
+
+    const params = new URLSearchParams({
+      client_id: clientId,
+      redirect_uri: redirectUri,
+      response_type: 'code',
+      scope: 'openid email profile',
+      state,
+      nonce,
+      code_challenge: challenge,
+      code_challenge_method: 'S256',
+    });
+    locationImpl.assign(`${authorizeEndpoint}?${params}`);
+  }
+
+  async function completeSignIn(callbackUrl) {
+    const url = new URL(callbackUrl);
+    const error = url.searchParams.get('error');
+    if (error) {
+      const description = url.searchParams.get('error_description') || error;
+      throw new Error(description);
+    }
+    const code = url.searchParams.get('code');
+    const state = url.searchParams.get('state');
+    if (!code) throw new Error('callback URL has no code');
+
+    const raw = storage.getItem(PENDING_KEY);
+    const pending = raw ? JSON.parse(raw) : null;
+    if (!pending || !state || pending.state !== state) {
+      throw new Error('sign-in state mismatch');
+    }
+
+    const body = new URLSearchParams({
+      grant_type: 'authorization_code',
+      code,
+      redirect_uri: redirectUri,
+      client_id: clientId,
+      code_verifier: pending.verifier,
+    });
+    const res = await fetchImpl(tokenEndpoint, {
+      method: 'POST',
+      // The provider sets the refresh cookie on this response; without
+      // credentials: 'include' the browser drops that Set-Cookie header.
+      credentials: 'include',
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      body,
+    });
+    if (!res.ok) throw new Error(`token exchange failed (${res.status})`);
+    const data = await res.json();
+
+    const payload = decodeJwtPayload(data.id_token);
+    if (payload.nonce !== pending.nonce) throw new Error('id_token nonce mismatch');
+    if (payload.aud !== clientId) throw new Error('id_token aud mismatch');
+    if (String(payload.iss).replace(/\/$/, '') !== issuer) throw new Error('id_token iss mismatch');
+
+    storage.removeItem(PENDING_KEY);
+    const returnTo = isSameOriginPath(pending.returnTo) ? pending.returnTo : '/';
+    return { accessToken: data.access_token, returnTo };
+  }
+
+  function signOutUrl() {
+    const params = new URLSearchParams({
+      client_id: clientId,
+      post_logout_redirect_uri: postLogoutRedirectUri,
+    });
+    return `${endSessionEndpoint}?${params}`;
+  }
+
+  /** The hosted account console (KAN-241), told which app to link back to. */
+  function accountUrl() {
+    const params = new URLSearchParams({
+      client_id: clientId,
+      return_to: postLogoutRedirectUri,
+    });
+    return `${issuer}/account?${params}`;
+  }
+
+  return { beginSignIn, completeSignIn, signOutUrl, accountUrl };
+}

package/esm/theme.js

@@ -0,0 +1,47 @@
+// Theme plumbing: the same contract as the other FIKAR apps. The choice
+// (light, dark, system) is the account's; this module mirrors it locally so
+// the first paint is right, resolves system against the OS, and paints by
+// toggling `dark` on <html> plus data-theme, which the vendored @fikar-ai/design
+// tokens key on. The choice is stored under `${storagePrefix}-theme`.
+
+/** The localStorage key for an app's theme choice. The page's inline
+ * first-paint script reads the same key before any module has run. */
+export const themeKey = (prefix) => `${prefix}-theme`;
+export const THEMES = ['light', 'dark', 'system'];
+
+export function normalizeTheme(value) {
+  return THEMES.includes(value) ? value : 'system';
+}
+
+export function resolveTheme(theme, prefersDark) {
+  return theme === 'dark' || (theme === 'system' && prefersDark) ? 'dark' : 'light';
+}
+
+/** Wires storage, the root element and the OS query together. `onChange`
+ * receives the resolved theme after every paint, so canvases can repaint. */
+export function createTheme({ storagePrefix, storage, root, matchMedia, onChange = () => {} }) {
+  if (typeof storagePrefix !== 'string' || !storagePrefix) throw new Error('storagePrefix is required');
+  const THEME_KEY = themeKey(storagePrefix);
+  let theme = normalizeTheme(storage.getItem(THEME_KEY));
+  const query = matchMedia('(prefers-color-scheme: dark)');
+
+  function apply() {
+    const resolved = resolveTheme(theme, query.matches);
+    root.classList.toggle('dark', resolved === 'dark');
+    root.setAttribute('data-theme', theme);
+    onChange(resolved);
+    return resolved;
+  }
+
+  function set(next) {
+    theme = normalizeTheme(next);
+    storage.setItem(THEME_KEY, theme);
+    return apply();
+  }
+
+  if (typeof query.addEventListener === 'function') {
+    query.addEventListener('change', () => { if (theme === 'system') apply(); });
+  }
+
+  return { get: () => theme, set, apply, resolved: () => resolveTheme(theme, query.matches) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fikar-ai/design",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Fikar Ink design language — tokens, Tailwind preset + component layer. Single source of truth across all Fikar surfaces.",
   "type": "module",
   "license": "UNLICENSED",
@@ -21,6 +21,7 @@
     "./fonts/*": "./fonts/*",
     "./recipes/*": "./recipes/*",
     "./shell.js": "./shell.js",
+    "./esm/*": "./esm/*",
     "./templates/*": "./templates/*",
     "./preset": {
       "types": "./preset.d.ts",
@@ -51,6 +52,7 @@
     "recipes/status-badge.html",
     "recipes/time.html",
     "shell.js",
+    "esm/",
     "templates/",
     "preset.js",
     "preset.d.ts",

package/templates/jinja/launcher.html

@@ -18,6 +18,7 @@
   'cost-calculator': '<rect width="16" height="20" x="4" y="2" rx="2"/><line x1="8" x2="16" y1="6" y2="6"/><line x1="16" x2="16" y1="14" y2="18"/><path d="M16 10h.01"/><path d="M12 10h.01"/><path d="M8 10h.01"/><path d="M12 14h.01"/><path d="M8 14h.01"/><path d="M12 18h.01"/><path d="M8 18h.01"/>',
   'crs': '<circle cx="12" cy="4.5" r="2.5"/><path d="m10.2 6.3-3.9 3.9"/><circle cx="4.5" cy="12" r="2.5"/><path d="M7 12h10"/><circle cx="19.5" cy="12" r="2.5"/><path d="m13.8 17.7 3.9-3.9"/><circle cx="12" cy="19.5" r="2.5"/>',
   'dictionary': '<path d="M4 19.5v-15A2.5 2.5 0 0 1 6.5 2H19a1 1 0 0 1 1 1v18a1 1 0 0 1-1 1H6.5a1 1 0 0 1 0-5H20"/><path d="m8 13 4-7 4 7"/><path d="M9.1 11h5.7"/>',
+  'pii': '<path d="M20 13c0 5-3.5 7.5-7.66 8.95a1 1 0 0 1-.67-.01C7.5 20.5 4 18 4 13V6a1 1 0 0 1 1-1c2 0 4.5-1.2 6.24-2.72a1.17 1.17 0 0 1 1.52 0C14.51 3.81 17 5 19 5a1 1 0 0 1 1 1z"/><path d="m9 12 2 2 4-4"/>',
   'platform': '<line x1="21" x2="14" y1="4" y2="4"/><line x1="10" x2="3" y1="4" y2="4"/><line x1="21" x2="12" y1="12" y2="12"/><line x1="8" x2="3" y1="12" y2="12"/><line x1="21" x2="16" y1="20" y2="20"/><line x1="12" x2="3" y1="20" y2="20"/><line x1="14" x2="14" y1="2" y2="6"/><line x1="8" x2="8" y1="10" y2="14"/><line x1="16" x2="16" y1="18" y2="22"/>',
   'super-admin': '<path d="M6 22V4a2 2 0 0 1 2-2h8a2 2 0 0 1 2 2v18Z"/><path d="M6 12H4a2 2 0 0 0-2 2v6a2 2 0 0 0 2 2h2"/><path d="M18 9h2a2 2 0 0 1 2 2v9a2 2 0 0 1-2 2h-2"/><path d="M10 6h4"/><path d="M10 10h4"/><path d="M10 14h4"/><path d="M10 18h4"/>',
 } %}