@digithings-ai/ui 0.0.0-stage → 0.1.0

package/src/components/chat/boot-signal.ts

@@ -0,0 +1,144 @@
+/**
+ * Same-window signal that the DigiChat boot animation has settled.
+ * DigichatBootLoader dispatches it; surfaces that reveal copy after the boot
+ * (e.g. the welcome body typewriter) listen for it so their animation is not
+ * spent behind a boot overlay.
+ */
+export const DIGI_CHAT_READY_EVENT = "digichat:ready";
+
+/** Mark the boot as settled for this document (idempotent). */
+export function signalDigichatReady(): void {
+  if (typeof document === "undefined") return;
+  document.documentElement.dataset.digichatReady = "1";
+  window.dispatchEvent(new Event(DIGI_CHAT_READY_EVENT));
+}
+
+/** Whether the boot already settled in this document. */
+export function hasDigichatReady(): boolean {
+  return (
+    typeof document !== "undefined" &&
+    document.documentElement.dataset.digichatReady === "1"
+  );
+}
+
+/**
+ * Same-window signal that the boot overlay has left the stage (it starts
+ * fading). Surfaces that hold their choreography until the handoff - e.g. the
+ * welcome typewriter in "takeover" handoff mode - listen for it.
+ */
+export const DIGI_CHAT_REVEALED_EVENT = "digichat:boot-revealed";
+
+/** Mark the boot handoff as started for this document (idempotent). */
+export function signalDigichatRevealed(): void {
+  if (typeof document === "undefined") return;
+  document.documentElement.dataset.digichatRevealed = "1";
+  window.dispatchEvent(new Event(DIGI_CHAT_REVEALED_EVENT));
+}
+
+/** Whether the boot handoff already started in this document. */
+export function hasDigichatRevealed(): boolean {
+  return (
+    typeof document !== "undefined" &&
+    document.documentElement.dataset.digichatRevealed === "1"
+  );
+}
+
+/**
+ * Boot-step channel: the app reports real milestones as they happen
+ * (deployment configuration applied, chat runtime up) so the boot animation
+ * can complete its rows against the actual boot instead of a fixed timeline.
+ */
+export const DIGI_CHAT_BOOT_STEP_EVENT = "digichat:boot-step";
+
+/**
+ * Real boot milestones the app reports.
+ * `services` lands once every sleep-on-idle backend the chat needs has
+ * answered its warm-up probe. The iframe host reports that step.
+ */
+export type DigichatBootStep = "config" | "runtime" | "services";
+
+/** Report a real boot milestone for this document (idempotent per step). */
+export function signalDigichatBootStep(step: DigichatBootStep): void {
+  if (typeof document === "undefined") return;
+  const root = document.documentElement;
+  const done = root.dataset.digichatBootSteps?.split(",") ?? [];
+  if (done.includes(step)) return;
+  root.dataset.digichatBootSteps = [...done, step].join(",");
+  window.dispatchEvent(
+    new CustomEvent(DIGI_CHAT_BOOT_STEP_EVENT, { detail: step }),
+  );
+}
+
+/** Boot milestones already reported in this document. */
+export function digichatBootSteps(): readonly string[] {
+  if (typeof document === "undefined") return [];
+  return document.documentElement.dataset.digichatBootSteps?.split(",") ?? [];
+}
+
+/** Milliseconds since this document started loading (boot clock). */
+export function digichatBootClockMs(): number {
+  return typeof performance === "undefined" ? 0 : performance.now();
+}
+
+/**
+ * Lab switch: `?handoff=` picks how the boot hands off to the chat.
+ * Comma-separated: `reveal` (re-run the hero entrance), `type` (welcome
+ * takeover), `drift` (motion match), `beat` (pause before the fade).
+ */
+export type DigichatHandoff = {
+  reveal: boolean;
+  type: boolean;
+  drift: boolean;
+  beat: boolean;
+};
+
+/**
+ * Parse the `?handoff=` lab switch. The reveal hand-off ships by default;
+ * `?handoff=none` (or `off`) restores the hard cut, and any other comma list
+ * opts into exactly those modes.
+ */
+export function resolveHandoff(): DigichatHandoff {
+  const off: DigichatHandoff = {
+    reveal: false,
+    type: false,
+    drift: false,
+    beat: false,
+  };
+  if (typeof window === "undefined") return off;
+  const raw = new URLSearchParams(window.location.search).get("handoff");
+  if (raw === null) return { ...off, reveal: true };
+  const modes = new Set(
+    raw
+      .split(",")
+      .map((mode) => mode.trim())
+      .filter(Boolean),
+  );
+  if (modes.has("none") || modes.has("off")) return off;
+  return {
+    reveal: modes.has("reveal"),
+    type: modes.has("type"),
+    drift: modes.has("drift"),
+    beat: modes.has("beat"),
+  };
+}
+
+/**
+ * Service warm-up phase (sleep-on-idle backends). The app sets it while it
+ * waits for /api/embed/warmup; the boot loader and the assistant pending row
+ * read it to say "Waking up services…" instead of a separate banner.
+ */
+export type DigichatWarmupPhase = "idle" | "waking" | "ready" | "error";
+export const DIGI_CHAT_WARMUP_EVENT = "digichat:warmup";
+
+export function setDigichatWarmupPhase(phase: DigichatWarmupPhase): void {
+  if (typeof document === "undefined") return;
+  const root = document.documentElement;
+  if (root.dataset.digichatWarmup === phase) return;
+  root.dataset.digichatWarmup = phase;
+  window.dispatchEvent(new CustomEvent(DIGI_CHAT_WARMUP_EVENT, { detail: phase }));
+}
+
+export function getDigichatWarmupPhase(): DigichatWarmupPhase {
+  if (typeof document === "undefined") return "idle";
+  return (document.documentElement.dataset.digichatWarmup as DigichatWarmupPhase) || "idle";
+}

