@elabs-ai/components-ui 4.0.0 → 4.1.0

package/src/lib/check-result.ts

@@ -0,0 +1,33 @@
+/**
+ * One verification verdict about an action — a linter, a type check, a test run,
+ * a policy hook. Shared vocabulary across packages: `ChangeReview` (#112) shows the
+ * checks a proposed edit already passed, `AgentEvent` (#109) shows the checks a
+ * runtime hook ran around a tool call. One runtime concept, one shape.
+ *
+ * Presentational only (D5): this type records a verdict someone else computed.
+ * Nothing in brand-ui ever runs a check.
+ *
+ * Rendering contract, binding on every consumer: `ok` must reach the user through
+ * an ICON and ACCESSIBLE TEXT, never through colour alone — the greyscale test in
+ * `.claude/rules/accessibility.md`.
+ */
+export interface CheckResult {
+  /** What ran, verbatim as the runtime names it: "eslint", "tsc", "pre_tool_use". */
+  label: string;
+  /** Did it pass? The verdict; the only required field besides `label`. */
+  ok: boolean;
+  /** One line of explanation. Renders as a secondary line, collapsed when long. */
+  detail?: string;
+  /** Wall-clock duration in milliseconds. Format with `formatElapsed`. */
+  durationMs?: number;
+  /** When it ran relative to the action it gates. Groups results into sections. */
+  phase?: "before" | "after";
+}
+
+/** A count summary, when the individual verdicts are not available. */
+export interface CheckSummary {
+  /** How many checks ran. */
+  ran: number;
+  /** How many of them passed. `passed <= ran`. */
+  passed: number;
+}

package/src/lib/diff-line.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import { diffLineAccessibleLabel, diffLineMarker, type DiffLineType } from "./diff-line";
+
+describe("diffLineMarker", () => {
+  it.each([
+    ["add", "+"],
+    ["del", "−"],
+    ["context", " "],
+    ["hunk", ""],
+    ["meta", ""],
+  ] as const)("returns %s's marker as %s", (type, expected) => {
+    expect(diffLineMarker(type)).toBe(expected);
+  });
+
+  it("uses a NO-BREAK SPACE (U+00A0) for context, not a plain space — must survive JSX/HTML whitespace collapsing", () => {
+    expect(diffLineMarker("context")).toBe(" ");
+    expect(diffLineMarker("context").charCodeAt(0)).toBe(0xa0);
+  });
+});
+
+describe("diffLineAccessibleLabel", () => {
+  it("returns the added-line key for an add row", () => {
+    expect(diffLineAccessibleLabel("add")).toBe("ai.diffView.addedLine");
+  });
+
+  it("returns the removed-line key for a del row", () => {
+    expect(diffLineAccessibleLabel("del")).toBe("ai.diffView.removedLine");
+  });
+
+  it.each(["context", "hunk", "meta"] as DiffLineType[])(
+    "returns undefined for %s (no polarity)",
+    (type) => {
+      expect(diffLineAccessibleLabel(type)).toBeUndefined();
+    },
+  );
+});

package/src/lib/diff-line.ts

