@schlessera/brain-ui-react 0.35.0 → 0.37.0

package/src/lib/mermaid-theme.ts

@@ -1,5 +1,5 @@
 /**
- * Mermaid theme variables for the two surfaces a diagram can land on.
+ * Mermaid theme variables for the two schemes a diagram can land on.
  *
  * Mermaid's stock "dark" theme is a blue-grey palette that reads as foreign
  * next to the app's warm-neutral chrome, and its "neutral" theme is what the
@@ -7,17 +7,29 @@
  * variables below, so an in-app diagram and a shared PNG are recognisably the
  * same product.
  *
- * Two rules kept the palette honest:
- *   - Surfaces follow the tokens in theme.css, not approximations of them. A
- *     chat diagram sits on `--color-surface` (#141619), not on the page
- *     background, because MermaidBlock draws it on a raised plate.
- *   - Multi-series colors reuse CATEGORICAL_SLOTS from the graph view, which
- *     is the repo's one CVD-validated categorical palette. Slot order is the
- *     CVD-safety mechanism there and is preserved here.
+ * Every value is a kit token, read for the scheme (`readToken`), because
+ * mermaid's `themeVariables` take literal colours and cannot follow a CSS
+ * custom property:
+ *   - The six diagram surfaces are the kit's `--bk-diagram-*` (seventh drop
+ *     §L6): the grounds are surfaces, and every LINE is information and takes
+ *     the 3:1 bar. Text is the ink — a node's label never takes its node's
+ *     colour.
+ *   - Multi-series colours are the kit's canvas slots, the repo's one
+ *     CVD-validated categorical palette, respelled per theme in the same
+ *     order: a series keeps its slot between a dark diagram and its paper
+ *     export, and the slot order is the CVD-safety mechanism.
+ *   - A bar that carries `on-fill` text (an active, done or critical task) is
+ *     a FILL, never an ink or a mark: on paper a darkened accent under
+ *     near-black text is unreadable.
+ *
+ * The share pipeline renders in `light`, whatever the screen shows: a share
+ * lands in a mail client or a printer, which assume paper.
  */
-import { CATEGORICAL_SLOTS, OTHER_COLOR } from "../components/graph/lib/graph-helpers.js";
+import type { TokenName } from "@schlessera/brain-ui-kit";
+
+import { readToken, type ColorScheme } from "./light-dark.js";
 
-export type MermaidTheme = "dark" | "light";
+export type MermaidTheme = ColorScheme;
 
 // These variables reach mermaid through initialize(), NOT through a
 // `%%{init: …}%%` directive: mermaid's directive path rewrites `'` to `"`
@@ -25,222 +37,179 @@ export type MermaidTheme = "dark" | "light";
 // a font stack cannot survive it. See the note in mermaid.ts.
 const SANS = '"Plus Jakarta Sans", system-ui, -apple-system, sans-serif';
 
