@elabs-ai/components-ui 4.0.0 → 4.1.0

package/src/illustrations/illustrations.stories.tsx

@@ -0,0 +1,94 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import type { ComponentType } from "react";
+import {
+  EmptyListIllustration,
+  NoResultsIllustration,
+  NoAccessIllustration,
+  ErrorIllustration,
+  OfflineIllustration,
+  SuccessIllustration,
+  FirstRunIllustration,
+  type IllustrationProps,
+} from "./index";
+
+/**
+ * Demo wrapper: illustrations are pure `currentColor` line art plus one
+ * meaning-bearing accent (`--primary-text` by default; `--success-text` on
+ * `SuccessIllustration`, `--destructive` on `ErrorIllustration`), so a story
+ * renders them inside a `text-muted-foreground` container — the same ambient
+ * color `StatePanel` applies via its icon/illustration slot. `StatePanel`
+ * retints the accent to `--destructive` for any illustration placed in a
+ * `kind="error"` slot via the `--illustration-accent` custom property (see
+ * `illustration-base.tsx`) — see `States/StatePanel`'s "Error (with
+ * illustration, #24 P0-2)" story for that pairing.
+ */
+function Demo(props: IllustrationProps & { as: ComponentType<IllustrationProps> }) {
+  const { as: Illustration, ...rest } = props;
+  return (
+    <div className="text-muted-foreground">
+      <Illustration {...rest} />
+    </div>
+  );
+}
+
+const meta = {
+  title: "States/Illustrations",
+  component: Demo,
+  tags: ["autodocs"],
+  argTypes: {
+    size: {
+      control: "text",
+      description: "Rendered width/height (any CSS length). Legible ~4rem–10rem.",
+    },
+  },
+} satisfies Meta<typeof Demo>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const EmptyList: Story = {
+  args: { as: EmptyListIllustration },
+};
+
+export const NoResults: Story = {
+  args: { as: NoResultsIllustration },
+};
+
+export const NoAccess: Story = {
+  args: { as: NoAccessIllustration },
+};
+
+export const Error: Story = {
+  args: { as: ErrorIllustration },
+};
+
+export const Offline: Story = {
+  args: { as: OfflineIllustration },
+};
+
+export const Success: Story = {
+  args: { as: SuccessIllustration },
+};
+
+export const FirstRun: Story = {
+  args: { as: FirstRunIllustration },
+};
+
+export const CustomSize: Story = {
+  name: "Custom size (10rem)",
+  args: { as: EmptyListIllustration, size: "10rem" },
+};
+
+export const AllStates: Story = {
+  name: "All seven, side by side",
+  render: () => (
+    <div className="flex flex-wrap gap-8 text-muted-foreground">
+      <EmptyListIllustration />
+      <NoResultsIllustration />
+      <NoAccessIllustration />
+      <ErrorIllustration />
+      <OfflineIllustration />
+      <SuccessIllustration />
+      <FirstRunIllustration />
+    </div>
+  ),
+};

package/src/illustrations/illustrations.test.tsx