@@ -0,0 +1,63 @@
+/**
+ * The unified-diff line model behind `DiffView` (`@elabs-ai/components-ai`,
+ * #102) and the terminal CLI look-alike family's own diff hunk (issue #117).
+ *
+ * Promoted here (not duplicated) because `@elabs-ai/components-ai` and
+ * `@elabs-ai/components-terminal` are layer-2 DAG SIBLINGS and may not import
+ * each other — `ui` is upstream of both
+ * (docs/decisions/2026-09-01-brainless-adoption-architecture.md § 4). This
+ * module is the shiki-free half: the line shape, the marker glyph and the
+ * screen-reader polarity label. Intra-line syntax highlighting (Shiki) and
+ * the diff's presentational chrome stay in `@elabs-ai/components-ai`'s
+ * `diff-view.tsx` — `ui` does not depend on Shiki and never will for one
+ * component (see the decision doc § 3).
+ *
+ * The `DiffLine` model and the polarity-prefix technique are adapted from
+ * `theswerd/brainless` (MIT) — see `ATTRIBUTION.md`.
+ */
+
+/** What role a line plays in the diff. */
+export type DiffLineType = "add" | "del" | "context" | "hunk" | "meta";
+
+/** One line of a unified diff. Absent gutter numbers are load-bearing (see below). */
+export interface DiffLine {
+  type: DiffLineType;
+  /** Line number in the original file. Absent on `add` — there is no old line. */
+  oldNumber?: number;
+  /** Line number in the new file. Absent on `del` — there is no new line. */
+  newNumber?: number;
+  /** The line's text, without its leading `+` / `-` / ` ` marker. */
+  text: string;
+}
+
+/**
+ * The single-character marker glyph for a real source line (`add`/`del`/
+ * `context`). `hunk`/`meta` lines are diff headers, not source, and render
+ * through a full-width row instead — this returns `""` for them.
+ */
+export function diffLineMarker(type: DiffLineType): string {
+  switch (type) {
+    case "add":
+      return "+";
+    case "del":
+      return "−";
+    case "context":
+      return " ";
+    default:
+      return "";
+  }
+}
+
+/**
+ * The `ui` locale-message KEY (not the translated text) for the `sr-only`
+ * screen-reader polarity word an `add`/`del` row carries ALONGSIDE its marker
+ * glyph and its fill tint — colour is never the only channel (WCAG 1.4.1).
+ * `undefined` for `context`/`hunk`/`meta`, which carry no polarity.
+ */
+export function diffLineAccessibleLabel(
+  type: DiffLineType,
+): "ai.diffView.addedLine" | "ai.diffView.removedLine" | undefined {
+  if (type === "add") return "ai.diffView.addedLine";
+  if (type === "del") return "ai.diffView.removedLine";
+  return undefined;
+}

package/src/lib/diff-rows.test.ts

@@ -0,0 +1,76 @@
+import { act, renderHook } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import type { DiffLine } from "./diff-line";
+import { collapseDiffRows, useDiffRows } from "./diff-rows";
+
+function contextLine(index: number): DiffLine {
+  return { type: "context", oldNumber: index, newNumber: index, text: `line ${index}` };
+}
+
+describe("collapseDiffRows", () => {
+  it("renders every line when contextLines is undefined", () => {
+    const lines = Array.from({ length: 5 }, (_, i) => contextLine(i));
+    const rows = collapseDiffRows(lines, undefined);
+    expect(rows).toHaveLength(5);
+    expect(rows.every((row) => row.kind === "line")).toBe(true);
+  });
+
+  it("does not collapse a run at or below the threshold", () => {
+    const lines = Array.from({ length: 4 }, (_, i) => contextLine(i));
+    const rows = collapseDiffRows(lines, 4);
+    expect(rows).toHaveLength(4);
+    expect(rows.every((row) => row.kind === "line")).toBe(true);
+  });
+
+  it("collapses a run longer than contextLines, keeping top and bottom context", () => {
+    const lines = Array.from({ length: 10 }, (_, i) => contextLine(i));
+    const rows = collapseDiffRows(lines, 4);
+    // top=2, bottom=2, collapsed hiddenCount = 10 - 2 - 2 = 6. `runStart` is the
+    // run's OWN start index (0 — the whole 10-line run is one context block),
+    // not the index of the first hidden line — it is the key `expand()` takes.
+    expect(rows.map((row) => row.kind)).toEqual(["line", "line", "collapsed", "line", "line"]);
+    const collapsed = rows.find((row) => row.kind === "collapsed");
+    expect(collapsed).toMatchObject({ kind: "collapsed", runStart: 0, hiddenCount: 6 });
+  });
+
+  it("renders a run in full when its start index is in `expanded`", () => {
+    const lines = Array.from({ length: 10 }, (_, i) => contextLine(i));
+    const rows = collapseDiffRows(lines, 4, new Set([0]));
+    expect(rows).toHaveLength(10);
+    expect(rows.every((row) => row.kind === "line")).toBe(true);
+  });
+
+  it("does not collapse non-context lines flanking a run", () => {
+    const lines: DiffLine[] = [
+      { type: "add", newNumber: 1, text: "added" },
+      ...Array.from({ length: 8 }, (_, i) => contextLine(i)),
+      { type: "del", oldNumber: 99, text: "removed" },
+    ];
+    const rows = collapseDiffRows(lines, 4);
+    expect(rows[0]).toMatchObject({ kind: "line", index: 0 });
+    expect(rows.at(-1)).toMatchObject({ kind: "line", index: 9 });
+    expect(rows.some((row) => row.kind === "collapsed")).toBe(true);
+  });
+});
+
+describe("useDiffRows", () => {
+  it("starts with no run expanded", () => {
+    const lines = Array.from({ length: 10 }, (_, i) => contextLine(i));
+    const { result } = renderHook(() => useDiffRows(lines, 4));
+    expect(result.current.rows.some((row) => row.kind === "collapsed")).toBe(true);
+  });
+
+  it("expand() reveals the collapsed run's lines", () => {
+    const lines = Array.from({ length: 10 }, (_, i) => contextLine(i));
+    const { result } = renderHook(() => useDiffRows(lines, 4));
+
+    const collapsed = result.current.rows.find((row) => row.kind === "collapsed");
+    expect(collapsed).toBeDefined();
+    const runStart = (collapsed as { runStart: number }).runStart;
+
+    act(() => result.current.expand(runStart));
+
+    expect(result.current.rows.every((row) => row.kind === "line")).toBe(true);
+    expect(result.current.rows).toHaveLength(10);
+  });
+});