package/src/components/chat/chat-surfaces.ts

@@ -0,0 +1,52 @@
+/**
+ * Surface class strings for the first-party digichat Thread — the digiweb analog
+ * of assistant-ui `surfaces.tsx`. Paper / field / live / mono / code sit on
+ * `[data-theme]` + `--term-*` + rose livery (see styles/chat-aui.css). No pills.
+ */
+
+export const DIGICHAT_GLYPHS = {
+  user: ">",
+  assistant: "▸",
+  system: "·",
+} as const;
+
+export const digichatSurfaces = {
+  thread:
+    "digichat-thread aui-root aui-thread-root flex h-full min-h-0 flex-col bg-term-bg font-mono text-term-ink",
+  viewport:
+    "digichat-thread__viewport flex min-h-0 flex-1 flex-col gap-[0.55rem] overflow-y-auto overscroll-contain px-[0.9rem] pt-[0.75rem] pb-[0.85rem]",
+  footer:
+    "digichat-thread__footer aui-thread-viewport-footer sticky bottom-0 mt-auto flex flex-col gap-[0.4rem] bg-term-bg pt-[0.35rem] pb-[0.35rem]",
+  empty: "digichat-thread__empty aui-thread-empty flex flex-col gap-[0.7rem]",
+  welcome: "aui-thread-welcome-root flex flex-col gap-[0.45rem]",
+  welcomeTitle:
+    "aui-thread-welcome-message-inner m-0 max-w-[36rem] font-mono text-[1.05rem] font-normal leading-[1.4] tracking-[-0.02em] text-term-ink",
+  welcomeBody:
+    "aui-thread-welcome-copy m-0 max-w-[46ch] font-mono text-[0.82rem] font-normal leading-[1.45] text-term-mute",
+  examples: "aui-thread-welcome-suggestions flex flex-col gap-[0.1rem]",
+  example:
+    "digichat-example aui-thread-welcome-suggestion grid cursor-pointer grid-cols-[1.25rem_minmax(0,1fr)] items-baseline gap-x-[0.55rem] rounded-none border-0 bg-transparent px-0 py-[0.15rem] text-left font-mono text-[0.82rem] text-ink-soft",
+  exampleMark: "select-none font-mono text-[0.88rem] leading-[1.45] text-term-ink",
+  turn: "digichat-turn flex flex-col items-stretch gap-[0.2rem]",
+  composer:
+    "digichat-composer aui-composer-root flex flex-col gap-[0.35rem] rounded-none border border-hair bg-transparent px-[0.75rem] pt-[0.55rem] pb-[0.45rem]",
+  composerRow: "flex items-start gap-[0.55rem]",
+  composerGlyph: "shrink-0 select-none font-mono text-[0.9rem] leading-[1.5] text-ink",
+  composerInput:
+    "aui-composer-input min-h-[1.5rem] w-full resize-none border-0 bg-transparent font-mono text-[0.9rem] leading-[1.5] text-ink outline-none",
+  composerTray: "flex items-center justify-between gap-[0.75rem]",
+  action:
+    "digichat-action inline-flex cursor-pointer items-center rounded-none border-0 bg-transparent p-0 font-mono text-[0.66rem] tracking-[0.02em] text-ink-mute",
+  actionRow:
+    "digichat-action-row mt-[0.25rem] ml-[1.8rem] flex flex-wrap items-center gap-[0.75rem]",
+  send: "aui-composer-send inline-flex h-8 cursor-pointer items-center justify-center rounded-none font-mono text-[0.72rem]",
+  stop: "inline-flex h-8 cursor-pointer items-center justify-center rounded-none border border-hair bg-transparent px-[0.85rem] font-mono text-[0.72rem] text-ink",
+  scrollBtn:
+    "digichat-scroll-btn mx-auto cursor-pointer rounded-none border border-hair bg-surface px-[0.6rem] py-[0.2rem] font-mono text-[0.66rem] text-ink-mute",
+  attach: "digichat-attach inline-flex items-center gap-[0.35rem] border border-hair px-[0.45rem] py-[0.15rem] font-mono text-[0.66rem] text-ink-soft",
+  error: "ml-[1.8rem] mt-[0.35rem] border border-danger/40 px-[0.7rem] py-[0.4rem] font-mono text-[0.78rem] text-danger",
+  list: "digichat-thread-list flex w-56 shrink-0 flex-col border-r border-term-hair bg-term-bg font-mono",
+  listItem:
+    "digichat-thread-list__item block h-7 w-full truncate rounded-none border-0 bg-transparent px-[0.7rem] py-0 text-left font-mono text-[0.75rem] leading-7 text-term-ink data-[active]:bg-term-fill",
+  pane: "flex h-full min-h-0 flex-col rounded-none border border-term-hair bg-term-bg",
+} as const;

