@elabs-ai/components-ui 4.0.0 → 4.1.0

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 import { ClassValue } from 'clsx';
 import { LucideIcon, LucideProps } from 'lucide-react';
 import * as react from 'react';
-import react__default, { HTMLAttributes, ReactNode, InputHTMLAttributes, ButtonHTMLAttributes, ComponentProps, ComponentPropsWithoutRef, ReactElement, TextareaHTMLAttributes, TdHTMLAttributes, ThHTMLAttributes, LiHTMLAttributes, AnchorHTMLAttributes, OlHTMLAttributes } from 'react';
-import * as AccordionPrimitive from '@radix-ui/react-accordion';
+import react__default, { ReactNode, HTMLAttributes, SVGProps, InputHTMLAttributes, ButtonHTMLAttributes, ComponentProps, ComponentPropsWithoutRef, ReactElement, TextareaHTMLAttributes, TdHTMLAttributes, ThHTMLAttributes, LiHTMLAttributes, AnchorHTMLAttributes, OlHTMLAttributes } from 'react';
 import * as class_variance_authority_types from 'class-variance-authority/types';
-import * as _radix_ui_react_separator from '@radix-ui/react-separator';
 import { VariantProps } from 'class-variance-authority';
+import * as AccordionPrimitive from '@radix-ui/react-accordion';
+import * as _radix_ui_react_separator from '@radix-ui/react-separator';
 import * as TooltipPrimitive from '@radix-ui/react-tooltip';
 import * as AlertDialogPrimitive from '@radix-ui/react-alert-dialog';
 import * as AspectRatioPrimitive from '@radix-ui/react-aspect-ratio';
@@ -21,10 +21,7 @@ import * as ContextMenuPrimitive from '@radix-ui/react-context-menu';
 import * as vaul from 'vaul';
 import { Drawer as Drawer$1 } from 'vaul';
 import * as DropdownMenuPrimitive from '@radix-ui/react-dropdown-menu';
-import * as _radix_ui_react_slot from '@radix-ui/react-slot';
 import * as _radix_ui_react_label from '@radix-ui/react-label';
-import * as react_hook_form from 'react-hook-form';
-import { FieldValues, FieldPath, ControllerProps } from 'react-hook-form';
 import * as HoverCardPrimitive from '@radix-ui/react-hover-card';
 import * as input_otp from 'input-otp';
 import * as PopoverPrimitive from '@radix-ui/react-popover';
@@ -34,6 +31,7 @@ import * as NavigationMenuPrimitive from '@radix-ui/react-navigation-menu';
 import * as ProgressPrimitive from '@radix-ui/react-progress';
 import * as RadioGroupPrimitive from '@radix-ui/react-radio-group';
 import * as ResizablePrimitive from 'react-resizable-panels';
+import { z } from 'zod';
 import * as ScrollAreaPrimitive from '@radix-ui/react-scroll-area';
 import * as SelectPrimitive from '@radix-ui/react-select';
 import * as SliderPrimitive from '@radix-ui/react-slider';
@@ -54,8 +52,14 @@ import { Virtualizer } from '@tanstack/react-virtual';
  */
 declare function cn(...inputs: ClassValue[]): string;
 
-/** Returns true when the viewport is below the mobile breakpoint (768px). */
-declare function useIsMobile(): boolean;
+/**
+ * Returns true when the viewport is below `breakpoint` (default 768px, the
+ * mobile breakpoint). Additive optional argument (ADR 0035 §5) — every
+ * existing zero-arg call site is unchanged. A caller with its own threshold
+ * (e.g. `ContextRail`'s `overlayBreakpoint`) passes it directly instead of a
+ * second hook.
+ */
+declare function useIsMobile(breakpoint?: number): boolean;
 
 /**
  * Browser file-download helpers — the single home for the
@@ -505,6 +509,642 @@ type StreamdownTranslationMap = Record<StreamdownTranslationKey, string>;
  */
 declare function useStreamdownTranslations(): StreamdownTranslationMap;
 