package/src/lib/diff-rows.ts

@@ -0,0 +1,92 @@
+/**
+ * The context-run-collapsing hunk-windowing algorithm behind `DiffView`
+ * (`@elabs-ai/components-ai`, #102, where it shipped as the private
+ * `useVisibleRows`) and the terminal CLI look-alike family's own diff hunk
+ * (issue #117).
+ *
+ * Promoted here (not duplicated) because `@elabs-ai/components-ai` and
+ * `@elabs-ai/components-terminal` are layer-2 DAG SIBLINGS and may not import
+ * each other — `ui` is upstream of both
+ * (docs/decisions/2026-09-01-brainless-adoption-architecture.md § 4). The
+ * windowing algorithm is shiki-free and DOM-free; `ui` already hosts hooks
+ * (`use-mobile`, `use-copy-to-clipboard`), so a hook alongside a pure
+ * function is an ordinary shape here, not a new category.
+ */
+import { useCallback, useMemo, useState } from "react";
+import type { DiffLine } from "./diff-line";
+
+/**
+ * One rendered row: either a real diff line, or a collapsed run of
+ * consecutive `context` lines longer than the caller's `contextLines`.
+ */
+export type DiffRow =
+  | { kind: "line"; line: DiffLine; index: number }
+  | { kind: "collapsed"; runStart: number; hiddenCount: number };
+
+/**
+ * Collapse long runs of consecutive `context` lines behind a single
+ * `"collapsed"` row, keeping `Math.ceil(contextLines / 2)` lines of context
+ * at the top of the run and `Math.floor(contextLines / 2)` at the bottom —
+ * so a reader always sees context on both sides of a hidden gap. A run
+ * already in `expanded` (by its start index) renders in full instead.
+ *
+ * Pure: no state, no effect. `useDiffRows` below is the stateful wrapper
+ * that owns the `expanded` set for a component.
+ */
+export function collapseDiffRows(
+  lines: DiffLine[],
+  contextLines: number | undefined,
+  expanded: ReadonlySet<number> = new Set(),
+): DiffRow[] {
+  if (!contextLines || contextLines <= 0) {
+    return lines.map((line, index) => ({ kind: "line", line, index }));
+  }
+  const out: DiffRow[] = [];
+  let i = 0;
+  while (i < lines.length) {
+    if (lines[i]?.type !== "context") {
+      out.push({ kind: "line", line: lines[i]!, index: i });
+      i++;
+      continue;
+    }
+    const runStart = i;
+    let j = i;
+    while (j < lines.length && lines[j]?.type === "context") j++;
+    const runLength = j - runStart;
+    if (runLength <= contextLines || expanded.has(runStart)) {
+      for (let k = runStart; k < j; k++) out.push({ kind: "line", line: lines[k]!, index: k });
+    } else {
+      const top = Math.ceil(contextLines / 2);
+      const bottom = Math.floor(contextLines / 2);
+      for (let k = runStart; k < runStart + top; k++)
+        out.push({ kind: "line", line: lines[k]!, index: k });
+      out.push({ kind: "collapsed", runStart, hiddenCount: runLength - top - bottom });
+      for (let k = j - bottom; k < j; k++) out.push({ kind: "line", line: lines[k]!, index: k });
+    }
+    i = j;
+  }
+  return out;
+}
+
+/**
+ * Stateful wrapper around `collapseDiffRows`: owns the set of run-start
+ * indices a caller has expanded via the "show more" control, and returns the
+ * current row list alongside an `expand` action.
+ */
+export function useDiffRows(
+  lines: DiffLine[],
+  contextLines: number | undefined,
+): { rows: DiffRow[]; expand: (runStart: number) => void } {
+  const [expanded, setExpanded] = useState<ReadonlySet<number>>(new Set());
+
+  const rows = useMemo(
+    () => collapseDiffRows(lines, contextLines, expanded),
+    [lines, contextLines, expanded],
+  );
+
+  const expand = useCallback((runStart: number) => {
+    setExpanded((prev) => new Set(prev).add(runStart));
+  }, []);
+
+  return { rows, expand };
+}