package/src/components/chat/connection-status.ts

@@ -0,0 +1,40 @@
+/**
+ * The pre-response status line (DIG-4459).
+ *
+ * Before the agent answers, the loading row shows the animation on its own.
+ * It carries text only when the server actually told us something: a
+ * `data-connection` part with a `message` ("Waking up services…", "Waiting
+ * for model capacity — retrying in 8s"). A bare state such as `connecting`
+ * is just the wait for a response, so it gets no text, and the client never
+ * makes up a default line of its own.
+ */
+type MessagePartLike = {
+  readonly type: string;
+  readonly name?: string;
+  readonly data?: unknown;
+};
+
+/** States that end the pre-response phase: any earlier message is stale. */
+const SETTLED_STATES = new Set(["connected", "ready"]);
+
+/**
+ * The status text the server sent for this turn, or null. The latest
+ * connection part wins; a settled state clears the line.
+ */
+export function connectionStatusText(
+  parts: readonly MessagePartLike[],
+): string | null {
+  let text: string | null = null;
+  for (const part of parts) {
+    if (part.type !== "data" || part.name !== "connection") continue;
+    const data = (part.data ?? {}) as { state?: unknown; message?: unknown };
+    if (typeof data.state === "string" && SETTLED_STATES.has(data.state)) {
+      text = null;
+      continue;
+    }
+    const message =
+      typeof data.message === "string" ? data.message.trim() : "";
+    text = message.length > 0 ? message : null;
+  }
+  return text;
+}

package/src/components/chat/digichat-wordmark.ts

