From 2556d88eb69e46aa00250b7e3c5fc7fd785590ce Mon Sep 17 00:00:00 2001
From: Michael Ramos <mdramos8@gmail.com>
Date: Tue, 1 Sep 2026 23:20:55 -0700
Subject: [PATCH 1/6] feat(ui): pure decision spec for the unified header
 control
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

buildDecisionSpec maps { app, gate, count, hasFeedback,
approvalNotesSupported } onto one primary plus ordered menu items —
labels, subtitles and confirm strings verbatim from the approved
prototype (DESIGN_final-proposal.html). approvalNotesSupported gates
every approve-carrying item; the discard item is count-gated so it can
never offer to discard zero annotations; frozen copy is marked inline.
Pure (no React, no DOM) so the full state matrix runs in the plain
bun test lane.
---
 packages/ui/utils/decisionSpec.test.ts | 190 +++++++++++++++++
 packages/ui/utils/decisionSpec.ts      | 274 +++++++++++++++++++++++++
 2 files changed, 464 insertions(+)
 create mode 100644 packages/ui/utils/decisionSpec.test.ts
 create mode 100644 packages/ui/utils/decisionSpec.ts

diff --git a/packages/ui/utils/decisionSpec.test.ts b/packages/ui/utils/decisionSpec.test.ts
new file mode 100644
index 000000000..7ae058fca
--- /dev/null
+++ b/packages/ui/utils/decisionSpec.test.ts
@@ -0,0 +1,190 @@
+import { describe, expect, it } from 'bun:test';
+import {
+  buildDecisionSpec,
+  type DecisionSpec,
+  type DecisionSpecInput,
+} from './decisionSpec';
+
+/** Every input combination the spec can receive, for the invariant sweeps. */
+function allInputs(): DecisionSpecInput[] {
+  const inputs: DecisionSpecInput[] = [];
+  for (const app of ['annotate', 'review'] as const)
+    for (const gate of [false, true])
+      for (const hasFeedback of [false, true])
+        for (const approvalNotesSupported of [false, true])
+          for (const count of [0, 1, 3])
+            inputs.push({ app, gate, count, hasFeedback, approvalNotesSupported });
+  return inputs;
+}
+
+function itemIds(spec: DecisionSpec): string[] {
+  return spec.items.map((item) => item.id);
+}
+
+describe('buildDecisionSpec state matrix', () => {
+  // Guards the model itself: each row of the spec's state table produces the
+  // expected primary and the expected ordered menu.
+  it('annotate, no feedback, no gate → Done + note/request-changes', () => {
+    const spec = buildDecisionSpec({
+      app: 'annotate', gate: false, count: 0, hasFeedback: false, approvalNotesSupported: false,
+    });
+    expect(spec.primary.label).toBe('Done'); // frozen copy, maintainer-approved
+    expect(spec.primary.tone).toBe('success');
+    expect(spec.primary.icon).toBe('check');
+    expect(itemIds(spec)).toEqual(['note-with-approval', 'request-changes']);
+    // "Done with a note…" posts /api/feedback — never capability-gated.
+    expect(spec.items[0].composer?.actionLabel).toBe('Done — send note');
+    expect(spec.items[1].dividerBefore).toBe(true);
+    expect(spec.items[1].composer?.actionLabel).toBe('Send as feedback');
+  });
+
+  it('annotate, no feedback, gate → Approve; approve-note item only with the capability', () => {
+    const withCap = buildDecisionSpec({
+      app: 'annotate', gate: true, count: 0, hasFeedback: false, approvalNotesSupported: true,
+    });
+    expect(withCap.primary.label).toBe('Approve'); // frozen copy, maintainer-approved
+    expect(withCap.primary.tone).toBe('success');
+    expect(itemIds(withCap)).toEqual(['note-with-approval', 'request-changes']);
+    expect(withCap.items[0].label).toBe('Approve with a note…');
+
+    const withoutCap = buildDecisionSpec({
+      app: 'annotate', gate: true, count: 0, hasFeedback: false, approvalNotesSupported: false,
+    });
+    expect(itemIds(withoutCap)).toEqual(['request-changes']);
+    expect(withoutCap.items[0].dividerBefore).toBe(false);
+  });
+
+  it('annotate, feedback (n) → Send Feedback + note/(approve-with-notes)/discard', () => {
+    const nonGate = buildDecisionSpec({
+      app: 'annotate', gate: false, count: 3, hasFeedback: true, approvalNotesSupported: true,
+    });
+    expect(nonGate.primary.label).toBe('Send Feedback'); // frozen copy, maintainer-approved
+    expect(nonGate.primary.tone).toBe('primary');
+    expect(nonGate.primary.icon).toBe('send');
+    // No gate ⇒ no approve channel ⇒ no Approve-with-notes, capability or not.
+    expect(itemIds(nonGate)).toEqual(['note-with-feedback', 'discard-and-finish']);
+    expect(nonGate.items[1].label).toBe('Done, discard 3 annotations…');
+    expect(nonGate.items[1].confirm?.confirmText).toBe('Discard & finish'); // frozen copy
+
+    const gate = buildDecisionSpec({
+      app: 'annotate', gate: true, count: 3, hasFeedback: true, approvalNotesSupported: true,
+    });
+    expect(itemIds(gate)).toEqual(['note-with-feedback', 'approve-with-notes', 'discard-and-finish']);
+    expect(gate.items[1].label).toBe('Approve with notes'); // frozen copy, maintainer-approved
+    expect(gate.items[2].label).toBe('Approve, discard 3 annotations…');
+    expect(gate.items[2].confirm?.confirmText).toBe('Discard & approve'); // frozen copy
+
+    const gateNoCap = buildDecisionSpec({
+      app: 'annotate', gate: true, count: 3, hasFeedback: true, approvalNotesSupported: false,
+    });
+    expect(itemIds(gateNoCap)).toEqual(['note-with-feedback', 'discard-and-finish']);
+  });
+
+  it('review, no feedback → Approve; phase-1 menu is Request changes only', () => {
+    const phase1 = buildDecisionSpec({
+      app: 'review', gate: true, count: 0, hasFeedback: false, approvalNotesSupported: false,
+    });
+    expect(phase1.primary.label).toBe('Approve');
+    expect(itemIds(phase1)).toEqual(['request-changes']);
+
+    const phase2 = buildDecisionSpec({
+      app: 'review', gate: true, count: 0, hasFeedback: false, approvalNotesSupported: true,
+    });
+    expect(itemIds(phase2)).toEqual(['note-with-approval', 'request-changes']);
+    expect(phase2.items[0].label).toBe('Approve with a note…');
+  });
+
+  it('review, feedback (n) → Send Feedback + note/(approve-with-notes)/discard', () => {
+    const phase2 = buildDecisionSpec({
+      app: 'review', gate: true, count: 3, hasFeedback: true, approvalNotesSupported: true,
+    });
+    expect(phase2.primary.label).toBe('Send Feedback');
+    expect(phase2.primary.shortLabel).toBe('Send');
+    expect(itemIds(phase2)).toEqual(['note-with-feedback', 'approve-with-notes', 'discard-and-finish']);
+
+    const phase1 = buildDecisionSpec({
+      app: 'review', gate: true, count: 3, hasFeedback: true, approvalNotesSupported: false,
+    });
+    expect(itemIds(phase1)).toEqual(['note-with-feedback', 'discard-and-finish']);
+    expect(phase1.items[1].dividerBefore).toBe(true);
+  });
+});
+
+describe('buildDecisionSpec invariants', () => {
+  // Guards the maintainer's hard rule: Approve/Done and Send Feedback never
+  // render side by side — there is exactly one primary and the menu never
+  // smuggles a second one in.
+  it('never yields two primaries, in any input combination', () => {
+    for (const input of allInputs()) {
+      const spec = buildDecisionSpec(input);
+      expect(spec.primary.id).toBe('primary');
+      expect(itemIds(spec)).not.toContain('primary');
+      // The header shows Send Feedback XOR a positive finish, never both.
+      const positiveLabels = ['Done', 'Approve'];
+      if (spec.primary.label === 'Send Feedback') {
+        expect(positiveLabels).not.toContain(spec.primary.label);
+      } else {
+        expect(positiveLabels).toContain(spec.primary.label);
+      }
+    }
+  });
+
+  // Guards rendering an item that silently drops content: without the
+  // capability advert, no approve-carrying item exists in the approval flows.
+  it('approvalNotesSupported: false ⇒ no approve-carrying item anywhere', () => {
+    for (const input of allInputs()) {
+      if (input.approvalNotesSupported) continue;
+      if (input.app === 'annotate' && !input.gate) continue; // no approve channel at all
+      const ids = itemIds(buildDecisionSpec(input));
+      expect(ids).not.toContain('approve-with-notes');
+      expect(ids).not.toContain('note-with-approval');
+    }
+  });
+
+  // Guards a refactor that drops the one remaining guard dialog.
+  it('every discard item carries a confirm', () => {
+    for (const input of allInputs()) {
+      for (const item of buildDecisionSpec(input).items) {
+        if (item.id === 'discard-and-finish') {
+          expect(item.confirm).toBeDefined();
+          expect(item.tone).toBe('destructive');
+        }
+      }
+    }
+  });
+
+  // Guards a stale count in the label after an annotation is deleted.
+  it('interpolates the live count into the pill and the discard copy', () => {
+    const zero = buildDecisionSpec({
+      app: 'annotate', gate: false, count: 0, hasFeedback: true, approvalNotesSupported: false,
+    });
+    expect(zero.primary.count).toBeUndefined();
+    // Nothing to discard at zero — no discard item with a lying "0 annotations".
+    expect(itemIds(zero)).not.toContain('discard-and-finish');
+
+    const three = buildDecisionSpec({
+      app: 'review', gate: true, count: 3, hasFeedback: true, approvalNotesSupported: true,
+    });
+    expect(three.primary.count).toBe(3);
+    const discard = three.items.find((item) => item.id === 'discard-and-finish')!;
+    expect(discard.label).toContain('3');
+    expect(discard.confirm!.title).toContain('3');
+
+    const one = buildDecisionSpec({
+      app: 'annotate', gate: false, count: 1, hasFeedback: true, approvalNotesSupported: false,
+    });
+    const discardOne = one.items.find((item) => item.id === 'discard-and-finish')!;
+    expect(discardOne.label).toBe('Done, discard 1 annotation…');
+  });
+
+  // Every composer item must actually be a composer and every plain item must
+  // not — the control branches on these fields, so an item with both (or a
+  // confirm item with a composer) would render an unreachable surface.
+  it('composer and confirm are mutually exclusive per item', () => {
+    for (const input of allInputs()) {
+      for (const item of buildDecisionSpec(input).items) {
+        expect(item.composer && item.confirm).toBeFalsy();
+      }
+    }
+  });
+});
diff --git a/packages/ui/utils/decisionSpec.ts b/packages/ui/utils/decisionSpec.ts
new file mode 100644
index 000000000..2e9c00949
--- /dev/null
+++ b/packages/ui/utils/decisionSpec.ts
@@ -0,0 +1,274 @@
+/**
+ * Pure state→spec mapping for the unified header decision control.
+ *
+ * No React, no DOM, no imports — this is what keeps the state matrix testable
+ * in the plain `bun test` lane and keeps "both apps and both states are data,
+ * not forked components" true. `DecisionControl.tsx` renders whatever this
+ * returns; the apps translate ids into handlers.
+ *
+ * NOT host-supported surface: like ActionMenu/ConfirmDialog, this module is
+ * app-shared chrome and is deliberately absent from the README supported-import
+ * list and the strict-consumer tsconfig.
+ *
+ * Labels, subtitles and confirm strings are the approved prototype's, verbatim
+ * (DESIGN_final-proposal.html `spec()`), which is authoritative over any older
+ * branch or mock copy.
+ */
+
+export type DecisionActionId =
+  | 'primary'              // the left segment
+  | 'note-with-approval'   // "Done with a note…" / "Approve with a note…"
+  | 'request-changes'      // "Request changes…"
+  | 'note-with-feedback'   // "Send with a note…"
+  | 'approve-with-notes'   // review + gate-annotate; capability-gated
+  | 'discard-and-finish';  // "Done/Approve, discard n annotations…"
+
+export type DecisionTone = 'success' | 'primary' | 'destructive';
+
+export interface DecisionPrimary {
+  id: 'primary';
+  label: string;            // 'Done' | 'Approve' | 'Send Feedback'
+  shortLabel?: string;      // 'Send' — the lg-breakpoint label
+  mobileLabel?: string;     // compact/touch row label
+  title: string;            // tooltip / aria description
+  tone: Exclude<DecisionTone, 'destructive'>;
+  icon: 'check' | 'send';
+  count?: number;           // rendered as the inline pill; omitted when 0
+}
+
+export interface DecisionComposer {
+  title: string;            // popover back-button title, e.g. 'Send with a note'
+  actionLabel: string;      // the composer's own button, e.g. 'Send feedback with note'
+  tone: Exclude<DecisionTone, 'destructive'>;
+  icon: 'check' | 'send';
+  placeholder: string;      // 'Add a note...'
+}
+
+export interface DecisionConfirm {
+  title: string;
+  message: string;
+  confirmText: string;
+}
+
+export interface DecisionMenuItem {
+  id: Exclude<DecisionActionId, 'primary'>;
+  label: string;
+  subtitle: string;
+  tone: DecisionTone;
+  icon: 'check' | 'send';
+  dividerBefore?: boolean;
+  composer?: DecisionComposer;   // present ⇒ the item morphs the popover
+  confirm?: DecisionConfirm;     // present ⇒ the item raises one confirm
+}
+
+export interface DecisionSpec {
+  primary: DecisionPrimary;
+  items: DecisionMenuItem[];
+}
+
+export interface DecisionSpecInput {
+  app: 'annotate' | 'review';
+  /** Annotate: `gate`. Review: always true — review's primary decision IS approval. */
+  gate: boolean;
+  /** The count rendered in the pill and interpolated into labels. */
+  count: number;
+  /**
+   * Whether there is anything to send. Deliberately separate from `count`:
+   * annotate counts direct edits / saved-file changes / attachments as
+   * feedback with count 0 (`hasFeedbackContent` in the annotate app).
+   */
+  hasFeedback: boolean;
+  /** Does the runtime deliver feedback on approve? Gates every approve-carrying item. */
+  approvalNotesSupported: boolean;
+}
+
+export const DECISION_NOTE_PLACEHOLDER = 'Add a note...';
+
+function annotationNoun(count: number): string {
+  return count === 1 ? 'annotation' : 'annotations';
+}
+
+/**
+ * The empty state: no feedback to send, the primary is the positive finish.
+ * `approvalFlow` (gate annotate, or review) makes it `Approve`; plain annotate
+ * gets `Done`.
+ */
+function buildEmptySpec(input: DecisionSpecInput, approvalFlow: boolean): DecisionSpec {
+  // "Done with a note…" posts /api/feedback like every other non-gated annotate
+  // outcome, so it is never capability-gated. "Approve with a note…" carries a
+  // note on the approve channel, which four runtimes still discard — it renders
+  // only where the advert says delivery works (never an item that silently
+  // drops content).
+  const positive: DecisionMenuItem | null = approvalFlow
+    ? input.approvalNotesSupported
+      ? {
+          id: 'note-with-approval',
+          label: 'Approve with a note…',
+          subtitle: 'Approve and send a short note with it',
+          tone: 'success',
+          icon: 'check',
+          composer: {
+            title: 'Approve with a note',
+            actionLabel: 'Approve — send note',
+            tone: 'success',
+            icon: 'check',
+            placeholder: DECISION_NOTE_PLACEHOLDER,
+          },
+        }
+      : null
+    : {
+        id: 'note-with-approval',
+        label: 'Done with a note…',
+        subtitle: 'Finish and send a short note with the approval',
+        tone: 'success',
+        icon: 'check',
+        composer: {
+          title: 'Done with a note',
+          actionLabel: 'Done — send note',
+          tone: 'success',
+          icon: 'check',
+          placeholder: DECISION_NOTE_PLACEHOLDER,
+        },
+      };
+
+  const requestChanges: DecisionMenuItem = {
+    id: 'request-changes',
+    // Frozen copy (maintainer-approved): 'Request changes…'.
+    label: 'Request changes…',
+    subtitle: 'Write overall feedback — sent as a change request',
+    tone: 'primary',
+    icon: 'send',
+    dividerBefore: positive !== null,
+    composer: {
+      title: 'Request changes',
+      actionLabel: 'Send as feedback',
+      tone: 'primary',
+      icon: 'send',
+      placeholder: DECISION_NOTE_PLACEHOLDER,
+    },
+  };
+
+  return {
+    primary: approvalFlow
+      ? {
+          id: 'primary',
+          // Frozen copy (maintainer-approved): 'Approve'.
+          label: 'Approve',
+          title: 'Approve — no changes requested',
+          tone: 'success',
+          icon: 'check',
+        }
+      : {
+          id: 'primary',
+          // Frozen copy (maintainer-approved): 'Done'.
+          label: 'Done',
+          title: 'Finish — records that you reviewed with no feedback',
+          tone: 'success',
+          icon: 'check',
+        },
+    items: positive ? [positive, requestChanges] : [requestChanges],
+  };
+}
+
+/**
+ * The feedback state: something to send, the primary is `Send Feedback`.
+ * Identical across apps; only the discard item's verb follows the flow.
+ */
+function buildFeedbackSpec(input: DecisionSpecInput, approvalFlow: boolean): DecisionSpec {
+  const { count } = input;
+  const noun = annotationNoun(count);
+
+  const items: DecisionMenuItem[] = [
+    {
+      id: 'note-with-feedback',
+      label: 'Send with a note…',
+      subtitle:
+        count > 0
+          ? `Add an overall note on top of your ${count} ${noun}`
+          : 'Add an overall note on top of your feedback',
+      tone: 'primary',
+      icon: 'send',
+      composer: {
+        title: 'Send with a note',
+        actionLabel: 'Send feedback with note',
+        tone: 'primary',
+        icon: 'send',
+        placeholder: DECISION_NOTE_PLACEHOLDER,
+      },
+    },
+  ];
+
+  // The divider separates "send" alternates from "approve away" alternates —
+  // it sits before whichever approve-flavoured item comes first.
+  let dividerPending = true;
+
+  // Capability-gated AND count-gated: with zero annotations (feedback is
+  // direct edits/attachments) there are no notes to ride along, so the item
+  // would be a no-op with a lying label.
+  if (approvalFlow && input.approvalNotesSupported && count > 0) {
+    items.push({
+      id: 'approve-with-notes',
+      // Frozen copy (maintainer-approved): 'Approve with notes'.
+      label: 'Approve with notes',
+      subtitle: `Approve; your ${count} ${noun} ride along as non-blocking guidance`,
+      tone: 'success',
+      icon: 'check',
+      dividerBefore: dividerPending,
+    });
+    dividerPending = false;
+  }
+
+  // Destructive by definition — it throws the annotations away — so it always
+  // carries the one confirm the new model keeps. With count 0 there is nothing
+  // to discard and the item is omitted.
+  if (count > 0) {
+    items.push({
+      id: 'discard-and-finish',
+      label: approvalFlow
+        ? `Approve, discard ${count} ${noun}…`
+        : `Done, discard ${count} ${noun}…`,
+      subtitle: 'Asks to confirm — the annotations are not sent',
+      tone: 'destructive',
+      icon: 'check',
+      dividerBefore: dividerPending,
+      confirm: approvalFlow
+        ? {
+            title: `Discard ${count} ${noun} and approve?`,
+            message:
+              'Your annotations are change requests. Approving without them tells the agent no changes are needed.',
+            // Frozen copy (maintainer-approved): 'Discard & approve'.
+            confirmText: 'Discard & approve',
+          }
+        : {
+            title: `Discard ${count} ${noun} and finish?`,
+            message:
+              'Your annotations are change requests. Finishing without them sends a "reviewed, no feedback" record.',
+            // Frozen copy (maintainer-approved): 'Discard & finish'.
+            confirmText: 'Discard & finish',
+          },
+    });
+  }
+
+  return {
+    primary: {
+      id: 'primary',
+      // Frozen copy (maintainer-approved): 'Send Feedback'.
+      label: 'Send Feedback',
+      shortLabel: 'Send',
+      mobileLabel: 'Send feedback',
+      title: 'Send your feedback to the agent',
+      tone: 'primary',
+      icon: 'send',
+      count: count > 0 ? count : undefined,
+    },
+    items,
+  };
+}
+
+export function buildDecisionSpec(input: DecisionSpecInput): DecisionSpec {
+  // Review's primary positive decision IS approval, gate flag or not.
+  const approvalFlow = input.app === 'review' || input.gate;
+  return input.hasFeedback
+    ? buildFeedbackSpec(input, approvalFlow)
+    : buildEmptySpec(input, approvalFlow);
+}