package/src/lib/format-duration.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from "vitest";
+import { formatElapsed } from "./format-duration";
+
+describe("formatElapsed", () => {
+  it.each([
+    // [elapsedMs, expected]
+    [0, "0ms"],
+    [420, "420ms"],
+    [999, "999ms"],
+    [1000, "1.0s"],
+    [8000, "8.0s"],
+    [9949, "9.9s"],
+    [10000, "10s"],
+    [42000, "42s"],
+    [59000, "59s"],
+    [60000, "1m00s"],
+    [77000, "1m17s"],
+    [605000, "10m05s"],
+  ] as const)("formats %dms as %s", (elapsedMs, expected) => {
+    expect(formatElapsed(elapsedMs)).toBe(expected);
+  });
+});

package/src/lib/format-duration.ts

@@ -0,0 +1,30 @@
+const MS_PER_SECOND = 1000;
+const SECONDS_PER_MINUTE = 60;
+const TEN_SECONDS = 10;
+
+/**
+ * Human-readable elapsed time — one formatter for every "how long did this take"
+ * surface in the system: `TurnStatus`'s running turn (#105), `ChangeReview`'s check
+ * rows (#112), `AgentEvent`'s hook durations (#109).
+ *
+ * Exported so a consumer's own elapsed-time surfaces agree with ours.
+ * Adapted from `brainless`'s turn-status elapsed formatter (MIT, see `ATTRIBUTION.md`).
+ *
+ * Rungs: sub-second → "420ms" · under ten seconds → "8.0s" · under a minute → "45s" ·
+ * beyond → "2m05s".
+ */
+export function formatElapsed(elapsedMs: number): string {
+  if (elapsedMs < MS_PER_SECOND) {
+    return `${Math.round(elapsedMs)}ms`;
+  }
+
+  const totalSeconds = elapsedMs / MS_PER_SECOND;
+
+  if (totalSeconds < SECONDS_PER_MINUTE) {
+    return `${totalSeconds.toFixed(totalSeconds < TEN_SECONDS ? 1 : 0)}s`;
+  }
+
+  const minutes = Math.floor(totalSeconds / SECONDS_PER_MINUTE);
+  const seconds = Math.round(totalSeconds % SECONDS_PER_MINUTE);
+  return `${minutes}m${String(seconds).padStart(2, "0")}s`;
+}

package/src/lib/has-renderable-content.test.ts

@@ -0,0 +1,49 @@
+import { createElement } from "react";
+import { describe, expect, it } from "vitest";
+import { hasRenderableContent } from "./has-renderable-content";
+
+describe("hasRenderableContent", () => {
+  it("is false for every scalar falsy value", () => {
+    expect(hasRenderableContent(undefined)).toBe(false);
+    expect(hasRenderableContent(null)).toBe(false);
+    expect(hasRenderableContent(false)).toBe(false);
+    expect(hasRenderableContent("")).toBe(false);
+    expect(hasRenderableContent(0)).toBe(false);
+  });
+
+  it("is true for a non-empty string or a truthy number", () => {
+    expect(hasRenderableContent("Required.")).toBe(true);
+    expect(hasRenderableContent(1)).toBe(true);
+  });
+
+  it("is false for an empty array — arrays are always truthy, which is exactly the bug this helper exists to avoid", () => {
+    expect(hasRenderableContent([])).toBe(false);
+  });
+
+  it("is false for an array of only falsy children", () => {
+    expect(hasRenderableContent([false, null, undefined])).toBe(false);
+  });
+
+  it("is false for an array of only empty strings — Children.toArray alone keeps '' and would still report content", () => {
+    expect(hasRenderableContent(["", ""])).toBe(false);
+  });
+
+  it("is true for an array containing at least one renderable child", () => {
+    expect(hasRenderableContent([false, "Required."])).toBe(true);
+  });
+
+  it("is true for a single React element", () => {
+    expect(hasRenderableContent(createElement("span", null, "hi"))).toBe(true);
+  });
+
+  // [KNOWN LIMIT] — an element naming a component that will render `null` is
+  // still an inert, truthy descriptor at this point; whether it renders
+  // anything is not decidable before React actually renders it. Documented
+  // limit, not a bug — see the JSDoc above `hasRenderableContent`.
+  it("[KNOWN LIMIT] is true for an element whose component will render null — not knowable before render", () => {
+    function RendersNull() {
+      return null;
+    }
+    expect(hasRenderableContent(createElement(RendersNull))).toBe(true);
+  });
+});