@@ -0,0 +1,355 @@
+/**
+ * DIGICHAT block wordmark.
+ *
+ * Glyph cells are 7×10. A terminal cell is about twice as tall as it is wide,
+ * so the TUI draws with half-blocks (▀ ▄ █), the same method as
+ * digivoice/tui/src/hero.js. D, I, G, C, H, and T are that file's bitmaps.
+ * Gaps stay empty. One color mode per cell: 38;2 only when truecolor is on,
+ * otherwise 38;5. Never both.
+ *
+ * The settled word is the mark. The scramble plays once per session, then one
+ * letter flashes. It does not loop.
+ */
+
+export const WORD = "DIGICHAT";
+export const STEP_MS = 80;
+export const SPIN_MS = 240;
+export const LOCK_MS = 180;
+export const HOLD_MS = 960;
+export const FLASH_MS = 200;
+/** SPIN + 8 * LOCK + HOLD = 2.64s. */
+export const CYCLE_MS = SPIN_MS + 8 * LOCK_MS + HOLD_MS;
+/** Inside the hold, after the last lock flash. */
+export const SETTLED_MS = 2000;
+/** Quiet stretch between single-letter flashes after the scramble. */
+export const IDLE_GAP_MS = 6400;
+export const WORDMARK_SESSION_KEY = "digichat:wordmark-played";
+export const WORDMARK_CLOCK_HOST = "__digichatWordmarkClock";
+
+export const POOL = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!?#$%&*+-=/<>().,:;@";
+
+export const SHADES = {
+  dim: { rgb: 95, cube: 59 },
+  rest: { rgb: 215, cube: 188 },
+  flash: { rgb: 255, cube: 231 },
+} as const;
+
+export type ShadeName = keyof typeof SHADES;
+export type CellColor = { rgb: number } | { cube: number };
+
+export type WordCell = {
+  ch: string;
+  color: CellColor | null;
+};
+
+export type SlotFrame = {
+  ch: string | null;
+  shade: ShadeName;
+};
+
+const GLYPHS: Record<string, readonly string[]> = {
+  A: ["..###..", ".#####.", "##...##", "##...##", "#######", "#######", "##...##", "##...##", "##...##", "##...##"],
+  B: ["######.", "#######", "##...##", "##...##", "######.", "######.", "##...##", "##...##", "#######", "######."],
+  C: [".#####.", "#######", "##.....", "##.....", "##.....", "##.....", "##.....", "##.....", "#######", ".#####."],
+  D: ["######.", "#######", "##...##", "##...##", "##...##", "##...##", "##...##", "##...##", "#######", "######."],
+  E: ["#######", "#######", "##.....", "##.....", "######.", "######.", "##.....", "##.....", "#######", "#######"],
+  F: ["#######", "#######", "##.....", "##.....", "######.", "######.", "##.....", "##.....", "##.....", "##....."],
+  G: [".#####.", "#######", "##.....", "##.....", "##..###", "##..###", "##...##", "##...##", "#######", ".#####."],
+  H: ["##...##", "##...##", "##...##", "##...##", "#######", "#######", "##...##", "##...##", "##...##", "##...##"],
+  I: ["#######", "#######", "..##...", "..##...", "..##...", "..##...", "..##...", "..##...", "#######", "#######"],
+  J: ["...####", "...####", ".....##", ".....##", ".....##", ".....##", "##...##", "##...##", "#######", ".#####."],
+  K: ["##...##", "##..##.", "##.##..", "####...", "###....", "####...", "##.##..", "##..##.", "##...##", "##...##"],
+  L: ["##.....", "##.....", "##.....", "##.....", "##.....", "##.....", "##.....", "##.....", "#######", "#######"],
+  M: ["##...##", "###.###", "##.#.##", "##.#.##", "##...##", "##...##", "##...##", "##...##", "##...##", "##...##"],
+  N: ["##...##", "###..##", "###..##", "##.#.##", "##.#.##", "##..###", "##..###", "##...##", "##...##", "##...##"],
+  O: [".#####.", "#######", "##...##", "##...##", "##...##", "##...##", "##...##", "##...##", "#######", ".#####."],
+  P: ["######.", "#######", "##...##", "##...##", "#######", "######.", "##.....", "##.....", "##.....", "##....."],
+  Q: [".#####.", "#######", "##...##", "##...##", "##...##", "##.#.##", "##..##.", "##...##", "#######", ".####.#"],
+  R: ["######.", "#######", "##...##", "##...##", "#######", "######.", "##.##..", "##..##.", "##...##", "##...##"],
+  S: [".######", "#######", "##.....", "##.....", "######.", "######.", ".....##", ".....##", "#######", "######."],
+  T: ["#######", "#######", "...##..", "...##..", "...##..", "...##..", "...##..", "...##..", "...##..", "...##.."],
+  U: ["##...##", "##...##", "##...##", "##...##", "##...##", "##...##", "##...##", "##...##", "#######", ".#####."],
+  V: ["##...##", "##...##", "##...##", "##...##", "##...##", "##...##", "##...##", "##...##", ".#####.", "..###.."],
+  W: ["##...##", "##...##", "##...##", "##...##", "##.#.##", "##.#.##", "##.#.##", "###.###", ".#####.", ".##.##."],
+  X: ["##...##", "##...##", ".##.##.", "..###..", "..###..", "..###..", ".##.##.", "##...##", "##...##", "##...##"],
+  Y: ["##...##", "##...##", "##...##", ".##.##.", "..###..", "...##..", "...##..", "...##..", "...##..", "...##.."],
+  Z: ["#######", "#######", ".....##", "....##.", "...##..", "..##...", ".##....", "##.....", "#######", "#######"],
+  "0": [".#####.", "#######", "##...##", "##..###", "##.#.##", "###..##", "##...##", "##...##", "#######", ".#####."],
+  "1": ["..##...", ".###...", "####...", "..##...", "..##...", "..##...", "..##...", "..##...", "#######", "#######"],
+  "2": [".#####.", "#######", ".....##", ".....##", ".#####.", "#####..", "##.....", "##.....", "#######", "#######"],
+  "3": [".#####.", "#######", ".....##", ".....##", "..####.", "..####.", ".....##", ".....##", "#######", ".#####."],
+  "4": ["...##..", "..###..", ".#.##..", "##.##..", "##.##..", "#######", "#######", "...##..", "...##..", "...##.."],
+  "5": ["#######", "#######", "##.....", "##.....", "######.", ".######", ".....##", ".....##", "#######", "######."],
+  "6": [".#####.", "#######", "##.....", "##.....", "######.", "#######", "##...##", "##...##", "#######", ".#####."],
+  "7": ["#######", "#######", ".....##", "....##.", "...##..", "..##...", "..##...", "..##...", "..##...", "..##..."],
+  "8": [".#####.", "#######", "##...##", "##...##", ".#####.", ".#####.", "##...##", "##...##", "#######", ".#####."],
+  "9": [".#####.", "#######", "##...##", "##...##", "#######", ".######", ".....##", ".....##", "#######", ".#####."],
+  "!": ["..##...", "..##...", "..##...", "..##...", "..##...", "..##...", ".......", "..##...", "..##...", "......."],
+  "?": [".#####.", "#######", "##...##", "....##.", "...##..", "..##...", ".......", "..##...", "..##...", "......."],
+  "#": [".##.##.", ".##.##.", "#######", "#######", ".##.##.", ".##.##.", "#######", "#######", ".##.##.", ".##.##."],
+  $: ["..##...", ".######", "##.##..", "##.....", ".#####.", ".....##", "..##.##", "######.", "..##...", "..##..."],
+  "%": ["##...##", "##..##.", "##.##..", "##.#...", "..##...", "...#.##", "..##.##", ".##..##", "##...##", "##...##"],
+  "&": [".##....", "###....", "##.....", ".####..", "##..##.", "##..##.", "##..##.", "##..##.", ".####.#", "..##.##"],
+  "*": [".......", "##...##", ".##.##.", "..###..", "#######", "..###..", ".##.##.", "##...##", ".......", "......."],
+  "+": [".......", "..##...", "..##...", "..##...", "#######", "#######", "..##...", "..##...", "..##...", "......."],
+  "-": [".......", ".......", ".......", ".......", "#######", "#######", ".......", ".......", ".......", "......."],
+  "=": [".......", ".......", "#######", "#######", ".......", ".......", "#######", "#######", ".......", "......."],
+  "/": [".....##", "....##.", "....##.", "...##..", "...##..", "..##...", "..##...", ".##....", ".##....", "##....."],
+  "<": ["....##.", "...##..", "..##...", ".##....", "##.....", "##.....", ".##....", "..##...", "...##..", "....##."],
+  ">": [".##....", "..##...", "...##..", "....##.", ".....##", ".....##", "....##.", "...##..", "..##...", ".##...."],
+  "(": ["...##..", "..##...", ".##....", "##.....", "##.....", "##.....", "##.....", ".##....", "..##...", "...##.."],
+  ")": ["..##...", "...##..", "....##.", ".....##", ".....##", ".....##", ".....##", "....##.", "...##..", "..##..."],
+  ".": [".......", ".......", ".......", ".......", ".......", ".......", ".......", "..##...", "..##...", "......."],
+  ",": [".......", ".......", ".......", ".......", ".......", ".......", "..##...", "..##...", "...##..", "..##..."],
+  ":": [".......", "..##...", "..##...", ".......", ".......", ".......", "..##...", "..##...", ".......", "......."],
+  ";": [".......", "..##...", "..##...", ".......", ".......", "..##...", "..##...", "...##..", "..##...", "......."],
+  "@": [".#####.", "##...##", "##.###.", "##.#.##", "##.#.##", "##.###.", "##.....", "##...##", ".#####.", "......."],
+};
+
+export function glyphOf(ch: string): readonly string[] | null {
+  return GLYPHS[ch] ?? null;
+}
+
+export function letterGap(cols: number, letters: number): number {
+  for (const gap of [2, 1, 0]) {
+    const width = letters * 7 + Math.max(0, letters - 1) * gap;
+    if (width <= Math.max(1, cols - 2)) return gap;
+  }
+  return 0;
+}
+
+export function truecolorEnabled(colorterm: string | undefined): boolean {
+  const value = (colorterm ?? "").toLowerCase();
+  return value === "truecolor" || value === "24bit";
+}
+
+function mod(tMs: number, cycle: number): number {
+  const t = Number.isFinite(tMs) ? Math.floor(tMs) : 0;
+  return ((t % cycle) + cycle) % cycle;
+}
+
+function poolChar(slot: number, step: number): string | null {
+  let x = Math.imul(step + 1, 0x9e3779b1) ^ Math.imul(slot + 1, 0x85ebca6b);
+  x = Math.imul(x ^ (x >>> 16), 0x7feb352d);
+  x = (x ^ (x >>> 15)) >>> 0;
+  for (let i = 0; i < POOL.length; i += 1) {
+    const ch = POOL[(x + i) % POOL.length];
+    if (ch && GLYPHS[ch]) return ch;
+  }
+  return null;
+}
+
+export function slotsAt(tMs: number, word = WORD): SlotFrame[] {
+  const letters = word.toUpperCase();
+  const t = mod(tMs, CYCLE_MS);
+  const frames: SlotFrame[] = [];
+  for (let slot = 0; slot < letters.length; slot += 1) {
+    const letter = letters[slot] ?? "";
+    const lockAt = SPIN_MS + slot * LOCK_MS;
+    if (t < lockAt) {
+      frames.push({ ch: poolChar(slot, Math.floor(t / STEP_MS)), shade: "dim" });
+      continue;
+    }
+    const known = Boolean(GLYPHS[letter]);
+    const shade: ShadeName = t < lockAt + FLASH_MS ? "flash" : "rest";
+    frames.push({ ch: known ? letter : null, shade });
+  }
+  return frames;
+}
+
+/** Settled word. One letter flashes, then the word rests. Characters never scramble. */
+export function idleSlots(idleElapsed: number, word = WORD): SlotFrame[] {
+  const base = slotsAt(SETTLED_MS, word);
+  const span = IDLE_GAP_MS + FLASH_MS;
+  const elapsed = Number.isFinite(idleElapsed) ? Math.max(0, idleElapsed) : 0;
+  if (elapsed % span < IDLE_GAP_MS) return base;
+  const index = Math.floor(elapsed / span) % Math.max(1, base.length);
+  return base.map((slot, i) => (i === index ? { ch: slot.ch, shade: "flash" } : slot));
+}
+
+/**
+ * One scramble from t=0 when `full` is set. After CYCLE_MS, or when `full` is
+ * clear, only the idle flash remains.
+ */
+export function heroSlots(elapsedMs: number, full: boolean, word = WORD): SlotFrame[] {
+  const elapsed = Number.isFinite(elapsedMs) ? Math.max(0, elapsedMs) : 0;
+  if (full && elapsed < CYCLE_MS) return slotsAt(elapsed, word);
+  return idleSlots(full ? elapsed - CYCLE_MS : elapsed, word);
+}
+
+export type WordmarkStore = {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+};
+
+export type WordmarkClock = { origin: number; full: boolean };
+
+/** First call in a tab plays the scramble and records it. A later call does not. */
+export function readFullPlay(store: WordmarkStore | null): boolean {
+  if (!store) return true;
+  try {
+    if (store.getItem(WORDMARK_SESSION_KEY) === "1") return false;
+    store.setItem(WORDMARK_SESSION_KEY, "1");
+    return true;
+  } catch {
+    return true;
+  }
+}
+
+export function ensureWordmarkClock(
+  now: number,
+  store: WordmarkStore | null,
+  current: WordmarkClock | null,
+): WordmarkClock {
+  if (current) return current;
+  return { origin: now, full: readFullPlay(store) };
+}
+
+export function wordmarkSample(now: number, clock: WordmarkClock): { elapsed: number; full: boolean } {
+  return { elapsed: Math.max(0, now - clock.origin), full: clock.full };
+}
+
+function colorOf(shade: ShadeName, truecolor: boolean): CellColor {
+  const tone = SHADES[shade];
+  return truecolor ? { rgb: tone.rgb } : { cube: tone.cube };
+}
+
+type Pixel = { on: boolean; shade: ShadeName | null };
+
+function gridFor(frames: readonly SlotFrame[], gap: number): Pixel[][] {
+  const rows: Pixel[][] = Array.from({ length: 10 }, () => []);
+  let drawn = 0;
+  for (const frame of frames) {
+    const glyph = frame.ch ? GLYPHS[frame.ch] : undefined;
+    if (!glyph) continue;
+    if (drawn > 0) {
+      for (const row of rows) {
+        for (let g = 0; g < gap; g += 1) row.push({ on: false, shade: null });
+      }
+    }
+    for (let y = 0; y < 10; y += 1) {
+      const line = glyph[y] ?? ".......";
+      for (const mark of line) rows[y]?.push({ on: mark === "#", shade: frame.shade });
+    }
+    drawn += 1;
+  }
+  return rows;
+}
+
+const BLANK: WordCell = { ch: " ", color: null };
+
+function linesFor(
+  frames: readonly SlotFrame[],
+  { cols = 100, truecolor = false, gap }: { cols?: number; truecolor?: boolean; gap?: number } = {},
+): { lines: WordCell[][]; gap: number; rows: number } {
+  const count = frames.filter((frame) => frame.ch && GLYPHS[frame.ch]).length;
+  const usedGap = gap ?? letterGap(cols, Math.max(1, count));
+  const grid = gridFor(frames, count > 1 ? usedGap : 0);
+  const width = grid[0]?.length ?? 0;
+  if (width === 0) {
+    return { lines: Array.from({ length: 5 }, () => [{ ...BLANK }]), gap: usedGap, rows: 5 };
+  }
+  const lines: WordCell[][] = [];
+  for (let y = 0; y < 10; y += 2) {
+    const cells: WordCell[] = [];
+    for (let x = 0; x < width; x += 1) {
+      const top = grid[y]?.[x];
+      const bot = grid[y + 1]?.[x];
+      const topOn = top?.on === true;
+      const botOn = bot?.on === true;
+      if (!topOn && !botOn) {
+        cells.push({ ...BLANK });
+        continue;
+      }
+      let ch = "▄";
+      let shade = bot?.shade ?? top?.shade ?? "rest";
+      if (topOn && botOn) {
+        ch = "█";
+        shade = top?.shade ?? shade;
+      } else if (topOn) {
+        ch = "▀";
+        shade = top?.shade ?? shade;
+      }
+      cells.push({ ch, color: colorOf(shade, truecolor) });
+    }
+    lines.push(cells);
+  }
+  return { lines, gap: usedGap, rows: lines.length };
+}
+
+export function wordmarkLines(
+  word = WORD,
+  { cols = 100, tMs = SETTLED_MS, truecolor = false, gap }: {
+    cols?: number;
+    tMs?: number;
+    truecolor?: boolean;
+    gap?: number;
+  } = {},
+): { lines: WordCell[][]; gap: number; rows: number } {
+  return linesFor(slotsAt(tMs, word), { cols, truecolor, gap });
+}
+
+export function heroWordmarkLines(
+  word = WORD,
+  { cols = 100, elapsed = 0, full = false, truecolor = false, gap }: {
+    cols?: number;
+    elapsed?: number;
+    full?: boolean;
+    truecolor?: boolean;
+    gap?: number;
+  } = {},
+): { lines: WordCell[][]; gap: number; rows: number } {
+  return linesFor(heroSlots(elapsed, full, word), { cols, truecolor, gap });
+}
+
+export type WordPixel = { x: number; y: number; shade: ShadeName };
+
+function pixelsFor(frames: readonly SlotFrame[], gap: number): { pixels: WordPixel[]; width: number; height: number } {
+  const pixels: WordPixel[] = [];
+  let cursor = 0;
+  let drawn = 0;
+  for (const frame of frames) {
+    const glyph = frame.ch ? GLYPHS[frame.ch] : undefined;
+    if (!glyph) continue;
+    if (drawn > 0) cursor += gap;
+    for (let y = 0; y < 10; y += 1) {
+      const line = glyph[y] ?? "";
+      for (let x = 0; x < line.length; x += 1) {
+        if (line[x] === "#") pixels.push({ x: cursor + x, y, shade: frame.shade });
+      }
+    }
+    cursor += 7;
+    drawn += 1;
+  }
+  return { pixels, width: Math.max(cursor, 0), height: 10 };
+}
+
+export function wordmarkPixels(
+  tMs = SETTLED_MS,
+  { word = WORD, gap = 1 }: { word?: string; gap?: number } = {},
+): { pixels: WordPixel[]; width: number; height: number } {
+  return pixelsFor(slotsAt(tMs, word), gap);
+}
+
+export function heroWordmarkPixels(
+  elapsed = 0,
+  full = false,
+  { word = WORD, gap = 1 }: { word?: string; gap?: number } = {},
+): { pixels: WordPixel[]; width: number; height: number } {
+  return pixelsFor(heroSlots(elapsed, full, word), gap);
+}
+
+export function shadeHex(shade: ShadeName): string {
+  const channel = SHADES[shade].rgb.toString(16).padStart(2, "0");
+  return `#${channel}${channel}${channel}`;
+}
+
+/** One SGR color selector. A cell never carries both 38;5 and 38;2. */
+export function cellSgr(cell: WordCell): string {
+  if (!cell.color) return "";
+  if ("rgb" in cell.color) {
+    const n = cell.color.rgb;
+    return `38;2;${n};${n};${n}`;
+  }
+  return `38;5;${cell.color.cube}`;
+}