+/**
+ * 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`.
+ */
+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. */
+interface CheckSummary {
+    /** How many checks ran. */
+    ran: number;
+    /** How many of them passed. `passed <= ran`. */
+    passed: number;
+}
+
+/**
+ * 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".
+ */
+declare function formatElapsed(elapsedMs: number): string;
+
+/** True when a raw error MESSAGE names a module the runtime could not load. */
+declare function isModuleNotFoundMessage(message: string): boolean;
+/**
+ * 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.
+ */
+declare function isOptionalPeerMissing(value: unknown): boolean;
+
+/**
+ * The generic, component-agnostic half of a trigger-driven inline palette —
+ * "is the caret sitting inside a `trigger + query` run, and how do I splice a
+ * chosen result back in". Zero React, zero DOM, zero knowledge of mentions.
+ *
+ * Lifted out of `MentionInput`'s private `findQuery`/`isWordBoundary`
+ * (docs/decisions/2026-09-01-brainless-adoption-architecture.md § 5) so a second
+ * trigger-driven surface (a slash-command palette) reuses the algorithm instead
+ * of re-implementing it. `MentionInput` consumes this module unchanged — see
+ * `mention-input.tsx`.
+ */
+/**
+ * Where a trigger character is allowed to START a query.
+ *
+ * `"word"`       — index 0, or preceded by whitespace / "(" / "[".  (`MentionInput`'s
+ *                  behaviour, unchanged — an "@" inside an email address must not open a popup.)
+ * `"line-start"` — index 0, or preceded by "\n".  (A slash palette: "/help" opens, "cd /usr" does not.)
+ */
+type TriggerBoundary = "word" | "line-start";
+/** An in-progress `trigger + query` run under the caret. */
+interface TriggerQuery {
+    /** Offset of the trigger character in `text`. */
+    start: number;
+    /** The query WITHOUT the trigger character. */
+    query: string;
+}
+interface FindTriggerQueryOptions {
+    /** @default "word" */
+    boundary?: TriggerBoundary;
+    /**
+     * Veto a candidate whose trigger character has already been consumed by a
+     * committed token — `MentionInput` passes `mentionAt(...)` here so an
+     * inserted "@Ada Lovelace" cannot re-open the popup. Omit when there are no
+     * committed tokens (a slash palette has none).
+     */
+    isTriggerConsumed?: (start: number) => boolean;
+}
+/**
+ * Is the caret sitting inside a `trigger + query` run?
+ *
+ * DERIVED from committed text + caret, never intercepted at keydown — a
+ * keydown-driven trigger must `preventDefault()` every printable character and
+ * re-insert it by hand, which destroys IME composition, native undo, spellcheck
+ * and paste. Deriving means the popup opens identically whether the trigger
+ * arrived by typing, pasting, an IME commit, or a click that moved the caret
+ * back into a half-typed query.
+ */
+declare function findTriggerQuery(text: string, caret: number, trigger: string, options?: FindTriggerQueryOptions): TriggerQuery | null;
+/** The plain-text half of an insert: splice `insertText` over the run, and say where the caret lands. */
+declare function replaceTriggerRun(text: string, queryStart: number, caret: number, insertText: string): {
+    text: string;
+    caret: number;
+};
+
+/**
+ * The command model behind a `/`-triggered slash-command palette
+ * (`PromptInputSlash` in `@elabs-ai/components-ai`, and the terminal CLI
+ * look-alike family's own palette — 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, so this is the one legal shared home
+ * (docs/decisions/2026-09-01-brainless-adoption-architecture.md § 4, the
+ * promotion rule: "a helper shared by two layer-2 siblings moves UP to `ui`,
+ * it is never duplicated sideways"). No DOM, no keyboard wiring, no rendering
+ * — the popover, the caret tracking and the row markup stay in each
+ * package's own presentational component.
+ */
+
+/** One entry a slash palette offers. Ships no vocabulary — entirely prop-driven. */
+interface SlashCommand {
+    /** Stable name, WITHOUT the leading "/" (e.g. `"help"`, not `"/help"`). */
+    name: string;
+    /** One line shown next to the name. */
+    description?: string;
+    /** Extra prefix-match aids beyond `name` (matched case-insensitively). */
+    keywords?: string[];
+    /** Leading glyph. Decorative — the row is identified by `name`. */
+    icon?: ReactNode;
+}
+/**
+ * Case-insensitive PREFIX match on `name`, falling back to a prefix match on
+ * any `keyword`. Prefix (not substring) is deliberate: `/hel` should surface
+ * `/help`, not e.g. a hypothetical `/channel`.
+ */
+declare function defaultSlashCommandFilter(command: SlashCommand, query: string): boolean;
+/** Next index in `[0, count)`, wrapping at both ends. `-1` when `count` is 0. */
+declare function stepIndex(count: number, from: number, direction: 1 | -1): number;
+
+/**
+ * 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.
+ */
+type ApprovalScope = "once" | "session" | "always" | "deny";
+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.
+ */
+declare const APPROVAL_SCOPE_DESCRIPTION_KEYS: Record<ApprovalScope, string>;
+
+/**
+ * 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. */
+type DiffLineType = "add" | "del" | "context" | "hunk" | "meta";
+/** One line of a unified diff. Absent gutter numbers are load-bearing (see below). */
+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.
+ */
+declare function diffLineMarker(type: DiffLineType): string;
+/**
+ * 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.
+ */
+declare function diffLineAccessibleLabel(type: DiffLineType): "ai.diffView.addedLine" | "ai.diffView.removedLine" | undefined;
+
+/**
+ * One rendered row: either a real diff line, or a collapsed run of
+ * consecutive `context` lines longer than the caller's `contextLines`.
+ */
+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.
+ */
+declare function collapseDiffRows(lines: DiffLine[], contextLines: number | undefined, expanded?: ReadonlySet<number>): DiffRow[];
+/**
+ * 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.
+ */
+declare function useDiffRows(lines: DiffLine[], contextLines: number | undefined): {
+    rows: DiffRow[];
+    expand: (runStart: number) => void;
+};
+
+/**
+ * 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.
+ */
+
+/**
+ * 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).
+ */
+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).
+ */
+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.
+ */
+declare const EFFORT_SIZE_RUNGS: readonly ["size-2.5", "size-3", "size-3.5", "size-4", "size-4.5", "size-5", "size-5.5", "size-6"];
+/**
+ * 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.
+ */
+declare function effortRungForIndex(index: number, count: number): (typeof EFFORT_SIZE_RUNGS)[number];
+
+/** The canonical, closed 7-state status enum (research 10 §B.1). */
+declare const STATUSES: readonly ["pending", "running", "complete", "awaiting-approval", "denied", "failed", "skipped"];
+type Status = (typeof STATUSES)[number];
+/** Closed tone set for the out-of-vocabulary escape hatch (CALM treatments only). */
+declare const STATUS_TONES: readonly ["neutral", "info", "success", "warning", "destructive"];
+type StatusTone = (typeof STATUS_TONES)[number];
+/**
+ * An out-of-vocabulary status. Prefer the canonical `Status` enum; reach for
+ * this only when the domain genuinely has a state the 7 do not express (e.g. a
+ * run engine's `stopped_guardrail`). Map it ONCE, near your domain — not per
+ * call site.
+ */
+interface CustomStatus {
+    label: string;
+    tone: StatusTone;
+    /** Optional Lucide glyph. Omitted → label-only (no default glyph). */
+    icon?: LucideIcon;
+}
+/** Narrows `Status | CustomStatus` — the object form is always the escape hatch. */
+declare function isCustomStatus(status: Status | CustomStatus): status is CustomStatus;
+/**
+ * The canonical semantic ROLE per status — the single source of truth for
+ * status colour (#392). Any other status-keyed colour map in the repo
+ * (`Timeline`'s `NODE_STYLE`, or a future one) must be TESTED against this,
+ * not hand-authored — a second literal copy is exactly how `NODE_STYLE`
+ * drifted (`running` rendered `--primary` while this map said `--info`).
+ * Do NOT interpolate `bg-${STATUS_ROLE[status]}` into a class map: Tailwind
+ * scans source statically, so a template-literal class emits no CSS. Keep
+ * consuming maps as literal class strings, verified against this export by a
+ * test.
+ */
+declare const STATUS_ROLE: {
+    readonly pending: "secondary";
+    readonly running: "info";
+    readonly complete: "success";
+    readonly "awaiting-approval": "warning";
+    readonly denied: "muted";
+    readonly failed: "destructive";
+    readonly skipped: "secondary";
+};
+/** Default human-readable label per status (override via `children`). */
+declare const STATUS_LABELS: Record<Status, string>;
+/**
+ * Lucide glyph per out-of-vocabulary TONE — the same five-tone escape hatch
+ * `CustomStatus` uses (`STATUS_TONES`). A consumer that encodes a bare TONE
+ * with no fuller `Status` semantics (e.g. `@elabs-ai/components-flow`'s `FlowNode.tone`,
+ * #387) derives its non-colour cue from here instead of inventing a second
+ * icon vocabulary — each entry reuses the SAME icon `STATUS_ICONS` already
+ * pairs with that tone's one canonical status (`success`→`complete`'s
+ * `CheckCircle2`, `warning`→`awaiting-approval`'s `Clock`,
+ * `destructive`→`failed`'s `AlertCircle`). `neutral`/`info` have no entry:
+ * nothing consumes them yet, and reaching for a glyph on every neutral/
+ * default-toned element would be assistive-tech noise on the common case —
+ * extend this map, don't fork a new one, the day something needs them.
+ */
+declare const STATUS_TONE_ICONS: Partial<Record<StatusTone, LucideIcon>>;
+interface StatusIconProps extends Omit<LucideProps, "ref"> {
+    /** The canonical execution status (closed enum). */
+    status: Status;
+}
+/**
+ * The icon + status-color atom `StatusBadge` itself composes — for tight rows
+ * (test-result rows, timeline/rail nodes) where a full badge is too heavy.
+ * Decorative by default (`aria-hidden`); the adjacent row text must carry the
+ * status name for AT users.
+ */
+declare const StatusIcon: react.ForwardRefExoticComponent<StatusIconProps & react.RefAttributes<SVGSVGElement>>;
+declare const statusBadgeVariants: (props?: ({
+    status?: "pending" | "running" | "complete" | "awaiting-approval" | "denied" | "failed" | "skipped" | null | undefined;
+    tone?: "success" | "warning" | "destructive" | "info" | "neutral" | null | undefined;
+    size?: "md" | "sm" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+interface StatusBadgeProps extends HTMLAttributes<HTMLSpanElement>, Omit<VariantProps<typeof statusBadgeVariants>, "status" | "tone"> {
+    /** The canonical execution status, or a mapped out-of-vocabulary one (#363). */
+    status: Status | CustomStatus;
+    /** Render label-only (no status icon). */
+    hideIcon?: boolean;
+}
+declare const StatusBadge: react.ForwardRefExoticComponent<StatusBadgeProps & react.RefAttributes<HTMLSpanElement>>;
+/** The editor/markdown `Timeline` 3-state vocabulary (`@elabs-ai/components-editor`). */
+type TimelineStatus = "done" | "active" | "pending";
+/**
+ * Map the Timeline `done|active|pending` vocabulary onto the canonical
+ * `Status` (research 10 §B.1 mapping b — lossless; the timeline only
+ * expresses 3 of the 7 states). The AI-SDK `ToolUIPart` mapper lives in
+ * `@elabs-ai/components-ai` (`statusFromToolState`, tool.tsx) so `@elabs-ai/components-ui` stays free of
+ * the `ai` dependency (D6).
+ */
+declare function fromTimelineStatus(status: TimelineStatus): Status;
+
+/**
+ * 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.
+ */
+
+/**
+ * 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).
+ */
+type AgentEventPhase = "before" | "after" | "lifecycle";
+/** An event's verdict. Maps onto the existing closed `Status` — see `agentEventOutcomeStatus`. */
+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.
+ */
+declare function agentEventOutcomeStatus(outcome: AgentEventOutcome): Status;
+
+/**
+ * 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.
+ */
+
+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;
+}
+interface SessionWhatsNewItem {
+    /** What changed, e.g. "Faster file search". */
+    label: string;
+    /** Optional link to release notes / a changelog entry. */
+    href?: string;
+}
+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;
+}
+
+interface IllustrationProps extends SVGProps<SVGSVGElement> {
+    /**
+     * Rendered width & height (any CSS length — pass a `rem` value to stay
+     * density/zoom-aware). Illustrations are drawn to read clearly from about
+     * `4rem` (64px) up to `10rem` (160px).
+     * @default "7rem"
+     */
+    size?: string | number;
+}
+/**
+ * Accent-semantics convention (#48 finding 1): an illustration draws at most
+ * ONE accent mark (via `illustrationAccent()` below), and it exists ONLY
+ * when it carries information the silhouette (the `currentColor`-stroked
+ * subject) does not already supply on its own — never as ornamental
+ * flourish wearing a meaning-bearing token. Applied across the seven
+ * shipped illustrations:
+ * - **Meaning-bearing (kept):** the "×" that turns a magnifying glass into
+ *   "no results" (`NoResultsIllustration`), the keyhole that turns a padlock
+ *   body into "restricted" (`NoAccessIllustration`), the checkmark that
+ *   turns a bare ring into "success" (`SuccessIllustration`), the
+ *   exclamation that turns a torn document into "warning" rather than
+ *   merely "broken" (`ErrorIllustration`).
+ * - **Was decorative-only, removed (#48):** the "add" badge on
+ *   `EmptyListIllustration` (three rows already read as "empty list" on
+ *   their own), the sparkle on `FirstRunIllustration` (the planted flag
+ *   already reads as "start here"), and the broken-link fragments on
+ *   `OfflineIllustration` (a slashed cloud already reads as "disconnected" —
+ *   the universal "no signal" idiom). Their accent-free silhouettes carry
+ *   the full state alone, matching how `ErrorIllustration`'s silhouette
+ *   already did before this convention was written down.
+ * Every illustration is `aria-hidden` regardless (the state's title/
+ * description text is the ACCESSIBLE channel — see `illustrationSvgProps`
+ * below), so this is a visual-consistency rule, not an a11y requirement on
+ * its own; don't regress the silhouette-carries-meaning property while
+ * redrawing any of the four kept accents above.
+ */
+/**
+ * The custom property every illustration's single meaning-bearing accent
+ * reads through. `StatePanel` sets it on the illustration slot's wrapper for
+ * `kind="error"` (`var(--destructive-text)`) so the accent follows the
+ * panel's tint instead of staying pinned to one hue inside a re-colored slot
+ * (#24 fix round 1, P0-2) — without this, an illustration whose accent
+ * defaults to the brand hue renders a lime badge on a red error panel. Falls
+ * back to each illustration's own default hue when no ambient override is
+ * set.
+ */
+declare const ILLUSTRATION_ACCENT_VAR = "--illustration-accent";
+/**
+ * Build the `style` value for an illustration's accent ink: honors the
+ * ambient `--illustration-accent` override when set, otherwise `fallback`.
+ * `fallback` must be the correct **mark rung** for the accent's hue — e.g.
+ * `var(--primary-text)` (NOT `var(--primary)`, a plate color that measures
+ * 1.42:1 on `--card` in the `light` theme — #24 fix round 1, P0-1; see
+ * `.claude/rules/styling-and-tokens.md` "Which status rung a graphical MARK
+ * reaches for"), `var(--success-text)` for a positive-outcome accent, or
+ * `var(--destructive-text)` for an error accent — the TEXT rung, deliberately
+ * distinct from the FILL rung (`--destructive`) `StatePanel` puts the
+ * SUBJECT on for `kind="error"`, so the two don't collapse onto one colour
+ * (#48 finding 2).
+ */
+declare function illustrationAccent(fallback: string): string;
+
+/**
+ * Empty list / zero-data-yet state. Three line-art rows read as "empty list"
+ * on their own silhouette — no accent mark, per the accent-semantics
+ * convention in `illustration-base.tsx` (#48 finding 1): a floating "add"
+ * badge here would repeat information the rows already supply, not add any.
+ */
+declare const EmptyListIllustration: react.ForwardRefExoticComponent<Omit<IllustrationProps, "ref"> & react.RefAttributes<SVGSVGElement>>;
+
+/**
+ * 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".
+ */
+declare const NoResultsIllustration: react.ForwardRefExoticComponent<Omit<IllustrationProps, "ref"> & react.RefAttributes<SVGSVGElement>>;
+
+/**
+ * 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.
+ */
+declare const NoAccessIllustration: react.ForwardRefExoticComponent<Omit<IllustrationProps, "ref"> & react.RefAttributes<SVGSVGElement>>;
+
+/**
+ * Recoverable-failure state. A line-art document split into two halves with a
+ * visible gap between them — distinguishable from `NoAccessIllustration`/
+ * `OfflineIllustration` by silhouette alone (a split document reads as
+ * "broken" even in greyscale), per the WCAG 1.4.1 "never color-only" rule.
+ * The exclamation mark IS meaning-bearing (per the accent-semantics
+ * convention in `illustration-base.tsx`, #48 finding 1) — it turns "torn
+ * document" into "warning", information the silhouette alone doesn't carry —
+ * so it stays, in the upper-right quadrant of the right-hand half, clear of
+ * both documents' outlines.
+ *
+ * Redrawn for #24 fix round 1 (P1-3) — the previous cracked-card + tiny alert
+ * triangle read as a lightning bolt or a broken-image placeholder and the
+ * triangle's exclamation collapsed to an illegible blob at 4rem.
+ *
+ * Redrawn again for #48 finding 3 — the mark previously sat at (76-84,
+ * 54-95), exactly where the two document halves' torn edges converge, so it
+ * read as a knot of overlapping lines rather than a "!". Moved to
+ * (98-113, 44-85), 8-15 units clear of the nearest tear line at every
+ * y-coordinate it spans.
+ */
+declare const ErrorIllustration: react.ForwardRefExoticComponent<Omit<IllustrationProps, "ref"> & react.RefAttributes<SVGSVGElement>>;
+
+/**
+ * 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`).
+ */
+declare const OfflineIllustration: react.ForwardRefExoticComponent<Omit<IllustrationProps, "ref"> & react.RefAttributes<SVGSVGElement>>;
+
+/**
+ * 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.
+ */
+declare const SuccessIllustration: react.ForwardRefExoticComponent<Omit<IllustrationProps, "ref"> & react.RefAttributes<SVGSVGElement>>;
+
+/**
+ * First-run / onboarding state. A line-art planted flag — reads as "start
+ * here" on its own silhouette, distinct from `SuccessIllustration`. No
+ * accent mark, per the accent-semantics convention in `illustration-base.tsx`
+ * (#48 finding 1): a decorative sparkle here would repeat information the
+ * flag already supplies, not add any.
+ */
+declare const FirstRunIllustration: react.ForwardRefExoticComponent<Omit<IllustrationProps, "ref"> & react.RefAttributes<SVGSVGElement>>;
+
 declare const Accordion: react.ForwardRefExoticComponent<(AccordionPrimitive.AccordionSingleProps | AccordionPrimitive.AccordionMultipleProps) & react.RefAttributes<HTMLDivElement>>;
 declare const AccordionItem: react.ForwardRefExoticComponent<Omit<AccordionPrimitive.AccordionItemProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
 declare const AccordionTrigger: react.ForwardRefExoticComponent<Omit<AccordionPrimitive.AccordionTriggerProps & react.RefAttributes<HTMLButtonElement>, "ref"> & react.RefAttributes<HTMLButtonElement>>;
@@ -552,7 +1192,7 @@ declare const Input: react.ForwardRefExoticComponent<InputProps & react.RefAttri
 
 declare const buttonVariants: (props?: ({
     variant?: "link" | "default" | "secondary" | "outline" | "destructive" | "outline-subtle" | "ghost" | null | undefined;
-    size?: "default" | "sm" | "lg" | "icon" | "icon-sm" | "icon-lg" | null | undefined;
+    size?: "default" | "sm" | "icon" | "lg" | "icon-sm" | "icon-lg" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
     /** Render the child element as the button (Radix Slot) instead of a <button>. */
@@ -579,6 +1219,28 @@ declare const SidebarProvider: react.ForwardRefExoticComponent<Omit<react.ClassA
     defaultOpen?: boolean;
     open?: boolean;
     onOpenChange?: (open: boolean) => void;
+    /**
+     * Drives the frame's inset treatment from an ANCESTOR the whole frame can
+     * see — `SidebarInset` (#342 fix) reads it as `data-variant` on this
+     * wrapper via `group-data-[variant=inset]/sidebar-wrapper:`, which reaches
+     * regardless of DOM order (unlike the legacy `peer-*` combinator, which
+     * only matches a Sidebar that comes AFTER). Optional and unset by
+     * default, so an existing caller that only sets `variant` on `Sidebar`
+     * is unaffected.
+     */
+    variant?: "sidebar" | "floating" | "inset";
+    /**
+     * Default `"app"` — today's behaviour, byte-identical. `"nested"` is for
+     * a `SidebarProvider` a compound component (e.g. `ContextRail`, ADR 0035
+     * §4) mounts internally so `useSidebar()` reports ITS OWN state to its
+     * own parts: it still provides `SidebarContext` and the two
+     * `--sidebar-width*` custom properties (which survive `display:
+     * contents`), but renders no frame box, no `data-slot`/`data-variant`/
+     * `data-state`, registers no global `⌘B`/`Ctrl+B` listener, and writes no
+     * `sidebar_state` cookie — so a nested rail can never be mistaken for a
+     * second app frame. See the emission table in ADR 0035 §4.
+     */
+    frame?: "app" | "nested";
 }, "ref"> & react.RefAttributes<HTMLDivElement>>;
 declare const Sidebar: react.ForwardRefExoticComponent<Omit<react.ClassAttributes<HTMLDivElement> & react.HTMLAttributes<HTMLDivElement> & {
     side?: "left" | "right";
@@ -587,7 +1249,41 @@ declare const Sidebar: react.ForwardRefExoticComponent<Omit<react.ClassAttribute
 }, "ref"> & react.RefAttributes<HTMLDivElement>>;
 declare const SidebarTrigger: react.ForwardRefExoticComponent<Omit<ButtonProps & react.RefAttributes<HTMLButtonElement>, "ref"> & react.RefAttributes<HTMLButtonElement>>;
 declare const SidebarRail: react.ForwardRefExoticComponent<Omit<react.DetailedHTMLProps<react.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref"> & react.RefAttributes<HTMLButtonElement>>;
-declare const SidebarInset: react.ForwardRefExoticComponent<Omit<react.DetailedHTMLProps<react.HTMLAttributes<HTMLElement>, HTMLElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
+/**
+ * Which sides of the floating "inset" surface get a gutter, once an ancestor
+ * drives the treatment (`SidebarProvider variant="inset"`, or the legacy
+ * immediately-preceding `Sidebar variant="inset"`).
+ *
+ * - `"auto"` (default) — today's rule, unchanged: a gutter on every side
+ *   except the leading edge (`m-2 ms-0`, because the classic layout puts the
+ *   sidebar there), plus the leading edge's gutter returns (`ms-2`) once that
+ *   sidebar collapses and its own gap closes.
+ * - `"none"` — no gutter margin (the unconditional radius/shadow below still
+ *   apply).
+ * - An object — pick sides explicitly. `{ start: true, bottom: true }` is the
+ *   "flush rail" geometry: a leading + bottom gutter only, no top, no
+ *   trailing, because the trailing edge sits flush against a rail — a tab
+ *   must touch the page it belongs to.
+ *
+ * PRECEDENCE (fix round 1, #342): a caller composing BOTH mechanisms at once
+ * — `SidebarProvider variant="inset"` AND a LEFT `Sidebar variant="inset"`,
+ * the shape a left-hand shell (e.g. the sidebar-02 rebuild) uses — never hits
+ * a class-order race, because the ancestor-scoped and legacy peer-scoped
+ * margin classes are BOTH derived from this same `gutter` value, so whenever
+ * both selectors match they emit identical declarations instead of competing
+ * ones; the resolved geometry is always exactly what `gutter` says, decided
+ * by this prop, never by the generated stylesheet's rule order.
+ */
+type SidebarInsetGutter = "auto" | "none" | {
+    top?: boolean;
+    bottom?: boolean;
+    start?: boolean;
+    end?: boolean;
+};
+interface SidebarInsetProps extends ComponentProps<"main"> {
+    gutter?: SidebarInsetGutter;
+}
+declare const SidebarInset: react.ForwardRefExoticComponent<Omit<SidebarInsetProps, "ref"> & react.RefAttributes<HTMLDivElement>>;
 declare const SidebarInput: react.ForwardRefExoticComponent<Omit<InputProps & react.RefAttributes<HTMLInputElement>, "ref"> & react.RefAttributes<HTMLInputElement>>;
 declare const SidebarHeader: react.ForwardRefExoticComponent<Omit<react.DetailedHTMLProps<react.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
 declare const SidebarFooter: react.ForwardRefExoticComponent<Omit<react.DetailedHTMLProps<react.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
@@ -715,12 +1411,18 @@ interface AppShellProps {
     className?: string;
     /** Class for the scrolling main content region. */
     mainClassName?: string;
+    /**
+     * The `<main>` region's id, and the skip link's target. Override it when a
+     * page mounts more than one shell — two elements sharing `main-content`
+     * would make the skip link ambiguous. @default "main-content"
+     */
+    mainId?: string;
 }
 /**
  * App-first layout: fixed-height viewport with an optional sidebar, a top bar,
  * and a scrollable main region. Pure layout — bring your own nav components.
  */
-declare function AppShell({ sidebar, topNav, children, className, mainClassName }: AppShellProps): react.JSX.Element;
+declare function AppShell({ sidebar, topNav, children, className, mainClassName, mainId, }: AppShellProps): react.JSX.Element;
 
 declare const AspectRatio: react.ForwardRefExoticComponent<AspectRatioPrimitive.AspectRatioProps & react.RefAttributes<HTMLDivElement>>;
 
@@ -1097,6 +1799,13 @@ interface ChangeHunk {
     status?: ChangeHunkStatus;
     /** Per-hunk provenance override (overrides the review-level provenance). */
     provenance?: ChangeProvenance;
+    /**
+     * Verification results for this hunk (lint / types / tests / policy hooks).
+     * Purely informational — a failing check never blocks approval, it only
+     * informs the reviewer's decision. Grouped into "Before" / "After" sections
+     * when both phases are present.
+     */
+    checks?: CheckResult[];
 }
 /** State surface exposed by the ChangeReview context. */
 interface ChangeReviewState {
@@ -1192,7 +1901,7 @@ interface ChangeReviewHunkProps extends Omit<HTMLAttributes<HTMLLIElement>, "chi
  * Approval state is signalled with TWO non-color cues:
  * - icon: Check (approved) vs plain toggle (pending)
  * - label: "Approved" badge vs "Approve" button text
- * This ensures the state is clear in all three themes including the low-chroma
+ * This ensures the state is clear in every theme including the low-chroma
  * monochrome surfaces (colorblind-safe).
  */
 declare const ChangeReviewHunk: react.ForwardRefExoticComponent<ChangeReviewHunkProps & react.RefAttributes<HTMLLIElement>>;
@@ -1569,10 +2278,29 @@ declare const Command: react.ForwardRefExoticComponent<CommandProps & react.RefA
  * external input above the tree).
  */
 declare function useCommandActiveItemId(): string | undefined;
-declare function CommandDialog({ children, filter, ...props }: ComponentPropsWithoutRef<typeof Dialog> & {
+type CommandDialogProps = ComponentPropsWithoutRef<typeof Dialog> & {
     /** Custom cmdk ranking (e.g. strict substring instead of fuzzy). */
     filter?: ComponentPropsWithoutRef<typeof Command$1>["filter"];
-}): react.JSX.Element;
+    /**
+     * The dialog's accessible name, rendered `sr-only`.
+     *
+     * OPTIONAL, and deliberately so: callers that already render their own
+     * `DialogTitle` in `children` must not be forced to move it, and
+     * `@elabs-ai/components-ai`'s `VoiceSelectorDialog` passes this whole prop
+     * type straight through. Supply it when you have no visible title — a
+     * `Dialog` with no accessible name is a Radix warning and an axe violation.
+     */
+    title?: ReactNode;
+};
+/**
+ * A ⌘K command palette in a modal `Dialog`.
+ *
+ * This IS the palette presentation of `Command` — there is no separate
+ * "selector" component. For an inline pill that opens the same grouped,
+ * searchable list anchored under itself (a composer footer), reach for
+ * `ModelPicker` instead.
+ */
+declare function CommandDialog({ children, filter, title, ...props }: CommandDialogProps): react.JSX.Element;
 declare const CommandInput: react.ForwardRefExoticComponent<Omit<Omit<Pick<Pick<react.DetailedHTMLProps<react.InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "key" | keyof react.InputHTMLAttributes<HTMLInputElement>> & {
     ref?: React.Ref<HTMLInputElement>;
 } & {
@@ -1630,6 +2358,31 @@ declare const CommandItem: react.ForwardRefExoticComponent<Omit<{
 } & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
 declare function CommandShortcut({ className, ...props }: HTMLAttributes<HTMLSpanElement>): react.JSX.Element;
 
+interface CommandTriggerProps extends ComponentProps<"button"> {
+    /** The visible and announced label. Defaults to "Search". */
+    label?: string;
+    /** The shortcut hint. Defaults to the platform-correct ⌘ K / Ctrl K. */
+    shortcut?: string;
+}
+/**
+ * The command-palette opener, shaped like a search field: label left, shortcut
+ * pinned right, collapsing to the icon alone under `sm`.
+ *
+ * The button’s accessible name comes entirely from `aria-label` — that is what
+ * stops the `Kbd`’s shortcut glyph from concatenating into it (#117); a
+ * non-empty `aria-label` short-circuits accessible-name computation before the
+ * DOM is ever consulted. The visible label and the `Kbd` are ALSO marked
+ * `aria-hidden`, per `accessibility.md`, as defence in depth: if `aria-label`
+ * is ever dropped, that turns a silent regression into a loud one — an empty
+ * accessible name rather than a plausible wrong one. They do not do the work
+ * themselves.
+ *
+ * `shortcut` reads `navigator` at render time when omitted, which can differ
+ * between server and client — a consumer that server-renders this component
+ * should pass `shortcut` explicitly to avoid a hydration mismatch.
+ */
+declare const CommandTrigger: react.ForwardRefExoticComponent<Omit<CommandTriggerProps, "ref"> & react.RefAttributes<HTMLButtonElement>>;
+
 interface ConfirmDialogProps {
     /** Controlled open state — the app owns it. */
     open: boolean;
@@ -1724,6 +2477,77 @@ declare const ContextMenuLabel: react.ForwardRefExoticComponent<Omit<ContextMenu
 declare const ContextMenuSeparator: react.ForwardRefExoticComponent<Omit<ContextMenuPrimitive.ContextMenuSeparatorProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
 declare function ContextMenuShortcut({ className, ...props }: HTMLAttributes<HTMLSpanElement>): react.JSX.Element;
 
+/** One switchable section of a `ContextRail`. */
+interface ContextRailSection {
+    /** Stable identifier — the switcher's `SidebarMenuButton` key and the
+     * value reported to `activeSectionId`/`onActiveSectionChange`. */
+    id: string;
+    /** Visible label. Feeds the switcher entry's accessible name and the
+     * body's heading — never rendered as visible text in the switcher
+     * itself, which stays icon-only in every state. */
+    label: string;
+    /** Icon shown in the switcher, in both the expanded and collapsed
+     * (48px icon strip) presentations. Decorative — wrapped `aria-hidden`. */
+    icon: ReactNode;
+    /** Optional count badge. Visible in BOTH states (unlike
+     * `SidebarMenuBadge`, which hides under `collapsible="icon"`) and folded
+     * into the switcher entry's accessible name, e.g. "Sources 3 items". */
+    count?: number;
+    /** Rendered only while this section is active — the rail mounts exactly
+     * one section's content at a time. */
+    content: ReactNode;
+    /** Disables the switcher entry; clicking it is a no-op. */
+    disabled?: boolean;
+}
+interface ContextRailProps extends Omit<ComponentProps<"div">, "onSelect" | "children"> {
+    /** The sections the switcher can pick between. An empty array renders
+     * the `empty` slot instead of a switcher. */
+    sections: ContextRailSection[];
+    /** Controlled active section id. */
+    activeSectionId?: string;
+    /** Initial active section id (uncontrolled). Defaults to `sections[0]`. */
+    defaultActiveSectionId?: string;
+    /** Fires with the clicked section's id — including a re-click of the
+     * already-active section (open/close is a separate concern, see `open`). */
+    onActiveSectionChange?: (sectionId: string) => void;
+    /** Controlled expanded/collapsed state. Clicking the ACTIVE switcher
+     * entry toggles this; clicking an INACTIVE entry sets it `true`. */
+    open?: boolean;
+    /** Initial expanded/collapsed state (uncontrolled). Defaults to `true`. */
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** Expanded width, published as `--sidebar-width`. @default "20rem" */
+    width?: string;
+    /** Replaces the default localized empty state when `sections` is empty. */
+    empty?: ReactNode;
+    /**
+     * Below this viewport width the rail renders its own 48px strip plus a
+     * `Sheet` for the expanded body instead of mounting `Sidebar` — dev-only
+     * warns if set below 768. @default 768
+     */
+    overlayBreakpoint?: number;
+}
+/**
+ * A right-hand rail whose collapsed state is a 48px icon strip that doubles
+ * as its own section switcher. Built on `Sidebar`/`SidebarProvider`
+ * (`frame="nested"`, ADR 0035 §4) as an implementation detail — the public
+ * seam is `sections` + `activeSectionId`/`onActiveSectionChange` (which
+ * section) and `open`/`onOpenChange` (expanded or collapsed), both
+ * controlled/uncontrolled. Below `overlayBreakpoint` it renders its own
+ * strip plus a `Sheet` instead of mounting `Sidebar`. See
+ * `docs/ADR/0035-context-rail-and-side-dock.md` §3.
+ *
+ * Known constraint (task-11f-brief.md Finding 5): below `overlayBreakpoint`
+ * the expanded body is a `Sheet`, which always spans the full browser
+ * viewport, while the persistent 48px strip is bounded by whatever container
+ * the host gives the rail. In a host container shorter than the viewport
+ * (any app shell with a toolbar above the rail), the strip stops mid-screen
+ * while the sheet keeps going — the two read as unrelated surfaces. Give
+ * `ContextRail` a full-viewport-height host container below the breakpoint
+ * to avoid this seam.
+ */
+declare const ContextRail: react.ForwardRefExoticComponent<Omit<ContextRailProps, "ref"> & react.RefAttributes<HTMLDivElement>>;
+
 interface CopyableValueProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "value" | "children"> {
     /**
      * The EXACT text written to the clipboard — the unrounded, un-abbreviated
@@ -1849,7 +2673,12 @@ declare function DropdownMenuShortcut({ className, ...props }: React.HTMLAttribu
 interface EmptyStateProps {
     title: ReactNode;
     description?: ReactNode;
-    /** Optional icon/illustration shown above the title. */
+    /**
+     * Optional icon shown above the title, clamped to a fixed 40×40 (this
+     * wrapper only ever forwards `icon` to `StatePanel`, never `illustration`
+     * — for a larger, unclamped illustration use
+     * `StatePanel kind="empty" illustration={...}` directly).
+     */
     icon?: ReactNode;
     /** Primary/secondary actions. */
     actions?: ReactNode;
@@ -1981,14 +2810,129 @@ interface ExpandDialogProps extends Omit<ExpandDialogContentProps, "title" | "ch
  */
 declare const ExpandDialog: react.ForwardRefExoticComponent<ExpandDialogProps & react.RefAttributes<HTMLDivElement>>;
 
+interface FieldRootProps extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * Whether the field is currently invalid. Drives `aria-invalid` on every
+     * `FieldControl` and error styling on `FieldLabel` — independent of
+     * whether a `FieldError` with content is actually mounted, so a caller can
+     * mark the control invalid before its message has settled.
+     */
+    invalid?: boolean;
+    /** Whether the field is required. Drives `aria-required` on every `FieldControl`. */
+    required?: boolean;
+}
+/**
+ * Compound-anatomy field: `FieldRoot` owns id generation and `aria-describedby`
+ * composition; `FieldLabel`/`FieldControl`/`FieldDescription`/`FieldError` read
+ * that state from context and can be composed in ANY order/layout — including
+ * more than one `FieldControl` in one row (e.g. first/last name) or a
+ * `FieldDescription` placed before the control. Mirrors the same accessibility
+ * wiring `FieldRow` (`../field-row`) already validated (id/`aria-describedby`/
+ * `aria-invalid`/`role="alert"`), adapted to a shared lifted-state context so
+ * it holds across independently-composed parts; `FieldRow` remains the
+ * convenience wrapper for the common single-control case and is unaffected by
+ * this addition (#43).
+ *
+ * @example
+ * ```tsx
+ * <FieldRoot invalid={!!error} required>
+ *   <FieldLabel>{label}</FieldLabel>
+ *   <FieldControl><Input /></FieldControl>
+ *   <FieldDescription>{helpText}</FieldDescription>
+ *   <FieldError>{error}</FieldError>
+ * </FieldRoot>
+ * ```
+ */
+declare const FieldRoot: react.ForwardRefExoticComponent<FieldRootProps & react.RefAttributes<HTMLDivElement>>;
+declare const FieldLabel: react.ForwardRefExoticComponent<Omit<Omit<_radix_ui_react_label.LabelProps & react.RefAttributes<HTMLLabelElement>, "ref"> & react.RefAttributes<HTMLLabelElement>, "ref"> & react.RefAttributes<HTMLLabelElement>>;
+interface FieldControlProps {
+    /**
+     * The single field control (`Input`, `Textarea`, `Select`, …). Receives
+     * `id`/`aria-describedby`/`aria-invalid`/`aria-required` via a Radix
+     * `Slot` — must be a single element that forwards those props to a real
+     * form control. Compose more than one `FieldControl` inside one
+     * `FieldRoot` for a multi-control row (each gets its own independent id;
+     * give every control but the first its own explicit `id`, the same way
+     * you would for any two form controls that must not collide). `FieldLabel`
+     * can only associate with ONE control (the first to mount), so give every
+     * OTHER control in the row its own `aria-label` — a shared visual label
+     * plus a placeholder is not a real accessible name for the rest.
+     */
+    children: ReactElement<{
+        id?: string;
+        "aria-describedby"?: string;
+    }>;
+}
+declare const FieldControl: react.ForwardRefExoticComponent<FieldControlProps & react.RefAttributes<HTMLElement>>;
+/**
+ * Optional field help text. Renders nothing — and registers no
+ * `aria-describedby` reference — when `children` is falsy (`false`/`0`/`""`/
+ * `null`/`undefined`), an empty array, or an array containing only falsy
+ * values (`{list.map(...)}` on an empty list; `[a && "x", b && "y"]` with
+ * both false) — matching `FieldRow`'s `description ? … : null` convention:
+ * `{hint && <FieldDescription>{hint}</FieldDescription>}` is the supported
+ * way to express "no description".
+ *
+ * **Known limit:** a child that is itself a COMPONENT that renders nothing
+ * (returns `null`/an empty fragment) is not knowable from the element
+ * before render, so it still produces an empty paragraph that
+ * `aria-describedby` points at. `FieldRow` and the wider React ecosystem
+ * share this limit — pass a falsy child instead of a component that may
+ * render nothing.
+ */
+declare const FieldDescription: react.ForwardRefExoticComponent<HTMLAttributes<HTMLParagraphElement> & react.RefAttributes<HTMLParagraphElement>>;
+/**
+ * Validation error text, announced via `role="alert"`. Renders nothing —
+ * and registers no `aria-describedby` reference — when `children` is falsy
+ * (`false`/`0`/`""`/`null`/`undefined`), an empty array, or an array
+ * containing only falsy values (`{errors.map(...)}` on an empty array is
+ * exactly how a real form renders "no errors") — matching `FieldRow`'s
+ * `error ? … : null` convention: `{error && <FieldError>{error}</FieldError>}`
+ * is the supported way to express "no error".
+ *
+ * **Known limit:** a child that is itself a COMPONENT that renders nothing
+ * (returns `null`/an empty fragment) is not knowable from the element
+ * before render, so it still produces an empty `role="alert"` element that
+ * `aria-describedby` points at (a screen reader announces an empty alert).
+ * `FieldRow` and the wider React ecosystem share this limit — pass a falsy
+ * child instead of a component that may render nothing.
+ */
+declare const FieldError: react.ForwardRefExoticComponent<HTMLAttributes<HTMLParagraphElement> & react.RefAttributes<HTMLParagraphElement>>;
+
 interface FieldRowProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
     /** Field label — rendered as a real `<label>`, click-to-focus associated with the control. */
     label: ReactNode;
-    /** Optional help/description text, always visible (not gated by an error). */
+    /**
+     * Optional help/description text, always visible (not gated by an error).
+     * Renders nothing — and contributes no id to `aria-describedby` — when
+     * `description` is falsy (`false`/`0`/`""`/`null`/`undefined`), an empty
+     * array, or an array containing only falsy values (`{list.map(...)}` on an
+     * empty list; `[a && "x", b && "y"]` with both false).
+     *
+     * **Known limit:** a value that is itself a COMPONENT that renders nothing
+     * (returns `null`/an empty fragment) is not knowable before render, so it
+     * still produces an empty paragraph that `aria-describedby` points at.
+     * `FieldDescription` and the wider React ecosystem share this limit — pass
+     * a falsy value instead of a component that may render nothing, e.g.
+     * `description={hasHint ? hintText : undefined}`, never
+     * `description={<MaybeRendersNull />}`.
+     */
     description?: ReactNode;
     /**
      * Validation error text. When present: sets `aria-invalid` on the control,
      * is appended to `aria-describedby`, and is announced via `role="alert"`.
+     * Renders nothing — and leaves `aria-invalid="false"` — when `error` is
+     * falsy (`false`/`0`/`""`/`null`/`undefined`), an empty array, or an array
+     * containing only falsy values (`{errors.map(...)}` on an empty list — the
+     * idiomatic "no errors" shape).
+     *
+     * **Known limit:** a value that is itself a COMPONENT that renders nothing
+     * (returns `null`/an empty fragment) is not knowable before render, so it
+     * still produces an empty `role="alert"` element that `aria-describedby`
+     * points at. `FieldError` and the wider React ecosystem share this limit —
+     * pass a falsy value instead of a component that may render nothing, e.g.
+     * `error={hasError ? message : undefined}`, never
+     * `error={<MaybeRendersNull />}`.
      */
     error?: ReactNode;
     /**
@@ -2104,26 +3048,6 @@ interface FileUploadItemProps extends HTMLAttributes<HTMLLIElement> {
  */
 declare const FileUploadItem: react.ForwardRefExoticComponent<FileUploadItemProps & react.RefAttributes<HTMLLIElement>>;
 
-declare const Form: <TFieldValues extends FieldValues, TContext = any, TTransformedValues = TFieldValues>({ children, watch, getValues, getFieldState, setError, clearErrors, setValue, setValues, trigger, formState, resetField, reset, handleSubmit, unregister, control, register, setFocus, subscribe, }: react_hook_form.FormProviderProps<TFieldValues, TContext, TTransformedValues>) => React.JSX.Element;
-declare function FormField<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>>(props: ControllerProps<TFieldValues, TName>): react.JSX.Element;
-declare function useFormField(): {
-    invalid: boolean;
-    isDirty: boolean;
-    isTouched: boolean;
-    isValidating: boolean;
-    error?: react_hook_form.FieldError;
-    id: string;
-    name: string;
-    formItemId: string;
-    formDescriptionId: string;
-    formMessageId: string;
-};
-declare const FormItem: react.ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & react.RefAttributes<HTMLDivElement>>;
-declare const FormLabel: react.ForwardRefExoticComponent<Omit<Omit<_radix_ui_react_label.LabelProps & react.RefAttributes<HTMLLabelElement>, "ref"> & react.RefAttributes<HTMLLabelElement>, "ref"> & react.RefAttributes<HTMLLabelElement>>;
-declare const FormControl: react.ForwardRefExoticComponent<Omit<_radix_ui_react_slot.SlotProps & react.RefAttributes<HTMLElement>, "ref"> & react.RefAttributes<HTMLElement>>;
-declare const FormDescription: react.ForwardRefExoticComponent<HTMLAttributes<HTMLParagraphElement> & react.RefAttributes<HTMLParagraphElement>>;
-declare const FormMessage: react.ForwardRefExoticComponent<HTMLAttributes<HTMLParagraphElement> & react.RefAttributes<HTMLParagraphElement>>;
-
 declare const HoverCard: react.FC<HoverCardPrimitive.HoverCardProps>;
 declare const HoverCardTrigger: react.ForwardRefExoticComponent<HoverCardPrimitive.HoverCardTriggerProps & react.RefAttributes<HTMLAnchorElement>>;
 declare const HoverCardContent: react.ForwardRefExoticComponent<Omit<HoverCardPrimitive.HoverCardContentProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
@@ -2200,6 +3124,43 @@ declare const InputOTPSeparator: react.ForwardRefExoticComponent<react.HTMLAttri
 /** Keyboard key hint, e.g. <Kbd>⌘K</Kbd>. */
 declare const Kbd: react.ForwardRefExoticComponent<HTMLAttributes<HTMLElement> & react.RefAttributes<HTMLElement>>;
 
+/** One keyboard shortcut: the action it performs and its ordered key tokens. */
+interface Shortcut {
+    action: string;
+    /** Ordered key tokens, e.g. `["⌘", "K"]`. Rendered via {@link Kbd}. */
+    keys: string[];
+}
+/**
+ * A named group of shortcuts. There is deliberately no `count` field — the
+ * displayed count is always derived from `items.length`, never supplied by
+ * the caller (see issue #113: brainless, the upstream this was adapted from,
+ * shipped a `count` with no `items`, an honestly-unverifiable number).
+ */
+interface ShortcutGroup {
+    id: string;
+    label: string;
+    items: Shortcut[];
+    /** Whether this group starts expanded when search is inactive. @default false */
+    defaultOpen?: boolean;
+}
+interface KeyboardShortcutsProps extends Omit<ComponentProps<"div">, "onChange"> {
+    groups: ShortcutGroup[];
+    /** Show the built-in search field. @default true */
+    searchable?: boolean;
+    /** Controlled search query, if the app owns it. */
+    query?: string;
+    onQueryChange?: (query: string) => void;
+}
+/**
+ * A grouped, searchable presentation of a shortcut set. Renders **content
+ * only** — the app supplies the `Dialog`/`Sheet` shell, so the same
+ * component works in a modal, a settings page or a sidebar.
+ *
+ * Group counts are always derived from `items.length` (or the number of
+ * matching items while a search is active) — never a value passed in.
+ */
+declare const KeyboardShortcuts: react.ForwardRefExoticComponent<Omit<KeyboardShortcutsProps, "ref"> & react.RefAttributes<HTMLDivElement>>;
+
 interface KeyValueRow {
     key: string;
     value: string;
@@ -2329,12 +3290,44 @@ interface ListEditorProps extends Omit<HTMLAttributes<HTMLDivElement>, "onChange
  * keyboard-operable reorder (move-up/move-down buttons, not drag-and-drop —
  * no drag library exists in the monorepo and none should be added for this).
  *
- * Controlled via `value`/`onValueChange`; uncontrolled via `defaultValue`.
+ * Controlled via `value`/`onValueChange`; uncontrolled via `defaultValue`.
+ */
+declare const ListEditor: react.ForwardRefExoticComponent<ListEditorProps & react.RefAttributes<HTMLDivElement>>;
+
+/**
+ * ICU cardinal-plural category, per `Intl.PluralRules` ("zero" | "one" | "two"
+ * | "few" | "many" | "other"). Locales vary in which categories they use —
+ * English has only "one"/"other"; Polish and Russian also use "few"/"many" —
+ * so a `PluralMessage` may omit any category it doesn't need. `"other"` is the
+ * universal fallback every locale defines.
+ */
+type PluralCategory = Intl.LDMLPluralRule;
+/**
+ * A per-count message: one string per plural category, selected at render
+ * time via `Intl.PluralRules(locale).select(count)`. Each string still
+ * supports the same `{name}`-style interpolation as a plain message.
+ * Note: when passed to `t()`, `count` in `vars` must be a number, not a
+ * numeric string, to select the correct plural category.
+ */
+type PluralMessage = Partial<Record<PluralCategory, string>>;
+/** A single message value: a plain string, or a plural-form map. */
+type MessageValue = string | PluralMessage;
+/**
+ * Shipped English (en-US) default microcopy bundle.
+ *
+ * Keys are intentionally terse, semantic, and framework-agnostic so they
+ * translate cleanly into any target locale. Keep this list small and real —
+ * only add a key here when a component actually needs it.
  */
-declare const ListEditor: react.ForwardRefExoticComponent<ListEditorProps & react.RefAttributes<HTMLDivElement>>;
+declare const DEFAULT_MESSAGES: Record<string, MessageValue>;
 
-/** A flat map of string keys to their translated values. */
-type Messages = Record<string, string>;
+/**
+ * A flat map of string keys to their translated values — a plain string, or a
+ * `PluralMessage` (one string per ICU cardinal-plural category, e.g.
+ * `{ one: "{count} item", other: "{count} items" }`) for microcopy whose
+ * wording changes with a count. See `PluralMessage` in `./messages`.
+ */
+type Messages = Record<string, MessageValue>;
 interface LocaleContextValue {
     /** BCP-47 locale tag, e.g. "en-US", "ar-EG", "de-DE". */
     locale: string;
@@ -2342,8 +3335,13 @@ interface LocaleContextValue {
     dir: "ltr" | "rtl";
     /**
      * Translate a key.
-     * Falls back to: consumer messages → English default → the key itself.
-     * Supports simple `{name}`-style variable interpolation.
+     * Falls back to: an external `translate` resolver (if the provider was
+     * given one) → consumer `messages` → English default → the key itself.
+     * Supports simple `{name}`-style variable interpolation, and ICU
+     * cardinal-plural forms (`Intl.PluralRules`) when the resolved message is a
+     * `PluralMessage` map and `vars.count` is a number. Note: `count` must be a
+     * number, not a numeric string (e.g., `count: 3`, not `count: "3"`) to select
+     * the correct plural category.
      */
     t: (key: string, vars?: Record<string, string | number>) => string;
     /** Format a number using the active locale. Memoized per locale+opts hash. */
@@ -2368,6 +3366,21 @@ interface LocaleProviderProps {
      * to the English bundle.
      */
     messages?: Messages;
+    /**
+     * Optional external resolver — hand brand-ui's microcopy off to an app's own
+     * i18n runtime (next-intl, react-intl, i18next, …) instead of maintaining a
+     * second, flattened message catalogue. Called with the raw key and vars
+     * (not pre-interpolated), so a real ICU formatter gets real values and can
+     * do its own pluralization/number/date formatting.
+     *
+     * Return a string to use it as-is (brand-ui does NOT re-run its own
+     * `{name}` interpolation on it — the app's runtime already formatted it).
+     * Return `undefined`/`null` to decline a key; brand-ui then falls back to
+     * `messages` → `DEFAULT_MESSAGES` → the raw key, in that order — so a
+     * resolver only needs to cover the keys it actually wants to override.
+     * See `docs/I18N.md`.
+     */
+    translate?: (key: string, vars?: Record<string, string | number>) => string | undefined | null;
     children: ReactNode;
 }
 /**
@@ -2382,7 +3395,7 @@ interface LocaleProviderProps {
  *   every Radix primitive reads via context regardless of DOM position (ADR-0014).
  *   The `<div dir={dir}>` continues to carry direction for non-Radix content.
  */
-declare function LocaleProvider({ locale, dir, messages, children, }: LocaleProviderProps): react.JSX.Element;
+declare function LocaleProvider({ locale, dir, messages, translate, children, }: LocaleProviderProps): react.JSX.Element;
 /**
  * Read the active locale, direction, `t`, `formatNumber`, and `formatDate`.
  *
@@ -2392,15 +3405,6 @@ declare function LocaleProvider({ locale, dir, messages, children, }: LocaleProv
  */
 declare function useLocale(): LocaleContextValue;
 
-/**
- * Shipped English (en-US) default microcopy bundle.
- *
- * Keys are intentionally terse, semantic, and framework-agnostic so they
- * translate cleanly into any target locale. Keep this list small and real —
- * only add a key here when a component actually needs it.
- */
-declare const DEFAULT_MESSAGES: Record<string, string>;
-
 interface LoadingStateProps {
     /** Accessible status label. Defaults to "Loading…". */
     label?: ReactNode;
@@ -2806,14 +3810,22 @@ interface ModelPickerProps extends Omit<HTMLAttributes<HTMLDivElement>, "onSelec
     open?: boolean;
     /** Fires whenever the popover would open/close — a trigger click, or a row select. */
     onOpenChange?: (open: boolean) => void;
+    /**
+     * Rendered inside the popover BELOW the list — a persistent action row that is
+     * not one of the options (a free-text entry, a "browse…" affordance).
+     * Outside `CommandList` on purpose: it must not be filtered by the search query
+     * and must not participate in cmdk's roving selection.
+     */
+    footer?: ReactNode;
 }
 /**
  * A compact pill that opens a grouped, searchable target list anchored under
  * itself — sized to sit in a composer footer.
  *
- * The inline sibling of `@elabs-ai/components-ai`'s `ModelSelector`,
- * which is the same `Command` internals in a modal `Dialog`. Reach for that one
- * for a full command palette; reach for this one for an in-place picker.
+ * **Which one to reach for.** An inline pill in a composer footer, anchored
+ * under itself → this component. A full ⌘K palette → compose `CommandDialog` +
+ * `Command*` from this package directly; there is no separate "selector"
+ * component wrapping them.
  *
  * **`Command` lives inside a `Popover`, never a `DropdownMenu`, and that is not
  * a stylistic choice.** `DropdownMenuContent` owns roving tabindex and its own
@@ -2950,12 +3962,45 @@ interface NavNotificationsProps {
     notifications: NavNotification[];
     /** Label for the "view all" footer item. @default "View all notifications" */
     viewAllLabel?: string;
+    /**
+     * Which side of the trigger the menu opens on.
+     *
+     * The default is `"right"`, which is right for the surface this component was
+     * extracted from — a bell sitting in a left-hand nav rail. It is WRONG for a
+     * trigger at the end of a top bar: Radix collision-handling then flips the
+     * menu back across the trigger and it covers the controls beside it. Set
+     * `side="bottom"` (usually with `align="end"`) for a top-bar bell.
+     *
+     * @default "right"
+     */
+    side?: ComponentProps<typeof DropdownMenuContent>["side"];
+    /**
+     * How the menu aligns along that side. Radix's own default is `"center"`;
+     * pass `"end"` so a top-bar menu hangs from the trigger's outer edge instead
+     * of straddling it.
+     */
+    align?: ComponentProps<typeof DropdownMenuContent>["align"];
+    /**
+     * Extra classes for the component ROOT — the bell trigger — merged last, so a
+     * caller can override the shipped `rounded-full` (`component-api.md`).
+     *
+     * There is deliberately NO seam for the portalled menu surface: nothing needs
+     * one today, and an unused prop is a worse API than a missing one. The one
+     * thing a caller used to reach for it (dropping the rail's vertical inset for
+     * a top-bar menu) is now derived from `side` instead — see below.
+     */
+    className?: string;
 }
 /**
- * Sidebar notifications dropdown button. Shared primitive from sidebar-02 (issue #99).
- * Renders a bell-icon ghost button that opens a dropdown listing recent notifications.
+ * Notifications dropdown button. Shared primitive from sidebar-02 (issue #99).
+ * Renders a bell-icon ghost button that opens a dropdown listing recent
+ * notifications.
+ *
+ * Placement is caller-owned via `side`/`align`; the defaults are the original
+ * rail placement, so every existing call site renders unchanged. `className`
+ * styles the trigger, not the menu.
  */
-declare function NavNotifications({ notifications, viewAllLabel, }: NavNotificationsProps): react.JSX.Element;
+declare function NavNotifications({ notifications, viewAllLabel, side, align, className, }: NavNotificationsProps): react.JSX.Element;
 
 interface NavUserUser {
     name: string;
@@ -2978,14 +4023,14 @@ declare function NavUser({ user }: NavUserProps): react.JSX.Element;
 
 declare const NavigationMenu: react.ForwardRefExoticComponent<Omit<NavigationMenuPrimitive.NavigationMenuProps & react.RefAttributes<HTMLElement>, "ref"> & react.RefAttributes<HTMLElement>>;
 declare const NavigationMenuList: react.ForwardRefExoticComponent<Omit<NavigationMenuPrimitive.NavigationMenuListProps & react.RefAttributes<HTMLUListElement>, "ref"> & react.RefAttributes<HTMLUListElement>>;
-declare const NavigationMenuItem: react.ForwardRefExoticComponent<NavigationMenuPrimitive.NavigationMenuItemProps & react.RefAttributes<HTMLLIElement>>;
+declare const NavigationMenuItem: react.ForwardRefExoticComponent<Omit<NavigationMenuPrimitive.NavigationMenuItemProps & react.RefAttributes<HTMLLIElement>, "ref"> & react.RefAttributes<HTMLLIElement>>;
 declare const navigationMenuTriggerStyle: (props?: class_variance_authority_types.ClassProp | undefined) => string;
 declare const NavigationMenuTrigger: react.ForwardRefExoticComponent<Omit<NavigationMenuPrimitive.NavigationMenuTriggerProps & react.RefAttributes<HTMLButtonElement>, "ref"> & react.RefAttributes<HTMLButtonElement>>;
 declare const NavigationMenuContent: react.ForwardRefExoticComponent<Omit<NavigationMenuPrimitive.NavigationMenuContentProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
 declare const NavigationMenuLink: react.ForwardRefExoticComponent<NavigationMenuPrimitive.NavigationMenuLinkProps & react.RefAttributes<HTMLAnchorElement>>;
 declare const NavigationMenuViewport: react.ForwardRefExoticComponent<Omit<NavigationMenuPrimitive.NavigationMenuViewportProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
 
-interface PageShellProps {
+interface PageShellProps extends ComponentProps<"div"> {
     children: ReactNode;
     /** Optional header row (often a <SectionHeader />, or a <ViewToolbar> — see headerVariant). */
     header?: ReactNode;
@@ -3004,11 +4049,42 @@ interface PageShellProps {
     headerVariant?: "default" | "toolbar";
     /** Constrain content width. Defaults to "xl". */
     width?: "md" | "lg" | "xl" | "full";
+    /**
+     * "body" (default) — the page scrolls with the document. Byte-identical to
+     * the pre-#R6 behaviour; existing callers are unaffected.
+     * "content" — this container is the scroll port. Use inside a `SidebarInset`
+     * whose height is already bounded, so the top bar stays put. Defaults its own
+     * `tabIndex` to `0` (a scroll container must be keyboard-operable — WCAG
+     * 2.1.1, axe `scrollable-region-focusable`), following the `DialogBody`
+     * precedent; pass `tabIndex={-1}` to opt out when the content already
+     * supplies its own focusable child.
+     * "fill" — fills its parent and scrolls nothing itself; a child (a table, a
+     * canvas) owns the scrolling — and owns that child's keyboard reachability
+     * too, the same way.
+     */
+    scroll?: "body" | "content" | "fill";
+    /**
+     * Reserve a fixed header row so a page title lands at identical coordinates
+     * on every route, whether or not that route has a header. Default `false`.
+     *
+     * The row's height is a component-local CSS variable —
+     * `--page-shell-header-gutter`, declared on the root, default `--spacing(12)`
+     * (3rem / 48px at a 16px root — the height a one-line title already occupies
+     * inside the `headerVariant="toolbar"` bar's own `py-3`). It is NOT a theme
+     * token (`pnpm theme-parity:check` does not see it); retune it per surface the
+     * same way `--focus-ring-color` is retargeted elsewhere in this package:
+     * `<PageShell headerGutter className="[--page-shell-header-gutter:--spacing(16)]" />`.
+     *
+     * When `true` the header row renders **even if `header` is omitted** — that
+     * empty row is the whole mechanism, and it is what `headerGutter={false}`
+     * must never produce.
+     */
+    headerGutter?: boolean;
     className?: string;
     contentClassName?: string;
 }
 /** Page-level content container with consistent padding and max width. */
-declare function PageShell({ children, header, headerVariant, width, className, contentClassName, }: PageShellProps): react.JSX.Element;
+declare const PageShell: react.ForwardRefExoticComponent<Omit<PageShellProps, "ref"> & react.RefAttributes<HTMLDivElement>>;
 
 declare function Pagination({ className, ...props }: ComponentProps<"nav">): react.JSX.Element;
 declare const PaginationContent: react.ForwardRefExoticComponent<Omit<react.DetailedHTMLProps<react.HTMLAttributes<HTMLUListElement>, HTMLUListElement>, "ref"> & react.RefAttributes<HTMLUListElement>>;
@@ -3074,7 +4150,7 @@ interface RatingProps extends Omit<HTMLAttributes<HTMLDivElement>, "onChange" |
 declare const Rating: react.ForwardRefExoticComponent<RatingProps & react.RefAttributes<HTMLDivElement>>;
 
 declare function ResizablePanelGroup({ className, ...props }: React.ComponentProps<typeof ResizablePrimitive.PanelGroup>): react.JSX.Element;
-declare const ResizablePanel: react.ForwardRefExoticComponent<Omit<react.HTMLAttributes<HTMLAnchorElement | HTMLElement | HTMLDivElement | HTMLObjectElement | HTMLTitleElement | HTMLBodyElement | HTMLMetaElement | HTMLParagraphElement | HTMLSelectElement | HTMLLinkElement | HTMLAreaElement | HTMLAudioElement | HTMLBaseElement | HTMLQuoteElement | HTMLBRElement | HTMLButtonElement | HTMLCanvasElement | HTMLTableColElement | HTMLDataElement | HTMLDataListElement | HTMLModElement | HTMLDetailsElement | HTMLDialogElement | HTMLDListElement | HTMLEmbedElement | HTMLFieldSetElement | HTMLFormElement | HTMLHeadingElement | HTMLHeadElement | HTMLHRElement | HTMLHtmlElement | HTMLIFrameElement | HTMLImageElement | HTMLInputElement | HTMLLabelElement | HTMLLegendElement | HTMLLIElement | HTMLMapElement | HTMLMeterElement | HTMLOListElement | HTMLOptGroupElement | HTMLOptionElement | HTMLOutputElement | HTMLPreElement | HTMLProgressElement | HTMLScriptElement | HTMLSlotElement | HTMLSourceElement | HTMLSpanElement | HTMLStyleElement | HTMLTableElement | HTMLTableSectionElement | HTMLTableCellElement | HTMLTemplateElement | HTMLTextAreaElement | HTMLTimeElement | HTMLTableRowElement | HTMLTrackElement | HTMLUListElement | HTMLVideoElement | HTMLTableCaptionElement | HTMLMenuElement | HTMLPictureElement>, "id" | "onResize"> & {
+declare const ResizablePanel: react.ForwardRefExoticComponent<Omit<react.HTMLAttributes<HTMLAnchorElement | HTMLElement | HTMLDivElement | HTMLSpanElement | HTMLObjectElement | HTMLTitleElement | HTMLBodyElement | HTMLMetaElement | HTMLParagraphElement | HTMLSelectElement | HTMLLinkElement | HTMLAreaElement | HTMLAudioElement | HTMLBaseElement | HTMLQuoteElement | HTMLBRElement | HTMLButtonElement | HTMLCanvasElement | HTMLTableColElement | HTMLDataElement | HTMLDataListElement | HTMLModElement | HTMLDetailsElement | HTMLDialogElement | HTMLDListElement | HTMLEmbedElement | HTMLFieldSetElement | HTMLFormElement | HTMLHeadingElement | HTMLHeadElement | HTMLHRElement | HTMLHtmlElement | HTMLIFrameElement | HTMLImageElement | HTMLInputElement | HTMLLabelElement | HTMLLegendElement | HTMLLIElement | HTMLMapElement | HTMLMeterElement | HTMLOListElement | HTMLOptGroupElement | HTMLOptionElement | HTMLOutputElement | HTMLPreElement | HTMLProgressElement | HTMLScriptElement | HTMLSlotElement | HTMLSourceElement | HTMLStyleElement | HTMLTableElement | HTMLTableSectionElement | HTMLTableCellElement | HTMLTemplateElement | HTMLTextAreaElement | HTMLTimeElement | HTMLTableRowElement | HTMLTrackElement | HTMLUListElement | HTMLVideoElement | HTMLTableCaptionElement | HTMLMenuElement | HTMLPictureElement>, "id" | "onResize"> & {
     className?: string | undefined;
     collapsedSize?: number | undefined;
     collapsible?: boolean | undefined;
@@ -3127,6 +4203,1112 @@ interface RevealGroupProps extends HTMLAttributes<HTMLDivElement>, VariantProps<
  */
 declare const RevealGroup: react.ForwardRefExoticComponent<RevealGroupProps & react.RefAttributes<HTMLDivElement>>;
 
+/**
+ * schema-form-spec.ts — Serializable FormSpec for SchemaForm.
+ *
+ * SchemaForm is the GENERAL, app-UI spec-driven form renderer (issue #22):
+ * describe a configuration form as data, render it. It is the sibling of
+ * `@elabs-ai/components-ai`'s `MessageForm` / `fieldSpecSchema` — NOT a
+ * generalization of it. The two are deliberately separate schemas because
+ * they carry different trust models:
+ *
+ * - `MessageForm`'s `fieldSpecSchema` (`packages/ai/src/message-form-spec.ts`)
+ *   is what an LLM tool-call emits inside a chat message. Its vocabulary is
+ *   intentionally the SAFE subset — flat scalars only, no file input, no
+ *   password/credential format — so a model can never ask a user to hand it
+ *   a file or a secret through a chat-rendered form.
+ * - `SchemaForm`'s `fieldSpecSchema` here is DEVELOPER-AUTHORED: a product
+ *   describes an integration/config form (connector settings, environment
+ *   variables, auth method) as data instead of hand-writing it. That is a
+ *   fundamentally different trust boundary, so it is allowed the fuller
+ *   vocabulary Onyx-style connector forms need: `list`, `key-value`, `file`,
+ *   and grouped alternative field sets (`group`, tabs or advanced-collapsed).
+ *
+ * Shares its overall shape (fields/values/validate/normalize) with
+ * `message-form-spec.ts` by convention, not by import — merging them into one
+ * union would either smuggle `file`/`group` into the chat-safe schema or
+ * strip the safety comment from this one. See the issue-#22 result file for
+ * the full reasoning.
+ */
+
+/** A single enum choice: a plain value, or a `{ const, title }` pair. */
+declare const enumOptionSchema: z.ZodUnion<[z.ZodString, z.ZodObject<{
+    const: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    const: string;
+    title?: string | undefined;
+}, {
+    const: string;
+    title?: string | undefined;
+}>]>;
+type EnumOption = z.infer<typeof enumOptionSchema>;
+/** The submitted value of an enum option. */
+declare function optionValue(option: EnumOption): string;
+/** The display label of an enum option (falls back to its value). */
+declare function optionLabel(option: EnumOption): string;
+declare const keyValueRowSchema: z.ZodObject<{
+    key: z.ZodString;
+    value: z.ZodString;
+    /** Mask this row's value (rendered as `type="password"` with a reveal toggle). */
+    secret: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    key: string;
+    value: string;
+    secret?: boolean | undefined;
+}, {
+    key: string;
+    value: string;
+    secret?: boolean | undefined;
+}>;
+type FieldKeyValueRow = z.infer<typeof keyValueRowSchema>;
+/** A single-line or multi-line text field. */
+declare const stringFieldSchema: z.ZodObject<{
+    default: z.ZodOptional<z.ZodString>;
+    format: z.ZodOptional<z.ZodEnum<["email", "uri", "date", "date-time"]>>;
+    minLength: z.ZodOptional<z.ZodNumber>;
+    maxLength: z.ZodOptional<z.ZodNumber>;
+    /** A serialized RegExp source string (client-enforced when present). */
+    pattern: z.ZodOptional<z.ZodString>;
+    /** Render a textarea instead of a single-line input. */
+    multiline: z.ZodOptional<z.ZodBoolean>;
+    /** Value key in the emitted form state (the `values` object key). */
+    name: z.ZodString;
+    /** Human label. Falls back to a humanized `name` when omitted. */
+    label: z.ZodOptional<z.ZodString>;
+    /** Helper text shown under the control. */
+    description: z.ZodOptional<z.ZodString>;
+    /** Whether a value is required before the form can submit. */
+    required: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Conditional visibility: render (and validate/submit) this field only
+     * when another field's current value equals `equals` — e.g. show a
+     * "client secret" field only once `authMethod` equals `"oauth"`. Evaluated
+     * by `isFieldVisible` against the form's current values; a hidden field is
+     * excluded from rendering, validation and the first-invalid-focus walk, so
+     * a hidden `required` field never blocks submit.
+     */
+    visibleWhen: z.ZodOptional<z.ZodObject<{
+        /** Name of the controlling field. */
+        field: z.ZodString;
+        /** The controlling field's value that makes this field visible. */
+        equals: z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+    }, "strip", z.ZodTypeAny, {
+        field: string;
+        equals: string | number | boolean;
+    }, {
+        field: string;
+        equals: string | number | boolean;
+    }>>;
+    type: z.ZodLiteral<"string">;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    type: "string";
+    label?: string | undefined;
+    default?: string | undefined;
+    format?: "email" | "date" | "uri" | "date-time" | undefined;
+    pattern?: string | undefined;
+    maxLength?: number | undefined;
+    minLength?: number | undefined;
+    required?: boolean | undefined;
+    description?: string | undefined;
+    multiline?: boolean | undefined;
+    visibleWhen?: {
+        field: string;
+        equals: string | number | boolean;
+    } | undefined;
+}, {
+    name: string;
+    type: "string";
+    label?: string | undefined;
+    default?: string | undefined;
+    format?: "email" | "date" | "uri" | "date-time" | undefined;
+    pattern?: string | undefined;
+    maxLength?: number | undefined;
+    minLength?: number | undefined;
+    required?: boolean | undefined;
+    description?: string | undefined;
+    multiline?: boolean | undefined;
+    visibleWhen?: {
+        field: string;
+        equals: string | number | boolean;
+    } | undefined;
+}>;
+type StringFieldSpec = z.infer<typeof stringFieldSchema>;
+/** A floating-point number field. */
+declare const numberFieldSchema: z.ZodObject<{
+    default: z.ZodOptional<z.ZodNumber>;
+    min: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+    /** Value key in the emitted form state (the `values` object key). */
+    name: z.ZodString;
+    /** Human label. Falls back to a humanized `name` when omitted. */
+    label: z.ZodOptional<z.ZodString>;
+    /** Helper text shown under the control. */
+    description: z.ZodOptional<z.ZodString>;
+    /** Whether a value is required before the form can submit. */
+    required: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Conditional visibility: render (and validate/submit) this field only
+     * when another field's current value equals `equals` — e.g. show a
+     * "client secret" field only once `authMethod` equals `"oauth"`. Evaluated
+     * by `isFieldVisible` against the form's current values; a hidden field is
+     * excluded from rendering, validation and the first-invalid-focus walk, so
+     * a hidden `required` field never blocks submit.
+     */
+    visibleWhen: z.ZodOptional<z.ZodObject<{
+        /** Name of the controlling field. */
+        field: z.ZodString;
+        /** The controlling field's value that makes this field visible. */
+        equals: z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+    }, "strip", z.ZodTypeAny, {
+        field: string;
+        equals: string | number | boolean;
+    }, {
+        field: string;
+        equals: string | number | boolean;
+    }>>;
+    type: z.ZodLiteral<"number">;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    type: "number";
+    label?: string | undefined;
+    default?: number | undefined;
+    max?: number | undefined;
+    min?: number | undefined;
+    required?: boolean | undefined;
+    description?: string | undefined;
+    visibleWhen?: {
+        field: string;
+        equals: string | number | boolean;
+    } | undefined;
+}, {
+    name: string;
+    type: "number";
+    label?: string | undefined;
+    default?: number | undefined;
+    max?: number | undefined;
+    min?: number | undefined;
+    required?: boolean | undefined;
+    description?: string | undefined;
+    visibleWhen?: {
+        field: string;
+        equals: string | number | boolean;
+    } | undefined;
+}>;
+type NumberFieldSpec = z.infer<typeof numberFieldSchema>;
+/** A whole-number field. */
+declare const integerFieldSchema: z.ZodObject<{
+    default: z.ZodOptional<z.ZodNumber>;
+    min: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+    /** Value key in the emitted form state (the `values` object key). */
+    name: z.ZodString;
+    /** Human label. Falls back to a humanized `name` when omitted. */
+    label: z.ZodOptional<z.ZodString>;
+    /** Helper text shown under the control. */
+    description: z.ZodOptional<z.ZodString>;
+    /** Whether a value is required before the form can submit. */
+    required: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Conditional visibility: render (and validate/submit) this field only
+     * when another field's current value equals `equals` — e.g. show a
+     * "client secret" field only once `authMethod` equals `"oauth"`. Evaluated
+     * by `isFieldVisible` against the form's current values; a hidden field is
+     * excluded from rendering, validation and the first-invalid-focus walk, so
+     * a hidden `required` field never blocks submit.
+     */
+    visibleWhen: z.ZodOptional<z.ZodObject<{
+        /** Name of the controlling field. */
+        field: z.ZodString;
+        /** The controlling field's value that makes this field visible. */
+        equals: z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+    }, "strip", z.ZodTypeAny, {
+        field: string;
+        equals: string | number | boolean;
+    }, {
+        field: string;
+        equals: string | number | boolean;
+    }>>;
+    type: z.ZodLiteral<"integer">;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    type: "integer";
+    label?: string | undefined;
+    default?: number | undefined;
+    max?: number | undefined;
+    min?: number | undefined;
+    required?: boolean | undefined;
+    description?: string | undefined;
+    visibleWhen?: {
+        field: string;
+        equals: string | number | boolean;
+    } | undefined;
+}, {
+    name: string;
+    type: "integer";
+    label?: string | undefined;
+    default?: number | undefined;
+    max?: number | undefined;
+    min?: number | undefined;
+    required?: boolean | undefined;
+    description?: string | undefined;
+    visibleWhen?: {
+        field: string;
+        equals: string | number | boolean;
+    } | undefined;
+}>;
+type IntegerFieldSpec = z.infer<typeof integerFieldSchema>;
+/** A boolean checkbox field. */
+declare const booleanFieldSchema: z.ZodObject<{
+    default: z.ZodOptional<z.ZodBoolean>;
+    /** Value key in the emitted form state (the `values` object key). */
+    name: z.ZodString;
+    /** Human label. Falls back to a humanized `name` when omitted. */
+    label: z.ZodOptional<z.ZodString>;
+    /** Helper text shown under the control. */
+    description: z.ZodOptional<z.ZodString>;
+    /** Whether a value is required before the form can submit. */
+    required: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Conditional visibility: render (and validate/submit) this field only
+     * when another field's current value equals `equals` — e.g. show a
+     * "client secret" field only once `authMethod` equals `"oauth"`. Evaluated
+     * by `isFieldVisible` against the form's current values; a hidden field is
+     * excluded from rendering, validation and the first-invalid-focus walk, so
+     * a hidden `required` field never blocks submit.
+     */
+    visibleWhen: z.ZodOptional<z.ZodObject<{
+        /** Name of the controlling field. */
+        field: z.ZodString;
+        /** The controlling field's value that makes this field visible. */
+        equals: z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+    }, "strip", z.ZodTypeAny, {
+        field: string;
+        equals: string | number | boolean;
+    }, {
+        field: string;
+        equals: string | number | boolean;
+    }>>;
+    type: z.ZodLiteral<"boolean">;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    type: "boolean";
+    label?: string | undefined;
+    default?: boolean | undefined;
+    required?: boolean | undefined;
+    description?: string | undefined;
+    visibleWhen?: {
+        field: string;
+        equals: string | number | boolean;
+    } | undefined;
+}, {
+    name: string;
+    type: "boolean";
+    label?: string | undefined;
+    default?: boolean | undefined;
+    required?: boolean | undefined;
+    description?: string | undefined;
+    visibleWhen?: {
+        field: string;
+        equals: string | number | boolean;
+    } | undefined;
+}>;
+type BooleanFieldSpec = z.infer<typeof booleanFieldSchema>;
+/** A single-select enum (one value from `options`). */
+declare const enumFieldSchema: z.ZodObject<{
+    options: z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodObject<{
+        const: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        const: string;
+        title?: string | undefined;
+    }, {
+        const: string;
+        title?: string | undefined;
+    }>]>, "many">;
+    default: z.ZodOptional<z.ZodString>;
+    /** Value key in the emitted form state (the `values` object key). */
+    name: z.ZodString;
+    /** Human label. Falls back to a humanized `name` when omitted. */
+    label: z.ZodOptional<z.ZodString>;
+    /** Helper text shown under the control. */
+    description: z.ZodOptional<z.ZodString>;
+    /** Whether a value is required before the form can submit. */
+    required: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Conditional visibility: render (and validate/submit) this field only
+     * when another field's current value equals `equals` — e.g. show a
+     * "client secret" field only once `authMethod` equals `"oauth"`. Evaluated
+     * by `isFieldVisible` against the form's current values; a hidden field is
+     * excluded from rendering, validation and the first-invalid-focus walk, so
+     * a hidden `required` field never blocks submit.
+     */
+    visibleWhen: z.ZodOptional<z.ZodObject<{
+        /** Name of the controlling field. */
+        field: z.ZodString;
+        /** The controlling field's value that makes this field visible. */
+        equals: z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+    }, "strip", z.ZodTypeAny, {
+        field: string;
+        equals: string | number | boolean;
+    }, {
+        field: string;
+        equals: string | number | boolean;
+    }>>;
+    type: z.ZodLiteral<"enum">;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    type: "enum";
+    options: (string | {
+        const: string;
+        title?: string | undefined;
+    })[];
+    label?: string | undefined;
+    default?: string | undefined;
+    required?: boolean | undefined;
+    description?: string | undefined;
+    visibleWhen?: {
+        field: string;
+        equals: string | number | boolean;
+    } | undefined;
+}, {
+    name: string;
+    type: "enum";
+    options: (string | {
+        const: string;
+        title?: string | undefined;
+    })[];
+    label?: string | undefined;
+    default?: string | undefined;
+    required?: boolean | undefined;
+    description?: string | undefined;
+    visibleWhen?: {
+        field: string;
+        equals: string | number | boolean;
+    } | undefined;
+}>;
+type EnumFieldSpec = z.infer<typeof enumFieldSchema>;
+/** A multi-select enum (zero or more values from `options`). */
+declare const multiEnumFieldSchema: z.ZodObject<{
+    options: z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodObject<{
+        const: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        const: string;
+        title?: string | undefined;
+    }, {
+        const: string;
+        title?: string | undefined;
+    }>]>, "many">;
+    default: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** Value key in the emitted form state (the `values` object key). */
+    name: z.ZodString;
+    /** Human label. Falls back to a humanized `name` when omitted. */
+    label: z.ZodOptional<z.ZodString>;
+    /** Helper text shown under the control. */
+    description: z.ZodOptional<z.ZodString>;
+    /** Whether a value is required before the form can submit. */
+    required: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Conditional visibility: render (and validate/submit) this field only
+     * when another field's current value equals `equals` — e.g. show a
+     * "client secret" field only once `authMethod` equals `"oauth"`. Evaluated
+     * by `isFieldVisible` against the form's current values; a hidden field is
+     * excluded from rendering, validation and the first-invalid-focus walk, so
+     * a hidden `required` field never blocks submit.
+     */
+    visibleWhen: z.ZodOptional<z.ZodObject<{
+        /** Name of the controlling field. */
+        field: z.ZodString;
+        /** The controlling field's value that makes this field visible. */
+        equals: z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+    }, "strip", z.ZodTypeAny, {
+        field: string;
+        equals: string | number | boolean;
+    }, {
+        field: string;
+        equals: string | number | boolean;
+    }>>;
+    type: z.ZodLiteral<"multi-enum">;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    type: "multi-enum";
+    options: (string | {
+        const: string;
+        title?: string | undefined;
+    })[];
+    label?: string | undefined;
+    default?: string[] | undefined;
+    required?: boolean | undefined;
+    description?: string | undefined;
+    visibleWhen?: {
+        field: string;
+        equals: string | number | boolean;
+    } | undefined;
+}, {
+    name: string;
+    type: "multi-enum";
+    options: (string | {
+        const: string;
+        title?: string | undefined;
+    })[];
+    label?: string | undefined;
+    default?: string[] | undefined;
+    required?: boolean | undefined;
+    description?: string | undefined;
+    visibleWhen?: {
+        field: string;
+        equals: string | number | boolean;
+    } | undefined;
+}>;
+type MultiEnumFieldSpec = z.infer<typeof multiEnumFieldSchema>;
+/** A repeating list of strings (Onyx's `list`) → renders `ListEditor`. */
+declare const listFieldSchema: z.ZodObject<{
+    default: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    minItems: z.ZodOptional<z.ZodNumber>;
+    maxItems: z.ZodOptional<z.ZodNumber>;
+    itemPlaceholder: z.ZodOptional<z.ZodString>;
+    /** Value key in the emitted form state (the `values` object key). */
+    name: z.ZodString;
+    /** Human label. Falls back to a humanized `name` when omitted. */
+    label: z.ZodOptional<z.ZodString>;
+    /** Helper text shown under the control. */
+    description: z.ZodOptional<z.ZodString>;
+    /** Whether a value is required before the form can submit. */
+    required: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Conditional visibility: render (and validate/submit) this field only
+     * when another field's current value equals `equals` — e.g. show a
+     * "client secret" field only once `authMethod` equals `"oauth"`. Evaluated
+     * by `isFieldVisible` against the form's current values; a hidden field is
+     * excluded from rendering, validation and the first-invalid-focus walk, so
+     * a hidden `required` field never blocks submit.
+     */
+    visibleWhen: z.ZodOptional<z.ZodObject<{
+        /** Name of the controlling field. */
+        field: z.ZodString;
+        /** The controlling field's value that makes this field visible. */
+        equals: z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+    }, "strip", z.ZodTypeAny, {
+        field: string;
+        equals: string | number | boolean;
+    }, {
+        field: string;
+        equals: string | number | boolean;
+    }>>;
+    type: z.ZodLiteral<"list">;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    type: "list";
+    label?: string | undefined;
+    default?: string[] | undefined;
+    required?: boolean | undefined;
+    description?: string | undefined;
+    visibleWhen?: {
+        field: string;
+        equals: string | number | boolean;
+    } | undefined;
+    minItems?: number | undefined;
+    maxItems?: number | undefined;
+    itemPlaceholder?: string | undefined;
+}, {
+    name: string;
+    type: "list";
+    label?: string | undefined;
+    default?: string[] | undefined;
+    required?: boolean | undefined;
+    description?: string | undefined;
+    visibleWhen?: {
+        field: string;
+        equals: string | number | boolean;
+    } | undefined;
+    minItems?: number | undefined;
+    maxItems?: number | undefined;
+    itemPlaceholder?: string | undefined;
+}>;
+type ListFieldSpec = z.infer<typeof listFieldSchema>;
+/** A repeating key/value list, e.g. headers or env vars (Onyx's `string_pair_list`) → renders `KeyValueEditor`. */
+declare const keyValueFieldSchema: z.ZodObject<{
+    default: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        value: z.ZodString;
+        /** Mask this row's value (rendered as `type="password"` with a reveal toggle). */
+        secret: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        key: string;
+        value: string;
+        secret?: boolean | undefined;
+    }, {
+        key: string;
+        value: string;
+        secret?: boolean | undefined;
+    }>, "many">>;
+    keyPlaceholder: z.ZodOptional<z.ZodString>;
+    valuePlaceholder: z.ZodOptional<z.ZodString>;
+    /** Value key in the emitted form state (the `values` object key). */
+    name: z.ZodString;
+    /** Human label. Falls back to a humanized `name` when omitted. */
+    label: z.ZodOptional<z.ZodString>;
+    /** Helper text shown under the control. */
+    description: z.ZodOptional<z.ZodString>;
+    /** Whether a value is required before the form can submit. */
+    required: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Conditional visibility: render (and validate/submit) this field only
+     * when another field's current value equals `equals` — e.g. show a
+     * "client secret" field only once `authMethod` equals `"oauth"`. Evaluated
+     * by `isFieldVisible` against the form's current values; a hidden field is
+     * excluded from rendering, validation and the first-invalid-focus walk, so
+     * a hidden `required` field never blocks submit.
+     */
+    visibleWhen: z.ZodOptional<z.ZodObject<{
+        /** Name of the controlling field. */
+        field: z.ZodString;
+        /** The controlling field's value that makes this field visible. */
+        equals: z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+    }, "strip", z.ZodTypeAny, {
+        field: string;
+        equals: string | number | boolean;
+    }, {
+        field: string;
+        equals: string | number | boolean;
+    }>>;
+    type: z.ZodLiteral<"key-value">;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    type: "key-value";
+    label?: string | undefined;
+    default?: {
+        key: string;
+        value: string;
+        secret?: boolean | undefined;
+    }[] | undefined;
+    required?: boolean | undefined;
+    description?: string | undefined;
+    keyPlaceholder?: string | undefined;
+    valuePlaceholder?: string | undefined;
+    visibleWhen?: {
+        field: string;
+        equals: string | number | boolean;
+    } | undefined;
+}, {
+    name: string;
+    type: "key-value";
+    label?: string | undefined;
+    default?: {
+        key: string;
+        value: string;
+        secret?: boolean | undefined;
+    }[] | undefined;
+    required?: boolean | undefined;
+    description?: string | undefined;
+    keyPlaceholder?: string | undefined;
+    valuePlaceholder?: string | undefined;
+    visibleWhen?: {
+        field: string;
+        equals: string | number | boolean;
+    } | undefined;
+}>;
+type KeyValueFieldSpec = z.infer<typeof keyValueFieldSchema>;
+/** A file-upload field (Onyx's `file`) → renders `FileUpload`. No `default` — files cannot be defaulted. */
+declare const fileFieldSchema: z.ZodObject<{
+    /** Forwarded to the native `<input accept>` (comma-separated extensions/MIME types). */
+    accept: z.ZodOptional<z.ZodString>;
+    multiple: z.ZodOptional<z.ZodBoolean>;
+    /** Maximum individual file size, in bytes. */
+    maxSize: z.ZodOptional<z.ZodNumber>;
+    /** Maximum number of files (only meaningful when `multiple`). */
+    maxFiles: z.ZodOptional<z.ZodNumber>;
+    /** Value key in the emitted form state (the `values` object key). */
+    name: z.ZodString;
+    /** Human label. Falls back to a humanized `name` when omitted. */
+    label: z.ZodOptional<z.ZodString>;
+    /** Helper text shown under the control. */
+    description: z.ZodOptional<z.ZodString>;
+    /** Whether a value is required before the form can submit. */
+    required: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Conditional visibility: render (and validate/submit) this field only
+     * when another field's current value equals `equals` — e.g. show a
+     * "client secret" field only once `authMethod` equals `"oauth"`. Evaluated
+     * by `isFieldVisible` against the form's current values; a hidden field is
+     * excluded from rendering, validation and the first-invalid-focus walk, so
+     * a hidden `required` field never blocks submit.
+     */
+    visibleWhen: z.ZodOptional<z.ZodObject<{
+        /** Name of the controlling field. */
+        field: z.ZodString;
+        /** The controlling field's value that makes this field visible. */
+        equals: z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+    }, "strip", z.ZodTypeAny, {
+        field: string;
+        equals: string | number | boolean;
+    }, {
+        field: string;
+        equals: string | number | boolean;
+    }>>;
+    type: z.ZodLiteral<"file">;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    type: "file";
+    label?: string | undefined;
+    accept?: string | undefined;
+    multiple?: boolean | undefined;
+    required?: boolean | undefined;
+    description?: string | undefined;
+    maxSize?: number | undefined;
+    maxFiles?: number | undefined;
+    visibleWhen?: {
+        field: string;
+        equals: string | number | boolean;
+    } | undefined;
+}, {
+    name: string;
+    type: "file";
+    label?: string | undefined;
+    accept?: string | undefined;
+    multiple?: boolean | undefined;
+    required?: boolean | undefined;
+    description?: string | undefined;
+    maxSize?: number | undefined;
+    maxFiles?: number | undefined;
+    visibleWhen?: {
+        field: string;
+        equals: string | number | boolean;
+    } | undefined;
+}>;
+type FileFieldSpec = z.infer<typeof fileFieldSchema>;
+/**
+ * Any one field in a FormSpec — pre-declared here (a plain TS union, not
+ * `z.infer`) so `GroupItemSpec`/`GroupFieldSpec` below can reference it and
+ * vice versa. TypeScript resolves mutual recursion between `type`/`interface`
+ * declarations regardless of file order (no runtime value is involved); only
+ * the `const` zod schemas further down need an explicit `z.ZodType<…>`
+ * annotation to break the equivalent circular VALUE reference through
+ * `z.lazy`.
+ */
+type FieldSpec = StringFieldSpec | NumberFieldSpec | IntegerFieldSpec | BooleanFieldSpec | EnumFieldSpec | MultiEnumFieldSpec | ListFieldSpec | KeyValueFieldSpec | FileFieldSpec | GroupFieldSpec;
+/** One named branch of a `group` field's `groups` array. Recursive — a branch's `fields` are ordinary `FieldSpec`s, including nested groups. */
+interface GroupItemSpec {
+    /** Stable key for this branch — also the value stored when `variant: "tabs"`. */
+    key: string;
+    label: string;
+    description?: string;
+    fields: FieldSpec[];
+}
+/**
+ * Grouped alternative field sets (Onyx's `tab` / `string_tab`) → renders
+ * `Tabs` (`variant: "tabs"`, mutually exclusive — e.g. "OAuth" vs "API key")
+ * or a stack of `AdvancedGroup` disclosures (`variant: "advanced"` — always-
+ * available secondary fields, not mutually exclusive).
+ *
+ * For `variant: "tabs"`, the field's OWN value (`values[field.name]`) is the
+ * active branch's `key` — the group behaves like a single-select enum over
+ * its branches. Only the active branch's fields are validated/required;
+ * `variant: "advanced"` has no notion of an active branch, so every branch's
+ * fields are always validated.
+ */
+interface GroupFieldSpec {
+    type: "group";
+    name: string;
+    label?: string;
+    description?: string;
+    required?: boolean;
+    /** See `visibleWhen` on `baseField` — conditional visibility for the whole group (and its subtree). */
+    visibleWhen?: {
+        field: string;
+        equals: string | number | boolean;
+    };
+    variant: "tabs" | "advanced";
+    groups: GroupItemSpec[];
+    /** Default active branch key. Only meaningful for `variant: "tabs"`. @default groups[0].key */
+    default?: string;
+}
+declare const groupItemSchema: z.ZodType<GroupItemSpec>;
+declare const groupFieldSchema: z.ZodType<GroupFieldSpec>;
+/**
+ * NOTE: cast through `unknown` — `z.discriminatedUnion`'s own inferred output
+ * type is not assignable to the hand-declared `FieldSpec` union once one
+ * member (`groupFieldSchema`) is itself hand-typed via `z.ZodType<…>` rather
+ * than inferred; the runtime validator (discriminate on `type`, then run each
+ * member's real `.parse`) is unaffected; only the static type is asserted.
+ */
+declare const fieldSpecSchema: z.ZodType<FieldSpec>;
+/**
+ * The serializable form specification SchemaForm reads, renders and submits
+ * as `{ formName, values }`.
+ */
+declare const formSpecSchema: z.ZodObject<{
+    /** Stable identifier echoed back in the submit payload. */
+    formName: z.ZodString;
+    /** Heading rendered above the fields (also the accessible form name). */
+    title: z.ZodOptional<z.ZodString>;
+    /** Supplemental description under the title. */
+    description: z.ZodOptional<z.ZodString>;
+    /** The ordered fields to render. */
+    fields: z.ZodArray<z.ZodType<FieldSpec, z.ZodTypeDef, FieldSpec>, "many">;
+    /** Submit button label. @default "Submit" */
+    submitLabel: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    fields: FieldSpec[];
+    formName: string;
+    title?: string | undefined;
+    description?: string | undefined;
+    submitLabel?: string | undefined;
+}, {
+    fields: FieldSpec[];
+    formName: string;
+    title?: string | undefined;
+    description?: string | undefined;
+    submitLabel?: string | undefined;
+}>;
+type FormSpec = Omit<z.infer<typeof formSpecSchema>, "fields"> & {
+    fields: FieldSpec[];
+};
+/** A single field's value in the form state. */
+type FormValue = string | number | boolean | string[] | FieldKeyValueRow[] | File[] | undefined;
+/** The `values` object keyed by field `name`. */
+type FormValues = Record<string, FormValue>;
+/** The payload passed to `onSubmit`. */
+interface FormSubmitState {
+    /** Echoes `spec.formName`. */
+    formName: string;
+    /** The current field values keyed by field name. */
+    values: FormValues;
+}
+/** A validated, render-ready FormSpec. */
+interface NormalizedFormSpec {
+    formName: string;
+    title?: string;
+    description?: string;
+    submitLabel?: string;
+    fields: FieldSpec[];
+}
+declare function normalizeFormSpec(spec: unknown): {
+    ok: true;
+    spec: NormalizedFormSpec;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Find a field by name anywhere in the tree, including inside `group` branches. */
+declare function findFieldByName(fields: FieldSpec[], name: string): FieldSpec | undefined;
+/**
+ * Does `field` currently satisfy its own `visibleWhen` (if it has one)? A
+ * field with no `visibleWhen` is always visible. Shared by the render loops
+ * (schema-form.tsx) and `collectValidatableFields` below, so what's shown and
+ * what's validated/submitted never disagree.
+ */
+declare function isFieldVisible(field: FieldSpec, values: FormValues): boolean;
+/**
+ * The fields that currently participate in validation/submission: every
+ * scalar field, plus — for a `group` field — either the ACTIVE branch's
+ * fields (`variant: "tabs"`, keyed by `values[field.name]`) or ALL branches'
+ * fields (`variant: "advanced"`, nothing is mutually exclusive there). A
+ * field (or, for a hidden `group`, its whole subtree) whose `visibleWhen`
+ * does not currently hold is excluded entirely — a hidden `required` field
+ * must never block submit.
+ */
+declare function collectValidatableFields(fields: FieldSpec[], values: FormValues): FieldSpec[];
+/** The label to show for a field (explicit `label`, else a humanized `name`). */
+declare function fieldLabel(field: FieldSpec): string;
+/** Seed the initial values from every field's `default` (+ sensible empties), recursively. */
+declare function initialFormValues(fields: FieldSpec[]): FormValues;
+/**
+ * Validate one field's value against its declarative constraints.
+ * Returns a short human error message, or `null` when the value is valid.
+ * The vocabulary: required · email · url · min · max · minLength · maxLength ·
+ * pattern · numeric (integer whole-number) · minItems/maxItems (list).
+ */
+declare function validateField(field: FieldSpec, value: FormValue): string | null;
+/** Validate every VALIDATABLE field (see `collectValidatableFields`); returns a `{ [name]: error | null }` map. */
+declare function validateForm(fields: FieldSpec[], values: FormValues): Record<string, string | null>;
+/** Does `file` satisfy an `<input accept>`-style pattern (extensions, MIME types, or `type/*`)? */
+declare function fileMatchesAccept(file: File, accept: string | undefined): boolean;
+interface FileIssue {
+    reason: "wrong-type" | "too-large";
+    message: string;
+}
+/** Client-side per-file check for the designed `file` field states: wrong type, too large. */
+declare function checkFileIssue(file: File, field: FileFieldSpec): FileIssue | null;
+
+interface SchemaFormProviderProps {
+    /** A validated/normalized spec (a plain `FormSpec` also satisfies this). */
+    spec: NormalizedFormSpec;
+    /**
+     * Controlled values. When provided the component is controlled and
+     * `onChange` is the only way to update state.
+     */
+    values?: FormValues;
+    /** Called with the next full values object on any field change. */
+    onChange?: (values: FormValues) => void;
+    /** Called with `{ formName, values }` when a valid form is submitted. */
+    onSubmit?: (state: FormSubmitState) => void;
+    /** Disable every control (form is read-only). A deliberate, durable state. */
+    disabled?: boolean;
+    /** Terminal submitted state: controls are inert, values visible, no submit. */
+    submitted?: boolean;
+    /** In-flight submit: controls transiently blocked, submit shows a spinner. */
+    submitting?: boolean;
+    /** No fields to render yet (e.g. the spec is still being fetched) → skeleton. */
+    loading?: boolean;
+    /** A terminal, form-level submission error rendered above the submit control. */
+    error?: ReactNode;
+    children: ReactNode;
+}
+/**
+ * Lifts the form values. Controlled (pass `values`) or uncontrolled.
+ * Derives `isControlled = values !== undefined` and never flips modes.
+ */
+declare function SchemaFormProvider({ spec, values: valuesProp, onChange, onSubmit, disabled, submitted, submitting, loading, error, children, }: SchemaFormProviderProps): react.JSX.Element;
+interface SchemaFormFieldProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+    /** The field's `name` (its key in the spec + values). Resolved anywhere in the tree, including inside `group` branches. */
+    name: string;
+}
+/**
+ * Renders one field by name: label, control, description, inline error.
+ * Boolean fields render their own inline label (checkbox + label); `group`
+ * fields render their OWN label/description internally (a Tabs strip or a
+ * stack of disclosures isn't a single labelled control), so the standalone
+ * `<Label>` above is suppressed for both.
+ *
+ * Enforces its OWN `visibleWhen` (returns `null` when hidden) rather than
+ * trusting the caller to have filtered it out first: the documented custom-
+ * layout composition (`SchemaFormProvider` + the parts, see `SchemaForm`'s
+ * own doc comment) lets a consumer place `<SchemaFormField name="…" />`
+ * directly, bypassing `SchemaFormFields`'/`GroupTabsControl`'s/
+ * `AdvancedGroupBranch`'s own `isFieldVisible` filters — without this check
+ * the same spec would render a hidden field in a custom layout while
+ * validation/submission (which always excludes it) disagree.
+ */
+declare const SchemaFormField: react.ForwardRefExoticComponent<SchemaFormFieldProps & react.RefAttributes<HTMLDivElement>>;
+type SchemaFormFieldsProps = HTMLAttributes<HTMLDivElement>;
+/** Renders every top-level field in the spec, in order. A skeleton while `loading` with no fields. */
+declare const SchemaFormFields: react.ForwardRefExoticComponent<SchemaFormFieldsProps & react.RefAttributes<HTMLDivElement>>;
+type SchemaFormErrorProps = HTMLAttributes<HTMLDivElement>;
+/** A terminal, form-level submission error (e.g. "Couldn't save settings"). Renders nothing when absent. */
+declare const SchemaFormError: react.ForwardRefExoticComponent<SchemaFormErrorProps & react.RefAttributes<HTMLDivElement>>;
+interface SchemaFormSubmitProps extends Omit<HTMLAttributes<HTMLButtonElement>, "children"> {
+    /** Submit button label (overrides `spec.submitLabel`). @default "Submit" */
+    label?: string;
+}
+/**
+ * The submit affordance. Enabled until the request starts (validation runs on
+ * click), then transiently blocked. `submitting` uses `aria-disabled` + a
+ * click-handler guard — NEVER the native `disabled` attribute — so a focused
+ * button is never dropped from the tab order right after the user activates
+ * it (see the module doc comment / interaction-guidelines.md). The explicit,
+ * caller-set `disabled` (read-only form) stays native: that is a deliberate,
+ * durable state, not a transient auto-flip. A submitted form shows an inert
+ * "Submitted" note instead of a button.
+ */
+declare const SchemaFormSubmit: react.ForwardRefExoticComponent<SchemaFormSubmitProps & react.RefAttributes<HTMLButtonElement>>;
+/**
+ * `SchemaFormTestAction`'s lifecycle: `idle` → `pending` while `onTest` is in
+ * flight → `success`/`failure` once it settles. Deliberately local component
+ * state, NOT part of `SchemaFormContextValue` — so it can never affect field
+ * validity or gate `submit()` (issue #22 maintainer ruling, 2026-09-01: a
+ * form/group-level test-action slot, kept separate from field validity and
+ * never gating submit — not per-field `validateAsync` in the validation
+ * engine).
+ */
+type SchemaFormTestActionStatus = "idle" | "pending" | "success" | "failure";
+interface SchemaFormTestActionProps extends Omit<HTMLAttributes<HTMLDivElement>, "onError"> {
+    /**
+     * Runs the test (e.g. calls an API with the fields typed so far). Receives
+     * the form's CURRENT effective values — the same object `validateForm`
+     * would resolve against — but this call is entirely independent of
+     * validation: a field that is currently invalid, or an unrelated required
+     * field left empty, never blocks a test run. Resolve to signal success;
+     * reject (an `Error`, or throw) to signal failure — a rejected `Error`'s
+     * `message` becomes the shown failure reason.
+     */
+    onTest: (values: FormValues) => void | Promise<void>;
+    /** Button label. @default "Test connection" */
+    label?: string;
+    /** Label shown while pending. @default "Testing…" */
+    pendingLabel?: string;
+    /** Label shown on success. @default "Connected" */
+    successLabel?: string;
+    /** Fallback failure label when the rejection carries no message. @default "Test failed" */
+    failureLabel?: string;
+}
+/**
+ * A form- or group-level "Test connection" affordance: an async action the
+ * user can run to verify the values typed so far (e.g. hit a connector's
+ * `/ping` endpoint) BEFORE submitting. Place it anywhere inside a
+ * `SchemaFormProvider` tree — directly under `SchemaFormRoot` for a
+ * form-level test, or beside a `SchemaFormField` inside a `group` branch (a
+ * `TabsContent`/`AdvancedGroup`) for a per-credential-set test. Not part of
+ * `SchemaForm`'s default composition — an opt-in part a consumer places, the
+ * same way a custom layout composes `SchemaFormField` directly.
+ *
+ * Deliberately NOT wired into `errors`/`validateForm`/`submit()` — its
+ * pending/success/failure state is entirely local, so it can never block or
+ * silently gate the form's own submit control.
+ */
+declare const SchemaFormTestAction: react.ForwardRefExoticComponent<SchemaFormTestActionProps & react.RefAttributes<HTMLDivElement>>;
+type SchemaFormRootProps = Omit<HTMLAttributes<HTMLFormElement>, "onSubmit">;
+/**
+ * The `<form>` element wired to the context's `submit`. Never nest inside
+ * another `<form>` — compose it as its own top-level block.
+ */
+declare const SchemaFormRoot: react.ForwardRefExoticComponent<SchemaFormRootProps & react.RefAttributes<HTMLFormElement>>;
+type SchemaFormTitleProps = HTMLAttributes<HTMLParagraphElement>;
+/** The form heading. Its id is the `<form>`'s `aria-labelledby` target. */
+declare const SchemaFormTitle: react.ForwardRefExoticComponent<SchemaFormTitleProps & react.RefAttributes<HTMLParagraphElement>>;
+type SchemaFormDescriptionProps = HTMLAttributes<HTMLParagraphElement>;
+/** Supplemental description under the title. */
+declare const SchemaFormDescription: react.ForwardRefExoticComponent<SchemaFormDescriptionProps & react.RefAttributes<HTMLParagraphElement>>;
+interface SchemaFormFallbackProps extends HTMLAttributes<HTMLDivElement> {
+    /** Short human reason the form could not render. */
+    message?: string;
+}
+/**
+ * Shown when the spec is unusable. Mirrors `MessageFormFallback`: a calm,
+ * bordered status box with a short reason — never a thrown error.
+ */
+declare const SchemaFormFallback: react.ForwardRefExoticComponent<SchemaFormFallbackProps & react.RefAttributes<HTMLDivElement>>;
+interface SchemaFormProps extends Omit<HTMLAttributes<HTMLDivElement>, "onSubmit" | "onChange" | "title"> {
+    /** The serializable form specification. */
+    spec: FormSpec | unknown;
+    /** Controlled values (`{ [fieldName]: value }`). Omit for uncontrolled. */
+    values?: FormValues;
+    /** Called with the next full values object on any change. */
+    onChange?: (values: FormValues) => void;
+    /** Called with `{ formName, values }` on a valid submit. */
+    onSubmit?: (state: FormSubmitState) => void;
+    /** Submit button label (overrides `spec.submitLabel`). */
+    submitLabel?: string;
+    /** Disable every control (the whole form is read-only). */
+    disabled?: boolean;
+    /** Terminal submitted state: inert, values visible, submit replaced. */
+    submitted?: boolean;
+    /** In-flight submit: controls transiently blocked, spinner on submit. */
+    submitting?: boolean;
+    /** No fields to render yet (spec still loading) → skeleton. */
+    loading?: boolean;
+    /** A terminal, form-level submission error rendered above the submit control. */
+    error?: ReactNode;
+}
+/**
+ * Convenience composition: `Provider → Root(form) → title/description →
+ * Fields → Error → Submit`. For a custom layout, compose `SchemaFormProvider`
+ * + the parts. A malformed spec renders `SchemaFormFallback` (never throws).
+ */
+declare const SchemaForm: react.ForwardRefExoticComponent<SchemaFormProps & react.RefAttributes<HTMLDivElement>>;
+
+/**
+ * from-json-schema.ts — `fromJsonSchema()`: the narrow, documented JSON
+ * Schema → `FormSpec` adapter (issue #22, maintainer ruling 2026-09-01).
+ *
+ * Many consumers already have their config described as JSON Schema (an
+ * OpenAPI request body, a connector manifest). This maps ONLY the common
+ * subset such schemas actually use onto `SchemaForm`'s `FieldSpec`
+ * vocabulary:
+ *
+ *   { type: "string" }                          → StringFieldSpec
+ *   { type: "string", enum: [...] }              → EnumFieldSpec
+ *   { type: "number" | "integer" }                → NumberFieldSpec / IntegerFieldSpec
+ *   { type: "boolean" }                            → BooleanFieldSpec
+ *   { type: "array", items: { type: "string" } }    → ListFieldSpec (free text)
+ *   { type: "array",
+ *     items: { type: "string", enum: [...] } }       → MultiEnumFieldSpec
+ *                                                        (a CONSTRAINED array
+ *                                                        item schema maps onto
+ *                                                        the field type that
+ *                                                        actually enforces the
+ *                                                        constraint — see
+ *                                                        "Constraint keywords"
+ *                                                        below for why this
+ *                                                        one keyword IS read)
+ *   { type: "object", properties: {...} }            → GroupFieldSpec
+ *                                                        (variant: "advanced",
+ *                                                        one always-open branch)
+ *
+ * `title`/`description` map to `label`/`description`; `required` (the
+ * enclosing object schema's array of property names) maps to `required:
+ * true`; `default` maps when it is type-compatible; `minLength`/`maxLength`/
+ * `pattern`/`minimum`/`maximum`/`minItems`/`maxItems` map to their FieldSpec
+ * equivalents. `format` maps only the four values `StringFieldSpec` itself
+ * understands (`email`/`uri`/`date`/`date-time`) — any other `format` value
+ * (`"binary"`, `"password"`, a custom one) is ignored predictably, the same
+ * way an unknown JSON Schema `format` is defined to be advisory, not
+ * validating.
+ *
+ * Deliberately NOT a general draft-07/2020-12 implementation (the maintainer
+ * ruling's explicit narrow option) — this module does not resolve `$ref` and
+ * does not implement the `allOf`/`oneOf`/`anyOf`/`not` combinators. Those
+ * keywords change what a schema actually MEANS, and approximating them would
+ * risk producing a field that looks plausible but is wrong (e.g. rendering a
+ * `$ref`'d object as an empty string field) — silently wrong is exactly what
+ * this adapter must never be. So `fromJsonSchema()` REFUSES: any of those
+ * five keywords, found anywhere in the input (top-level or nested inside a
+ * property/items schema), throws `UnsupportedJsonSchemaError` naming the
+ * keyword and its JSON-Pointer-style path. Pre-resolve/inline that part of
+ * the schema before calling `fromJsonSchema()`, or hand-write the affected
+ * `FieldSpec`.
+ *
+ * A property whose `type` this subset does not cover (e.g. `"null"`, a
+ * JSON-Schema-2020-12 array-of-types, an array of non-string items, an
+ * object schema with no `properties`) is DROPPED from the result —
+ * predictable and non-fatal, the same lenient-parse philosophy
+ * `normalizeFormSpec` already uses for the render path, because omitting one
+ * field is recoverable in a way a mis-mapped `$ref`/combinator is not.
+ *
+ * CONSTRAINT KEYWORDS this subset does not read: `const`, `if`/`then`/`else`,
+ * `dependentSchemas`, `dependentRequired`, `additionalProperties`,
+ * `patternProperties`, `propertyNames`, `contains`, `multipleOf`,
+ * `exclusiveMinimum`/`exclusiveMaximum`, `uniqueItems`. These are
+ * READ-IGNORED, not refused — unlike `$ref`/`allOf`/`oneOf`/`anyOf`/`not`,
+ * none of them changes what TYPE a property maps to, so ignoring one never
+ * produces a wrongly-shaped field. But ignoring one DOES widen what the
+ * rendered form accepts relative to the source schema (a `const`-pinned
+ * property renders as an ordinary editable field, not a fixed one; a
+ * `multipleOf`-constrained number accepts any value in range). This is the
+ * one place `fromJsonSchema()` is honestly silently-permissive rather than
+ * silently-wrong or refusing — call it out in review when a schema leans on
+ * one of these keywords for validation the mapped form will not enforce.
+ * `items.enum` is the one exception among these: a constrained array-item
+ * schema is common enough (and cheap enough to map faithfully) that it reads
+ * `items.enum` and maps onto `MultiEnumFieldSpec` — see the table above —
+ * rather than joining this ignore list and widening into a free-text
+ * `ListFieldSpec`.
+ *
+ * Widening this subset later (more `format`s, `$ref` resolution) is an
+ * additive, non-breaking change to this one function — see issue #22's
+ * "worth having alongside" list.
+ */
+
+/**
+ * Thrown by `fromJsonSchema()` when the input uses a JSON Schema keyword
+ * outside its documented subset (see this module's doc comment) — never
+ * silently mismapped.
+ */
+declare class UnsupportedJsonSchemaError extends Error {
+    constructor(keyword: string, path: string);
+}
+interface FromJsonSchemaOptions {
+    /** `FormSpec.formName` — required; JSON Schema has no equivalent stable identifier. */
+    formName: string;
+    /** Overrides the mapped `schema.title`. */
+    title?: string;
+    /** Overrides the mapped `schema.description`. */
+    description?: string;
+    /** `FormSpec.submitLabel` — JSON Schema has no equivalent. */
+    submitLabel?: string;
+}
+/**
+ * Maps a JSON Schema OBJECT schema (an OpenAPI request body, a connector
+ * manifest) onto a `FormSpec`, using only the documented subset described in
+ * this module's doc comment. Throws `UnsupportedJsonSchemaError` if `schema`
+ * (at any depth) uses `$ref`/`allOf`/`oneOf`/`anyOf`/`not`, or if the
+ * top-level schema is not an object schema — never silently mismapped. A
+ * property whose shape falls outside the subset is dropped, not thrown on.
+ */
+declare function fromJsonSchema(schema: unknown, options: FromJsonSchemaOptions): FormSpec;
+
 declare const ScrollArea: react.ForwardRefExoticComponent<Omit<ScrollAreaPrimitive.ScrollAreaProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
 declare const ScrollBar: react.ForwardRefExoticComponent<Omit<ScrollAreaPrimitive.ScrollAreaScrollbarProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
 
@@ -3137,10 +5319,20 @@ interface SectionHeaderProps {
     actions?: ReactNode;
     /** Optional element rendered above the title (eyebrow / breadcrumbs). */
     eyebrow?: ReactNode;
+    /**
+     * The heading LEVEL the title contributes to the document outline. The
+     * visual (`text-title`) is identical for every value — pick the level the
+     * page's structure calls for, not the size you want (WCAG 1.3.1).
+     *
+     * Use `as="h1"` when this header titles the PAGE (a screen whose route it
+     * names); leave it at the default when it titles a section INSIDE a page
+     * that already has an `<h1>` elsewhere. @default "h2"
+     */
+    as?: "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
     className?: string;
 }
 /** A consistent page/section heading row with optional actions. */
-declare function SectionHeader({ title, description, actions, eyebrow, className, }: SectionHeaderProps): react.JSX.Element;
+declare function SectionHeader({ title, description, actions, eyebrow, as: TitleTag, className, }: SectionHeaderProps): react.JSX.Element;
 
 interface SegmentedFieldOption {
     /** The option's value, reported to `onValueChange`. */
@@ -3265,10 +5457,79 @@ declare function SheetFooter({ className, ...props }: HTMLAttributes<HTMLDivElem
 declare const SheetTitle: react.ForwardRefExoticComponent<Omit<DialogPrimitive.DialogTitleProps & react.RefAttributes<HTMLHeadingElement>, "ref"> & react.RefAttributes<HTMLHeadingElement>>;
 declare const SheetDescription: react.ForwardRefExoticComponent<Omit<DialogPrimitive.DialogDescriptionProps & react.RefAttributes<HTMLParagraphElement>, "ref"> & react.RefAttributes<HTMLParagraphElement>>;
 
+interface SideDockProps extends Omit<ComponentProps<"aside">, "title"> {
+    /**
+     * The dock's name. Rendered as its header heading, and as the `SheetTitle`
+     * of the overlay presentation. REQUIRED: the overlay cannot be accessible
+     * without it, and an optional prop with a generic default would ship a
+     * meaningless announced name into real apps.
+     */
+    title: ReactNode;
+    /**
+     * Optional longer description. Visible under the title in the column
+     * presentation; `sr-only` in the overlay presentation (the compact sheet
+     * header has no room for it, but it still reaches assistive tech).
+     */
+    description?: ReactNode;
+    /** Optional controls placed in the header row beside the built-in close button. */
+    headerActions?: ReactNode;
+    /** Controlled open state. Closed means zero width (content stays mounted, inert). */
+    open?: boolean;
+    /** Uncontrolled initial open state. Default `false` — a dock is summoned. */
+    defaultOpen?: boolean;
+    /** Called with the next open state. */
+    onOpenChange?: (open: boolean) => void;
+    /** Which edge it docks to. Default `"right"`. */
+    side?: "left" | "right";
+    /**
+     * `width`, `defaultWidth`, `minWidth`, `maxWidth`, `minContentWidth` and
+     * `resizable` (below) govern the COLUMN presentation only — viewport at or
+     * above `overlayBreakpoint`. Below that breakpoint the dock renders as an
+     * overlay `Sheet` sized by the viewport (`Sheet`'s own `w-3/4 max-w-sm`),
+     * so none of these props have any effect there.
+     */
+    /** Controlled width in px. */
+    width?: number;
+    /** Uncontrolled initial width in px. Default `400`. */
+    defaultWidth?: number;
+    /** Fires continuously during a resize — drive layout from this. */
+    onWidthChange?: (width: number) => void;
+    /** Fires once when an interaction ends — PERSIST from this. */
+    onWidthCommit?: (width: number) => void;
+    /** Lower bound in px. Default `320`. */
+    minWidth?: number;
+    /** Upper bound in px. Default `640`. */
+    maxWidth?: number;
+    /** Content width preserved when clamping against the live viewport, px. Default `480`. */
+    minContentWidth?: number;
+    /** Whether the resize handle renders. Default `true`. */
+    resizable?: boolean;
+    /**
+     * Viewport width in px below which the dock renders as an overlay `Sheet`
+     * instead of a column. Default `1100`. Deliberately ABOVE the library's
+     * 768px mobile breakpoint: a 400px dock at 768px leaves ~360px of content.
+     * This is the switch point for the column-only sizing props above — the
+     * overlay presentation ignores them entirely.
+     */
+    overlayBreakpoint?: number;
+}
+declare const SideDock: react.ForwardRefExoticComponent<Omit<SideDockProps, "ref"> & react.RefAttributes<HTMLElement>>;
+
 type SkeletonProps = HTMLAttributes<HTMLDivElement>;
 /** Loading placeholder. Compose with width/height utilities, e.g. `h-4 w-32`. */
 declare function Skeleton({ className, ...props }: SkeletonProps): react.JSX.Element;
 
+interface SkipLinkProps extends ComponentProps<"a"> {
+    /** The id of the landmark to jump to. Defaults to "main-content". */
+    targetId?: string;
+}
+/**
+ * The first focusable element of an application: invisible until focused, then a
+ * token-styled pill pinned to the top-start corner. Give the target element
+ * `id={targetId}` and `tabIndex={-1}` so focus actually lands there.
+ */
+declare const SkipLink: react.ForwardRefExoticComponent<Omit<SkipLinkProps, "ref"> & react.RefAttributes<HTMLAnchorElement>>;
+
 /** Props for a single `SliderPrimitive.Thumb` — see `SliderProps["thumbProps"]`. */
 type SliderThumbProps = ComponentPropsWithoutRef<typeof SliderPrimitive.Thumb>;
 type SliderProps = ComponentPropsWithoutRef<typeof SliderPrimitive.Root> & {
@@ -3450,11 +5711,29 @@ interface StatePanelProps extends VariantProps<typeof statePanelVariants> {
     /** Supporting description below the title. */
     description?: ReactNode;
     /**
-     * Icon or illustration shown above the title.
-     * For `"error"` defaults to a built-in warning triangle.
-     * For `"loading"` defaults to an animated spinner.
+     * Icon shown above the title, clamped to a uniform 40×40 so mismatched
+     * glyphs stay tidy. For `"error"` defaults to a built-in warning triangle.
+     * For `"loading"` defaults to an animated spinner. Ignored when
+     * `illustration` is also provided — see `illustration`.
      */
     icon?: ReactNode;
+    /**
+     * A larger illustration (one of `@elabs-ai/components-ui`'s shipped
+     * `*Illustration` components, or a consumer's own `ReactNode`) shown above
+     * the title instead of `icon`. Unlike `icon`, it is **not** clamped to
+     * 40×40 — an illustration governs its own size (see each illustration's
+     * `size` prop, `rem`-based, ~64px–160px). Takes precedence over `icon`
+     * when both are given.
+     */
+    illustration?: ReactNode;
+    /**
+     * Heading level for the panel's title (#328 convention). Set this to the
+     * level that correctly follows whatever heading precedes this panel in
+     * the document outline — e.g. `"h3"` inside a `ChartCard` whose own title
+     * is an `<h2>`.
+     * @default "h3"
+     */
+    titleAs?: "div" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
     /** Accessible label for the spinner in loading state. @default "Loading…" */
     loadingLabel?: string;
     /** Spinner size (loading kind only). @default "md" */
@@ -3468,113 +5747,28 @@ interface StatePanelProps extends VariantProps<typeof statePanelVariants> {
  * Replaces the three separate `EmptyState` / `ErrorState` / `LoadingState` components
  * while keeping those as back-compat thin wrappers.
  */
-declare function StatePanel({ kind, title, description, icon, loadingLabel, size, actions, className, }: StatePanelProps): react.JSX.Element;
-
-/** The canonical, closed 7-state status enum (research 10 §B.1). */
-declare const STATUSES: readonly ["pending", "running", "complete", "awaiting-approval", "denied", "failed", "skipped"];
-type Status = (typeof STATUSES)[number];
-/** Closed tone set for the out-of-vocabulary escape hatch (CALM treatments only). */
-declare const STATUS_TONES: readonly ["neutral", "info", "success", "warning", "destructive"];
-type StatusTone = (typeof STATUS_TONES)[number];
-/**
- * An out-of-vocabulary status. Prefer the canonical `Status` enum; reach for
- * this only when the domain genuinely has a state the 7 do not express (e.g. a
- * run engine's `stopped_guardrail`). Map it ONCE, near your domain — not per
- * call site.
- */
-interface CustomStatus {
-    label: string;
-    tone: StatusTone;
-    /** Optional Lucide glyph. Omitted → label-only (no default glyph). */
-    icon?: LucideIcon;
-}
-/** Narrows `Status | CustomStatus` — the object form is always the escape hatch. */
-declare function isCustomStatus(status: Status | CustomStatus): status is CustomStatus;
-/**
- * The canonical semantic ROLE per status — the single source of truth for
- * status colour (#392). Any other status-keyed colour map in the repo
- * (`Timeline`'s `NODE_STYLE`, or a future one) must be TESTED against this,
- * not hand-authored — a second literal copy is exactly how `NODE_STYLE`
- * drifted (`running` rendered `--primary` while this map said `--info`).
- * Do NOT interpolate `bg-${STATUS_ROLE[status]}` into a class map: Tailwind
- * scans source statically, so a template-literal class emits no CSS. Keep
- * consuming maps as literal class strings, verified against this export by a
- * test.
- */
-declare const STATUS_ROLE: {
-    readonly pending: "secondary";
-    readonly running: "info";
-    readonly complete: "success";
-    readonly "awaiting-approval": "warning";
-    readonly denied: "muted";
-    readonly failed: "destructive";
-    readonly skipped: "secondary";
-};
-/** Default human-readable label per status (override via `children`). */
-declare const STATUS_LABELS: Record<Status, string>;
-/**
- * Lucide glyph per out-of-vocabulary TONE — the same five-tone escape hatch
- * `CustomStatus` uses (`STATUS_TONES`). A consumer that encodes a bare TONE
- * with no fuller `Status` semantics (e.g. `@elabs-ai/components-flow`'s `FlowNode.tone`,
- * #387) derives its non-colour cue from here instead of inventing a second
- * icon vocabulary — each entry reuses the SAME icon `STATUS_ICONS` already
- * pairs with that tone's one canonical status (`success`→`complete`'s
- * `CheckCircle2`, `warning`→`awaiting-approval`'s `Clock`,
- * `destructive`→`failed`'s `AlertCircle`). `neutral`/`info` have no entry:
- * nothing consumes them yet, and reaching for a glyph on every neutral/
- * default-toned element would be assistive-tech noise on the common case —
- * extend this map, don't fork a new one, the day something needs them.
- */
-declare const STATUS_TONE_ICONS: Partial<Record<StatusTone, LucideIcon>>;
-interface StatusIconProps extends Omit<LucideProps, "ref"> {
-    /** The canonical execution status (closed enum). */
-    status: Status;
-}
-/**
- * The icon + status-color atom `StatusBadge` itself composes — for tight rows
- * (test-result rows, timeline/rail nodes) where a full badge is too heavy.
- * Decorative by default (`aria-hidden`); the adjacent row text must carry the
- * status name for AT users.
- */
-declare const StatusIcon: react.ForwardRefExoticComponent<StatusIconProps & react.RefAttributes<SVGSVGElement>>;
-declare const statusBadgeVariants: (props?: ({
-    status?: "running" | "pending" | "complete" | "awaiting-approval" | "denied" | "failed" | "skipped" | null | undefined;
-    tone?: "success" | "warning" | "destructive" | "info" | "neutral" | null | undefined;
-    size?: "md" | "sm" | null | undefined;
-} & class_variance_authority_types.ClassProp) | undefined) => string;
-interface StatusBadgeProps extends HTMLAttributes<HTMLSpanElement>, Omit<VariantProps<typeof statusBadgeVariants>, "status" | "tone"> {
-    /** The canonical execution status, or a mapped out-of-vocabulary one (#363). */
-    status: Status | CustomStatus;
-    /** Render label-only (no status icon). */
-    hideIcon?: boolean;
-}
-declare const StatusBadge: react.ForwardRefExoticComponent<StatusBadgeProps & react.RefAttributes<HTMLSpanElement>>;
-/** The editor/markdown `Timeline` 3-state vocabulary (`@elabs-ai/components-editor`). */
-type TimelineStatus = "done" | "active" | "pending";
-/**
- * Map the Timeline `done|active|pending` vocabulary onto the canonical
- * `Status` (research 10 §B.1 mapping b — lossless; the timeline only
- * expresses 3 of the 7 states). The AI-SDK `ToolUIPart` mapper lives in
- * `@elabs-ai/components-ai` (`statusFromToolState`, tool.tsx) so `@elabs-ai/components-ui` stays free of
- * the `ai` dependency (D6).
- */
-declare function fromTimelineStatus(status: TimelineStatus): Status;
+declare function StatePanel({ kind, title, description, icon, illustration, titleAs: Tag, loadingLabel, size, actions, className, }: StatePanelProps): react.JSX.Element;
 
 /**
  * Per-pane surface tone — the ground-offset tiering axis (research 08 §H, #193).
  * `plain` keeps the ambient ground (default; non-breaking). `card` RAISES the pane as
- * a white `bg-card` + `shadow-sm` and is robust across all three themes — a card is
+ * a white `bg-card` + `shadow-sm` and is robust across every theme — a card is
  * lighter than the page ground in BOTH light and dark, so it always reads as raised.
  * `muted` (`bg-surface-muted`) reads as a recessed well ONLY in light themes; in dark
  * themes `--surface-muted` is lighter than `--card`, so a `muted` pane reads as a faint
  * raised tint, not a recess (dark-mode layering only goes UP — there is no surface below
  * the page ground). For a guaranteed cross-theme raise/recess contrast, raise the focus
  * pane with `card` and leave the other `plain`.
+ *
+ * Exported so the same tone system reaches a `Layout/Resizable` pane — a draggable
+ * `ResizablePanel` composes `splitPaneVariants({ tone })` for the identical ground-offset
+ * tiering `SplitPanel` gives its `startTone`/`endTone`, instead of a hand-rolled second
+ * copy of these three classes. See `Layout/Resizable`'s `Tiered` story.
  */
-declare const paneToneVariants: (props?: ({
-    tone?: "card" | "muted" | "plain" | null | undefined;
+declare const splitPaneVariants: (props?: ({
+    tone?: "muted" | "card" | "plain" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
-type SplitPanelTone = NonNullable<VariantProps<typeof paneToneVariants>["tone"]>;
+type SplitPanelTone = NonNullable<VariantProps<typeof splitPaneVariants>["tone"]>;
 interface SplitPanelProps {
     start: ReactNode;
     end: ReactNode;
@@ -3597,8 +5791,12 @@ interface SplitPanelProps {
 }
 /**
  * Two-pane layout for master/detail, editor/preview and inspector workflows.
- * Static sizing by design (predictable in tests/SSR); for drag-to-resize wrap
- * with a resize hook or compose `react-resizable-panels` at the app level.
+ * Static sizing by design (predictable in tests/SSR) — `startSize` is a CSS grid
+ * track (`"320px"`, `"40%"`, `"1fr"`), not a percentage. For panes the user can
+ * drag to resize, reach for `Layout/Resizable`'s `ResizablePanelGroup`/
+ * `ResizablePanel`/`ResizableHandle` instead and apply `splitPaneVariants({ tone })`
+ * to a panel for the same ground-offset tiering. See
+ * [Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs).
  *
  * For a master/detail surface where the detail should read as a raised card on a
  * recessed list, use `startTone="muted" endTone="card"` (ground-offset tiering).
@@ -3607,6 +5805,26 @@ declare function SplitPanel({ start, end, direction, startSize, divider, startTo
 
 declare const Switch: react.ForwardRefExoticComponent<Omit<SwitchPrimitive.SwitchProps & react.RefAttributes<HTMLButtonElement>, "ref"> & react.RefAttributes<HTMLButtonElement>>;
 
+/**
+ * `Table`'s own scroll wrapper, gated on MEASURED overflow (#366).
+ *
+ * `className`/`ref`/`...props` all land on the `<table>` — unchanged, no new
+ * prop — so this wrapper is internal plumbing, not a new public surface. It
+ * follows `DataTable`'s non-virtualized branch verbatim
+ * (`packages/data/src/data-table/data-table.tsx:1658-1695`, #330), the
+ * closest precedent: a plain `overflow-auto` box with no pinned columns, no
+ * loading overlay and no edge fade to carry along, just the keyboard
+ * affordance itself.
+ *
+ * A table that FITS must stay a byte-identical no-op: no `tabIndex`, no
+ * `aria-label`, no ring — an unconditional stop would announce "scrollable"
+ * on content that never scrolls. Only a table that measurably overflows
+ * gets the tab stop, its accessible name (WCAG 4.1.2) and the compound focus
+ * ring (`focus-ring-inset` — the wrapper's own edge is the scroll clip, so an
+ * outside ring would be cut, `.claude/rules/theming.md`). No `role="region"`:
+ * both existing precedents (`DataTable`, `SheetTable`) decided against a
+ * redundant landmark over a real `<table>`, and this wrapper adds none either.
+ */
 declare const Table: react.ForwardRefExoticComponent<HTMLAttributes<HTMLTableElement> & react.RefAttributes<HTMLTableElement>>;
 declare const TableHeader: react.ForwardRefExoticComponent<HTMLAttributes<HTMLTableSectionElement> & react.RefAttributes<HTMLTableSectionElement>>;
 declare const TableBody: react.ForwardRefExoticComponent<HTMLAttributes<HTMLTableSectionElement> & react.RefAttributes<HTMLTableSectionElement>>;
@@ -3704,8 +5922,8 @@ type ThemeTransitionEffect = "polygon" | "circle" | "circle-blur" | "triangle";
  * Transitions API (the chanhdai.com "theme toggle effect", adapted to brand-ui).
  *
  * - Direction-aware: sets `data-vt="to-dark|to-light"` on `<html>` from the
- *   target theme's `dark` flag, so the clip-path wipes the right way for ANY of
- *   the three themes (not just light/dark).
+ *   target theme's `dark` flag, so the clip-path wipes the right way for ANY
+ *   theme (not just light/dark).
  * - `data-vt-effect` selects the reveal shape (default "polygon").
  * - Motion-aware: under `useReducedMotion()` (OS or in-app preference) — or when
  *   the browser lacks `startViewTransition` — it falls back to an instant,
@@ -4223,7 +6441,7 @@ declare const TEXT_ROLE_REM: {
 type TextRole = keyof typeof TEXT_ROLE_REM;
 declare const textVariants: (props?: ({
     variant?: "body" | "caption" | "meta" | "kpi" | "code" | "lead" | null | undefined;
-    tone?: "default" | "primary" | "muted" | null | undefined;
+    tone?: "default" | "muted" | "primary" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 type TextVariant = NonNullable<VariantProps<typeof textVariants>["variant"]>;
 type TextTone = NonNullable<VariantProps<typeof textVariants>["tone"]>;
@@ -4334,6 +6552,22 @@ interface FilterChipProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>,
      * as a sentence fragment out of context (and in a screen reader).
      */
     label: string;
+    /**
+     * Short, non-shrinking secondary text — a count, a unit (`"excluded 1,204"`).
+     * A second text slot rather than folding it into `label` (#284): `label` is
+     * the shrinkable, safe-to-truncate part; `trailing` is short and fixed-width
+     * and must never lose characters to the ellipsis. Same shape as
+     * `TurnStatus`'s and `TerminalWorking`'s `trailing` slot — a fixed-width
+     * companion beside a truncating label. Composed into the accessible name
+     * after `label` (`"Remove filter: <label> · <trailing>"`), so the byte-
+     * identical name from before this slot existed is unchanged.
+     *
+     * Trade-off: `trailing` is `shrink-0`, so an extremely narrow container now
+     * truncates `label` down to nothing before it touches `trailing`. That is
+     * the right default — the count is short and fixed, the label is the long,
+     * prose-shaped part — but it is a choice, not a free win.
+     */
+    trailing?: string;
     /** Remove this filter. The WHOLE chip is the remove control — see below. */
     onRemove: () => void;
 }
@@ -4435,6 +6669,90 @@ interface VirtualSelectProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement
  */
 declare const VirtualSelect: react.ForwardRefExoticComponent<VirtualSelectProps & react.RefAttributes<HTMLButtonElement>>;
 
+/**
+ * `WorkspacePicker`'s pure, directly-testable logic — kept out of the
+ * component for the same reason `../model-picker/model-picker-state.ts` does
+ * (see that file's header comment): an expression buried in JSX cannot be
+ * unit-tested in isolation, and relative-time arithmetic in particular has
+ * edge cases worth locking down on their own.
+ */
+/**
+ * One recent workspace. Deliberately a strict subset of `ModelPickerItem`'s
+ * shape (`id` / `name` → `label` / `path` → `description` / `lastOpenedAt` →
+ * a formatted `meta` entry) — see the reuse note in `workspace-picker.tsx`.
+ */
+interface Workspace {
+    id: string;
+    /** Rendered as the row's primary label and, when current, the trigger text. */
+    name: string;
+    /**
+     * The filesystem path. Long, user-supplied content — the row truncates it,
+     * never wraps or overflows.
+     */
+    path: string;
+    /**
+     * When this workspace was last opened. Rendered as a relative time via
+     * `Intl.RelativeTimeFormat` (`formatLastOpened`, below) — never a
+     * pre-formatted string the caller hands over.
+     */
+    lastOpenedAt?: Date;
+}
+/**
+ * "2 hours ago" / "in 3 minutes" / "yesterday" — `Intl.RelativeTimeFormat`
+ * picks the coarsest unit (minutes → hours → days) that still reads
+ * naturally, instead of e.g. "127 minutes ago".
+ *
+ * @param now - injection seam for tests; defaults to the real clock.
+ */
+declare function formatLastOpened(date: Date, locale: string, now?: number): string;
+
+interface WorkspacePickerProps extends Omit<HTMLAttributes<HTMLDivElement>, "onSelect"> {
+    /** Recent workspaces, most-relevant first — the caller owns ordering. */
+    workspaces: Workspace[];
+    /** The currently open workspace's id. */
+    currentId?: string;
+    /** Fires with the chosen workspace; the popover closes first. */
+    onSelect?: (workspace: Workspace) => void;
+    /**
+     * Free-text path entry, rendered in `ModelPicker`'s `footer` slot below the
+     * list. Fires with the raw string the user typed once it validates as
+     * non-empty — this component performs no filesystem access of any kind
+     * (presentation layer, D5); resolving, normalizing or checking the path is
+     * the caller's job.
+     */
+    onSubmitPath?: (path: string) => void;
+    /**
+     * Drives the same four-body state grid as `ModelPicker` — see
+     * `ModelPickerStatus`. Default `"ready"`, inherited from `ModelPicker`.
+     */
+    status?: ModelPickerStatus;
+    disabled?: boolean;
+    /** Accessible name for the trigger and the popover — what the control is FOR. */
+    "aria-label"?: string;
+    /** Controlled popover open state — see `ModelPicker`'s controlled contract. */
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+}
+/**
+ * Recent-workspace switcher — issue #111, decided in
+ * `docs/decisions/2026-09-01-brainless-adoption-architecture.md` § 7.
+ *
+ * A `ModelPicker` PRESET, not a new picker: `ModelPickerItem`'s
+ * `id`/`label`/`description`/`meta` shape is already a superset of what a
+ * workspace needs, so this component only supplies workspace-shaped
+ * defaults — it maps `path` into the truncating `description` slot, formats
+ * `lastOpenedAt` with `Intl.RelativeTimeFormat`, marks the current workspace
+ * in the row's TEXT (never colour alone — `ModelPicker`'s check glyph is
+ * `aria-hidden` and cannot carry that on its own), and renders the free-text
+ * path entry into `ModelPicker`'s `footer` slot so it sits below the list,
+ * un-filtered by the search query.
+ *
+ * Unlike `TeamSwitcher`, this has no `Sidebar` dependency — it works anywhere
+ * a picker is needed (a session launch card, a command palette), not only
+ * inside a sidebar.
+ */
+declare const WorkspacePicker: react.ForwardRefExoticComponent<WorkspacePickerProps & react.RefAttributes<HTMLDivElement>>;
+
 interface WizardStepMeta {
     /** Stable id for the step. */
     id: string;
@@ -4494,4 +6812,4 @@ interface WizardNavProps extends HTMLAttributes<HTMLDivElement> {
 /** WizardNav — Back / Next (or Finish on the last step) controls. */
 declare const WizardNav: react.ForwardRefExoticComponent<WizardNavProps & react.RefAttributes<HTMLDivElement>>;
 
-export { ATTRIBUTIONS, Accordion, AccordionContent, AccordionItem, AccordionTrigger, AdvancedGroup, type AdvancedGroupProps, Alert, AlertDescription, type AlertDescriptionProps, AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, AlertTitle, type AlertTitleProps, AppShell, type AppShellProps, AppSidebar, type AppSidebarProps, AspectRatio, type Attribution, type AttributionCategory, AttributionPanel, type AttributionPanelProps, Avatar, AvatarFallback, AvatarImage, Badge, type BadgeProps, BentoGrid, BentoGridItem, type BentoGridItemProps, type BentoGridItemVariants, type BentoGridProps, type BentoGridSize, BoundedNumber, type BoundedNumberProps, Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator, Button, ButtonGroup, ButtonGroupSeparator, ButtonGroupText, type ButtonProps, CATEGORY_LABEL, COLOR_TOKENS, COPY_FEEDBACK_MS, Calendar, type CalendarProps, Card, CardAction, CardContent, CardDescription, type CardDescriptionProps, CardFooter, CardHeader, type CardProps, CardTitle, type CardTitleProps, Carousel, type CarouselApi, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious, type ChangeHunk, type ChangeHunkStatus, type ChangeProvenance, ChangeReview, type ChangeReviewActions, ChangeReviewHeader, type ChangeReviewHeaderProps, ChangeReviewHunk, type ChangeReviewHunkProps, ChangeReviewList, type ChangeReviewListProps, type ChangeReviewProps, ChangeReviewProvenance, type ChangeReviewProvenanceProps, ChangeReviewProvider, type ChangeReviewProviderProps, type ChangeReviewState, Checkbox, Collapsible, CollapsibleContent, type CollapsiblePanelAttrs, type CollapsiblePanelSide, type CollapsiblePanelState, CollapsibleTrigger, ColorPicker, type ColorPickerProps, type ColorToken, Combobox, type ComboboxOption, type ComboboxProps, Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, type CommandProps, CommandSeparator, CommandShortcut, ConfirmDialog, type ConfirmDialogProps, ContextMenu, ContextMenuCheckboxItem, ContextMenuContent, ContextMenuGroup, ContextMenuItem, ContextMenuLabel, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSeparator, ContextMenuShortcut, ContextMenuSub, ContextMenuSubContent, ContextMenuSubTrigger, ContextMenuTrigger, type CopyToClipboard, CopyableValue, type CopyableValueProps, type CustomStatus, DEFAULT_MESSAGES, DOCUMENT_ADDRESS_KINDS, DatePicker, type DatePickerProps, DateRangePicker, type DateRangePickerProps, type DateRangePreset, Descriptions, DescriptionsItem, type DescriptionsItemProps, type DescriptionsProps, Dialog, DialogBody, type DialogBodyProps, DialogClose, DialogContent, DialogDescription, type DialogDismissGuard, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogSection, type DialogSectionProps, DialogTitle, DialogTrigger, type DocumentAddress, type DocumentAddressKind, type DocumentRect, Drawer, DrawerClose, DrawerContent, DrawerDescription, DrawerFooter, DrawerHeader, DrawerPortal, DrawerTitle, DrawerTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, EmptyState, type EmptyStateProps, ErrorState, type ErrorStateProps, ExpandDialog, ExpandDialogContent, type ExpandDialogContentProps, ExpandDialogHeader, type ExpandDialogHeaderProps, ExpandDialogPanes, type ExpandDialogPanesProps, type ExpandDialogProps, FILE_CATEGORY_ICONS, FieldRow, type FieldRowProps, type FileCategory, type FileKind, type FileSource, FileUpload, FileUploadDropzone, type FileUploadDropzoneProps, FileUploadItem, type FileUploadItemProps, FileUploadList, type FileUploadListProps, type FileUploadProps, type FileUploadStatus, FilterChip, type FilterChipProps, Form, FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage, Heading, type HeadingLevel, type HeadingProps, type HeadingSize, HoverCard, HoverCardContent, HoverCardTrigger, IconButton, type IconButtonProps, type IconButtonSize, Input, InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput, type InputGroupProps, InputGroupText, InputGroupTextarea, InputOTP, InputOTPGroup, InputOTPSeparator, InputOTPSlot, type InputProps, type InsertMentionResult, Kbd, KeyValueEditor, type KeyValueEditorProps, type KeyValueRow, Label, LinkPreview, LinkPreviewCard, type LinkPreviewCardProps, ListEditor, type ListEditorProps, LoadingState, type LoadingStateProps, type LocaleContextValue, LocaleProvider, type LocaleProviderProps, MatchHighlight, type MatchHighlightProps, type MatchRange, type Mention, MentionInput, MentionInputContent, type MentionInputContentProps, type MentionInputContextValue, MentionInputEmpty, type MentionInputEmptyProps, MentionInputItem, type MentionInputItemProps, MentionInputList, type MentionInputListProps, type MentionInputProps, MentionInputTextarea, type MentionInputTextareaProps, type MentionOption, type MentionValue, Menubar, MenubarCheckboxItem, MenubarContent, MenubarItem, MenubarRadioItem, MenubarSeparator, MenubarShortcut, MenubarSubContent, MenubarSubTrigger, MenubarTrigger, type Messages, MetricCard, type MetricCardEmphasis, type MetricCardProps, ModelPicker, type ModelPickerBody, type ModelPickerGroup, type ModelPickerItem, type ModelPickerProps, type ModelPickerStatus, NavMain, type NavMainProps, type NavMainRoute, type NavMainSubItem, type NavNotification, NavNotifications, type NavNotificationsProps, NavUser, type NavUserProps, type NavUserUser, NavigationMenu, NavigationMenuContent, NavigationMenuItem, NavigationMenuLink, NavigationMenuList, NavigationMenuTrigger, NavigationMenuViewport, type NormalizedText, NumberInput, type NumberInputProps, PROSE_HEADING_REM, PROSE_HEADING_TRACKING, PROSE_HEADING_WEIGHT, PageShell, type PageShellProps, Pagination, PaginationContent, PaginationEllipsis, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious, Popover, PopoverAnchor, PopoverContent, PopoverTrigger, Progress, type ProgressProps, ProseBlockquote, ProseHeading, type ProseHeadingLevel, type ProseHeadingProps, ProseInlineCode, ProseLink, type ProseLinkProps, ProseList, ProseListItem, type ProseListProps, ProseText, type ProseTextProps, type QuoteAddress, RadioGroup, RadioGroupItem, type RangeAddress, Rating, type RatingProps, type RectAddress, ResizableHandle, ResizablePanel, ResizablePanelGroup, type ResolvedFileSource, ResultCount, type ResultCountProps, Reveal, RevealGroup, type RevealGroupProps, type RevealProps, type Revision, type RevisionBranch, type RevisionEdge, RevisionTimeline, type RevisionTimelineDensity, type RevisionTimelineProps, STATUSES, STATUS_LABELS, STATUS_ROLE, STATUS_TONES, STATUS_TONE_ICONS, STREAMDOWN_TRANSLATION_KEYS, ScrollArea, ScrollBar, SectionHeader, type SectionHeaderProps, SegmentedField, type SegmentedFieldOption, type SegmentedFieldProps, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectSeparator, SelectTrigger, SelectValue, Separator, type SeparatorProps, Sheet, SheetClose, SheetContent, type SheetContentProps, SheetDescription, SheetFooter, SheetHeader, SheetPortal, SheetTitle, SheetTrigger, Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupAction, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarInput, SidebarInset, SidebarMenu, SidebarMenuAction, SidebarMenuBadge, SidebarMenuButton, SidebarMenuItem, SidebarMenuSkeleton, SidebarMenuSub, SidebarMenuSubButton, SidebarMenuSubItem, SidebarProvider, SidebarRail, SidebarSeparator, SidebarTrigger, Skeleton, type SkeletonProps, Slider, SliderNumber, type SliderNumberProps, type SliderProps, type SliderThumbProps, Spinner, type SpinnerProps, SplitPanel, type SplitPanelProps, type SplitPanelTone, StatePanel, type StatePanelProps, type Status, StatusBadge, type StatusBadgeProps, StatusIcon, type StatusIconProps, type StatusTone, type StreamdownTranslationKey, type StreamdownTranslationMap, Switch, TEXT_ROLE_REM, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, TagInput, type TagInputProps, TeamSwitcher, type TeamSwitcherProps, type TeamSwitcherTeam, Text, type TextProps, type TextRole, type TextTone, type TextVariant, Textarea, type TextareaProps, type ThemePreference, ThemeSwitcher, type ThemeSwitcherProps, type ThemeTransitionEffect, Timeline, type TimelineEntry, TimelineItem, type TimelineItemProps, type TimelineProps, TimelineRoot, type TimelineRootProps, type TimelineStatus, Toaster, type ToasterProps, Toggle, ToggleGroup, ToggleGroupItem, Toolbar, ToolbarButton, type ToolbarButtonProps, type ToolbarProps, ToolbarSeparator, type ToolbarSeparatorProps, ToolbarSlot, ToolbarToggleGroup, type ToolbarToggleGroupProps, ToolbarToggleItem, type ToolbarToggleItemProps, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, TopNav, type TopNavProps, Transfer, type TransferItem, type TransferProps, Tree, type TreeNode, type TreeProps, TreeSelect, type TreeSelectProps, type UploadFile, type UseCollapsiblePanelOptions, type UseCollapsiblePanelReturn, type UseCopyToClipboardOptions, type UseDialogDismissGuardOptions, type UseTreeKeyboardOptions, type UseTreeKeyboardResult, ViewToolbar, ViewToolbarFilters, type ViewToolbarFiltersProps, type ViewToolbarProps, VirtualSelect, type VirtualSelectOption, type VirtualSelectProps, Wizard, WizardNav, type WizardNavProps, type WizardProps, WizardStep, type WizardStepMeta, type WizardStepProps, WizardSteps, type WizardStepsProps, type WizardValidator, alertVariants, badgeVariants, bentoGridItemVariants, buttonGroupVariants, buttonVariants, cardVariants, cn, countItems, defaultMentionFilter, dialogContentVariants, downloadBlob, downloadUrl, expandDialogPanesVariants, extensionOf, fileIconFor, fromTimelineStatus, headingVariants, hunkVariants, inputGroupAddonVariants, inputGroupVariants, insertMention, isCustomStatus, laneColor, mediaTypeFromName, mentionAt, mentionEnd, modelPickerBody, navigationMenuTriggerStyle, normalizeFileSource, normalizeQuoteText, normalizeQuoteTextWithOffsets, normalizeRanges, progressIndicatorVariants, queryToRanges, remapMentions, resolveFileKind, revealVariants, revisionTimelineVariants, serializeMentions, showsInlineError, sidebarMenuButtonVariants, statePanelVariants, statusBadgeVariants, textVariants, toggleVariants, toolbarVariants, useCollapsiblePanel, useCommandActiveItemId, useCopyToClipboard, useDialogDismissGuard, useFileUpload, useFormField, useIsMobile, useLocale, useMentionInput, useSidebar, useStreamdownTranslations, useThemeTransition, useTreeKeyboard, useVirtualListbox };
+export { APPROVAL_SCOPE_DESCRIPTION_KEYS, ATTRIBUTIONS, Accordion, AccordionContent, AccordionItem, AccordionTrigger, AdvancedGroup, type AdvancedGroupProps, type AgentEventOutcome, type AgentEventPhase, Alert, AlertDescription, type AlertDescriptionProps, AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, AlertTitle, type AlertTitleProps, AppShell, type AppShellProps, AppSidebar, type AppSidebarProps, type ApprovalOption, type ApprovalScope, AspectRatio, type Attribution, type AttributionCategory, AttributionPanel, type AttributionPanelProps, Avatar, AvatarFallback, AvatarImage, Badge, type BadgeProps, BentoGrid, BentoGridItem, type BentoGridItemProps, type BentoGridItemVariants, type BentoGridProps, type BentoGridSize, type BooleanFieldSpec, BoundedNumber, type BoundedNumberProps, Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator, Button, ButtonGroup, ButtonGroupSeparator, ButtonGroupText, type ButtonProps, CATEGORY_LABEL, COLOR_TOKENS, COPY_FEEDBACK_MS, Calendar, type CalendarProps, Card, CardAction, CardContent, CardDescription, type CardDescriptionProps, CardFooter, CardHeader, type CardProps, CardTitle, type CardTitleProps, Carousel, type CarouselApi, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious, type ChangeHunk, type ChangeHunkStatus, type ChangeProvenance, ChangeReview, type ChangeReviewActions, ChangeReviewHeader, type ChangeReviewHeaderProps, ChangeReviewHunk, type ChangeReviewHunkProps, ChangeReviewList, type ChangeReviewListProps, type ChangeReviewProps, ChangeReviewProvenance, type ChangeReviewProvenanceProps, ChangeReviewProvider, type ChangeReviewProviderProps, type ChangeReviewState, type CheckResult, type CheckSummary, Checkbox, Collapsible, CollapsibleContent, type CollapsiblePanelAttrs, type CollapsiblePanelSide, type CollapsiblePanelState, CollapsibleTrigger, ColorPicker, type ColorPickerProps, type ColorToken, Combobox, type ComboboxOption, type ComboboxProps, Command, CommandDialog, type CommandDialogProps, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, type CommandProps, CommandSeparator, CommandShortcut, CommandTrigger, type CommandTriggerProps, ConfirmDialog, type ConfirmDialogProps, ContextMenu, ContextMenuCheckboxItem, ContextMenuContent, ContextMenuGroup, ContextMenuItem, ContextMenuLabel, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSeparator, ContextMenuShortcut, ContextMenuSub, ContextMenuSubContent, ContextMenuSubTrigger, ContextMenuTrigger, ContextRail, type ContextRailProps, type ContextRailSection, type CopyToClipboard, CopyableValue, type CopyableValueProps, type CustomStatus, DEFAULT_MESSAGES, DOCUMENT_ADDRESS_KINDS, DatePicker, type DatePickerProps, DateRangePicker, type DateRangePickerProps, type DateRangePreset, Descriptions, DescriptionsItem, type DescriptionsItemProps, type DescriptionsProps, Dialog, DialogBody, type DialogBodyProps, DialogClose, DialogContent, DialogDescription, type DialogDismissGuard, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogSection, type DialogSectionProps, DialogTitle, DialogTrigger, type DiffLine, type DiffLineType, type DiffRow, type DocumentAddress, type DocumentAddressKind, type DocumentRect, Drawer, DrawerClose, DrawerContent, DrawerDescription, DrawerFooter, DrawerHeader, DrawerPortal, DrawerTitle, DrawerTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, type EffortLevel, EmptyListIllustration, EmptyState, type EmptyStateProps, type EnumFieldSpec, type EnumOption, ErrorIllustration, ErrorState, type ErrorStateProps, ExpandDialog, ExpandDialogContent, type ExpandDialogContentProps, ExpandDialogHeader, type ExpandDialogHeaderProps, ExpandDialogPanes, type ExpandDialogPanesProps, type ExpandDialogProps, FILE_CATEGORY_ICONS, FieldControl, type FieldControlProps, FieldDescription, FieldError, type FieldKeyValueRow, FieldLabel, FieldRoot, type FieldRootProps, FieldRow, type FieldRowProps, type FieldSpec, type FileCategory, type FileFieldSpec, type FileIssue, type FileKind, type FileSource, FileUpload, FileUploadDropzone, type FileUploadDropzoneProps, FileUploadItem, type FileUploadItemProps, FileUploadList, type FileUploadListProps, type FileUploadProps, type FileUploadStatus, FilterChip, type FilterChipProps, type FindTriggerQueryOptions, FirstRunIllustration, type FormSpec, type FormSubmitState, type FormValue, type FormValues, type FromJsonSchemaOptions, type GroupFieldSpec, type GroupItemSpec, Heading, type HeadingLevel, type HeadingProps, type HeadingSize, HoverCard, HoverCardContent, HoverCardTrigger, ILLUSTRATION_ACCENT_VAR, IconButton, type IconButtonProps, type IconButtonSize, type IllustrationProps, Input, InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput, type InputGroupProps, InputGroupText, InputGroupTextarea, InputOTP, InputOTPGroup, InputOTPSeparator, InputOTPSlot, type InputProps, type InsertMentionResult, type IntegerFieldSpec, Kbd, KeyValueEditor, type KeyValueEditorProps, type KeyValueFieldSpec, type KeyValueRow, KeyboardShortcuts, type KeyboardShortcutsProps, Label, LinkPreview, LinkPreviewCard, type LinkPreviewCardProps, ListEditor, type ListEditorProps, type ListFieldSpec, LoadingState, type LoadingStateProps, type LocaleContextValue, LocaleProvider, type LocaleProviderProps, MatchHighlight, type MatchHighlightProps, type MatchRange, type Mention, MentionInput, MentionInputContent, type MentionInputContentProps, type MentionInputContextValue, MentionInputEmpty, type MentionInputEmptyProps, MentionInputItem, type MentionInputItemProps, MentionInputList, type MentionInputListProps, type MentionInputProps, MentionInputTextarea, type MentionInputTextareaProps, type MentionOption, type MentionValue, Menubar, MenubarCheckboxItem, MenubarContent, MenubarItem, MenubarRadioItem, MenubarSeparator, MenubarShortcut, MenubarSubContent, MenubarSubTrigger, MenubarTrigger, type MessageValue, type Messages, MetricCard, type MetricCardEmphasis, type MetricCardProps, ModelPicker, type ModelPickerBody, type ModelPickerGroup, type ModelPickerItem, type ModelPickerProps, type ModelPickerStatus, type MultiEnumFieldSpec, NavMain, type NavMainProps, type NavMainRoute, type NavMainSubItem, type NavNotification, NavNotifications, type NavNotificationsProps, NavUser, type NavUserProps, type NavUserUser, NavigationMenu, NavigationMenuContent, NavigationMenuItem, NavigationMenuLink, NavigationMenuList, NavigationMenuTrigger, NavigationMenuViewport, NoAccessIllustration, NoResultsIllustration, type NormalizedFormSpec, type NormalizedText, type NumberFieldSpec, NumberInput, type NumberInputProps, OfflineIllustration, type OperatingMode, PROSE_HEADING_REM, PROSE_HEADING_TRACKING, PROSE_HEADING_WEIGHT, PageShell, type PageShellProps, Pagination, PaginationContent, PaginationEllipsis, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious, type PluralCategory, type PluralMessage, Popover, PopoverAnchor, PopoverContent, PopoverTrigger, Progress, type ProgressProps, ProseBlockquote, ProseHeading, type ProseHeadingLevel, type ProseHeadingProps, ProseInlineCode, ProseLink, type ProseLinkProps, ProseList, ProseListItem, type ProseListProps, ProseText, type ProseTextProps, type QuoteAddress, RadioGroup, RadioGroupItem, type RangeAddress, Rating, type RatingProps, type RectAddress, ResizableHandle, ResizablePanel, ResizablePanelGroup, type ResolvedFileSource, ResultCount, type ResultCountProps, Reveal, RevealGroup, type RevealGroupProps, type RevealProps, type Revision, type RevisionBranch, type RevisionEdge, RevisionTimeline, type RevisionTimelineDensity, type RevisionTimelineProps, STATUSES, STATUS_LABELS, STATUS_ROLE, STATUS_TONES, STATUS_TONE_ICONS, STREAMDOWN_TRANSLATION_KEYS, SchemaForm, SchemaFormDescription, type SchemaFormDescriptionProps, SchemaFormError, type SchemaFormErrorProps, SchemaFormFallback, type SchemaFormFallbackProps, SchemaFormField, type SchemaFormFieldProps, SchemaFormFields, type SchemaFormFieldsProps, type SchemaFormProps, SchemaFormProvider, type SchemaFormProviderProps, SchemaFormRoot, type SchemaFormRootProps, SchemaFormSubmit, type SchemaFormSubmitProps, SchemaFormTestAction, type SchemaFormTestActionProps, type SchemaFormTestActionStatus, SchemaFormTitle, type SchemaFormTitleProps, ScrollArea, ScrollBar, SectionHeader, type SectionHeaderProps, SegmentedField, type SegmentedFieldOption, type SegmentedFieldProps, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectSeparator, SelectTrigger, SelectValue, Separator, type SeparatorProps, type SessionCapability, type SessionQuickAction, type SessionWhatsNewItem, Sheet, SheetClose, SheetContent, type SheetContentProps, SheetDescription, SheetFooter, SheetHeader, SheetPortal, SheetTitle, SheetTrigger, type Shortcut, type ShortcutGroup, SideDock, type SideDockProps, Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupAction, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarInput, SidebarInset, type SidebarInsetGutter, type SidebarInsetProps, SidebarMenu, SidebarMenuAction, SidebarMenuBadge, SidebarMenuButton, SidebarMenuItem, SidebarMenuSkeleton, SidebarMenuSub, SidebarMenuSubButton, SidebarMenuSubItem, SidebarProvider, SidebarRail, SidebarSeparator, SidebarTrigger, Skeleton, type SkeletonProps, SkipLink, type SkipLinkProps, type SlashCommand, Slider, SliderNumber, type SliderNumberProps, type SliderProps, type SliderThumbProps, Spinner, type SpinnerProps, SplitPanel, type SplitPanelProps, type SplitPanelTone, StatePanel, type StatePanelProps, type Status, StatusBadge, type StatusBadgeProps, StatusIcon, type StatusIconProps, type StatusTone, type StreamdownTranslationKey, type StreamdownTranslationMap, type StringFieldSpec, SuccessIllustration, Switch, TEXT_ROLE_REM, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, TagInput, type TagInputProps, TeamSwitcher, type TeamSwitcherProps, type TeamSwitcherTeam, Text, type TextProps, type TextRole, type TextTone, type TextVariant, Textarea, type TextareaProps, type ThemePreference, ThemeSwitcher, type ThemeSwitcherProps, type ThemeTransitionEffect, Timeline, type TimelineEntry, TimelineItem, type TimelineItemProps, type TimelineProps, TimelineRoot, type TimelineRootProps, type TimelineStatus, Toaster, type ToasterProps, Toggle, ToggleGroup, ToggleGroupItem, Toolbar, ToolbarButton, type ToolbarButtonProps, type ToolbarProps, ToolbarSeparator, type ToolbarSeparatorProps, ToolbarSlot, ToolbarToggleGroup, type ToolbarToggleGroupProps, ToolbarToggleItem, type ToolbarToggleItemProps, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, TopNav, type TopNavProps, Transfer, type TransferItem, type TransferProps, Tree, type TreeNode, type TreeProps, TreeSelect, type TreeSelectProps, type TriggerBoundary, type TriggerQuery, UnsupportedJsonSchemaError, type UploadFile, type UseCollapsiblePanelOptions, type UseCollapsiblePanelReturn, type UseCopyToClipboardOptions, type UseDialogDismissGuardOptions, type UseTreeKeyboardOptions, type UseTreeKeyboardResult, ViewToolbar, ViewToolbarFilters, type ViewToolbarFiltersProps, type ViewToolbarProps, VirtualSelect, type VirtualSelectOption, type VirtualSelectProps, Wizard, WizardNav, type WizardNavProps, type WizardProps, WizardStep, type WizardStepMeta, type WizardStepProps, WizardSteps, type WizardStepsProps, type WizardValidator, type Workspace, WorkspacePicker, type WorkspacePickerProps, agentEventOutcomeStatus, alertVariants, badgeVariants, bentoGridItemVariants, booleanFieldSchema, buttonGroupVariants, buttonVariants, cardVariants, checkFileIssue, cn, collapseDiffRows, collectValidatableFields, countItems, defaultMentionFilter, defaultSlashCommandFilter, dialogContentVariants, diffLineAccessibleLabel, diffLineMarker, downloadBlob, downloadUrl, effortRungForIndex, enumFieldSchema, enumOptionSchema, expandDialogPanesVariants, extensionOf, fieldLabel, fieldSpecSchema, fileFieldSchema, fileIconFor, fileMatchesAccept, findFieldByName, findTriggerQuery, formSpecSchema, formatElapsed, formatLastOpened, fromJsonSchema, fromTimelineStatus, groupFieldSchema, groupItemSchema, headingVariants, hunkVariants, illustrationAccent, initialFormValues, inputGroupAddonVariants, inputGroupVariants, insertMention, integerFieldSchema, isCustomStatus, isFieldVisible, isModuleNotFoundMessage, isOptionalPeerMissing, keyValueFieldSchema, keyValueRowSchema, laneColor, listFieldSchema, mediaTypeFromName, mentionAt, mentionEnd, modelPickerBody, multiEnumFieldSchema, navigationMenuTriggerStyle, normalizeFileSource, normalizeFormSpec, normalizeQuoteText, normalizeQuoteTextWithOffsets, normalizeRanges, numberFieldSchema, optionLabel, optionValue, progressIndicatorVariants, queryToRanges, remapMentions, replaceTriggerRun, resolveFileKind, revealVariants, revisionTimelineVariants, serializeMentions, showsInlineError, sidebarMenuButtonVariants, splitPaneVariants, statePanelVariants, statusBadgeVariants, stepIndex, stringFieldSchema, textVariants, toggleVariants, toolbarVariants, useCollapsiblePanel, useCommandActiveItemId, useCopyToClipboard, useDialogDismissGuard, useDiffRows, useFileUpload, useIsMobile, useLocale, useMentionInput, useSidebar, useStreamdownTranslations, useThemeTransition, useTreeKeyboard, useVirtualListbox, validateField, validateForm };