package/src/lib/has-renderable-content.ts

@@ -0,0 +1,32 @@
+import { Children, type ReactNode } from "react";
+
+/**
+ * Whether `node` has any renderable content. `{condition && "message"}` is
+ * the ordinary React idiom for optional content, and `condition === false`
+ * must render nothing — a `false`/`0`/`""`/`null`/`undefined` value is "no
+ * content", not an empty paragraph/alert. `Boolean(node)` alone is not
+ * enough: an array is always truthy, so `{errors.map(...)}` on an empty list
+ * (or `[a && "x", b && "y"]` with both false) would still count as content.
+ * `Children.toArray` drops `null`/`undefined`/booleans from an array but
+ * KEEPS `""` (and `0`), so an array like `["", ""]` would still slip through
+ * as "content" without the trailing `.filter(Boolean)` — filtering after
+ * `toArray` is what makes this match the scalar check for every array shape,
+ * not just the ones `toArray` already prunes.
+ *
+ * Shared by `FieldDescription`/`FieldError` (`../components/field/field.tsx`)
+ * and `FieldRow` (`../components/field-row/field-row.tsx`) — extracted so a
+ * fix to the predicate reaches every caller instead of drifting between
+ * hand-duplicated copies, which is exactly how `FieldRow` ended up with the
+ * weaker, bare-truthiness version of this check for two rounds of `Field*`
+ * fixes (#93).
+ *
+ * **Known limit:** a `node` that is itself a component returning `null` (or
+ * an empty fragment) is not knowable from the element before render — a
+ * React element is always truthy, whatever the component it names will
+ * return, so this function reports `true` for it. That limit is documented
+ * on `FieldDescription`/`FieldError`/`FieldRow`'s own JSDoc; it is not, and
+ * cannot be, fixed here.
+ */
+export function hasRenderableContent(node: ReactNode): boolean {
+  return Boolean(node) && Children.toArray(node).filter(Boolean).length > 0;
+}

package/src/lib/operating-mode.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import { effortRungForIndex } from "./operating-mode";
+
+describe("effortRungForIndex", () => {
+  it("returns the smallest rung for a single-level scale", () => {
+    expect(effortRungForIndex(0, 1)).toBe("size-2.5");
+  });
+
+  it("returns the smallest rung for the first of several levels", () => {
+    expect(effortRungForIndex(0, 4)).toBe("size-2.5");
+  });
+
+  it("returns the largest rung for the last of several levels", () => {
+    expect(effortRungForIndex(3, 4)).toBe("size-6");
+  });
+
+  it("grows monotonically across the scale", () => {
+    const RUNGS = [
+      "size-2.5",
+      "size-3",
+      "size-3.5",
+      "size-4",
+      "size-4.5",
+      "size-5",
+      "size-5.5",
+      "size-6",
+    ];
+    const count = 5;
+    const indices = Array.from({ length: count }, (_, i) =>
+      RUNGS.indexOf(effortRungForIndex(i, count)),
+    );
+    for (let i = 1; i < indices.length; i++) {
+      expect(indices[i]).toBeGreaterThanOrEqual(indices[i - 1]!);
+    }
+  });
+});

package/src/lib/operating-mode.ts

