@elabs-ai/components-ui 4.0.0 → 4.2.0

package/src/illustrations/no-results-illustration.tsx

@@ -0,0 +1,46 @@
+import { forwardRef } from "react";
+import {
+  illustrationSvgProps,
+  illustrationAccent,
+  type IllustrationProps,
+} from "./illustration-base";
+
+/**
+ * Search / filter with zero matches. A line-art magnifying glass with a
+ * `--primary-text` "×" inside the lens standing in for "nothing matched".
+ * The "×" is meaning-bearing (per the accent-semantics convention in
+ * `illustration-base.tsx`, #48 finding 1) — a bare magnifying glass alone
+ * reads as "search", not "no results".
+ */
+export const NoResultsIllustration = forwardRef<SVGSVGElement, IllustrationProps>(
+  function NoResultsIllustration({ size, className, ...props }, ref) {
+    return (
+      <svg
+        ref={ref}
+        {...illustrationSvgProps(size, className)}
+        data-slot="no-results-illustration"
+        {...props}
+      >
+        <circle cx="68" cy="66" r="30" />
+        <line x1="89.2" y1="87.2" x2="124" y2="122" />
+        <line
+          x1="56"
+          y1="54"
+          x2="80"
+          y2="78"
+          style={{ stroke: illustrationAccent("var(--primary-text)") }}
+          strokeWidth={3}
+        />
+        <line
+          x1="80"
+          y1="54"
+          x2="56"
+          y2="78"
+          style={{ stroke: illustrationAccent("var(--primary-text)") }}
+          strokeWidth={3}
+        />
+      </svg>
+    );
+  },
+);
+NoResultsIllustration.displayName = "NoResultsIllustration";

package/src/illustrations/offline-illustration.tsx

@@ -0,0 +1,37 @@
+import { forwardRef } from "react";
+import { illustrationSvgProps, type IllustrationProps } from "./illustration-base";
+
+/**
+ * Disconnected / no-network state. A line-art cloud crossed by a slash — the
+ * universal "disabled/no signal" idiom — reads as "offline" on its own
+ * silhouette. No accent mark, per the accent-semantics convention in
+ * `illustration-base.tsx` (#48 finding 1).
+ *
+ * Redrawn for #24 fix round 1 (P1-4) — the previous cloud path's closing curve
+ * left a visible hook/spur, and the dashed tether + falling node read as a
+ * raindrop rather than a severed connection while pulling the ink centre 11.5
+ * units below the shared stage centre.
+ *
+ * Redrawn again for #48 finding 4 — the two small rounded-rect "chain link"
+ * fragments below the slash read as loose debris/dashes rather than a
+ * "broken link" gesture. Removed rather than redrawn: the cloud+slash
+ * silhouette already fully conveys "offline" without them (the same
+ * reasoning that dropped the decorative accents from `EmptyListIllustration`/
+ * `FirstRunIllustration`).
+ */
+export const OfflineIllustration = forwardRef<SVGSVGElement, IllustrationProps>(
+  function OfflineIllustration({ size, className, ...props }, ref) {
+    return (
+      <svg
+        ref={ref}
+        {...illustrationSvgProps(size, className)}
+        data-slot="offline-illustration"
+        {...props}
+      >
+        <path d="M44.9,100.4 C44.9,83.6 56.4,72.4 67.9,75.2 C70.2,58.4 86.3,50 97.8,61.2 C111.6,55.6 125.4,69.6 120.8,86.4 C127.7,92 125.4,106 116.2,106 L54.1,106 C49.5,106 44.9,104.6 44.9,100.4 Z" />
+        <line x1="36" y1="112" x2="124" y2="36" strokeWidth={4} />
+      </svg>
+    );
+  },
+);
+OfflineIllustration.displayName = "OfflineIllustration";

package/src/illustrations/success-illustration.tsx