-/** Ordered series colors, long enough for the 12-slot scales mermaid asks for. */
-const SERIES = [...CATEGORICAL_SLOTS, OTHER_COLOR, "#67b8e3", "#eab354", "#b197d4"];
+interface DiagramPalette {
+  bg: string;
+  node: string;
+  cluster: string;
+  line: string;
+  clusterBorder: string;
+  text: string;
+  /** The raised surface: sequence activations, notes, alternate sections. */
+  raised: string;
+  /** The card edge, as a neutral bar ground. */
+  edge: string;
+  muted: string;
+  /** The amber ink: titles, note borders, the quadrant point. */
+  accent: string;
+  /** The teal ink: the active activation, the today line. */
+  affirm: string;
+  /** The red ink: error text. */
+  danger: string;
+  /** Text on a fill — near-black in both themes. */
+  onFill: string;
+  /** The three fills that carry on-fill text: active, done, critical. */
+  amberFill: string;
+  neutralFill: string;
+  redFill: string;
+  /** Ordered series colours, long enough for the 12-slot scales mermaid asks for. */
+  series: string[];
+}
+
+function palette(scheme: ColorScheme): DiagramPalette {
+  const t = (name: TokenName) => readToken(name, scheme);
+  return {
+    bg: t("diagram-bg"),
+    node: t("diagram-node"),
+    cluster: t("diagram-cluster"),
+    line: t("diagram-line"),
+    clusterBorder: t("diagram-cluster-border"),
+    text: t("diagram-text"),
+    raised: t("color-raised"),
+    edge: t("color-edge"),
+    muted: t("color-ink-mute"),
+    accent: t("color-amber"),
+    affirm: t("color-teal"),
+    danger: t("color-red"),
+    onFill: t("on-fill"),
+    amberFill: t("amber-fill"),
+    neutralFill: t("neutral-fill"),
+    redFill: t("red-fill"),
+    series: [
+      ...[1, 2, 3, 4, 5, 6, 7, 8].map((n) => t(`canvas-slot-${n}` as TokenName)),
+      t("canvas-other"),
+      t("blue-mark"),
+      t("gold-mark"),
+      t("purple-mark"),
+    ],
+  };
+}
 
 /** Expand a scale into the `${prefix}0..count-1` (or 1-based) shape mermaid wants. */