@@ -0,0 +1,98 @@
+import type { CSSProperties } from "react";
+import { describe, expect, it } from "vitest";
+import { render } from "@testing-library/react";
+import {
+  EmptyListIllustration,
+  NoResultsIllustration,
+  NoAccessIllustration,
+  ErrorIllustration,
+  OfflineIllustration,
+  SuccessIllustration,
+  FirstRunIllustration,
+  ILLUSTRATION_ACCENT_VAR,
+  illustrationAccent,
+} from "./index";
+
+// No literal hex anywhere in a rendered attribute — only `currentColor` or a
+// `var(--…)` token reference (inline style or attribute) may carry color.
+const RAW_HEX_RE = /#[0-9a-fA-F]{3,6}\b/;
+
+const ILLUSTRATIONS = [
+  ["EmptyListIllustration", EmptyListIllustration, "empty-list-illustration"],
+  ["NoResultsIllustration", NoResultsIllustration, "no-results-illustration"],
+  ["NoAccessIllustration", NoAccessIllustration, "no-access-illustration"],
+  ["ErrorIllustration", ErrorIllustration, "error-illustration"],
+  ["OfflineIllustration", OfflineIllustration, "offline-illustration"],
+  ["SuccessIllustration", SuccessIllustration, "success-illustration"],
+  ["FirstRunIllustration", FirstRunIllustration, "first-run-illustration"],
+] as const;
+
+describe("state illustrations", () => {
+  it.each(ILLUSTRATIONS)(
+    "%s renders a decorative, token-driven <svg>",
+    (_name, Component, slot) => {
+      const { container } = render(<Component />);
+      const svg = container.querySelector("svg");
+      expect(svg).not.toBeNull();
+      expect(svg?.tagName.toLowerCase()).toBe("svg");
+      expect(svg).toHaveAttribute("aria-hidden", "true");
+      expect(svg).toHaveAttribute("role", "presentation");
+      expect(svg).toHaveAttribute("data-slot", slot);
+
+      // No raw hex anywhere in the tree's attributes (element attrs + style attr).
+      const offenders: string[] = [];
+      for (const el of Array.from(container.querySelectorAll("*"))) {
+        for (const attr of Array.from(el.attributes)) {
+          if (RAW_HEX_RE.test(attr.value)) {
+            offenders.push(`${el.tagName}[${attr.name}]="${attr.value}"`);
+          }
+        }
+      }
+      expect(offenders).toEqual([]);
+    },
+  );
+
+  it("accepts a custom `size` and applies it as width/height", () => {
+    const { container } = render(<EmptyListIllustration size="10rem" />);
+    const svg = container.querySelector("svg");
+    expect(svg).toHaveAttribute("width", "10rem");
+    expect(svg).toHaveAttribute("height", "10rem");
+  });
+
+  it("defaults to a rem-based size within the legible 64px–160px range", () => {
+    const { container } = render(<NoResultsIllustration />);
+    const svg = container.querySelector("svg");
+    const width = svg?.getAttribute("width") ?? "";
+    expect(width).toMatch(/rem$/);
+  });
+
+  it("merges a caller className without dropping the base classes", () => {
+    const { container } = render(<SuccessIllustration className="text-primary" />);
+    const svg = container.querySelector("svg");
+    expect(svg?.getAttribute("class")).toContain("text-primary");
+  });
+
+  // #12/#53 review (P2): `ILLUSTRATION_ACCENT_VAR` is the mechanism `StatePanel`
+  // uses internally to safely retint an illustration's meaning-bearing accent
+  // (see illustration-base.tsx). A consumer rendering an illustration OUTSIDE
+  // `StatePanel` needs the same seam without duplicating the private
+  // "--illustration-accent" string, so the barrel must export it.
+  it("exports ILLUSTRATION_ACCENT_VAR — the public retint seam for consumers outside StatePanel", () => {
+    expect(ILLUSTRATION_ACCENT_VAR).toBe("--illustration-accent");
+    // A consumer can set it inline exactly the way StatePanel does internally.
+    const { container } = render(
+      <div style={{ [ILLUSTRATION_ACCENT_VAR]: "var(--success-text)" } as CSSProperties}>
+        <SuccessIllustration />
+      </div>,
+    );
+    const wrapper = container.firstChild as HTMLElement;
+    expect(wrapper.style.getPropertyValue(ILLUSTRATION_ACCENT_VAR)).toBe("var(--success-text)");
+  });
+
+  it("exports illustrationAccent — the public helper for building an illustration's fallback stroke/fill color", () => {
+    const fallback = "var(--success-text)";
+    const result = illustrationAccent(fallback);
+    // illustrationAccent(fallback) returns var(--illustration-accent, fallback)
+    expect(result).toBe(`var(${ILLUSTRATION_ACCENT_VAR}, ${fallback})`);
+  });
+});

package/src/illustrations/index.ts

@@ -0,0 +1,16 @@
+export type { IllustrationProps } from "./illustration-base";
+// The custom-property name a consumer sets to safely retint an illustration's
+// meaning-bearing accent (see `StatePanel`'s own usage). Previously only the
+// illustration components + `IllustrationProps` were exported here, so a
+// consumer rendering an illustration OUTSIDE `StatePanel` had no way to reach
+// this seam without duplicating the private string (#12/#53 review, P2).
+// Relates to the wider "illustration customization" tracking issue #46 — this
+// change exports the existing constant, it does not itself resolve #46.
+export { ILLUSTRATION_ACCENT_VAR, illustrationAccent } from "./illustration-base";
+export { EmptyListIllustration } from "./empty-list-illustration";
+export { NoResultsIllustration } from "./no-results-illustration";
+export { NoAccessIllustration } from "./no-access-illustration";
+export { ErrorIllustration } from "./error-illustration";
+export { OfflineIllustration } from "./offline-illustration";
+export { SuccessIllustration } from "./success-illustration";
+export { FirstRunIllustration } from "./first-run-illustration";

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

@@ -0,0 +1,45 @@
+import { forwardRef } from "react";
+import {
+  illustrationSvgProps,
+  illustrationAccent,
+  type IllustrationProps,
+} from "./illustration-base";
+
+/**
+ * Permission / access-denied state. A line-art padlock with a `--primary-text`
+ * keyhole — reads as "restricted", not "broken". The keyhole is meaning-bearing
+ * (per the accent-semantics convention in `illustration-base.tsx`, #48
+ * finding 1) — it's what distinguishes a padlock from a generic rounded box.
+ */
+export const NoAccessIllustration = forwardRef<SVGSVGElement, IllustrationProps>(
+  function NoAccessIllustration({ size, className, ...props }, ref) {
+    return (
+      <svg
+        ref={ref}
+        {...illustrationSvgProps(size, className)}
+        data-slot="no-access-illustration"
+        {...props}
+      >
+        <path d="M50,72 V52 A30,20 0 0 1 110,52 V72" />
+        <rect x="36" y="72" width="88" height="48" rx="10" />
+        <circle
+          cx="80"
+          cy="92"
+          r="6"
+          style={{ stroke: illustrationAccent("var(--primary-text)") }}
+          strokeWidth={3}
+        />
+        <rect
+          x="77"
+          y="98"
+          width="6"
+          height="12"
+          rx="2"
+          style={{ stroke: illustrationAccent("var(--primary-text)") }}
+          strokeWidth={3}
+        />
+      </svg>
+    );
+  },
+);
+NoAccessIllustration.displayName = "NoAccessIllustration";

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
@@ -64,6 +65,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 +149,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 +163,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 +205,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 +243,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",
+};