@elabs-ai/components-ai 4.0.0 → 4.1.0

package/src/permission-mode-select.stories.tsx

@@ -0,0 +1,82 @@
+/**
+ * PermissionModeSelect — the standing-permission-policy chooser (#104).
+ *
+ * Distinct from `ApprovalCard`/`Confirmation` (#103): that renders ONE
+ * per-call decision; this renders the standing POLICY that decides how many
+ * of those decisions ever get asked. The mode vocabulary below is example
+ * data only — the component hardcodes no agent's mode names.
+ */
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, fn } from "storybook/test";
+
+import { PermissionModeSelect, type PermissionMode } from "./permission-mode-select";
+
+const MODES: PermissionMode[] = [
+  {
+    id: "ask",
+    label: "Ask each time",
+    consequence: "Every command and file edit waits for your approval before it runs.",
+  },
+  {
+    id: "auto-safe",
+    label: "Auto-approve safe actions",
+    consequence:
+      "Reads and edits inside this project run without asking; a shell command, or anything outside the project, still asks.",
+    keyHint: "⌥⇧A",
+  },
+  {
+    id: "unrestricted",
+    label: "Unrestricted",
+    consequence:
+      "Every action runs immediately, including shell commands and edits outside this project — nothing is held back for approval.",
+    keyHint: "⌥⇧U",
+  },
+];
+
+const meta = {
+  title: "AI/PermissionModeSelect",
+  component: PermissionModeSelect,
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "A standing-permission-policy chooser: each mode carries the sentence describing what it actually permits, and the mode currently in force is marked in text (not colour alone). Built on the RadioGroup primitive for keyboard/announcement behaviour; the mode vocabulary is entirely app-supplied via the `modes` prop.",
+      },
+    },
+  },
+  args: {
+    modes: MODES,
+    currentId: "ask",
+    onValueChange: fn(),
+  },
+  tags: ["autodocs"],
+} satisfies Meta<typeof PermissionModeSelect>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Three modes, each with its consequence sentence; "Ask each time" is in force. */
+export const Default: Story = {
+  render: (args) => <PermissionModeSelect {...args} className="max-w-md" />,
+};
+
+/** Selecting a different mode reports the new id without moving the "Current" marker. */
+export const SelectingADifferentMode: Story = {
+  render: (args) => <PermissionModeSelect {...args} className="max-w-md" />,
+  play: async ({ canvas, args, userEvent }) => {
+    const current = canvas.getByRole("radio", { name: /ask each time.*current/i });
+    await expect(current).toBeChecked();
+
+    const unrestricted = canvas.getByRole("radio", { name: "Unrestricted" });
+    await userEvent.click(unrestricted);
+
+    await expect(unrestricted).toBeChecked();
+    await expect(args.onValueChange).toHaveBeenCalledWith("unrestricted");
+    // The mode in force is app-controlled — selecting a new highlight does not
+    // relabel a different mode "current" on its own.
+    await expect(
+      canvas.getByRole("radio", { name: /ask each time.*current/i }),
+    ).toBeInTheDocument();
+  },
+};

package/src/permission-mode-select.test.tsx