@@ -0,0 +1,81 @@
+/**
+ * The operating-mode and reasoning-effort vocabulary behind
+ * `PromptInputMode`/`PromptInputEffort` (`@elabs-ai/components-ai`, #104/#107)
+ * and the terminal CLI look-alike family's own composer chips (issue #117).
+ *
+ * Promoted here (not duplicated) because `@elabs-ai/components-ai` and
+ * `@elabs-ai/components-terminal` are layer-2 DAG SIBLINGS and may not import
+ * each other — `ui` is upstream of both
+ * (docs/decisions/2026-09-01-brainless-adoption-architecture.md § 4). Both
+ * types are caller-supplied vocabulary objects — never a vendor union — which
+ * #117 requires: no vendor mode/effort union may appear in a public type.
+ */
+import type { ReactNode } from "react";
+
+/**
+ * One app-defined operating mode — how autonomously the agent may act while
+ * this mode is active. `brand-ui` ships no vocabulary: `id`/`label` are
+ * entirely the consumer's (e.g. `"auto"`/`"Auto"`, `"plan"`/`"Plan first"`,
+ * or a completely different product's own terms).
+ */
+export interface OperatingMode {
+  /** Stable identifier — round-trips through `value`/`onValueChange`. */
+  id: string;
+  /** Visible + accessible name. */
+  label: string;
+  /** One line of guidance shown under the label in the menu. */
+  description?: string;
+  /** A shortcut hint rendered as a `Kbd` chip next to the label (e.g. `"⇧ Tab"`). */
+  keyHint?: string;
+  /** Leading glyph. Decorative — the mode is identified by `label`, not the icon. */
+  icon?: ReactNode;
+}
+
+/**
+ * One rung of an app-defined reasoning-effort scale. `brand-ui` ships no
+ * vocabulary: `id`/`label` are entirely the consumer's (e.g.
+ * `"low"`/`"Low"` … `"max"`/`"Max"`, or a completely different product's own
+ * terms and however many rungs it wants).
+ */
+export interface EffortLevel {
+  /** Stable identifier — round-trips through `value`/`onValueChange`. */
+  id: string;
+  /** Visible + accessible name for this rung. */
+  label: string;
+}
+
+/**
+ * Growing-square size rungs (Tailwind's own spacing scale — `size-2.5` through
+ * `size-6`), indexed by ordinal position so a caller never invents a raw
+ * pixel value. All in ONE `tailwind-merge` class group (`size`), so
+ * overriding a base size class is a guaranteed, order-independent swap
+ * rather than a `w-*`/`h-*` vs `size-*` conflict tailwind-merge can't see.
+ */
+const EFFORT_SIZE_RUNGS = [
+  "size-2.5",
+  "size-3",
+  "size-3.5",
+  "size-4",
+  "size-4.5",
+  "size-5",
+  "size-5.5",
+  "size-6",
+] as const;
+
+/**
+ * The size class for rung `index` of `count` evenly-spaced rungs — the
+ * growing-square ramp `PromptInputEffort` (and the terminal composer's own
+ * effort chips) render, low to high.
+ */
+export function effortRungForIndex(
+  index: number,
+  count: number,
+): (typeof EFFORT_SIZE_RUNGS)[number] {
+  if (count <= 1) return EFFORT_SIZE_RUNGS[0];
+  const position = index / (count - 1);
+  const rungIndex = Math.min(
+    EFFORT_SIZE_RUNGS.length - 1,
+    Math.max(0, Math.round(position * (EFFORT_SIZE_RUNGS.length - 1))),
+  );
+  return EFFORT_SIZE_RUNGS[rungIndex] ?? EFFORT_SIZE_RUNGS[0];
+}

package/src/lib/optional-peer.ts