From 90dd3577e15c28229bafd8bdb0df7bd24620f45f Mon Sep 17 00:00:00 2001
From: Michael Ramos <mdramos8@gmail.com>
Date: Tue, 1 Sep 2026 23:21:03 -0700
Subject: [PATCH 2/6] feat(ui): DecisionControl split pill + note field/dialog
 + dismissable-popover hook
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The joined split control: incumbent primary segment (never opens the
popover, never fades while it is open — the popover holds only
alternates, so the primary keeps its meaning), caret popover with
role=menu rows and roving arrow-key focus, in-place composer morph
(Esc ladder consumes on exactly two rungs, drafts kept; Mod+Enter
submits trimmed; plain Enter is a newline; empty note refocuses instead
of graying), and the single discard confirm through ConfirmDialog.

useDismissablePopover is the shared pointerdown-outside + Escape effect
with the framed-surface strategy: window blur to an iframe dismisses,
since iframe clicks never reach the parent document. ActionMenuItem
gains additive role/className props and ExitButton an additive
appearance='ghost' form; defaults are byte-identical for existing
consumers. DOM tests registered in the CI seam-contract step so they
cannot silently skip.
---
 .github/workflows/test.yml                    |   1 +
 packages/ui/components/ActionMenu.tsx         |  11 +-
 .../ui/components/DecisionControl.test.tsx    | 293 ++++++++++
 packages/ui/components/DecisionControl.tsx    | 542 ++++++++++++++++++
 packages/ui/components/ToolbarButtons.tsx     |  20 +-
 packages/ui/hooks/useDismissablePopover.ts    |  57 ++
 6 files changed, 922 insertions(+), 2 deletions(-)
 create mode 100644 packages/ui/components/DecisionControl.test.tsx
 create mode 100644 packages/ui/components/DecisionControl.tsx
 create mode 100644 packages/ui/hooks/useDismissablePopover.ts

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 3116632e9..451258e35 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -177,6 +177,7 @@ jobs:
           packages/editor/components/AppHeader.webmcpIndicator.test.tsx
           packages/ui/components/MathBlock.firstPaint.test.tsx
           packages/ui/components/DiagramBlock.lazyRetry.test.tsx