@@ -0,0 +1,40 @@
+import { forwardRef } from "react";
+import {
+  illustrationSvgProps,
+  illustrationAccent,
+  type IllustrationProps,
+} from "./illustration-base";
+
+/**
+ * Completed / positive-outcome state. A line-art ring with a `--success-text`
+ * checkmark — a ring + check needs no rays. The checkmark is meaning-bearing
+ * (per the accent-semantics convention in `illustration-base.tsx`, #48
+ * finding 1) — a bare ring alone carries no state at all.
+ *
+ * Redrawn for #24 fix round 1 (P0-1, P1-4) — the checkmark previously used
+ * `--primary` (re-creating the "success chips read as primary" confusion #334
+ * removed from the tokens) at `strokeWidth={6}` (off the shared accent-weight
+ * rule), and the three radiating ticks straddled the now-removed dashed stage
+ * (two crossed it, one didn't), reading as a clock/sun rather than a
+ * celebration.
+ */
+export const SuccessIllustration = forwardRef<SVGSVGElement, IllustrationProps>(
+  function SuccessIllustration({ size, className, ...props }, ref) {
+    return (
+      <svg
+        ref={ref}
+        {...illustrationSvgProps(size, className)}
+        data-slot="success-illustration"
+        {...props}
+      >
+        <circle cx="80" cy="78" r="44" />
+        <path
+          d="M59,81 L75,96 L103,60"
+          style={{ stroke: illustrationAccent("var(--success-text)") }}
+          strokeWidth={3}
+        />
+      </svg>
+    );
+  },
+);
+SuccessIllustration.displayName = "SuccessIllustration";

package/src/index.ts

@@ -9,7 +9,8 @@
  * components require their own peer libs (declared in package.json), e.g.
  * Drawer (vaul), Command (cmdk), Toast (sonner), Calendar (react-day-picker),
  * Carousel (embla-carousel-react), Resizable (react-resizable-panels),