@@ -0,0 +1,59 @@
+/**
+ * Detect a dynamic `import()` of an OPTIONAL peer that is not installed
+ * (issue #33 — mermaid / xterm / Rive / media-chrome are optional peers of
+ * `@elabs-ai/components-ai`, reached only through its lazy boundaries:
+ * `_lazy-mermaid.ts`, `_interactive-terminal-xterm.ts`, `_persona-rive.tsx` and
+ * `_audio-player-media-chrome.tsx`).
+ *
+ * Bundlers and runtimes report this differently (`ERR_MODULE_NOT_FOUND`,
+ * `Cannot find module`, `Failed to resolve module specifier`, Vite/browser's
+ * `Failed to fetch dynamically imported module`), so match on the SHAPES
+ * rather than one runtime's wording. A false positive here is cheap — the
+ * developer is told to install a package instead of seeing a raw
+ * module-resolution stack trace — and a false negative is the failure mode
+ * this exists to avoid.
+ *
+ * **Canonical home (promoted here per
+ * `docs/decisions/2026-09-01-brainless-adoption-architecture.md` § 2).** `ui` is
+ * upstream of every layer-2 package (`ai`, `terminal`, …) in the one-way
+ * package graph (`tokens` → `ui`/`icons` →
+ * `data`/`ai`/`flow`/`maps`/`charts`/`marketing`/`editor`/`viewer`), so this is
+ * an ordinary downward import for all of them — unlike the sibling-to-sibling
+ * case (e.g. `ai` ↔ `viewer`), which the graph forbids and which is why a
+ * safety-critical predicate like this one must never be copy-pasted sideways
+ * again. `packages/ai/src/_optional-peer.ts` still exists as a private,
+ * underived-prefixed module for one merge window (issue #116 deletes it and
+ * rewires its three importers onto this one); nothing imports this copy yet.
+ *
+ * It does NOT mirror `@elabs-ai/components-viewer`'s PRIMARY mechanism: the
+ * viewer's adapters throw a typed `ViewerError` carrying `code`/`packages`
+ * fields, and only fall back to string-matching for an error that didn't
+ * originate as one. This module has no typed-error primary path — every lazy
+ * boundary that uses it classifies purely by matching the caught error's
+ * message shape. That difference is why a shape mismatch (a resolved module
+ * with the wrong exports, rather than a rejected import) can slip past this
+ * detector silently instead of being caught by construction — see
+ * `_lazy-mermaid.ts`'s `loadEngine()` guard, added for exactly that gap
+ * (issue #33 review).
+ */
+const MODULE_NOT_FOUND_PATTERN =
+  /cannot find module|failed to resolve|dynamically imported module|module not found/i;
+
+/** True when a raw error MESSAGE names a module the runtime could not load. */
+export function isModuleNotFoundMessage(message: string): boolean {
+  return MODULE_NOT_FOUND_PATTERN.test(message);
+}
+
+/**
+ * True when `value` is (or looks like) a failed dynamic `import()` of a
+ * missing optional peer. Accepts anything a `.catch()` or an error boundary
+ * might see: an `Error` instance (checked by `code` first, then message), or
+ * `undefined`/other for anything that clearly is not one.
+ */
+export function isOptionalPeerMissing(value: unknown): boolean {
+  if (!(value instanceof Error)) return false;
+  if ("code" in value && (value as { code?: unknown }).code === "ERR_MODULE_NOT_FOUND") {
+    return true;
+  }
+  return isModuleNotFoundMessage(value.message);
+}

package/src/lib/session-launch.ts

@@ -0,0 +1,37 @@
+/**
+ * The session-launch vocabulary behind `SessionHeader`
+ * (`@elabs-ai/components-ai`, #110) and the terminal CLI look-alike family's
+ * own launch banner (issue #117, T7 — the "Empty" and "First-run" states).
+ *
+ * Promoted here (not duplicated) because `@elabs-ai/components-ai` and
+ * `@elabs-ai/components-terminal` are layer-2 DAG SIBLINGS and may not import
+ * each other — `ui` is upstream of both
+ * (docs/decisions/2026-09-01-brainless-adoption-architecture.md § 4). Pure
+ * item types, no behaviour.
+ */
+import type { ReactNode } from "react";
+
+export interface SessionCapability {
+  /** Short capability name, e.g. "Web search". */
+  label: string;
+  /** One-line detail rendered under the label. */
+  description?: string;
+  /** Decorative leading glyph — a Lucide icon element. */
+  icon?: ReactNode;
+}
+
+export interface SessionWhatsNewItem {
+  /** What changed, e.g. "Faster file search". */
+  label: string;
+  /** Optional link to release notes / a changelog entry. */
+  href?: string;
+}
+
+export interface SessionQuickAction {
+  /** Visible label, e.g. "New chat". */
+  label: string;
+  /** Shortcut hint, rendered with the `Kbd` primitive (e.g. "⌘N"). */
+  keyHint?: string;
+  /** Invoked when the action is chosen. */
+  onSelect?: () => void;
+}