+          packages/ui/components/DecisionControl.test.tsx
 
   opencode-v2:
     name: OpenCode 2 installed package
diff --git a/packages/ui/components/ActionMenu.tsx b/packages/ui/components/ActionMenu.tsx
index 4993ab2b3..4f7186b19 100644
--- a/packages/ui/components/ActionMenu.tsx
+++ b/packages/ui/components/ActionMenu.tsx
@@ -69,6 +69,12 @@ interface ActionMenuItemProps {
   subtitle?: string;
   badge?: React.ReactNode;
   disabled?: boolean;
+  /** ARIA menu semantics for hosts that render a real `role="menu"` popover
+   *  (DecisionControl). Default undefined so existing consumers are unchanged. */
+  role?: 'menuitem';
+  /** Appended to the row's classes (e.g. a tone token). Default undefined so
+   *  existing consumers are byte-identical. */
+  className?: string;
 }
 
 export const ActionMenuItem: React.FC<ActionMenuItemProps> = ({
@@ -78,13 +84,16 @@ export const ActionMenuItem: React.FC<ActionMenuItemProps> = ({
   subtitle,
   badge,
   disabled = false,
+  role,
+  className,
 }) => (
   <button
     data-pn-touch-target
     type="button"
     onClick={onClick}
     disabled={disabled}
-    className="flex w-full items-center gap-2 px-3 py-2 text-left text-xs transition-colors hover:bg-muted disabled:cursor-not-allowed disabled:opacity-45 disabled:hover:bg-transparent"
+    role={role}
+    className={`flex w-full items-center gap-2 px-3 py-2 text-left text-xs transition-colors hover:bg-muted disabled:cursor-not-allowed disabled:opacity-45 disabled:hover:bg-transparent${className ? ` ${className}` : ''}`}
   >
     <span className="text-muted-foreground">{icon}</span>
     {subtitle ? (
diff --git a/packages/ui/components/DecisionControl.test.tsx b/packages/ui/components/DecisionControl.test.tsx
new file mode 100644
index 000000000..412190a9d
--- /dev/null
+++ b/packages/ui/components/DecisionControl.test.tsx
@@ -0,0 +1,293 @@
+import { afterEach, describe, expect, mock, test } from 'bun:test';
+import React, { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { DecisionControl, type DecisionHandler } from './DecisionControl';
+import { buildDecisionSpec, type DecisionActionId, type DecisionSpecInput } from '../utils/decisionSpec';
+
+const hasDom = typeof document !== 'undefined';
+
+let root: Root | null = null;
+let host: HTMLElement | null = null;
+
+const REVIEW_FEEDBACK: DecisionSpecInput = {
+  app: 'review', gate: true, count: 3, hasFeedback: true, approvalNotesSupported: true,
+};
+const ANNOTATE_EMPTY: DecisionSpecInput = {
+  app: 'annotate', gate: false, count: 0, hasFeedback: false, approvalNotesSupported: false,
+};
+
+function makeHandlers(): Record<DecisionActionId, ReturnType<typeof mock>> {
+  return {
+    'primary': mock((_note?: string) => undefined),
+    'note-with-approval': mock((_note?: string) => undefined),
+    'request-changes': mock((_note?: string) => undefined),
+    'note-with-feedback': mock((_note?: string) => undefined),
+    'approve-with-notes': mock((_note?: string) => undefined),
+    'discard-and-finish': mock((_note?: string) => undefined),
+  };
+}
+
+async function mountControl(
+  input: DecisionSpecInput,
+  handlers: Record<DecisionActionId, DecisionHandler>,
+  extraProps: Partial<React.ComponentProps<typeof DecisionControl>> = {},
+): Promise<void> {
+  host = document.createElement('div');
+  document.body.appendChild(host);
+  root = createRoot(host);
+  await act(async () => {
+    root!.render(
+      <DecisionControl
+        spec={buildDecisionSpec(input)}
+        handlers={handlers}
+        busy={false}
+        isLoading={false}
+        {...extraProps}
+      />,
+    );
+  });
+}
+
+function popover(): HTMLElement | null {
+  return document.querySelector<HTMLElement>('[data-decision-popover]');
+}
+
+async function openMenu(): Promise<void> {
+  const caret = document.querySelector<HTMLButtonElement>('[data-decision-caret]');
+  if (!caret) throw new Error('caret did not render');
+  await act(async () => caret.click());
+}
+
+function menuItems(): HTMLButtonElement[] {
+  return Array.from(document.querySelectorAll<HTMLButtonElement>('[role="menuitem"]'));
+}
+
+async function clickItem(labelPart: string): Promise<void> {
+  const item = menuItems().find((el) => el.textContent?.includes(labelPart));
+  if (!item) throw new Error(`menu item containing "${labelPart}" not found`);
+  await act(async () => item.click());
+}
+
+function noteInput(): HTMLTextAreaElement {
+  const el = document.querySelector<HTMLTextAreaElement>('[data-decision-note-input]');
+  if (!el) throw new Error('note field did not render');
+  return el;
+}
+
+async function typeNote(value: string): Promise<void> {
+  const el = noteInput();
+  const setter = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(el), 'value')?.set;
+  setter?.call(el, value);
+  await act(async () => {
+    el.dispatchEvent(new Event('input', { bubbles: true }));
+  });
+}
+
+async function pressKey(target: EventTarget, init: KeyboardEventInit): Promise<KeyboardEvent> {
+  const event = new KeyboardEvent('keydown', { bubbles: true, cancelable: true, ...init });
+  await act(async () => {
+    target.dispatchEvent(event);
+  });
+  return event;
+}
+
+afterEach(async () => {
+  if (root) await act(async () => root!.unmount());
+  root = null;
+  host?.remove();
+  host = null;
+  if (hasDom) document.body.replaceChildren();
+});
+
+describe('DecisionControl', () => {
+  // Guards the in-flight branches' zero-state flip coming back: the left
+  // segment fires the primary and NEVER opens the popover, in both states.
+  test.skipIf(!hasDom)('left segment calls handlers.primary and never opens the popover', async () => {
+    for (const input of [ANNOTATE_EMPTY, REVIEW_FEEDBACK]) {
+      const handlers = makeHandlers();
+      await mountControl(input, handlers);
+      const primary = document.querySelector<HTMLButtonElement>('[data-decision-primary]');
+      await act(async () => primary!.click());
+      expect(handlers.primary).toHaveBeenCalledTimes(1);
+      expect(popover()).toBeNull();
+      await act(async () => root!.unmount());
+      root = null;
+      host?.remove();
+      host = null;
+      document.body.replaceChildren();
+    }
+  });
+
+  // Guards a revert to a one-line field: Enter stays a newline, Mod+Enter
+  // (both modifier spellings) fires the composer action once, trimmed.
+  test.skipIf(!hasDom)('Mod+Enter submits the trimmed note; plain Enter does not submit', async () => {
+    for (const modifier of [{ metaKey: true }, { ctrlKey: true }]) {
+      const handlers = makeHandlers();
+      await mountControl(REVIEW_FEEDBACK, handlers);
+      await openMenu();
+      await clickItem('Send with a note…');
+      await typeNote('  ship it  ');
+
+      await pressKey(noteInput(), { key: 'Enter' });
+      expect(handlers['note-with-feedback']).not.toHaveBeenCalled();
+      expect(popover()?.dataset.decisionPopover).toBe('composer');
+
+      await pressKey(noteInput(), { key: 'Enter', ...modifier });
+      expect(handlers['note-with-feedback']).toHaveBeenCalledTimes(1);
+      expect(handlers['note-with-feedback']).toHaveBeenCalledWith('ship it');
+      expect(popover()).toBeNull();
+
+      await act(async () => root!.unmount());
+      root = null;
+      host?.remove();
+      host = null;
+      document.body.replaceChildren();
+    }
+  });
+
+  // Guards both throwing away a half-typed note and hijacking the host app's
+  // own Escape ladder.
+  test.skipIf(!hasDom)('Escape ladder: composer keeps the draft, menu consumes, closed propagates', async () => {
+    const handlers = makeHandlers();
+    await mountControl(REVIEW_FEEDBACK, handlers);
+
+    const documentEscapes: KeyboardEvent[] = [];
+    const spy = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') documentEscapes.push(event);
+    };
+    document.addEventListener('keydown', spy);
+    try {
+      // Rung 1: composer → menu, draft kept.
+      await openMenu();
+      await clickItem('Send with a note…');
+      await typeNote('half a thought');
+      await pressKey(noteInput(), { key: 'Escape' });
+      expect(popover()?.dataset.decisionPopover).toBe('menu');
+      expect(documentEscapes.length).toBe(0);
+      await clickItem('Send with a note…');
+      expect(noteInput().value).toBe('half a thought');
+      await pressKey(noteInput(), { key: 'Escape' });
+
+      // Rung 2: menu → closed, consumed, focus back on the caret.
+      const focused = document.activeElement as HTMLElement;
+      await pressKey(focused ?? popover()!, { key: 'Escape' });
+      expect(popover()).toBeNull();
+      expect(documentEscapes.length).toBe(0);
+      expect(document.activeElement).toBe(
+        document.querySelector('[data-decision-caret]'),
+      );
+
+      // Rung 3: nothing open → the event is NOT consumed by the control.
+      await pressKey(document.body, { key: 'Escape' });
+      expect(documentEscapes.length).toBe(1);
+    } finally {
+      document.removeEventListener('keydown', spy);
+    }
+  });
+
+  // The action stays visually enabled and an empty note refocuses the field —
+  // never a disabled-gray submit, never an empty submission.
+  test.skipIf(!hasDom)('empty note does not submit and refocuses the field', async () => {
+    const handlers = makeHandlers();
+    await mountControl(REVIEW_FEEDBACK, handlers);
+    await openMenu();
+    await clickItem('Send with a note…');
+    await typeNote('   ');
+
+    const send = document.querySelector<HTMLButtonElement>('[data-decision-composer-send]');
+    expect(send?.disabled).toBe(false);
+    await act(async () => send!.click());
+
+    expect(handlers['note-with-feedback']).not.toHaveBeenCalled();
+    expect(popover()?.dataset.decisionPopover).toBe('composer');
+    expect(document.activeElement).toBe(noteInput());
+  });
+
+  // Guards a refactor that fires the destructive discard without its one
+  // confirm, and the cancel path that must return to the open menu.
+  test.skipIf(!hasDom)('discard item raises the confirm; confirm fires, cancel returns to the menu', async () => {
+    const handlers = makeHandlers();
+    await mountControl(REVIEW_FEEDBACK, handlers);
+    await openMenu();
+    await clickItem('Approve, discard 3 annotations…');
+
+    const dialog = () =>
+      document.querySelector<HTMLElement>('[data-plannotator-confirm-dialog]');
+    expect(dialog()).not.toBeNull();
+    expect(handlers['discard-and-finish']).not.toHaveBeenCalled();
+
+    // Cancel: back to the open menu, one decision still one click away.
+    const cancel = Array.from(dialog()!.querySelectorAll('button')).find(
+      (el) => el.textContent === 'Cancel',
+    );
+    await act(async () => cancel!.click());
+    expect(dialog()).toBeNull();
+    expect(popover()?.dataset.decisionPopover).toBe('menu');
+    expect(handlers['discard-and-finish']).not.toHaveBeenCalled();
+
+    // Confirm: exactly one handler call, after confirmation only.
+    await clickItem('Approve, discard 3 annotations…');
+    const go = Array.from(dialog()!.querySelectorAll('button')).find(
+      // Frozen copy (maintainer-approved): 'Discard & approve'.
+      (el) => el.textContent === 'Discard & approve',
+    );
+    await act(async () => go!.click());
+    expect(handlers['discard-and-finish']).toHaveBeenCalledTimes(1);
+    expect(dialog()).toBeNull();
+  });
+
+  // Guards the HTML/live-app hang-over-the-page defect: iframe clicks never
+  // reach the parent document, so iframe focus must dismiss — but only when
+  // the host says the surface is framed.
+  test.skipIf(!hasDom)('blur to an iframe dismisses only with dismissOnIframeFocus', async () => {
+    for (const framed of [true, false]) {
+      const handlers = makeHandlers();
+      await mountControl(REVIEW_FEEDBACK, handlers, { dismissOnIframeFocus: framed });
+      await openMenu();
+      expect(popover()).not.toBeNull();
+
+      const iframe = document.createElement('iframe');
+      document.body.appendChild(iframe);
+      iframe.focus();
+      await act(async () => {
+        window.dispatchEvent(new Event('blur'));
+        await new Promise((resolve) => setTimeout(resolve, 0));
+      });
+
+      if (framed) expect(popover()).toBeNull();
+      else expect(popover()).not.toBeNull();
+
+      iframe.remove();
+      await act(async () => root!.unmount());
+      root = null;
+      host?.remove();
+      host = null;
+      document.body.replaceChildren();
+    }
+  });
+
+  // Guards the menu's keyboard contract: arrow keys rove between the
+  // role="menuitem" rows and wrap at both ends.
+  test.skipIf(!hasDom)('roving focus: Down/Up move between menu items and wrap', async () => {
+    const handlers = makeHandlers();
+    await mountControl(REVIEW_FEEDBACK, handlers);
+    await openMenu();
+
+    const items = menuItems();
+    expect(items.length).toBe(3);
+    expect(document.activeElement).toBe(items[0]);
+
+    await pressKey(popover()!, { key: 'ArrowDown' });
+    expect(document.activeElement).toBe(items[1]);
+    await pressKey(popover()!, { key: 'ArrowDown' });
+    expect(document.activeElement).toBe(items[2]);
+    await pressKey(popover()!, { key: 'ArrowDown' });
+    expect(document.activeElement).toBe(items[0]);
+    await pressKey(popover()!, { key: 'ArrowUp' });
+    expect(document.activeElement).toBe(items[2]);
+    await pressKey(popover()!, { key: 'End' });
+    expect(document.activeElement).toBe(items[2]);
+    await pressKey(popover()!, { key: 'Home' });
+    expect(document.activeElement).toBe(items[0]);
+  });
+});
diff --git a/packages/ui/components/DecisionControl.tsx b/packages/ui/components/DecisionControl.tsx
new file mode 100644
index 000000000..f855d900d
--- /dev/null
+++ b/packages/ui/components/DecisionControl.tsx
@@ -0,0 +1,542 @@
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+import { Check, ChevronDown, Loader2, Send } from 'lucide-react';
+import { Button } from './ui/button';
+import { Dialog, DialogContent, DialogDescription, DialogTitle } from './ui/dialog';
+import { ActionMenuDivider, ActionMenuItem } from './ActionMenu';
+import { ConfirmDialog, type ConfirmDialogProps } from './ConfirmDialog';
+import { useDismissablePopover } from '../hooks/useDismissablePopover';
+import { useCompactTouchLayout } from '../hooks/useIsMobile';
+import { submitHint } from '../utils/platform';
+import { cn } from '../lib/utils';
+import type {
+  DecisionActionId,
+  DecisionComposer,
+  DecisionMenuItem,
+  DecisionSpec,
+  DecisionTone,
+} from '../utils/decisionSpec';
+
+/**
+ * The unified header decision control: one joined split pill — the incumbent
+ * primary on the left, a caret on the right whose popover carries the
+ * alternate decisions and the in-place note composer. Rendered entirely from a
+ * `DecisionSpec` (see `utils/decisionSpec.ts`); the host owns the handlers.
+ *
+ * NOT host-supported surface (like ActionMenu/ConfirmDialog): session/transport
+ * chrome for Plannotator's own decision endpoints, deliberately absent from
+ * the README supported-import list.
+ *
+ * Interaction contract (the load-bearing rules):
+ * - The left segment never opens the popover and never changes meaning within
+ *   a state; the caret owns the popover.
+ * - Choosing a composer item MORPHS the same popover into the note composer —
+ *   same element, children swap, never a second popover.
+ * - Esc ladder: composer → back to the menu keeping the draft; menu → close,
+ *   focus returns to the caret. The event is consumed (stopPropagation) on
+ *   exactly those two rungs; with nothing open the host app's own Escape
+ *   ladder still runs.
+ * - Mod+Enter in the note field fires the composer's labelled action; plain
+ *   Enter is a newline, always.
+ * - An empty note never submits and never grays the action: the click
+ *   refocuses the field instead.
+ */
+export type DecisionHandler = (note?: string) => void;
+
+export interface DecisionControlProps {
+  spec: DecisionSpec;
+  handlers: Record<DecisionActionId, DecisionHandler>;
+  /** isSubmitting || isExiting || isApproving — disables both segments and
+   *  closes an open popover. */
+  busy: boolean;
+  /** Spinner on the primary only. */
+  isLoading: boolean;
+  labelBreakpoint?: 'md' | 'lg';
+  /** The host says the surface is framed (raw-HTML srcdoc / live-app proxy):
+   *  clicks inside the iframe never reach the parent document, so iframe
+   *  focus dismisses the popover instead. */
+  dismissOnIframeFocus?: boolean;
+  /** Confirm surface override; defaults to the ui ConfirmDialog. */
+  confirmDialog?: React.ComponentType<ConfirmDialogProps>;
+}
+
+const NOTE_MAX_HEIGHT_PX = 144;
+
+const ICONS: Record<'check' | 'send', React.ReactNode> = {
+  check: <Check className="size-3.5" />,
+  send: <Send className="size-3.5" />,
+};
+
+function toneButtonVariant(tone: Exclude<DecisionTone, 'destructive'>): 'success' | 'default' {
+  return tone === 'success' ? 'success' : 'default';
+}
+
+function itemToneClass(tone: DecisionTone): string | undefined {
+  if (tone === 'destructive') return 'text-destructive';
+  if (tone === 'success') return 'text-success';
+  return undefined;
+}
+
+function useAutoGrow(text: string) {
+  const ref = useRef<HTMLTextAreaElement>(null);
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    el.style.height = 'auto';
+    el.style.height = `${Math.min(el.scrollHeight, NOTE_MAX_HEIGHT_PX)}px`;
+  }, [text]);
+  return ref;
+}
+
+export interface DecisionNoteFieldProps {
+  text: string;
+  onTextChange: (value: string) => void;
+  /** Mod+Enter / the labelled action. The owner enforces the empty-note
+   *  no-op-and-refocus rule, so this fires for any text. */
+  onSubmit: () => void;
+  /** Escape. Consumes the event; the owner decides what "back" means. */
+  onCancel: () => void;
+  placeholder?: string;
+  disabled?: boolean;
+  autoFocus?: boolean;
+}
+
+/**
+ * The shared multi-line note field: two rows at rest, grows to 144px, then
+ * scrolls. Controlled — the owner keeps the text so stepping back does not
+ * discard a half-typed note. Exported separately because a third consumer
+ * (the review sidebar's "+ General comment") composes it outside the control.
+ */
+export const DecisionNoteField: React.FC<DecisionNoteFieldProps> = ({
+  text,
+  onTextChange,
+  onSubmit,
+  onCancel,
+  placeholder = 'Add a note...',
+  disabled = false,
+  autoFocus = true,
+}) => {
+  const ref = useAutoGrow(text);
+
+  useEffect(() => {
+    if (autoFocus) ref.current?.focus();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [autoFocus]);
+
+  const handleKeyDown = useCallback(
+    (event: React.KeyboardEvent<HTMLTextAreaElement>) => {
+      if (event.key === 'Escape') {
+        // A consuming rung of the Esc ladder: the host apps run their own
+        // Escape ladders and must not also see this event.
+        event.preventDefault();
+        event.stopPropagation();
+        onCancel();
+        return;
+      }
+      if (event.key === 'Enter' && (event.metaKey || event.ctrlKey)) {
+        event.preventDefault();
+        event.stopPropagation();
+        if (!disabled) onSubmit();
+      }
+      // Plain Enter falls through: the field is multi-line and Enter's job is
+      // a newline.
+    },
+    [disabled, onCancel, onSubmit],
+  );
+
+  return (
+    <textarea
+      ref={ref}
+      rows={2}
+      value={text}
+      onChange={(event) => onTextChange(event.target.value)}
+      onKeyDown={handleKeyDown}
+      placeholder={placeholder}
+      aria-label={placeholder}
+      data-decision-note-input="true"
+      data-pn-mobile-editable
+      disabled={disabled}
+      className="block w-full resize-none overflow-y-auto rounded-md border border-border bg-background px-2.5 py-1.5 text-sm leading-snug text-foreground outline-none placeholder:text-muted-foreground focus-visible:ring-1 focus-visible:ring-ring/40"
+      style={{ maxHeight: NOTE_MAX_HEIGHT_PX }}
+    />
+  );
+};
+
+/**
+ * The compact/touch note composer. The desktop composer morphs inside the
+ * caret popover, which is the wrong shape on touch (the header menu popup
+ * closes on outside pointerdown and its max-height fights the soft keyboard),
+ * so compact rows open this dialog instead.
+ */
+export const DecisionNoteDialog: React.FC<{
+  isOpen: boolean;
+  onClose: () => void;
+  composer: DecisionComposer;
+  onSubmit: (note: string) => void;
+  disabled?: boolean;
+  /** Free prose under the title, e.g. what the note rides along with. */
+  subtitle?: string;
+}> = ({ isOpen, onClose, composer, onSubmit, disabled = false, subtitle }) => {
+  const isCompactTouchLayout = useCompactTouchLayout();
+  const [text, setText] = useState('');
+  const contentRef = useRef<HTMLDivElement>(null);
+
+  // If the surface goes busy while the dialog is open, close it rather than
+  // leaving an editable field whose action can no longer do anything.
+  useEffect(() => {
+    if (disabled && isOpen) onClose();
+  }, [disabled, isOpen, onClose]);
+
+  const submit = useCallback(() => {
+    if (disabled) return;
+    const trimmed = text.trim();
+    if (trimmed.length === 0) {
+      // Same contract as the popover composer: the action stays full-strength
+      // and an empty-note tap refocuses the field — on touch this also raises
+      // the keyboard, which is what the tap was asking for.
+      contentRef.current
+        ?.querySelector<HTMLTextAreaElement>('[data-decision-note-input]')
+        ?.focus();
+      return;
+    }
+    onSubmit(trimmed);
+    setText('');
+    onClose();
+  }, [disabled, onClose, onSubmit, text]);
+
+  return (
+    <Dialog open={isOpen} onOpenChange={(open) => { if (!open) onClose(); }}>
+      <DialogContent
+        ref={contentRef}
+        data-decision-note-composer="dialog"
+        // Opening the sheet must not raise the touch keyboard on its own.
+        initialFocus={isCompactTouchLayout ? false : undefined}
+        className="max-w-md rounded-xl bg-card p-4 text-foreground"
+      >
+        <DialogTitle className="font-semibold mb-1">{composer.title}</DialogTitle>
+        {subtitle ? (
+          <DialogDescription className="text-sm text-muted-foreground mb-3">
+            {subtitle}
+          </DialogDescription>
+        ) : null}
+        <DecisionNoteField
+          text={text}
+          onTextChange={setText}
+          onSubmit={submit}
+          onCancel={onClose}
+          placeholder={composer.placeholder}
+          disabled={disabled}
+          autoFocus={!isCompactTouchLayout}
+        />
+        <div className="mt-3 flex items-center justify-between gap-2">
+          <span className="text-[11px] leading-snug text-muted-foreground">{submitHint}</span>
+          <Button
+            variant={toneButtonVariant(composer.tone)}
+            size="xs"
+            data-decision-composer-send="true"
+            onClick={submit}
+            disabled={disabled}
+            title={composer.actionLabel}
+            iconLeft={ICONS[composer.icon]}
+          >
+            {composer.actionLabel}
+          </Button>
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+};
+
+type PopoverState = null | 'menu' | 'composer';
+
+export const DecisionControl: React.FC<DecisionControlProps> = ({
+  spec,
+  handlers,
+  busy,
+  isLoading,
+  labelBreakpoint = 'md',
+  dismissOnIframeFocus = false,
+  confirmDialog,
+}) => {
+  const rootRef = useRef<HTMLDivElement>(null);
+  const popoverRef = useRef<HTMLDivElement>(null);
+  const caretRef = useRef<HTMLButtonElement>(null);
+  const [popover, setPopover] = useState<PopoverState>(null);
+  const [activeItemId, setActiveItemId] = useState<DecisionMenuItem['id'] | null>(null);
+  // Drafts are keyed per item so stepping back from a composer (Esc, back
+  // button, even closing the popover) keeps the half-typed note.
+  const [drafts, setDrafts] = useState<Record<string, string>>({});
+  const [confirmItem, setConfirmItem] = useState<DecisionMenuItem | null>(null);
+
+  const activeItem =
+    popover === 'composer' && activeItemId
+      ? spec.items.find((item) => item.id === activeItemId) ?? null
+      : null;
+
+  const closePopover = useCallback((options?: { focusCaret?: boolean }) => {
+    setPopover(null);
+    setActiveItemId(null);
+    if (options?.focusCaret) caretRef.current?.focus();
+  }, []);
+
+  const dismiss = useCallback(() => closePopover(), [closePopover]);
+
+  useDismissablePopover({
+    enabled: popover !== null,
+    ref: rootRef,
+    onDismiss: dismiss,
+    dismissOnIframeFocus,
+  });
+
+  // Busy = a decision is in flight: nothing in the popover can do anything
+  // anymore, so it must not hang over a disabled pill.
+  useEffect(() => {
+    if (busy) {
+      setPopover(null);
+      setActiveItemId(null);
+      setConfirmItem(null);
+    }
+  }, [busy]);
+
+  // Roving focus entry point: whenever the menu (re)appears — caret click,
+  // back from the composer, confirm cancel — focus its first row.
+  useEffect(() => {
+    if (popover !== 'menu') return;
+    popoverRef.current?.querySelector<HTMLButtonElement>('[role="menuitem"]')?.focus();
+  }, [popover]);
+
+  const selectItem = useCallback((item: DecisionMenuItem) => {
+    if (item.composer) {
+      setActiveItemId(item.id);
+      setPopover('composer');
+      return;
+    }
+    if (item.confirm) {
+      // The confirm replaces the popover; cancel reopens the menu so one
+      // decision stays one click away.
+      setConfirmItem(item);
+      setPopover(null);
+      return;
+    }
+    closePopover();
+    handlers[item.id]?.();
+  }, [closePopover, handlers]);
+
+  const submitComposer = useCallback(() => {
+    if (!activeItem) return;
+    const trimmed = (drafts[activeItem.id] ?? '').trim();
+    if (trimmed.length === 0) {
+      // Empty note: the action stays visually enabled and the click puts the
+      // cursor back in the field — never a disabled-gray submit.
+      popoverRef.current
+        ?.querySelector<HTMLTextAreaElement>('[data-decision-note-input]')
+        ?.focus();
+      return;
+    }
+    setDrafts((prev) => {
+      const next = { ...prev };
+      delete next[activeItem.id];
+      return next;
+    });
+    closePopover();
+    handlers[activeItem.id]?.(trimmed);
+  }, [activeItem, closePopover, drafts, handlers]);
+
+  const backToMenu = useCallback(() => {
+    setPopover('menu');
+    setActiveItemId(null);
+  }, []);
+
+  const handlePopoverKeyDown = useCallback(
+    (event: React.KeyboardEvent<HTMLDivElement>) => {
+      if (event.key === 'Escape') {
+        // The two consuming rungs of the Esc ladder. (The note field consumes
+        // its own Escape before it reaches here — same first rung.)
+        event.preventDefault();
+        event.stopPropagation();
+        if (popover === 'composer') backToMenu();
+        else closePopover({ focusCaret: true });
+        return;
+      }
+      if (popover !== 'menu') return;
+      const keys = ['ArrowDown', 'ArrowUp', 'Home', 'End'];
+      if (!keys.includes(event.key)) return;
+      const items = Array.from(
+        popoverRef.current?.querySelectorAll<HTMLButtonElement>('[role="menuitem"]') ?? [],
+      );
+      if (items.length === 0) return;
+      event.preventDefault();
+      event.stopPropagation();
+      const current = items.indexOf(document.activeElement as HTMLButtonElement);
+      let next = 0;
+      if (event.key === 'ArrowDown') next = current < 0 ? 0 : (current + 1) % items.length;
+      else if (event.key === 'ArrowUp') next = current <= 0 ? items.length - 1 : current - 1;
+      else if (event.key === 'Home') next = 0;
+      else next = items.length - 1;
+      items[next]?.focus();
+    },
+    [backToMenu, closePopover, popover],
+  );
+
+  const primaryVariant = toneButtonVariant(spec.primary.tone);
+  const Confirm = confirmDialog ?? ConfirmDialog;
+
+  return (
+    <div ref={rootRef} className="relative inline-flex">
+      {/* Left segment — the incumbent primary. It never opens the popover and,
+          deliberately, never fades or disables while the popover is open: the
+          popover holds only ALTERNATE decisions, so the primary keeps its
+          meaning and stays clickable (reverses the held branches' fade, which
+          existed because their panel duplicated the primary's own action). */}
+      <Button
+        variant={primaryVariant}
+        size="xs"
+        onClick={() => handlers.primary?.()}
+        disabled={busy}
+        title={spec.primary.title}
+        data-decision-primary="true"
+        iconLeft={
+          isLoading
+            ? <Loader2 className="size-3.5 animate-spin" />
+            : ICONS[spec.primary.icon]
+        }
+        className="rounded-r-none border-r-0"
+      >
+        {spec.primary.shortLabel ? (
+          <>
+            {/* Responsive spans copied from FeedbackButton so the toolbar
+                width below xl is unchanged in review. */}
+            <span className={labelBreakpoint === 'lg' ? 'hidden lg:inline xl:hidden' : 'hidden md:inline lg:hidden'}>
+              {spec.primary.shortLabel}
+            </span>
+            <span className={labelBreakpoint === 'lg' ? 'hidden xl:inline' : 'hidden lg:inline'}>
+              {spec.primary.label}
+            </span>
+          </>
+        ) : (
+          <span className={labelBreakpoint === 'lg' ? 'hidden lg:inline' : 'hidden md:inline'}>
+            {spec.primary.label}
+          </span>
+        )}
+        {typeof spec.primary.count === 'number' && (
+          // The count is the state indicator, not decoration: present at every
+          // breakpoint, unlike the labels.
+          <span
+            data-decision-count="true"
+            className="rounded-full bg-white/25 px-1.5 text-[10px] font-bold leading-4"
+          >
+            {spec.primary.count}
+          </span>
+        )}
+      </Button>
+
+      {/* Right segment — the caret. */}
+      <Button
+        ref={caretRef}
+        variant={primaryVariant}
+        size="xs"
+        onClick={() => {
+          if (popover) closePopover();
+          else setPopover('menu');
+        }}
+        disabled={busy}
+        aria-haspopup="menu"
+        aria-expanded={popover !== null}
+        aria-label="More decisions"
+        data-decision-caret="true"
+        className="rounded-l-none px-1.5"
+      >
+        <ChevronDown
+          className={cn('size-3.5 transition-transform duration-150', popover && 'rotate-180')}
+          aria-hidden="true"
+        />
+      </Button>
+
+      {popover !== null && (
+        // One popover element for both states: choosing a composer item swaps
+        // the children in place (morph), never mounts a second popover.
+        <div
+          ref={popoverRef}
+          role={popover === 'menu' ? 'menu' : undefined}
+          data-decision-popover={popover}
+          onKeyDown={handlePopoverKeyDown}
+          className="absolute right-0 top-full z-[70] mt-1.5 w-[22rem] max-w-[calc(100vw-2rem)] rounded-lg border border-border bg-popover shadow-xl"
+        >
+          {popover === 'menu' ? (
+            <div className="py-1">
+              {spec.items.map((item) => (
+                <React.Fragment key={item.id}>
+                  {item.dividerBefore ? <ActionMenuDivider /> : null}
+                  <ActionMenuItem
+                    role="menuitem"
+                    icon={ICONS[item.icon]}
+                    label={item.label}
+                    subtitle={item.subtitle}
+                    className={itemToneClass(item.tone)}
+                    onClick={() => selectItem(item)}
+                  />
+                </React.Fragment>
+              ))}
+            </div>
+          ) : activeItem?.composer ? (
+            <div className="p-2">
+              <button
+                type="button"
+                data-decision-composer-back="true"
+                onClick={backToMenu}
+                className="mb-1.5 flex items-center gap-1 rounded px-1.5 py-1 text-xs text-muted-foreground transition-colors hover:text-foreground"
+              >
+                <ChevronDown className="size-3 rotate-90" aria-hidden="true" />
+                {activeItem.composer.title}
+              </button>
+              <DecisionNoteField
+                text={drafts[activeItem.id] ?? ''}
+                onTextChange={(value) =>
+                  setDrafts((prev) => ({ ...prev, [activeItem.id]: value }))
+                }
+                onSubmit={submitComposer}
+                onCancel={backToMenu}
+                placeholder={activeItem.composer.placeholder}
+              />
+              <div className="mt-2 flex items-center justify-between gap-2 px-0.5">
+                <span className="text-[11px] leading-snug text-muted-foreground">
+                  {submitHint} send · Esc back, note kept
+                </span>
+                <Button
+                  variant={toneButtonVariant(activeItem.composer.tone)}
+                  size="xs"
+                  data-decision-composer-send="true"
+                  onClick={submitComposer}
+                  title={activeItem.composer.actionLabel}
+                  iconLeft={ICONS[activeItem.composer.icon]}
+                >
+                  {activeItem.composer.actionLabel}
+                </Button>
+              </div>
+            </div>
+          ) : null}
+        </div>
+      )}
+
+      {confirmItem?.confirm && (
+        <Confirm
+          isOpen
+          onClose={() => {
+            setConfirmItem(null);
+            setPopover('menu');
+          }}
+          onConfirm={() => {
+            const id = confirmItem.id;
+            setConfirmItem(null);
+            handlers[id]?.();
+          }}
+          title={confirmItem.confirm.title}
+          message={confirmItem.confirm.message}
+          confirmText={confirmItem.confirm.confirmText}
+          cancelText="Cancel"
+          variant="warning"
+          showCancel
+        />
+      )}
+    </div>
+  );
+};
diff --git a/packages/ui/components/ToolbarButtons.tsx b/packages/ui/components/ToolbarButtons.tsx
index e7f7e87e8..2b9cbaa33 100644
--- a/packages/ui/components/ToolbarButtons.tsx
+++ b/packages/ui/components/ToolbarButtons.tsx
@@ -111,6 +111,10 @@ interface ExitButtonProps {
   isLoading?: boolean;
   title?: string;
   labelBreakpoint?: ToolbarLabelBreakpoint;
+  /** `'ghost'` renders the icon-only ghost-X form that sits beside the
+   *  decision control. Default `'pill'` keeps every existing caller
+   *  byte-identical. */
+  appearance?: 'pill' | 'ghost';
 }
 
 export const ExitButton: React.FC<ExitButtonProps> = ({
@@ -119,7 +123,21 @@ export const ExitButton: React.FC<ExitButtonProps> = ({
   isLoading = false,
   title = 'Close session without sending feedback',
   labelBreakpoint = 'md',
-}) => (
+  appearance = 'pill',
+}) => appearance === 'ghost' ? (
+  <Button
+    variant="ghost"
+    size="xs"
+    onClick={onClick}
+    disabled={disabled || isLoading}
+    title={title}
+    // Icon-only at every breakpoint, so the accessible name must live here.
+    aria-label={title}
+    className="px-2 text-muted-foreground"
+  >
+    {isLoading ? '…' : <X className="size-3.5" aria-hidden="true" />}
+  </Button>
+) : (
   <Button
     variant="secondary"
     size="xs"
diff --git a/packages/ui/hooks/useDismissablePopover.ts b/packages/ui/hooks/useDismissablePopover.ts
new file mode 100644
index 000000000..11fbd2663
--- /dev/null
+++ b/packages/ui/hooks/useDismissablePopover.ts
@@ -0,0 +1,57 @@
+import { useEffect } from 'react';
+
+/**
+ * Outside-`pointerdown` + Escape dismissal for anchored popovers — the effect
+ * ActionMenu and ApproveDropdown each hand-roll today (converting them onto
+ * this hook is a separate cleanup, so their behavior does not change here).
+ *
+ * `dismissOnIframeFocus` is the explicit strategy for framed surfaces
+ * (raw-HTML srcdoc, live-app proxy): a click inside the iframe never produces
+ * a `pointerdown` in the parent document, but it does move focus into the
+ * frame, which fires `blur` on the parent window. The check runs on the next
+ * task because `document.activeElement` is not yet updated inside the blur
+ * handler.
+ */
+export function useDismissablePopover({
+  enabled,
+  ref,
+  onDismiss,
+  dismissOnIframeFocus,
+}: {
+  enabled: boolean;
+  ref: React.RefObject<HTMLElement | null>;
+  onDismiss: () => void;
+  dismissOnIframeFocus?: boolean;
+}) {
+  useEffect(() => {
+    if (!enabled) return;
+
+    const handlePointerDown = (event: PointerEvent) => {
+      const target = event.target as Node | null;
+      if (target && ref.current && ref.current.contains(target)) return;
+      onDismiss();
+    };
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') onDismiss();
+    };
+
+    let blurTimer: ReturnType<typeof setTimeout> | undefined;
+    const handleWindowBlur = () => {
+      blurTimer = setTimeout(() => {
+        if (document.activeElement?.tagName === 'IFRAME') onDismiss();
+      }, 0);
+    };
+
+    document.addEventListener('pointerdown', handlePointerDown);
+    document.addEventListener('keydown', handleKeyDown);
+    if (dismissOnIframeFocus) window.addEventListener('blur', handleWindowBlur);
+
+    return () => {
+      document.removeEventListener('pointerdown', handlePointerDown);
+      document.removeEventListener('keydown', handleKeyDown);
+      if (dismissOnIframeFocus) window.removeEventListener('blur', handleWindowBlur);
+      if (blurTimer !== undefined) clearTimeout(blurTimer);
+    };
+  }, [enabled, ref, onDismiss, dismissOnIframeFocus]);
+}

From 8f00018451ee036ae2a611594cfcb400c0c9780c Mon Sep 17 00:00:00 2001
From: Michael Ramos <mdramos8@gmail.com>
Date: Tue, 1 Sep 2026 23:21:10 -0700
Subject: [PATCH 3/6] feat(ui): shared decision-control shortcut scope
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

One scope at the shortcuts root (both apps mount the identical control)
documenting only the two chords the control implements: Mod+Enter
submits the note, Escape steps back keeping it. Enter is deliberately
not documented as submit — it is a newline. Registry test guards that
the scope composes into both adopting settings registries without id
or token collisions ahead of the PR2/PR3 registration.
---
 packages/ui/shortcuts.test.ts                 | 12 +++++++
 .../ui/shortcuts/decisionControl.shortcuts.ts | 31 +++++++++++++++++++
 packages/ui/shortcuts/index.ts                |  1 +
 3 files changed, 44 insertions(+)
 create mode 100644 packages/ui/shortcuts/decisionControl.shortcuts.ts

diff --git a/packages/ui/shortcuts.test.ts b/packages/ui/shortcuts.test.ts
index 3d9a4495a..6d00fa14c 100644
--- a/packages/ui/shortcuts.test.ts
+++ b/packages/ui/shortcuts.test.ts
@@ -4,6 +4,7 @@ import { reviewSettingsShortcutRegistry } from '../review-editor/shortcuts';
 import {
   annotationModeShortcuts,
   createShortcutRegistry,
+  decisionControlShortcuts,
   defineShortcutScope,
   dispatchShortcutEvent,
   formatShortcutBindingText,
@@ -392,6 +393,17 @@ describe('shortcuts', () => {
     expect(preventDefaultCalls).toBe(2);
   });
 
+  // The decision-control scope ships in PR1 unmounted; PR2/PR3 add it to the
+  // annotate and review settings registries. This guards that registration in
+  // advance: a duplicate scope id or non-normalized binding token would only
+  // surface as a throw at app startup otherwise.
+  it('decision-control scope composes cleanly into both adopting registries', () => {
+    expect(decisionControlShortcuts.id).toBe('decision-control');
+    for (const registry of [annotateSettingsShortcutRegistry, reviewSettingsShortcutRegistry]) {
+      expect(validateShortcutRegistry([...registry, decisionControlShortcuts])).toEqual([]);
+    }
+  });
+
   it('leaves annotation mode alone when Alt is held', () => {
     // AltGr sends Ctrl+Alt; the binding declares no Alt, so it must not fire.
     const altGrEvent = {
diff --git a/packages/ui/shortcuts/decisionControl.shortcuts.ts b/packages/ui/shortcuts/decisionControl.shortcuts.ts
new file mode 100644
index 000000000..74f09b5cd
--- /dev/null
+++ b/packages/ui/shortcuts/decisionControl.shortcuts.ts
@@ -0,0 +1,31 @@
+import { defineShortcutScope } from './core';
+
+/**
+ * The header decision control's note composer (shortcuts root, not
+ * plan-review/ or code-review/: both apps mount the identical control with
+ * identical semantics).
+ *
+ * Documents ONLY the chords the control actually implements — bindings must
+ * match shipped behavior (`DecisionControl.tsx`). Enter is a newline in the
+ * note field and must never be documented as submit.
+ */
+export const decisionControlShortcuts = defineShortcutScope({
+  id: 'decision-control',
+  title: 'Decision control',
+  shortcuts: {
+    submitNote: {
+      description: 'Send the note with the decision you picked',
+      bindings: ['Mod+Enter'],
+      section: 'Actions',
+      hint: "Available while the decision control's note field is open. Enter inserts a newline.",
+      displayOrder: 12,
+    },
+    closeNote: {
+      description: 'Step back to the decision menu, keeping the note',
+      bindings: ['Escape'],
+      section: 'Actions',
+      hint: "Available while the decision control's note field is open.",
+      displayOrder: 14,
+    },
+  },
+});
diff --git a/packages/ui/shortcuts/index.ts b/packages/ui/shortcuts/index.ts
index 7c82d6c6b..4d8bdb887 100644
--- a/packages/ui/shortcuts/index.ts
+++ b/packages/ui/shortcuts/index.ts
@@ -1,6 +1,7 @@
 export * from './core';
 export * from './runtime';
 export { historyShortcuts, useHistoryShortcuts } from './history.shortcuts';
+export { decisionControlShortcuts } from './decisionControl.shortcuts';
 
 // plan-review scopes
 export { annotationModeShortcuts, useAnnotationModeShortcuts } from './plan-review/annotationMode.shortcuts';

From 88c73d9a2e2d9ae03d1acc9019deae646f4397c0 Mon Sep 17 00:00:00 2001
From: Michael Ramos <mdramos8@gmail.com>
Date: Tue, 1 Sep 2026 23:21:10 -0700
Subject: [PATCH 4/6] chore(ui): bump @plannotator/ui to 0.38.0
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Internal (non-host-surface) decision-control primitives only:
DecisionControl, decisionSpec, useDismissablePopover join the
unsupported list — no supported import is added. Core pin stays exact
at 0.25.1; smoke:package verified the 0.38.0 tarball.
---
 packages/ui/HANDOFF.md   | 5 +++--
 packages/ui/README.md    | 2 +-
 packages/ui/package.json | 2 +-
 3 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/packages/ui/HANDOFF.md b/packages/ui/HANDOFF.md
index 6e996d216..20ce9f5b5 100644
--- a/packages/ui/HANDOFF.md
+++ b/packages/ui/HANDOFF.md
@@ -237,6 +237,7 @@ Don't import these in a host. Each hits hardcoded Plannotator endpoints:
 - `utils/sharing` — Plannotator's public paste service (share-URL feature).
 - `hooks/useUpdateCheck`, `components/MenuVersionSection`, `components/PlanHeaderMenu` — Plannotator release checks.
 - `utils/planAgentInstructions`, `utils/reviewAgentInstructions` — generate agent instructions that curl Plannotator's local API.
+- `components/DecisionControl`, `utils/decisionSpec`, `hooks/useDismissablePopover` — session decision chrome for Plannotator's own approve/deny/exit endpoints (a host's session decisions are its own outcomes against its own backend).
 
 If Workspaces ever wants one of these surfaces, the path is the same as everything else: add a seam to the module in a Plannotator PR, don't fork the component.
 
@@ -676,8 +677,8 @@ Additive only, but required: `@plannotator/ui` 0.32.0 imports the new `@plannota
 
 ## Publishing & versioning
 
-- The current pair is `@plannotator/ui` `0.37.0` on `@plannotator/core` `0.25.1`. Core 0.25.1 publishes the `annotation-threads` subpath already used by `AnnotationPanel` and `utils/parser`; UI pins that corrected core exactly. UI 0.37.0 adds the Viewer-owned document-header seam (a new public API, hence the minor bump; 0.36.1 was reserved for it but never published) while retaining the `hideQuickLabel` and `StickyHeaderLane` seams from the 0.35.x and 0.36.0 releases.
-- Recent pairs, for the consumer's install matrix: ui 0.32.0 on core 0.25.0 (lockstep, `html-anchor`), ui 0.33.0 and ui 0.34.0 on core 0.25.0 (ui only), and ui 0.35.2, ui 0.36.0, and ui 0.37.0 on core 0.25.1 (0.36.1 was never published). Do not consume ui 0.35.0 externally because its published manifest contains `workspace:*`; do not consume ui 0.35.1 because its exact core 0.25.0 dependency lacks the `annotation-threads` export.
+- The current pair is `@plannotator/ui` `0.38.0` on `@plannotator/core` `0.25.1`. UI 0.38.0 adds only internal decision-control primitives (`DecisionControl`, `decisionSpec`, `useDismissablePopover` — not host-supported surface, see the unsupported list). UI 0.37.0 added the Viewer-owned document-header seam (a new public API, hence the minor bump; 0.36.1 was reserved for it but never published) while retaining the `hideQuickLabel` and `StickyHeaderLane` seams from the 0.35.x and 0.36.0 releases; core 0.25.1 publishes the `annotation-threads` subpath already used by `AnnotationPanel` and `utils/parser`, and UI pins that corrected core exactly.
+- Recent pairs, for the consumer's install matrix: ui 0.32.0 on core 0.25.0 (lockstep, `html-anchor`), ui 0.33.0 and ui 0.34.0 on core 0.25.0 (ui only), and ui 0.35.2, ui 0.36.0, ui 0.37.0, and ui 0.38.0 on core 0.25.1 (0.36.1 was never published). Do not consume ui 0.35.0 externally because its published manifest contains `workspace:*`; do not consume ui 0.35.1 because its exact core 0.25.0 dependency lacks the `annotation-threads` export.
 - When both packages change, **publish `core` first**: ui 0.32.0 imports the `@plannotator/core/html-anchor` subpath, which no earlier published core (0.24.0 and before) has, just as ui 0.29.0 needed core 0.23.0 for `@plannotator/core/annotatable`. Bump core, update UI's exact core dependency to the same new version, and run `bun install` so `bun.lock` records the new workspace versions before packing either package.
 - The HTML annotation seams also changed the guides.show viewer **stylesheet** (five utility rules from `HtmlSurfaceControls`; the viewer JS is unchanged), so `packages/core/guide-viewer-manifest.ts` now pins a CSS hash that exists on guides.show only after the deploy workflow has published this build's `/v1/` assets. A guide exported from this build before that deploy would pin a stylesheet the host does not serve yet: **deploy guides.show before any release that ships this manifest.**
 - UI declares the already published core version exactly in its source manifest. Do not replace it with `workspace:*`: direct publication can preserve that protocol and make the package impossible to install outside this repository. Bun links the local core workspace whenever its version matches the exact dependency. Before publishing, run `bun run --cwd packages/ui smoke:package`; it checks the source and packed manifests, required tarball subpaths, local Bun linking, and a real pnpm install in an external temporary consumer. When both packages change, publish **`core` first, then `ui`**.
diff --git a/packages/ui/README.md b/packages/ui/README.md
index 76555bd60..06e943865 100644
--- a/packages/ui/README.md
+++ b/packages/ui/README.md
@@ -250,7 +250,7 @@ npm install @plannotator/ui @plannotator/core
 - `@plannotator/core` — pure utils + types, zero deps, browser-safe (CI enforces no `node:` imports). Published.
 - `@plannotator/ui` — React components/hooks + theme + `configure()`. Depends on an exact published `@plannotator/core` version. Published.
 - `@plannotator/shared`, `@plannotator/ai` — stay private to the monorepo; `shared` re-exports `core`'s modules via shims so Plannotator's internals are untouched.
-- Currently `@plannotator/ui` 0.37.0 depends exactly on `@plannotator/core` 0.25.1. `core` is bumped only when something under `packages/core` changes, so `ui` can advance alone. Keep the published core version exact in `packages/ui/package.json`; do not use a `workspace:` protocol there, because a directly published manifest must remain installable outside this monorepo. Bun still links the matching local workspace during development. When both packages change, publish `core` first, then build and publish the UI tarball. See HANDOFF.md "Publishing & versioning" for the verification command.
+- Currently `@plannotator/ui` 0.38.0 depends exactly on `@plannotator/core` 0.25.1. `core` is bumped only when something under `packages/core` changes, so `ui` can advance alone. Keep the published core version exact in `packages/ui/package.json`; do not use a `workspace:` protocol there, because a directly published manifest must remain installable outside this monorepo. Bun still links the matching local workspace during development. When both packages change, publish `core` first, then build and publish the UI tarball. See HANDOFF.md "Publishing & versioning" for the verification command.
 
 ## The one rule
 
diff --git a/packages/ui/package.json b/packages/ui/package.json
index b62fcfd05..f89333d1e 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@plannotator/ui",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "type": "module",
   "exports": {
     "./components/*": "./components/*.tsx",

From 5b2325033845145434d62f16b07b6394e1d356b7 Mon Sep 17 00:00:00 2001
From: Michael Ramos <mdramos8@gmail.com>
Date: Tue, 1 Sep 2026 23:37:08 -0700
Subject: [PATCH 5/6] fix(ui): consume the popover-dismissing Escape;
 frozen-copy test hygiene
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review F1: the hook's document-level Escape dismissed the popover but let
the event travel on to the apps' window-level Escape ladders — from PR2
one Esc would both close the menu AND drop an HTML-annotate surface to
Interact. The hook now skips defaultPrevented events and, when it acts,
calls preventDefault + stopPropagation (document bubbles before window).
An outside-focus Escape while the composer is open closes the whole
popover — an outside-dismissal gesture like an outside click; the draft
is kept — commented at the dismiss call site. New DOM test pins all
three: open+outside-focus consumes, composer case closes-all keeping the
draft, closed control consumes nothing (verified failing without the
hook fix).

Review F3: pin the frozen 'Request changes…' label (it is in the spec's
frozen set but was never asserted) and downgrade the unfrozen sentence
pins (composer action labels, approve-note labels, discard sentences) to
data assertions — flow verb, live count, singular form, composer
distinctness — per the Testing Rules.
---
 .../ui/components/DecisionControl.test.tsx    | 48 +++++++++++++++++++
 packages/ui/components/DecisionControl.tsx    |  6 +++
 packages/ui/hooks/useDismissablePopover.ts    |  8 +++-
 packages/ui/utils/decisionSpec.test.ts        | 27 +++++++----
 4 files changed, 80 insertions(+), 9 deletions(-)

diff --git a/packages/ui/components/DecisionControl.test.tsx b/packages/ui/components/DecisionControl.test.tsx
index 412190a9d..b58318f64 100644
--- a/packages/ui/components/DecisionControl.test.tsx
+++ b/packages/ui/components/DecisionControl.test.tsx
@@ -236,6 +236,54 @@ describe('DecisionControl', () => {
     expect(dialog()).toBeNull();
   });
 
+  // Guards the Escape leak: when focus has dropped OUTSIDE the popover (Tab
+  // past the last item, click on popover padding), the document-level Escape
+  // must dismiss AND consume — the host apps' window-level Escape ladders
+  // must never also act on the same keypress. A closed control must not
+  // consume anything.
+  test.skipIf(!hasDom)('outside-focus Escape dismisses fail-closed; closed control does not consume', async () => {
+    const handlers = makeHandlers();
+    await mountControl(REVIEW_FEEDBACK, handlers);
+
+    const windowEscapes: KeyboardEvent[] = [];
+    const windowSpy = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') windowEscapes.push(event);
+    };
+    window.addEventListener('keydown', windowSpy);
+    try {
+      // Menu open, focus outside: Escape closes and never reaches window.
+      await openMenu();
+      (document.activeElement as HTMLElement | null)?.blur?.();
+      const consumed = await pressKey(document.body, { key: 'Escape' });
+      expect(popover()).toBeNull();
+      expect(consumed.defaultPrevented).toBe(true);
+      expect(windowEscapes.length).toBe(0);
+
+      // Composer open, focus outside: consume-and-close-ALL (an outside
+      // Escape is an outside-dismissal gesture, like an outside click) — and
+      // the draft survives the full close.
+      await openMenu();
+      await clickItem('Send with a note…');
+      await typeNote('kept across dismissal');
+      (document.activeElement as HTMLElement | null)?.blur?.();
+      await pressKey(document.body, { key: 'Escape' });
+      expect(popover()).toBeNull();
+      expect(windowEscapes.length).toBe(0);
+      await openMenu();
+      await clickItem('Send with a note…');
+      expect(noteInput().value).toBe('kept across dismissal');
+      await pressKey(noteInput(), { key: 'Escape' }); // back to menu
+      await pressKey(document.activeElement!, { key: 'Escape' }); // close
+
+      // Closed: the control holds no listener, the ladder gets the event.
+      const passedThrough = await pressKey(document.body, { key: 'Escape' });
+      expect(passedThrough.defaultPrevented).toBe(false);
+      expect(windowEscapes.length).toBe(1);
+    } finally {
+      window.removeEventListener('keydown', windowSpy);
+    }
+  });
+
   // Guards the HTML/live-app hang-over-the-page defect: iframe clicks never
   // reach the parent document, so iframe focus must dismiss — but only when
   // the host says the surface is framed.
diff --git a/packages/ui/components/DecisionControl.tsx b/packages/ui/components/DecisionControl.tsx
index f855d900d..347e5599b 100644
--- a/packages/ui/components/DecisionControl.tsx
+++ b/packages/ui/components/DecisionControl.tsx
@@ -278,6 +278,12 @@ export const DecisionControl: React.FC<DecisionControlProps> = ({
     if (options?.focusCaret) caretRef.current?.focus();
   }, []);
 
+  // Outside-dismissal (outside pointerdown, iframe focus, or an Escape whose
+  // focus has already left the control) closes the WHOLE popover, composer
+  // included: the user's attention has left the control, so restoring the
+  // intermediate menu rung would fight where they are — and the draft is kept
+  // in `drafts` either way. The three-rung Esc ladder applies only while
+  // focus is inside the popover (handlePopoverKeyDown / the note field).
   const dismiss = useCallback(() => closePopover(), [closePopover]);
 
   useDismissablePopover({
diff --git a/packages/ui/hooks/useDismissablePopover.ts b/packages/ui/hooks/useDismissablePopover.ts
index 11fbd2663..6d5cdef4a 100644
--- a/packages/ui/hooks/useDismissablePopover.ts
+++ b/packages/ui/hooks/useDismissablePopover.ts
@@ -33,7 +33,13 @@ export function useDismissablePopover({
     };
 
     const handleKeyDown = (event: KeyboardEvent) => {
-      if (event.key === 'Escape') onDismiss();
+      if (event.key !== 'Escape' || event.defaultPrevented) return;
+      // Fail closed: an Escape that dismisses the popover is consumed here
+      // (document bubbles before window), so the host apps' window-level
+      // Escape ladders never also act on it — one Escape, one rung.
+      event.preventDefault();
+      event.stopPropagation();
+      onDismiss();
     };
 
     let blurTimer: ReturnType<typeof setTimeout> | undefined;
diff --git a/packages/ui/utils/decisionSpec.test.ts b/packages/ui/utils/decisionSpec.test.ts
index 7ae058fca..193603a25 100644
--- a/packages/ui/utils/decisionSpec.test.ts
+++ b/packages/ui/utils/decisionSpec.test.ts
@@ -32,10 +32,15 @@ describe('buildDecisionSpec state matrix', () => {
     expect(spec.primary.tone).toBe('success');
     expect(spec.primary.icon).toBe('check');
     expect(itemIds(spec)).toEqual(['note-with-approval', 'request-changes']);
-    // "Done with a note…" posts /api/feedback — never capability-gated.
-    expect(spec.items[0].composer?.actionLabel).toBe('Done — send note');
+    // Frozen copy (maintainer-approved): 'Request changes…'.
+    expect(spec.items[1].label).toBe('Request changes…');
+    // "Done with a note…" posts /api/feedback — never capability-gated. The
+    // two composers must stay DISTINCT actions (positive finish vs change
+    // request) — the labels themselves are free prose.
+    expect(spec.items[0].composer?.tone).toBe('success');
     expect(spec.items[1].dividerBefore).toBe(true);
-    expect(spec.items[1].composer?.actionLabel).toBe('Send as feedback');
+    expect(spec.items[1].composer?.tone).toBe('primary');
+    expect(spec.items[0].composer?.actionLabel).not.toBe(spec.items[1].composer?.actionLabel);
   });
 
   it('annotate, no feedback, gate → Approve; approve-note item only with the capability', () => {
@@ -45,7 +50,9 @@ describe('buildDecisionSpec state matrix', () => {
     expect(withCap.primary.label).toBe('Approve'); // frozen copy, maintainer-approved
     expect(withCap.primary.tone).toBe('success');
     expect(itemIds(withCap)).toEqual(['note-with-approval', 'request-changes']);
-    expect(withCap.items[0].label).toBe('Approve with a note…');
+    // Free prose except the verb: the gate's positive-note item must speak of
+    // approving, not finishing.
+    expect(withCap.items[0].label).toContain('Approve');
 
     const withoutCap = buildDecisionSpec({
       app: 'annotate', gate: true, count: 0, hasFeedback: false, approvalNotesSupported: false,
@@ -63,7 +70,9 @@ describe('buildDecisionSpec state matrix', () => {
     expect(nonGate.primary.icon).toBe('send');
     // No gate ⇒ no approve channel ⇒ no Approve-with-notes, capability or not.
     expect(itemIds(nonGate)).toEqual(['note-with-feedback', 'discard-and-finish']);
-    expect(nonGate.items[1].label).toBe('Done, discard 3 annotations…');
+    // Label is free prose; the data is the flow verb and the live count.
+    expect(nonGate.items[1].label).toContain('Done,');
+    expect(nonGate.items[1].label).toContain('3');
     expect(nonGate.items[1].confirm?.confirmText).toBe('Discard & finish'); // frozen copy
 
     const gate = buildDecisionSpec({
@@ -71,7 +80,8 @@ describe('buildDecisionSpec state matrix', () => {
     });
     expect(itemIds(gate)).toEqual(['note-with-feedback', 'approve-with-notes', 'discard-and-finish']);
     expect(gate.items[1].label).toBe('Approve with notes'); // frozen copy, maintainer-approved
-    expect(gate.items[2].label).toBe('Approve, discard 3 annotations…');
+    expect(gate.items[2].label).toContain('Approve,');
+    expect(gate.items[2].label).toContain('3');
     expect(gate.items[2].confirm?.confirmText).toBe('Discard & approve'); // frozen copy
 
     const gateNoCap = buildDecisionSpec({
@@ -91,7 +101,7 @@ describe('buildDecisionSpec state matrix', () => {
       app: 'review', gate: true, count: 0, hasFeedback: false, approvalNotesSupported: true,
     });
     expect(itemIds(phase2)).toEqual(['note-with-approval', 'request-changes']);
-    expect(phase2.items[0].label).toBe('Approve with a note…');
+    expect(phase2.items[0].label).toContain('Approve');
   });
 
   it('review, feedback (n) → Send Feedback + note/(approve-with-notes)/discard', () => {
@@ -174,7 +184,8 @@ describe('buildDecisionSpec invariants', () => {
       app: 'annotate', gate: false, count: 1, hasFeedback: true, approvalNotesSupported: false,
     });
     const discardOne = one.items.find((item) => item.id === 'discard-and-finish')!;
-    expect(discardOne.label).toBe('Done, discard 1 annotation…');
+    // The singular form is the data here, not the sentence around it.
+    expect(discardOne.label).toContain('1 annotation…');
   });
 
   // Every composer item must actually be a composer and every plain item must

From dfdb2332a0e4df9cfaf542cea60510ee30e65cee Mon Sep 17 00:00:00 2001
From: Michael Ramos <mdramos8@gmail.com>
Date: Tue, 1 Sep 2026 23:48:00 -0700
Subject: [PATCH 6/6] chore(guides): refresh viewer manifest for the shortcuts
 barrel change

---
 packages/core/guide-viewer-manifest.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/core/guide-viewer-manifest.ts b/packages/core/guide-viewer-manifest.ts
index a1e483867..05fbbad36 100644
--- a/packages/core/guide-viewer-manifest.ts
+++ b/packages/core/guide-viewer-manifest.ts
@@ -6,9 +6,9 @@ import type { GuideViewerAssets } from "./guide-format";
 
 export const GUIDE_VIEWER_MANIFEST: Omit<GuideViewerAssets, "baseUrl"> = {
   js: "viewer.AnU5z-dd.js",
-  css: "viewer.BWA5Rzwo.css",
+  css: "viewer.D7WwEXBg.css",
   jsIntegrity: "sha384-iOm8MrJ1lGtn93UvbQr02EvCOHwQqXcDd84+5pUwfCSoYy146a+tLaemgZjNql8c",
-  cssIntegrity: "sha384-Q9u2GcsAQO3r93fnqIo1YUOHl11vUm908qK7wPn0jiJd3rVoJZH/HqL4KPzwGWk0",
+  cssIntegrity: "sha384-9mL9Mhu3b+Tc4SXsoajp8zIRnjx6hy8eDVIPufiPADXCThZ0Dw45jSRUSCQUEGQv",
   langs: {
     "astro": "chunks/astro.BykyiR6i.js",
     "c": "chunks/c.BIGW1oBm.js",