- * Form (react-hook-form + zod), InputOTP (input-otp).
+ * InputOTP (input-otp). Form (react-hook-form + zod) is NOT on this barrel —
+ * it lives on the "@elabs-ai/components-ui/form" subpath (issue #26).
  */
 
 // Utilities
@@ -20,6 +21,11 @@ export { useIsMobile } from "./lib/use-mobile";
 // Browser file-download mechanics — one home for the Blob/URL → <a download> dance
 // (shared by ConversationDownload, downloadCsv, and Gallery). SSR-guarded.
 export { downloadBlob, downloadUrl } from "./lib/download";
+// Shared CSV (RFC 4180) value stringification + injection-guarded field
+// quoting — one home for logic `@elabs-ai/components-data`'s `toCsv` and
+// `@elabs-ai/components-charts`'s ChartFrame serializer both need (charts may
+// not depend on data, so both build on this instead).
+export { csvStringifyValue, csvQuoteField } from "./lib/csv";
 // Clipboard write + transient "copied" flag — one implementation for the
 // editor's copy button and `CopyableValue`, so the timing and the
 // "no clipboard in this context" answer are defined once.
@@ -64,6 +70,63 @@ export {
   type StreamdownTranslationKey,
   type StreamdownTranslationMap,
 } from "./lib/streamdown-translations";
+// A verification verdict (linter/type-check/test run/policy hook) — shared
+// vocabulary between `ChangeReview` (this package) and `ai`'s `AgentEvent`
+// (docs/decisions/2026-09-01-brainless-adoption-architecture.md § 6). `ai`
+// imports this rather than declaring its own.
+export { type CheckResult, type CheckSummary } from "./lib/check-result";
+// One elapsed-time formatter for every "how long did this take" surface —
+// `TurnStatus` (ai), `ChangeReview`'s check rows, `AgentEvent`'s hook
+// durations (§ 6 / § 6.1 of the doc above).
+export { formatElapsed } from "./lib/format-duration";
+// Optional-peer detection, promoted from `@elabs-ai/components-ai` (§ 2 of the
+// doc above) — `ui` is upstream of every layer-2 package, so this is the one
+// legal home for a helper shared by DAG siblings.
+export { isModuleNotFoundMessage, isOptionalPeerMissing } from "./lib/optional-peer";
+// The generic trigger-driven-query algorithm behind `MentionInput`'s popup,
+// generalised (§ 5 of the doc above) so a second trigger surface (a
+// slash-command palette) reuses it instead of re-implementing it.
+export {
+  findTriggerQuery,
+  replaceTriggerRun,
+  type FindTriggerQueryOptions,
+  type TriggerBoundary,
+  type TriggerQuery,
+} from "./lib/trigger-query";
+// The T0 promotion wave (issue #117 — see
+// docs/decisions/2026-09-01-brainless-adoption-architecture.md § 4/§ 10(b)):
+// headless models/helpers behind several `@elabs-ai/components-ai` composer
+// and transcript surfaces, promoted here (never duplicated) because
+// `@elabs-ai/components-ai` and `@elabs-ai/components-terminal` are layer-2
+// DAG siblings that may not import each other — `ui` is upstream of both.
+export { defaultSlashCommandFilter, stepIndex, type SlashCommand } from "./lib/slash-command";
+export {
+  APPROVAL_SCOPE_DESCRIPTION_KEYS,
+  type ApprovalOption,
+  type ApprovalScope,
+} from "./lib/approval-option";
+export {
+  diffLineAccessibleLabel,
+  diffLineMarker,
+  type DiffLine,
+  type DiffLineType,
+} from "./lib/diff-line";
+export { collapseDiffRows, useDiffRows, type DiffRow } from "./lib/diff-rows";
+export { effortRungForIndex, type EffortLevel, type OperatingMode } from "./lib/operating-mode";
+export {
+  agentEventOutcomeStatus,
+  type AgentEventOutcome,
+  type AgentEventPhase,
+} from "./lib/agent-event-model";
+export {
+  type SessionCapability,
+  type SessionQuickAction,
+  type SessionWhatsNewItem,
+} from "./lib/session-launch";
+// Empty/error/success/etc. state illustrations for StatePanel's `illustration`
+// slot (#24) — token-driven line art, kept alongside the utilities above
+// because it lives outside the folder-per-component `./components/` tree.
+export * from "./illustrations";
 
 // Components
 export * from "./components/accordion";
@@ -91,8 +154,10 @@ export * from "./components/collapsible-panel";
 export * from "./components/color-picker";
 export * from "./components/combobox";
 export * from "./components/command";
+export * from "./components/command-trigger";
 export * from "./components/confirm-dialog";
 export * from "./components/context-menu";
+export * from "./components/context-rail";
 export * from "./components/copyable-value";
 export * from "./components/date-picker";
 export * from "./components/date-range-picker";
@@ -103,15 +168,24 @@ export * from "./components/dropdown-menu";
 export * from "./components/empty-state";
 export * from "./components/error-state";
 export * from "./components/expand-dialog";
+export * from "./components/field";
 export * from "./components/field-row";
 export * from "./components/file-upload";
-export * from "./components/form";
+// `Form`/`FormField`/… are NOT re-exported from the main barrel — they are the
+// ONLY module in this package that imports `react-hook-form`/`@hookform/resolvers`
+// (peer, optional per issue #26). Re-exporting them here would pull that static
+// import into every consumer's bundled `dist/index.js` (bundlers must resolve a
+// top-level ESM import to build the module graph, even if the binding is never
+// used), forcing react-hook-form on every consumer regardless of whether they
+// use Form. Import the RHF-bound family from the dedicated subpath instead:
+// `import { Form, FormField, … } from "@elabs-ai/components-ui/form"`.
 export * from "./components/hover-card";
 export * from "./components/icon-button";
 export * from "./components/input";
 export * from "./components/input-group";
 export * from "./components/input-otp";
 export * from "./components/kbd";
+export * from "./components/keyboard-shortcuts";
 export * from "./components/key-value-editor";
 export * from "./components/label";
 export * from "./components/link-preview";
@@ -136,14 +210,17 @@ export * from "./components/radio-group";
 export * from "./components/rating";
 export * from "./components/resizable";
 export * from "./components/reveal";
+export * from "./components/schema-form";
 export * from "./components/scroll-area";
 export * from "./components/section-header";
 export * from "./components/segmented-field";
 export * from "./components/select";
 export * from "./components/separator";
 export * from "./components/sheet";
+export * from "./components/side-dock";
 export * from "./components/sidebar";
 export * from "./components/skeleton";
+export * from "./components/skip-link";
 export * from "./components/slider";
 export * from "./components/slider-number";
 export * from "./components/sonner";
@@ -171,4 +248,5 @@ export * from "./components/tree-select";
 export * from "./components/typography";
 export * from "./components/view-toolbar";
 export * from "./components/virtual-select";
+export * from "./components/workspace-picker";
 export * from "./components/wizard";

package/src/lib/agent-event-model.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from "vitest";
+import { agentEventOutcomeStatus, type AgentEventOutcome } from "./agent-event-model";
+
+describe("agentEventOutcomeStatus", () => {
+  it.each([
+    ["ok", "complete"],
+    ["blocked", "denied"],
+    ["failed", "failed"],
+  ] as [AgentEventOutcome, string][])("maps %s to the %s status", (outcome, expected) => {
+    expect(agentEventOutcomeStatus(outcome)).toBe(expected);
+  });
+});

package/src/lib/agent-event-model.ts

@@ -0,0 +1,42 @@
+/**
+ * The lifecycle/hook-event model behind `AgentEvent` (`@elabs-ai/components-ai`,
+ * #109) and the terminal CLI look-alike family's own event line (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).
+ * `agentEventOutcomeStatus` maps onto the existing closed 7-state `Status`
+ * (`components/status-badge/status-badge.tsx`), which already lives in
+ * `ui` — no eighth status is introduced.
+ */
+import type { Status } from "../components/status-badge/status-badge";
+
+/**
+ * When an event fired relative to the action it gates. A separate, WIDER
+ * vocabulary than `CheckResult.phase` (`"before" | "after"`, per-check): this
+ * one also admits `"lifecycle"` for events with no gated action (a turn's
+ * `user_prompt_submit`/`stop`). The two `phase` concepts answer different
+ * questions — "when did this event fire" vs "when did this check run" — and
+ * are never unified (§ 6.1 of the architecture decision above).
+ */
+export type AgentEventPhase = "before" | "after" | "lifecycle";
+
+/** An event's verdict. Maps onto the existing closed `Status` — see `agentEventOutcomeStatus`. */
+export type AgentEventOutcome = "ok" | "blocked" | "failed";
+
+/**
+ * `outcome` → the canonical 7-state `Status`. No new status value is added
+ * (issue #109 acceptance criteria); `blocked` maps to `denied` — a runtime
+ * hook refusing an action is the same shape as a human denying one.
+ */
+export function agentEventOutcomeStatus(outcome: AgentEventOutcome): Status {
+  switch (outcome) {
+    case "ok":
+      return "complete";
+    case "blocked":
+      return "denied";
+    case "failed":
+      return "failed";
+  }
+}

package/src/lib/approval-option.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vitest";
+import { APPROVAL_SCOPE_DESCRIPTION_KEYS, type ApprovalScope } from "./approval-option";
+
+describe("APPROVAL_SCOPE_DESCRIPTION_KEYS", () => {
+  it("has one message key per scope", () => {
+    const scopes: ApprovalScope[] = ["once", "session", "always", "deny"];
+    for (const scope of scopes) {
+      expect(typeof APPROVAL_SCOPE_DESCRIPTION_KEYS[scope]).toBe("string");
+      expect(APPROVAL_SCOPE_DESCRIPTION_KEYS[scope].length).toBeGreaterThan(0);
+    }
+  });
+
+  it("keys are distinct per scope", () => {
+    const values = Object.values(APPROVAL_SCOPE_DESCRIPTION_KEYS);
+    expect(new Set(values).size).toBe(values.length);
+  });
+});

package/src/lib/approval-option.ts

@@ -0,0 +1,53 @@
+/**
+ * The N-option, scoped-approval model behind `ApprovalCardOptions`
+ * (`@elabs-ai/components-ai`'s `confirmation.tsx`, #103) and the terminal CLI
+ * look-alike family's own permission row (issue #117) — a real coding-agent
+ * permission prompt is rarely a plain yes/no; it asks an N-option question
+ * whose options encode SCOPE ("Yes", "Yes, and don't ask again this
+ * session", "No, and tell the agent what to do instead").
+ *
+ * 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
+ * SYMBOLS have zero SDK coupling; only their previous host module
+ * (`confirmation.tsx`) imports `ai`'s `ToolUIPart`, so only the vocabulary —
+ * never the component — moves.
+ */
+
+/**
+ * How far a chosen option's permission reaches. Deliberately a closed,
+ * app-agnostic vocabulary (not a free string) so a consumer can derive an
+ * accessible fallback description per option (see
+ * `APPROVAL_SCOPE_DESCRIPTION_KEYS` below) — the one thing every option of a
+ * given scope always means, regardless of the agent-specific label wording.
+ */
+export type ApprovalScope = "once" | "session" | "always" | "deny";
+
+export interface ApprovalOption {
+  id: string;
+  label: string;
+  /**
+   * What choosing this option actually does. Optional: when omitted, the
+   * consumer renders a scope-derived sentence instead, so scope always
+   * reaches assistive tech through real text — never only through colour or
+   * a `data-*` attribute (WCAG 1.4.1).
+   */
+  description?: string;
+  scope: ApprovalScope;
+  /** Optional key hint shown beside the option, e.g. "1". */
+  keyHint?: string;
+}
+
+/**
+ * The locale-message KEY (not the translated text — `ui`'s locale catalogue,
+ * `components/locale-provider/messages.ts`, holds the English fallback and
+ * every other locale's translation) for the scope-derived sentence used only
+ * when `option.description` is omitted.
+ */
+export const APPROVAL_SCOPE_DESCRIPTION_KEYS: Record<ApprovalScope, string> = {
+  once: "ai.approvalCard.scopeOnceDescription",
+  session: "ai.approvalCard.scopeSessionDescription",
+  always: "ai.approvalCard.scopeAlwaysDescription",
+  deny: "ai.approvalCard.scopeDenyDescription",
+};

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/cn.ts

@@ -17,6 +17,15 @@ const twMerge = extendTailwindMerge({
       "font-size": [{ text: TEXT_ROLES }],
       // `font-display` is the display-face seam (sibling of font-mono, #187).
       "font-family": [{ font: ["display"] }],
+      // Theme-driven control/table knobs (themes.css § CONTROL UTILITIES and the
+      // `@theme inline` bridge) — so a caller's `h-8` / `rounded-none` /
+      // `font-bold` / `shadow-none` still replaces the token default.
+      "font-weight": [{ font: ["control", "table-header"] }],
+      rounded: [{ rounded: ["control"] }],
+      shadow: [{ shadow: ["input"] }],
+      h: [{ h: ["control", "control-sm", "control-lg", "header"] }],
+      size: [{ size: ["control", "control-sm", "control-lg"] }],
+      "min-w": [{ "min-w": ["control", "control-sm", "control-lg"] }],
     },
   },
 });