@@ -0,0 +1,100 @@
+import { describe, expect, it, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { PermissionModeSelect, type PermissionMode } from "./permission-mode-select";
+
+const modes: PermissionMode[] = [
+  {
+    id: "ask",
+    label: "Ask each time",
+    consequence: "Waits for your approval before every command and file edit.",
+  },
+  {
+    id: "auto",
+    label: "Auto-approve safe actions",
+    consequence:
+      "Approves reads and edits in this project automatically; shell commands still ask.",
+  },
+  {
+    id: "full",
+    label: "Unrestricted",
+    consequence: "Runs every action immediately — nothing is held back for approval.",
+  },
+];
+
+describe("PermissionModeSelect", () => {
+  it("renders every mode's consequence sentence", () => {
+    render(<PermissionModeSelect currentId="ask" modes={modes} />);
+
+    for (const mode of modes) {
+      expect(screen.getByText(mode.consequence)).toBeInTheDocument();
+    }
+  });
+
+  it("links each consequence sentence to its radio as an accessible DESCRIPTION", () => {
+    // Rendering the sentence is not the same as delivering it. A screen-reader
+    // user arrowing through the modes hears the radio's name and its
+    // description — nothing else in the option's box. Without the
+    // `aria-describedby` link they hear "Unrestricted" and never hear what
+    // unrestricted costs them, which is the exact failure this component's
+    // required `consequence` field exists to prevent. Asserting the text is
+    // merely present would pass on that broken markup, so assert the LINK.
+    render(<PermissionModeSelect currentId="ask" modes={modes} />);
+
+    for (const mode of modes) {
+      const radio = screen.getByRole("radio", { name: new RegExp(mode.label) });
+      const describedBy = radio.getAttribute("aria-describedby");
+
+      expect(describedBy).toBeTruthy();
+      expect(document.getElementById(describedBy as string)).toHaveTextContent(mode.consequence);
+    }
+  });
+
+  it("marks the in-force mode in the ACCESSIBLE NAME, not only via a class or data-* attribute", () => {
+    render(<PermissionModeSelect currentId="auto" modes={modes} />);
+
+    // The load-bearing assertion: querying by accessible NAME is the only way
+    // to prove the marker reaches a screen reader. Two class strings differing,
+    // or a bare `data-current` attribute, would pass a naive test while an AT
+    // user hears nothing — that is exactly the gap this test closes.
+    expect(
+      screen.getByRole("radio", { name: /auto-approve safe actions.*current/i }),
+    ).toBeInTheDocument();
+
+    // The other modes' accessible names carry no such marker.
+    expect(screen.getByRole("radio", { name: "Ask each time" })).toBeInTheDocument();
+    expect(screen.getByRole("radio", { name: "Unrestricted" })).toBeInTheDocument();
+  });
+
+  it("selecting a different mode reports its id without mutating currentId", async () => {
+    const onValueChange = vi.fn();
+    render(<PermissionModeSelect currentId="ask" modes={modes} onValueChange={onValueChange} />);
+
+    await userEvent.click(screen.getByRole("radio", { name: "Unrestricted" }));
+
+    expect(onValueChange).toHaveBeenCalledTimes(1);
+    expect(onValueChange).toHaveBeenCalledWith("full");
+
+    // The newly-highlighted radio is checked…
+    expect(screen.getByRole("radio", { name: "Unrestricted" })).toBeChecked();
+    // …but `currentId` — an app-controlled prop the component never writes to
+    // — still names "Ask each time": the marker has not moved to the
+    // selection, and "Unrestricted" carries no "current" marker of its own.
+    expect(screen.getByRole("radio", { name: /ask each time.*current/i })).toBeInTheDocument();
+    expect(screen.queryByRole("radio", { name: /unrestricted.*current/i })).not.toBeInTheDocument();
+  });
+
+  it("does not hardcode any mode vocabulary — every label/consequence comes from props", () => {
+    const customModes: PermissionMode[] = [
+      {
+        id: "x",
+        label: "Read-only sandbox",
+        consequence: "Nothing outside memory is ever touched.",
+      },
+    ];
+    render(<PermissionModeSelect currentId="x" modes={customModes} />);
+
+    expect(screen.getByRole("radio", { name: /read-only sandbox.*current/i })).toBeInTheDocument();
+    expect(screen.getByText("Nothing outside memory is ever touched.")).toBeInTheDocument();
+  });
+});

package/src/permission-mode-select.tsx

@@ -0,0 +1,137 @@
+"use client";
+
+import { forwardRef, useId, type ComponentProps } from "react";
+import { Badge, Kbd, Label, RadioGroup, RadioGroupItem, useLocale } from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+
+/**
+ * PermissionModeSelect — the standing-permission-policy chooser (#104).
+ *
+ * Distinct from `Confirmation`/`ApprovalCard` (#103): those render ONE
+ * per-call decision ("may I run this command?"). This renders the POLICY
+ * that governs how many of those per-call decisions ever occur ("how much
+ * may you do without asking?"). The two stay separate components with a
+ * documented relationship rather than one growing a boolean "policy mode"
+ * prop — see `.claude/rules/component-api.md` ("Avoid boolean-prop
+ * proliferation").
+ *
+ * The mode vocabulary is entirely app-defined: no agent's mode names are
+ * hardcoded in this file or in `PermissionMode`/`PermissionModeSelectProps`.
+ * `consequence` is a REQUIRED field — a mode whose effect is unstated is
+ * exactly the failure this component exists to prevent (three unlabelled
+ * radio buttons).
+ *
+ * Built on `@elabs-ai/components-ui`'s `RadioGroup` (Radix) for roving
+ * focus / arrow-key navigation / Space-Enter selection / announcement — this
+ * component does not hand-roll any of that. The in-force mode is marked in
+ * TEXT: a "Current" badge lives inside the `<Label>` associated with that
+ * mode's radio input, so it is part of the control's accessible name and
+ * recoverable in greyscale — never colour alone (WCAG 1.4.1).
+ */
+export interface PermissionMode {
+  id: string;
+  label: string;
+  /** What this mode actually permits — required, not optional. */
+  consequence: string;
+  keyHint?: string;
+}
+
+export interface PermissionModeSelectProps extends ComponentProps<"div"> {
+  modes: PermissionMode[];
+  value?: string;
+  defaultValue?: string;
+  onValueChange?: (id: string) => void;
+  /** The mode currently in force, marked distinctly from the highlighted one. */
+  currentId?: string;
+}
+
+export const PermissionModeSelect = forwardRef<HTMLDivElement, PermissionModeSelectProps>(
+  function PermissionModeSelect(
+    { modes, value, defaultValue, onValueChange, currentId, className, dir, ...props },
+    ref,
+  ) {
+    const { t } = useLocale();
+    const baseId = useId();
+
+    return (
+      <RadioGroup
+        ref={ref}
+        // `dir` on a plain <div> is a free-form HTML string; Radix's RadioGroup
+        // narrows it to "ltr" | "rtl". Cast at this single call site rather
+        // than widening (and so weakening) the public prop type.
+        dir={dir as "ltr" | "rtl" | undefined}
+        // The RadioGroup's own highlighted value is independent of `currentId`
+        // (the mode already in force) — they answer different questions, so
+        // neither prop ever derives the other except as an uncontrolled
+        // starting point: with nothing else specified, pre-select the mode
+        // that is currently in force.
+        defaultValue={defaultValue ?? currentId}
+        value={value}
+        onValueChange={onValueChange}
+        data-slot="permission-mode-select"
+        className={cn("grid gap-3", className)}
+        {...props}
+      >
+        {modes.map((mode) => {
+          const isCurrent = mode.id === currentId;
+          const itemId = `${baseId}-${mode.id}`;
+          // The consequence sentence is the whole point of this component (see
+          // the `consequence` prop doc above), so it has to reach assistive
+          // tech as a DESCRIPTION of the radio — not merely sit next to it in
+          // the DOM. Without this link a screen-reader user arrowing through
+          // the modes hears "Unrestricted" and never hears what unrestricted
+          // costs them. Same wiring as `ApprovalCardOptions` in
+          // `confirmation.tsx`, deliberately: one convention, not two.
+          const consequenceId = `${itemId}-consequence`;
+
+          return (
+            <div
+              key={mode.id}
+              data-slot="permission-mode-select-option"
+              className={cn(
+                "flex items-start gap-3 rounded-lg border border-border bg-card p-4",
+                "has-[[data-state=checked]]:border-primary",
+              )}
+            >
+              <RadioGroupItem
+                aria-describedby={consequenceId}
+                className="mt-1"
+                data-slot="permission-mode-select-input"
+                id={itemId}
+                value={mode.id}
+              />
+              <div className="grid flex-1 gap-1">
+                <div className="flex items-center justify-between gap-2">
+                  <Label
+                    className="text-body flex items-center gap-2 font-medium"
+                    data-slot="permission-mode-select-label"
+                    htmlFor={itemId}
+                  >
+                    {mode.label}
+                    {isCurrent ? (
+                      <Badge data-slot="permission-mode-select-current" variant="secondary">
+                        {t("ai.permissionModeSelect.current")}
+                      </Badge>
+                    ) : null}
+                  </Label>
+                  {mode.keyHint ? (
+                    <Kbd data-slot="permission-mode-select-key-hint">{mode.keyHint}</Kbd>
+                  ) : null}
+                </div>
+                <p
+                  className="text-meta text-muted-foreground"
+                  data-slot="permission-mode-select-consequence"
+                  id={consequenceId}
+                >
+                  {mode.consequence}
+                </p>
+              </div>
+            </div>
+          );
+        })}
+      </RadioGroup>
+    );
+  },
+);
+
+PermissionModeSelect.displayName = "PermissionModeSelect";

package/src/persona-missing-peer.test.tsx

@@ -0,0 +1,54 @@
+/**
+ * Issue #33 — `@rive-app/react-webgl2` is an OPTIONAL peer of
+ * `@elabs-ai/components-ai`, reached only through `lazy(() =>
+ * import("./_persona-rive"))` inside `Persona` (ADR 0019). A REJECTED `lazy()`
+ * import throws during render — `Suspense` alone does not catch that (it only
+ * covers the pending state) — so `Persona` wraps it in `LazyEngineBoundary`
+ * (`_lazy-engine-boundary.tsx`). This locks that the boundary actually falls
+ * back to the placeholder instead of taking the whole tree down.
+ *
+ * Separate file from `persona.test.tsx`: that file exercises the real
+ * (unmocked) `./_persona-rive` module and never awaits its resolution; this
+ * file mocks it to simulate the optional peer being absent, without touching
+ * the sibling file's assumptions.
+ *
+ * `vi.mock` factories are hoisted, so the mock itself must resolve
+ * successfully (a factory that throws or returns a rejected promise gets
+ * intercepted by Vitest's OWN "error when mocking a module" diagnostic
+ * instead of the message this test needs — see
+ * `interactive-terminal-missing-peer.test.tsx` for the same finding). So the
+ * module resolves fine and the simulated failure instead comes from the
+ * default export THROWING when React renders it — a real render-phase error,
+ * which is exactly what `LazyEngineBoundary` exists to catch.
+ */
+import { act, cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("./_persona-rive", () => ({
+  default: () => {
+    throw new Error("Cannot find module '@rive-app/react-webgl2'");
+  },
+}));
+
+import { Persona } from "./persona";
+
+afterEach(cleanup);
+
+const flush = () => act(async () => void (await new Promise((resolve) => setTimeout(resolve, 0))));
+
+describe("Persona — missing optional peer (#33)", () => {
+  it("falls back to the placeholder instead of crashing when the Rive engine fails to load", async () => {
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    render(<Persona state="idle" fallback={<span>resting</span>} />);
+    await flush();
+
+    // The tree survived — the caller-supplied fallback rendered — rather than
+    // the whole component (or its ancestors) unmounting.
+    expect(screen.getByText("resting")).toBeInTheDocument();
+    // The failure is still observable to a developer, not silently eaten.
+    expect(errorSpy).toHaveBeenCalled();
+
+    errorSpy.mockRestore();
+  });
+});

package/src/persona.tsx

@@ -2,10 +2,10 @@
 
 import { cn } from "@elabs-ai/components-ui/lib/cn";
 import { useLocale } from "@elabs-ai/components-ui";
-import type { RiveParameters } from "@rive-app/react-webgl2";
 import type { FC, ReactNode } from "react";
 import { lazy, memo, Suspense, useCallback, useState } from "react";
 
+import { LazyEngineBoundary } from "./_lazy-engine-boundary";
 import { PERSONA_SOURCES, type PersonaState, type PersonaVariant } from "./persona-sources";
 
 export { PERSONA_SOURCES };
@@ -15,10 +15,46 @@ export type { PersonaState, PersonaVariant };
  * The Rive runtime lives behind a dynamic import — `@rive-app/react-webgl2`
  * declares no `sideEffects`, so a static import would put the whole WebGL2
  * runtime and its `.wasm` in every consumer's entry chunk, `Persona` rendered or
- * not. `RiveParameters` above is a TYPE import and erases. See ADR 0019.
+ * not. See ADR 0019.
+ *
+ * Issue #101: `@rive-app/react-webgl2` (and, transitively, `@rive-app/webgl2`,
+ * which re-exports `RiveParameters`) is an OPTIONAL peer, so no PUBLIC export's
+ * type may structurally reference it — doing so would name the peer's module
+ * specifier in this package's generated root `.d.ts` and hand a
+ * `skipLibCheck: false` consumer who has not installed the peer a `TS2307` just
+ * for importing the barrel. `PersonaRiveEvent`/`PersonaRiveEventCallback` below
+ * are an OWNED mirror of the peer's `Event`/`EventCallback` (from
+ * `@rive-app/webgl2`'s `rive.d.ts`) — every one of `RiveParameters`'s
+ * `onLoad`/`onLoadError`/`onPause`/`onPlay`/`onStop` callbacks share that exact
+ * same `EventCallback` shape, so one owned type covers all five. The
+ * conformance assertion in `_persona-rive.tsx` (which still imports the real
+ * peer types — that module is reached only through `lazy()` and never sits in
+ * the barrel's declaration graph) proves this mirror stays assignable to the
+ * real peer type; a future Rive release that changes `Event`'s shape fails
+ * `pnpm --filter @elabs-ai/components-ai typecheck` locally instead of
+ * reaching a consumer as silent drift. Mirrors the identical pattern
+ * `packages/terminal/src/interactive-terminal.tsx` already established for
+ * `@xterm/xterm`'s `ITheme` (also issue #101).
  */
 const PersonaRive = lazy(() => import("./_persona-rive"));
 
+/**
+ * Owned mirror of `@rive-app/webgl2`'s `Event` (the parameter type every
+ * `RiveParameters` callback receives) — see the module doc comment above.
+ * `data` is deliberately widened to `unknown` rather than replicating Rive's
+ * `RiveEventPayload`/`LoopEvent`/`RiveFile` union: no callback in this package
+ * (or, realistically, a consumer's) narrows it, and `unknown` remains a safe,
+ * structurally-compatible supertype of the real union for the conformance
+ * assertion in `_persona-rive.tsx`.
+ */
+export interface PersonaRiveEvent {
+  type: string;
+  data?: unknown;
+}
+
+/** Owned mirror of `@rive-app/webgl2`'s `EventCallback`. */
+export type PersonaRiveEventCallback = (event: PersonaRiveEvent) => void;
+
 /**
  * Localized status announced when `state` changes, one key per `PersonaState`.
  * Typed as a `Record` (not a bare template string) so a `PersonaState` value
@@ -40,12 +76,12 @@ export interface PersonaProps {
    * so a blocked fetch never leaves an empty box.
    */
   fallback?: ReactNode;
-  onLoad?: RiveParameters["onLoad"];
-  onLoadError?: RiveParameters["onLoadError"];
-  onPause?: RiveParameters["onPause"];
-  onPlay?: RiveParameters["onPlay"];
+  onLoad?: PersonaRiveEventCallback;
+  onLoadError?: PersonaRiveEventCallback;
+  onPause?: PersonaRiveEventCallback;
+  onPlay?: PersonaRiveEventCallback;
   onReady?: () => void;
-  onStop?: RiveParameters["onStop"];
+  onStop?: PersonaRiveEventCallback;
   /**
    * Override the `.riv` artwork URL — point at a self-hosted copy when a CSP
    * blocks the default origin. Defaults to `PERSONA_SOURCES[variant].source`.
@@ -101,7 +137,7 @@ export const Persona: FC<PersonaProps> = memo(
     const { t } = useLocale();
     const [failed, setFailed] = useState(false);
 
-    const handleLoadError = useCallback<NonNullable<RiveParameters["onLoadError"]>>(
+    const handleLoadError = useCallback<PersonaRiveEventCallback>(
       (event) => {
         setFailed(true);
         onLoadError?.(event);
@@ -116,20 +152,30 @@ export const Persona: FC<PersonaProps> = memo(
     const visual = failed ? (
       placeholder
     ) : (
-      <Suspense fallback={placeholder}>
-        <PersonaRive
-          className={className}
-          onLoad={onLoad}
-          onLoadError={handleLoadError}
-          onPause={onPause}
-          onPlay={onPlay}
-          onReady={onReady}
-          onStop={onStop}
-          source={source}
-          src={src ?? source.source}
-          state={state}
-        />
-      </Suspense>
+      // The Rive runtime is an optional peer (`@rive-app/react-webgl2`, issue
+      // #33) reached via `lazy()` — a REJECTED import throws during render,
+      // which `Suspense` alone cannot catch (it only covers the pending
+      // state). `LazyEngineBoundary` catches that throw and falls back to the
+      // same placeholder a load-time `onLoadError` already renders.
+      // `renderMissing` stays pure — `LazyEngineBoundary.componentDidCatch`
+      // already logs the error once, correctly; logging it again here would
+      // double-report on every render this fallback re-mounts under.
+      <LazyEngineBoundary renderMissing={() => placeholder}>
+        <Suspense fallback={placeholder}>
+          <PersonaRive
+            className={className}
+            onLoad={onLoad}
+            onLoadError={handleLoadError}
+            onPause={onPause}
+            onPlay={onPlay}
+            onReady={onReady}
+            onStop={onStop}
+            source={source}
+            src={src ?? source.source}
+            state={state}
+          />
+        </Suspense>
+      </LazyEngineBoundary>
     );
 
     return (

package/src/plan.stories.tsx

@@ -0,0 +1,166 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import {
+  Plan,
+  PlanAction,
+  PlanApprove,
+  PlanComment,
+  PlanContent,
+  PlanDescription,
+  PlanFooter,
+  PlanHeader,
+  PlanRequestChanges,
+  PlanStatusLine,
+  PlanTitle,
+  PlanTrigger,
+} from "./plan";
+
+const meta = {
+  title: "AI/Plan",
+  component: Plan,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "The CHAT plan card — what the agent intends to do, optionally with an accept/edit decision. The console counterpart of a three-state agent checklist is `Terminal/TerminalTodoList`; the summary of what already ran is `AI/Task`. See [Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs). `status` is additive: a `Plan` rendered without it has no ARIA region, no rail and no status line.",
+      },
+    },
+  },
+} satisfies Meta<typeof Plan>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+const steps = (
+  <ol className="list-decimal space-y-1 ps-5 text-body text-muted-foreground">
+    <li>Pull the Q3 10-Q and Q2 board pack</li>
+    <li>Reconcile to the warehouse revenue table</li>
+    <li>Compute QoQ growth, ARR and gross margin</li>
+    <li>Draft a one-page note and export the figures</li>
+  </ol>
+);
+
+// The pre-#108 shape — no `status`, `isStreaming` defaults to `false`. Kept as
+// the Default story so the legacy, display-only usage stays exercised exactly
+// as before (#108 acceptance: existing usage renders unchanged).
+export const Default: Story = {
+  render: () => (
+    <Plan>
+      <PlanHeader>
+        <div className="min-w-0">
+          <PlanTitle>Draft the Q3 board note</PlanTitle>
+          <PlanDescription>
+            Retrieve filings, reconcile to the warehouse, then summarize.
+          </PlanDescription>
+        </div>
+        <PlanAction>
+          <PlanTrigger />
+        </PlanAction>
+      </PlanHeader>
+      <PlanContent>{steps}</PlanContent>
+      <PlanFooter>
+        <span className="text-meta text-muted-foreground">
+          4 steps · grounded in filings + warehouse
+        </span>
+      </PlanFooter>
+    </Plan>
+  ),
+};
+
+// The legacy display-only signal (pre-#108): the title/description shimmer
+// while the plan is still arriving. No decision contract is attached.
+export const Streaming: Story = {
+  render: () => (
+    <Plan isStreaming>
+      <PlanHeader>
+        <div className="min-w-0">
+          <PlanTitle>Draft the Q3 board note</PlanTitle>
+          <PlanDescription>Retrieving filings…</PlanDescription>
+        </div>
+        <PlanAction>
+          <PlanTrigger />
+        </PlanAction>
+      </PlanHeader>
+      <PlanContent>{steps}</PlanContent>
+    </Plan>
+  ),
+};
+
+// The decision contract (#108): a pending plan is a LABELLED GROUP (not
+// `role="alert"`) containing the three named actions — Approve is the filled
+// primary path, Request changes / Comment are quieter.
+export const Awaiting: Story = {
+  render: () => (
+    <Plan status="awaiting">
+      <PlanHeader>
+        <div className="min-w-0">
+          <PlanTitle>Draft the Q3 board note</PlanTitle>
+          <PlanDescription>
+            Retrieve filings, reconcile to the warehouse, then summarize.
+          </PlanDescription>
+        </div>
+        <PlanAction>
+          <PlanTrigger />
+        </PlanAction>
+      </PlanHeader>
+      <PlanContent>{steps}</PlanContent>
+      <PlanFooter className="flex-col items-stretch gap-3">
+        <PlanStatusLine />
+        <div className="flex w-full items-center justify-end gap-2">
+          <PlanComment>Comment</PlanComment>
+          <PlanRequestChanges>Request changes</PlanRequestChanges>
+          <PlanApprove>Approve</PlanApprove>
+        </div>
+      </PlanFooter>
+    </Plan>
+  ),
+};
+
+// A settled outcome renders `role="alert"`, the actions are gone, and the
+// outcome is carried in text + glyph (never rail colour alone).
+export const Approved: Story = {
+  render: () => (
+    <Plan status="approved">
+      <PlanHeader>
+        <div className="min-w-0">
+          <PlanTitle>Draft the Q3 board note</PlanTitle>
+          <PlanDescription>
+            Retrieve filings, reconcile to the warehouse, then summarize.
+          </PlanDescription>
+        </div>
+        <PlanAction>
+          <PlanTrigger />
+        </PlanAction>
+      </PlanHeader>
+      <PlanContent>{steps}</PlanContent>
+      <PlanFooter>
+        <PlanStatusLine />
+      </PlanFooter>
+    </Plan>
+  ),
+};
+
+export const ChangesRequested: Story = {
+  render: () => (
+    <Plan status="changes-requested">
+      <PlanHeader>
+        <div className="min-w-0">
+          <PlanTitle>Draft the Q3 board note</PlanTitle>
+          <PlanDescription>
+            Retrieve filings, reconcile to the warehouse, then summarize.
+          </PlanDescription>
+        </div>
+        <PlanAction>
+          <PlanTrigger />
+        </PlanAction>
+      </PlanHeader>
+      <PlanContent>{steps}</PlanContent>
+      <PlanFooter>
+        <PlanStatusLine>Changes requested — reconcile against Q2 instead</PlanStatusLine>
+      </PlanFooter>
+    </Plan>
+  ),
+};