package/src/components/chat/disclosure-chevron.tsx

@@ -0,0 +1,49 @@
+"use client";
+
+import { DotMatrix } from "./DotMatrix";
+
+/**
+ * The one caret for every collapsible row in the trace.
+ *
+ * The same square pixel chevron as the mark beside a user message
+ * (`DotMatrix` state `user`), in the 0.55rem box the trace caret had before.
+ * Closed, it points right. Open, the skin stylesheet rotates the cube svg
+ * 90° so it points down. The rotate is on `dot-matrix-grid` only — never
+ * this wrapper, the trigger, or the label. The glyph is decorative: every
+ * trigger it sits in is named by its visible text (DIG-4669), and the open
+ * state is the trigger's `aria-expanded`. The caret is a direct child of its
+ * trigger, and the rotation follows that trigger:
+ * `aria-expanded` and `data-panel-open` (Base UI) or `data-state="open"`
+ * (Radix). An open ancestor — the work chain's `data-open` — does not
+ * rotate the closed rows inside it.
+ */
+/**
+ * The turn as Tailwind utilities, so it holds in every host that scans this
+ * package (stock skins and the baseline catalog load no chat stylesheet). The
+ * DigiChat sheets repeat the same rotate with their own transition.
+ */
+export const TURN = [
+  "aui-disclosure-chevron",
+  "[&_[data-slot=dot-matrix-grid]]:transition-transform",
+  "motion-reduce:[&_[data-slot=dot-matrix-grid]]:transition-none",
+  "[[aria-expanded=true]>&_[data-slot=dot-matrix-grid]]:[transform:rotate(90deg)]",
+  "[[data-panel-open]>&_[data-slot=dot-matrix-grid]]:[transform:rotate(90deg)]",
+].join(" ");
+
+export function DisclosureChevron() {
+  return (
+    <span
+      data-slot="disclosure-chevron"
+      className={TURN}
+      style={{
+        position: "relative",
+        display: "inline-flex",
+        width: "0.55rem",
+        height: "0.55rem",
+        flex: "0 0 0.55rem",
+      }}
+    >
+      <DotMatrix state="user" decorative className="!size-[0.55rem]" />
+    </span>
+  );
+}

package/src/components/chat/followable-href.ts

@@ -0,0 +1,9 @@
+/**
+ * Citation links (DIG-3269): a non-web source (repo://, vault path) reaches the
+ * renderer with its href emptied by the sanitizer, and <a href=""> would reload
+ * the embed itself, query string included. Only these hrefs are links.
+ */
+export function isFollowableHref(href: string | undefined): boolean {
+  if (!href) return false;
+  return /^(https?:|mailto:|#|\/(?!\/))/i.test(href.trim());
+}