-function scale(prefix: string, count: number, oneBased = false): Record<string, string> {
+function scale(series: string[], prefix: string, count: number, oneBased = false): Record<string, string> {
   const out: Record<string, string> = {};
   for (let i = 0; i < count; i++) {
-    out[`${prefix}${oneBased ? i + 1 : i}`] = SERIES[i % SERIES.length];
+    out[`${prefix}${oneBased ? i + 1 : i}`] = series[i % series.length]!;
   }
   return out;
 }
 
 /**
- * Dark: the in-app palette. Node fills use `--color-surface-overlay` so nodes
- * sit a step above the block's own `--color-surface` plate, and borders use
- * #3d4150 rather than `--color-border` (#2a2d35) — a 1px border at the token
- * value all but disappears against the plate at diagram scale.
+ * The variables for one palette. Node fills use the diagram node surface so
+ * nodes sit a step above the block's own plate, and borders use the diagram
+ * line — a 1px border at the card-edge value all but disappears against the
+ * plate at diagram scale.
  */
-const DARK: Record<string, string | boolean> = {
-  darkMode: true,
-  background: "#141619",
-  fontFamily: SANS,
-  fontSize: "14px",
-
-  primaryColor: "#1e2128",
-  primaryTextColor: "#e8e4df",
-  primaryBorderColor: "#3d4150",
-  secondaryColor: "#1a1d22",
-  secondaryTextColor: "#e8e4df",
-  secondaryBorderColor: "#3d4150",
-  tertiaryColor: "#0c0e12",
-  tertiaryTextColor: "#8a8691",
-  tertiaryBorderColor: "#2a2d35",
-
-  mainBkg: "#1e2128",
-  nodeBorder: "#3d4150",
-  nodeTextColor: "#e8e4df",
-  textColor: "#e8e4df",
-  lineColor: "#8a8691",
-  defaultLinkColor: "#8a8691",
-  titleColor: "#e09f3e",
-  edgeLabelBackground: "#141619",
-  clusterBkg: "#0c0e12",
-  clusterBorder: "#2a2d35",
-
-  noteBkgColor: "#1a1d22",
-  noteTextColor: "#e8e4df",
-  noteBorderColor: "#e09f3e",
-  errorBkgColor: "#2a1a1a",
-  errorTextColor: "#f87171",
-
-  // Sequence
-  actorBkg: "#1e2128",
-  actorBorder: "#3d4150",
-  actorTextColor: "#e8e4df",
-  actorLineColor: "#3d4150",
-  signalColor: "#8a8691",
-  signalTextColor: "#e8e4df",
-  labelBoxBkgColor: "#1a1d22",
-  labelBoxBorderColor: "#2a2d35",
-  labelTextColor: "#e8e4df",
-  loopTextColor: "#e8e4df",
-  activationBkgColor: "#1a1d22",
-  activationBorderColor: "#5bb5a2",
-  sequenceNumberColor: "#0c0e12",
-
-  // State / class / journey
-  labelColor: "#e8e4df",
-  altBackground: "#0c0e12",
-  classText: "#e8e4df",
-
-  // Gantt
-  sectionBkgColor: "#1a1d22",
-  altSectionBkgColor: "#141619",
-  sectionBkgColor2: "#1e2128",
-  gridColor: "#2a2d35",
-  taskBkgColor: "#2a2d35",
-  taskTextColor: "#e8e4df",
-  taskTextOutsideColor: "#e8e4df",
-  taskTextDarkColor: "#0c0e12",
-  taskBorderColor: "#3d4150",
-  doneTaskBkgColor: "#565b66",
-  doneTaskBorderColor: "#3d4150",
-  activeTaskBkgColor: "#e09f3e",
-  activeTaskBorderColor: "#e09f3e",
-  critBkgColor: "#d03b3b",
-  critBorderColor: "#d03b3b",
-  todayLineColor: "#5bb5a2",
-
-  // Pie
-  pieTitleTextColor: "#e8e4df",
-  pieSectionTextColor: "#0c0e12",
-  pieLegendTextColor: "#e8e4df",
-  pieStrokeColor: "#141619",
-  pieOuterStrokeColor: "#2a2d35",
-
-  // Quadrant / requirement / misc surfaces that don't inherit cleanly
-  quadrant1Fill: "#1e2128",
-  quadrant2Fill: "#1a1d22",
-  quadrant3Fill: "#141619",
-  quadrant4Fill: "#1e2128",
-  quadrantPointFill: "#e09f3e",
-  quadrantTitleFill: "#e8e4df",
-  quadrantInternalBorderStrokeFill: "#2a2d35",
-  quadrantExternalBorderStrokeFill: "#3d4150",
-};
+function variables(scheme: ColorScheme, p: DiagramPalette): Record<string, string | boolean> {
+  return {
+    darkMode: scheme === "dark",
+    background: p.bg,
+    fontFamily: SANS,
+    fontSize: "14px",
+
+    primaryColor: p.node,
+    primaryTextColor: p.text,
+    primaryBorderColor: p.line,
+    secondaryColor: p.raised,
+    secondaryTextColor: p.text,
+    secondaryBorderColor: p.line,
+    tertiaryColor: p.cluster,
+    tertiaryTextColor: p.muted,
+    tertiaryBorderColor: p.clusterBorder,
+
+    mainBkg: p.node,
+    nodeBorder: p.line,
+    nodeTextColor: p.text,
+    textColor: p.text,
+    lineColor: p.line,
+    defaultLinkColor: p.line,
+    titleColor: p.accent,
+    edgeLabelBackground: p.bg,
+    clusterBkg: p.cluster,
+    clusterBorder: p.clusterBorder,
+
+    noteBkgColor: p.raised,
+    noteTextColor: p.text,
+    noteBorderColor: p.accent,
+    errorBkgColor: p.cluster,
+    errorTextColor: p.danger,
+
+    // Sequence
+    actorBkg: p.node,
+    actorBorder: p.line,
+    actorTextColor: p.text,
+    actorLineColor: p.line,
+    signalColor: p.line,
+    signalTextColor: p.text,
+    labelBoxBkgColor: p.raised,
+    labelBoxBorderColor: p.clusterBorder,
+    labelTextColor: p.text,
+    loopTextColor: p.text,
+    activationBkgColor: p.raised,
+    activationBorderColor: p.affirm,
+    sequenceNumberColor: p.onFill,
+
+    // State / class / journey
+    labelColor: p.text,
+    altBackground: p.cluster,
+    classText: p.text,
+
+    // Gantt
+    sectionBkgColor: p.raised,
+    altSectionBkgColor: p.bg,
+    sectionBkgColor2: p.node,
+    gridColor: p.clusterBorder,
+    taskBkgColor: p.edge,
+    taskTextColor: p.text,
+    taskTextOutsideColor: p.text,
+    taskTextDarkColor: p.onFill,
+    taskBorderColor: p.line,
+    doneTaskBkgColor: p.neutralFill,
+    doneTaskBorderColor: p.line,
+    activeTaskBkgColor: p.amberFill,
+    activeTaskBorderColor: p.amberFill,
+    critBkgColor: p.redFill,
+    critBorderColor: p.redFill,
+    todayLineColor: p.affirm,
+
+    // Pie
+    pieTitleTextColor: p.text,
+    pieSectionTextColor: p.onFill,
+    pieLegendTextColor: p.text,
+    pieStrokeColor: p.bg,
+    pieOuterStrokeColor: p.clusterBorder,
+
+    // Quadrant / requirement / misc surfaces that don't inherit cleanly
+    quadrant1Fill: p.node,
+    quadrant2Fill: p.raised,
+    quadrant3Fill: p.bg,
+    quadrant4Fill: p.node,
+    quadrantPointFill: p.accent,
+    quadrantTitleFill: p.text,
+    quadrantInternalBorderStrokeFill: p.clusterBorder,
+    quadrantExternalBorderStrokeFill: p.line,
+
+    ...scale(p.series, "pie", 12, true), // pie1..pie12
+    ...scale(p.series, "cScale", 12), // cScale0..11 (journey, timeline, xychart)
+    ...scale(p.series, "fillType", 8), // fillType0..7 (class/state/journey sections)
+    ...scale(p.series, "git", 8), // git0..git7 (gitgraph branches)
+  };
+}
 
 /**
- * Light: what the share renderer emits. Tuned against the PNG/PDF template's
- * own palette (`ui-server/src/render/template.ts`: #ffffff page, #f8fafc
- * surface, #e5e7eb border, #1f2937 text) so a diagram doesn't look pasted in.
- * The amber and teal are darkened from the app tokens — #e09f3e on white is a
- * 1.9:1 line, unusable for edges or titles.
+ * Theme variables for a scheme, as mermaid's `themeVariables` object. Read
+ * at call time, so a host that re-points a token and a theme switch are both
+ * honoured; `mermaid.ts` re-initialises per render anyway.
  */
-const LIGHT: Record<string, string | boolean> = {
-  darkMode: false,
-  background: "#ffffff",
-  fontFamily: SANS,
-  fontSize: "14px",
-
-  primaryColor: "#f8fafc",
-  primaryTextColor: "#1f2937",
-  primaryBorderColor: "#c3c9d2",
-  secondaryColor: "#f3f4f6",
-  secondaryTextColor: "#1f2937",
-  secondaryBorderColor: "#c3c9d2",
-  tertiaryColor: "#ffffff",
-  tertiaryTextColor: "#6b7280",
-  tertiaryBorderColor: "#e5e7eb",
-
-  mainBkg: "#f8fafc",
-  nodeBorder: "#c3c9d2",
-  nodeTextColor: "#1f2937",
-  textColor: "#1f2937",
-  lineColor: "#6b7280",
-  defaultLinkColor: "#6b7280",
-  titleColor: "#9a6516",
-  edgeLabelBackground: "#ffffff",
-  clusterBkg: "#f3f4f6",
-  clusterBorder: "#d7dbe0",
-
-  noteBkgColor: "#fdf6e8",
-  noteTextColor: "#1f2937",
-  noteBorderColor: "#9a6516",
-  errorBkgColor: "#fdecec",
-  errorTextColor: "#b42323",
-
-  // Sequence
-  actorBkg: "#f8fafc",
-  actorBorder: "#c3c9d2",
-  actorTextColor: "#1f2937",
-  actorLineColor: "#c3c9d2",
-  signalColor: "#6b7280",
-  signalTextColor: "#1f2937",
-  labelBoxBkgColor: "#f3f4f6",
-  labelBoxBorderColor: "#d7dbe0",
-  labelTextColor: "#1f2937",
-  loopTextColor: "#1f2937",
-  activationBkgColor: "#f3f4f6",
-  activationBorderColor: "#2f7d6b",
-  sequenceNumberColor: "#ffffff",
-
-  // State / class / journey
-  labelColor: "#1f2937",
-  altBackground: "#f3f4f6",
-  classText: "#1f2937",
-
-  // Gantt
-  sectionBkgColor: "#f8fafc",
-  altSectionBkgColor: "#ffffff",
-  sectionBkgColor2: "#f3f4f6",
-  gridColor: "#e5e7eb",
-  taskBkgColor: "#e5e7eb",
-  taskTextColor: "#1f2937",
-  taskTextOutsideColor: "#1f2937",
-  taskTextDarkColor: "#1f2937",
-  taskBorderColor: "#c3c9d2",
-  doneTaskBkgColor: "#d7dbe0",
-  doneTaskBorderColor: "#c3c9d2",
-  activeTaskBkgColor: "#e0a75a",
-  activeTaskBorderColor: "#9a6516",
-  critBkgColor: "#e08a8a",
-  critBorderColor: "#b42323",
-  todayLineColor: "#2f7d6b",
-
-  // Pie
-  pieTitleTextColor: "#1f2937",
-  pieSectionTextColor: "#ffffff",
-  pieLegendTextColor: "#1f2937",
-  pieStrokeColor: "#ffffff",
-  pieOuterStrokeColor: "#d7dbe0",
-
-  // Quadrant
-  quadrant1Fill: "#f8fafc",
-  quadrant2Fill: "#f3f4f6",
-  quadrant3Fill: "#ffffff",
-  quadrant4Fill: "#f8fafc",
-  quadrantPointFill: "#9a6516",
-  quadrantTitleFill: "#1f2937",
-  quadrantInternalBorderStrokeFill: "#e5e7eb",
-  quadrantExternalBorderStrokeFill: "#d7dbe0",
-};
-
-const SERIES_SCALES: Record<string, string> = {
-  ...scale("pie", 12, true), // pie1..pie12
-  ...scale("cScale", 12), // cScale0..11 (journey, timeline, xychart)
-  ...scale("fillType", 8), // fillType0..7 (class/state/journey sections)
-  ...scale("git", 8), // git0..git7 (gitgraph branches)
-};
-
-const THEME_VARIABLES: Record<MermaidTheme, Record<string, string | boolean>> = {
-  dark: { ...DARK, ...SERIES_SCALES },
-  light: { ...LIGHT, ...SERIES_SCALES },
-};
-
-/** Theme variables for a target surface, as mermaid's `themeVariables` object. */
 export function mermaidThemeVariables(theme: MermaidTheme): Record<string, string | boolean> {
-  return THEME_VARIABLES[theme];
+  return variables(theme, palette(theme));
 }

package/src/lib/passkeys.ts

@@ -4,11 +4,12 @@ import {
   browserSupportsWebAuthn,
   browserSupportsWebAuthnAutofill,
 } from "@simplewebauthn/browser";
-import { api } from "./api-client.js";
+import type { BrainApi } from "./api-client.js";
 
 /**
  * Thin ceremony wrappers around @simplewebauthn/browser. All server calls go
- * through api-client; success means the server set the session cookie.
+ * through the supplied API. Cancellation prevents starting a stale prompt or
+ * submitting its result; the browser library owns the page-wide prompt itself.
  */
 
 export function supportsPasskeys(): boolean {
@@ -31,20 +32,27 @@ export function isUserCancel(err: unknown): boolean {
  * Full login ceremony. With `useBrowserAutofill`, resolves only if the user
  * picks a passkey from the input's autofill suggestions (conditional UI).
  */
-export async function loginWithPasskey(opts?: {
+export async function loginWithPasskey(api: BrainApi, opts?: {
+  signal?: AbortSignal;
   useBrowserAutofill?: boolean;
 }): Promise<void> {
+  opts?.signal?.throwIfAborted();
   const optionsJSON = await api.passkeyLoginOptions();
+  opts?.signal?.throwIfAborted();
   const response = await startAuthentication({
     optionsJSON,
     useBrowserAutofill: opts?.useBrowserAutofill ?? false,
   });
+  opts?.signal?.throwIfAborted();
   await api.passkeyLoginVerify(response);
 }
 
 /** Full registration ceremony (requires an authenticated session). */
-export async function registerPasskey(label?: string): Promise<void> {
+export async function registerPasskey(api: BrainApi, label?: string, signal?: AbortSignal): Promise<void> {
+  signal?.throwIfAborted();
   const optionsJSON = await api.passkeyRegisterOptions();
+  signal?.throwIfAborted();
   const response = await startRegistration({ optionsJSON });
+  signal?.throwIfAborted();
   await api.passkeyRegisterVerify(response, label);
 }

package/src/lib/push-registration.ts

@@ -1,11 +1,12 @@
-import { api } from "./api-client.js";
+import type { BrainApi } from "./api-client.js";
 
 /**
  * Re-assert an existing browser subscription after authentication changes.
  * This does not request permission or create a subscription: it only binds an
  * already-enabled endpoint to the newly issued server principal.
  */
-export async function rebindPushSubscriptionAfterLogin(): Promise<void> {
+export async function rebindPushSubscriptionAfterLogin(api: BrainApi, signal?: AbortSignal): Promise<void> {
+  signal?.throwIfAborted();
   if (
     typeof Notification === "undefined" ||
     Notification.permission !== "granted" ||
@@ -23,7 +24,23 @@ export async function rebindPushSubscriptionAfterLogin(): Promise<void> {
       ? navigator.userAgent.slice(0, 100)
       : undefined;
   const registration = await serviceWorker.ready;
+  signal?.throwIfAborted();
   const subscription = await registration.pushManager.getSubscription();
+  signal?.throwIfAborted();
   if (!subscription) return;
+  if (subscription.options.applicationServerKey) {
+    const { publicKey } = await api.pushPublicKey();
+    signal?.throwIfAborted();
+    if (!subscriptionMatchesKey(subscription, publicKey)) return;
+  }
   await api.pushSubscribe(subscription.toJSON(), label);
 }
+
+/** A service-worker subscription may belong to another server's VAPID key. */
+export function subscriptionMatchesKey(subscription: PushSubscription, publicKey: string): boolean {
+  const key = subscription.options.applicationServerKey;
+  if (!key) return true;
+  let bin = "";
+  for (const b of new Uint8Array(key)) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "") === publicKey;
+}

package/src/lib/share-intake.ts

@@ -4,7 +4,7 @@ import {
   type ShareIntakeResult,
 } from "@schlessera/brain-ui-sdk/protocol";
 import type { StoredShare } from "@schlessera/brain-ui-sdk/share-target";
-import { apiBase } from "./backend.js";
+import type { BrainUiRoot } from "../root.js";
 import {
   fileToAttachment,
   validateAttachments,
@@ -75,7 +75,9 @@ export type ShareUploadOutcome =
  */
 export async function uploadShare(
   record: StoredShare,
-  fetchImpl: typeof fetch = fetch
+  fetchImpl: BrainUiRoot["request"],
+  apiBase: string,
+  signal?: AbortSignal
 ): Promise<ShareUploadOutcome> {
   const form = new FormData();
   if (record.title) form.set("title", record.title);
@@ -85,9 +87,10 @@ export async function uploadShare(
 
   let response: Response;
   try {
-    response = await fetchImpl(`${apiBase()}/share`, {
+    response = await fetchImpl(`${apiBase}/share`, {
       method: "POST",
       body: form,
+      signal,
     });
   } catch (err) {
     return { ok: false, error: err instanceof Error ? err.message : "network_error" };

package/src/lib/share.ts

@@ -1,4 +1,4 @@
-import { apiBase } from "./backend.js";
+import type { BrainUiRoot } from "../root.js";
 import type { RenderRequest } from "@schlessera/brain-ui-sdk/protocol";
 
 export type ShareKind = "file" | "text" | "richtext";
@@ -108,11 +108,12 @@ export async function copyRichText(html: string, plain: string): Promise<boolean
  * /api/files/content?raw=1 endpoint for share-the-bytes flows.
  */
 export async function fetchAsFile(
+  root: BrainUiRoot,
   url: string,
   filename: string,
   mime?: string
 ): Promise<File> {
-  const res = await fetch(url);
+  const res = await root.request(url);
   if (!res.ok) throw new Error(`fetch failed: ${res.status} ${res.statusText}`);
   const blob = await res.blob();
   return new File([blob], filename, { type: mime ?? blob.type ?? "application/octet-stream" });
@@ -122,10 +123,11 @@ export async function fetchAsFile(
  * POST to /api/render and return the resulting File. Throws on non-2xx.
  */
 export async function renderToFile(
+  root: BrainUiRoot,
   req: RenderRequest,
   filename: string
 ): Promise<File> {
-  const res = await fetch(`${apiBase()}/render`, {
+  const res = await root.request(`${root.apiBase()}/render`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify(req),
@@ -151,7 +153,7 @@ export async function renderToFile(
 /**
  * One-call helper: render content to PNG/PDF and dispatch the share sheet.
  */
-export async function renderAndShare(opts: {
+export async function renderAndShare(root: BrainUiRoot, opts: {
   content: string;
   contentType: RenderRequest["contentType"];
   format: RenderRequest["format"];
@@ -160,6 +162,7 @@ export async function renderAndShare(opts: {
   text?: string;
 }): Promise<boolean> {
   const file = await renderToFile(
+    root,
     { content: opts.content, contentType: opts.contentType, format: opts.format, title: opts.title },
     opts.filename
   );

package/src/lib/single-key.ts

@@ -0,0 +1,47 @@
+/**
+ * Single-letter shortcuts, focus-scoped (D36).
+ *
+ * The design's rule: `a` / `d` / `s` act only while the card they belong to
+ * holds focus; `j` / `k` only inside the focused list; anything global takes
+ * a modifier. So a letter is a shortcut exactly when it arrives bare — no
+ * modifier — and not from something the reader is typing into. Both checks
+ * live here so every list and card applies the same ones.
+ */
+export function isEditableTarget(target: EventTarget | null): boolean {
+  if (!(target instanceof HTMLElement)) return false;
+  if (target.isContentEditable) return true;
+  const tag = target.tagName;
+  return tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT";
+}
+
+/**
+ * The letter a keydown means as a shortcut, lowercase, or `null` when it is
+ * not one: a modifier is held, the key is not a single character, or the
+ * reader is typing into a field.
+ */
+export function singleKey(event: {
+  key: string;
+  metaKey: boolean;
+  ctrlKey: boolean;
+  altKey: boolean;
+  target: EventTarget | null;
+}): string | null {
+  if (event.metaKey || event.ctrlKey || event.altKey) return null;
+  if (event.key.length !== 1) return null;
+  if (isEditableTarget(event.target)) return null;
+  return event.key.toLowerCase();
+}
+
+/**
+ * Where focus goes once a card is decided or dismissed: the next card in
+ * document order, else the previous one, else the fallback — the composer
+ * for an in-chat approval, the page heading for an inbox. Called BEFORE the
+ * card leaves the DOM, so the neighbours are still where they were.
+ */
+export function focusAfterDecision(current: Element, cardSelector: string, fallbackSelector: string): void {
+  const cards = [...document.querySelectorAll<HTMLElement>(cardSelector)];
+  const here = cards.indexOf(current as HTMLElement);
+  const next = cards[here + 1] ?? cards[here - 1];
+  const target = next ?? document.querySelector<HTMLElement>(fallbackSelector);
+  target?.focus();
+}