package/src/lib/csv.ts

@@ -0,0 +1,48 @@
+/**
+ * Shared CSV (RFC 4180) primitives — value stringification + injection-guarded
+ * field quoting. Pure, no DOM, SSR-safe.
+ *
+ * The single home for logic previously duplicated between `@elabs-ai/components-data`'s
+ * `toCsv` and `@elabs-ai/components-charts`'s `ChartFrame` local serializer (charts may not
+ * depend on data per the one-way package rule, so both import this instead of
+ * one importing the other).
+ */
+
+/** Leading characters a spreadsheet may interpret as a formula trigger. */
+const INJECTION_TRIGGER = /^[=+\-@]/;
+
+/**
+ * True when `field` parses as a plain finite number, e.g. "-5" or "+12.3".
+ * A negative/positive number is not a formula — only guard fields that
+ * START with a trigger character AND are not actually numeric.
+ */
+function isNumericLiteral(field: string): boolean {
+  const trimmed = field.trim();
+  if (trimmed === "") return false;
+  return Number.isFinite(Number(trimmed));
+}
+
+/** Stringify a cell value for CSV: dates → ISO, objects → JSON, else `String()`. */
+export function csvStringifyValue(value: unknown): string {
+  if (value === null || value === undefined) return "";
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === "object") return JSON.stringify(value);
+  return String(value);
+}
+
+/**
+ * Quote/escape one CSV field: prefixes a leading `'` when the field starts
+ * with a formula-trigger character and is not a plain number (CSV-injection
+ * guard), then RFC-4180-quotes when it contains the delimiter, a double
+ * quote, or a line break.
+ */
+export function csvQuoteField(field: string, delimiter: string): string {
+  let out = field;
+  if (INJECTION_TRIGGER.test(out) && !isNumericLiteral(out)) {
+    out = "'" + out;
+  }
+  if (out.includes(delimiter) || out.includes('"') || out.includes("\n") || out.includes("\r")) {
+    return '"' + out.replaceAll('"', '""') + '"';
+  }
+  return out;
+}

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;
+}