@moldable-ai/ui 0.2.21 → 0.2.24

package/dist/lib/native-hardware/notifications.js

@@ -1,4 +1,4 @@
-import { callNativeHardwareBridge, } from './bridge';
+import { callNativeHardwareBridge, } from './bridge.js';
 export const NATIVE_NOTIFICATION_REQUEST_TYPE = 'moldable:native-notifications';
 export const NATIVE_NOTIFICATION_RESULT_TYPE = 'moldable:native-notifications-result';
 export const NATIVE_NOTIFICATION_MAX_TITLE_LENGTH = 256;

package/dist/lib/native-hardware/power-session.d.ts

@@ -1,5 +1,5 @@
-import { type NativeHardwareBridgeOptions } from './bridge';
-import type { NativeHardwareRequestEnvelope, NativeHardwareResultEnvelope } from './types';
+import { type NativeHardwareBridgeOptions } from './bridge.js';
+import type { NativeHardwareRequestEnvelope, NativeHardwareResultEnvelope } from './types.js';
 export declare const NATIVE_POWER_SESSION_REQUEST_TYPE: "moldable:native-power-session";
 export declare const NATIVE_POWER_SESSION_RESULT_TYPE: "moldable:native-power-session-result";
 export declare const NATIVE_POWER_SESSION_EVENT_TYPE: "moldable:native-power-session-event";

package/dist/lib/native-hardware/power-session.js

@@ -1,4 +1,4 @@
-import { NativeHardwareBridgeError, callNativeHardwareBridge, resolveNativeHardwareParentOrigin, } from './bridge';
+import { NativeHardwareBridgeError, callNativeHardwareBridge, resolveNativeHardwareParentOrigin, } from './bridge.js';
 export const NATIVE_POWER_SESSION_REQUEST_TYPE = 'moldable:native-power-session';
 export const NATIVE_POWER_SESSION_RESULT_TYPE = 'moldable:native-power-session-result';
 export const NATIVE_POWER_SESSION_EVENT_TYPE = 'moldable:native-power-session-event';

package/dist/lib/native-hardware/secure-storage.d.ts

@@ -1,4 +1,4 @@
-import { type NativeHardwareBridgeOptions } from './bridge';
+import { type NativeHardwareBridgeOptions } from './bridge.js';
 export declare const NATIVE_SECURE_STORAGE_REQUEST_TYPE: "moldable:native-secure-storage";
 export declare const NATIVE_SECURE_STORAGE_RESULT_TYPE: "moldable:native-secure-storage-result";
 export declare const SECURE_STORAGE_MAX_KEY_LENGTH = 128;

package/dist/lib/native-hardware/secure-storage.js

@@ -1,4 +1,4 @@
-import { callNativeHardwareBridge, } from './bridge';
+import { callNativeHardwareBridge, } from './bridge.js';
 export const NATIVE_SECURE_STORAGE_REQUEST_TYPE = 'moldable:native-secure-storage';
 export const NATIVE_SECURE_STORAGE_RESULT_TYPE = 'moldable:native-secure-storage-result';
 export const SECURE_STORAGE_MAX_KEY_LENGTH = 128;

package/dist/lib/native-hardware/serial-native.d.ts

@@ -1,5 +1,5 @@
-import { type MoldableNativeDeviceDescriptor } from './native-device-io';
-import type { MoldableSerialInputSignals, MoldableSerialOpenOptions, MoldableSerialOutputSignals, MoldableSerialPort, MoldableSerialPortInfo } from './serial';
+import { type MoldableNativeDeviceDescriptor } from './native-device-io.js';
+import type { MoldableSerialInputSignals, MoldableSerialOpenOptions, MoldableSerialOutputSignals, MoldableSerialPort, MoldableSerialPortInfo } from './serial.js';
 export declare class NativeMoldableSerialPort extends EventTarget implements MoldableSerialPort {
     readonly descriptor: MoldableNativeDeviceDescriptor;
     readable: ReadableStream<Uint8Array> | null;

package/dist/lib/native-hardware/serial-native.js

@@ -1,6 +1,6 @@
-import { NativeHardwareBridgeError } from './bridge';
-import { bytesFromNativeDeviceResult, bytesWrittenFromNativeDeviceResult, closeMoldableNativeDevice, executeMoldableNativeDeviceOperation, openMoldableNativeDevice, } from './native-device-io';
-import { NativeDeviceLifecycle, isNativeDeviceDisconnect, } from './native-device-lifecycle';
+import { NativeHardwareBridgeError } from './bridge.js';
+import { bytesFromNativeDeviceResult, bytesWrittenFromNativeDeviceResult, closeMoldableNativeDevice, executeMoldableNativeDeviceOperation, openMoldableNativeDevice, } from './native-device-io.js';
+import { NativeDeviceLifecycle, isNativeDeviceDisconnect, } from './native-device-lifecycle.js';
 export class NativeMoldableSerialPort extends EventTarget {
     descriptor;
     readable = null;

package/dist/lib/native-hardware/serial.js

@@ -1,7 +1,7 @@
-import { NativeHardwareBridgeError } from './bridge';
-import { abortedDeviceIoError, awaitDeviceIoWithAbort, deviceIoError, unsupportedDeviceIoError, } from './device-io-errors';
-import { listMoldableNativeDevices } from './native-device-io';
-import { NativeMoldableSerialPort } from './serial-native';
+import { NativeHardwareBridgeError } from './bridge.js';
+import { abortedDeviceIoError, awaitDeviceIoWithAbort, deviceIoError, unsupportedDeviceIoError, } from './device-io-errors.js';
+import { listMoldableNativeDevices } from './native-device-io.js';
+import { NativeMoldableSerialPort } from './serial-native.js';
 function assertNativeSerialFiltersSupported(options) {
     if (options.allowedBluetoothServiceClassIds?.length ||
         options.filters?.some((filter) => filter.bluetoothServiceClassId !== undefined)) {

package/dist/lib/native-hardware/system-audio.d.ts

@@ -1,4 +1,4 @@
-import { type NativeHardwareBridgeOptions } from './bridge';
+import { type NativeHardwareBridgeOptions } from './bridge.js';
 export declare const NATIVE_SYSTEM_AUDIO_MAX_REPLAY_FRAMES = 500;
 export declare const NATIVE_SYSTEM_AUDIO_PERMISSION_REQUEST_TIMEOUT_MS = 125000;
 export type MoldableSystemAudioCaptureMode = 'systemAudio' | 'systemMicrophone';

package/dist/lib/native-hardware/system-audio.js

@@ -1,4 +1,4 @@
-import { NativeHardwareBridgeError, callNativeHardwareBridge, resolveNativeHardwareParentOrigin, } from './bridge';
+import { NativeHardwareBridgeError, callNativeHardwareBridge, resolveNativeHardwareParentOrigin, } from './bridge.js';
 const NATIVE_SYSTEM_AUDIO_REQUEST_TYPE = 'moldable:system-audio-request';
 const NATIVE_SYSTEM_AUDIO_RESULT_TYPE = 'moldable:system-audio-response';
 const NATIVE_SYSTEM_AUDIO_EVENT_TYPE = 'moldable:system-audio-event';

package/dist/lib/native-hardware/usb-native.d.ts

@@ -1,5 +1,5 @@
-import { type MoldableNativeDeviceDescriptor } from './native-device-io';
-import type { MoldableUsbControlTransferParameters, MoldableUsbDevice, MoldableUsbInTransferResult, MoldableUsbOpenOptions, MoldableUsbOperationOptions, MoldableUsbOutTransferResult } from './usb';
+import { type MoldableNativeDeviceDescriptor } from './native-device-io.js';
+import type { MoldableUsbControlTransferParameters, MoldableUsbDevice, MoldableUsbInTransferResult, MoldableUsbOpenOptions, MoldableUsbOperationOptions, MoldableUsbOutTransferResult } from './usb.js';
 export declare class NativeMoldableUsbDevice extends EventTarget implements MoldableUsbDevice {
     readonly descriptor: MoldableNativeDeviceDescriptor;
     readonly vendorId: number;

package/dist/lib/native-hardware/usb-native.js

@@ -1,6 +1,6 @@
-import { NativeHardwareBridgeError } from './bridge';
-import { bytesFromNativeDeviceResult, bytesWrittenFromNativeDeviceResult, closeMoldableNativeDevice, executeMoldableNativeDeviceOperation, openMoldableNativeDevice, } from './native-device-io';
-import { NativeDeviceLifecycle, isNativeDeviceDisconnect, } from './native-device-lifecycle';
+import { NativeHardwareBridgeError } from './bridge.js';
+import { bytesFromNativeDeviceResult, bytesWrittenFromNativeDeviceResult, closeMoldableNativeDevice, executeMoldableNativeDeviceOperation, openMoldableNativeDevice, } from './native-device-io.js';
+import { NativeDeviceLifecycle, isNativeDeviceDisconnect, } from './native-device-lifecycle.js';
 const DEFAULT_TIMEOUT_MS = 10_000;
 export class NativeMoldableUsbDevice extends EventTarget {
     descriptor;

package/dist/lib/native-hardware/usb.js

@@ -1,7 +1,7 @@
-import { NativeHardwareBridgeError } from './bridge';
-import { awaitDeviceIoWithAbort, deviceIoError, unsupportedDeviceIoError, } from './device-io-errors';
-import { listMoldableNativeDevices } from './native-device-io';
-import { NativeMoldableUsbDevice, isNativeMoldableUsbDevice, } from './usb-native';
+import { NativeHardwareBridgeError } from './bridge.js';
+import { awaitDeviceIoWithAbort, deviceIoError, unsupportedDeviceIoError, } from './device-io-errors.js';
+import { listMoldableNativeDevices } from './native-device-io.js';
+import { NativeMoldableUsbDevice, isNativeMoldableUsbDevice, } from './usb-native.js';
 function assertNativeUsbFiltersSupported(filters) {
     if (filters?.some((filter) => filter.classCode !== undefined ||
         filter.subclassCode !== undefined ||

package/dist/lib/theme.js

@@ -1,7 +1,7 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useCallback, useContext, useEffect, useState, } from 'react';
-import { TooltipProvider } from '../components/ui/tooltip';
+import { TooltipProvider } from '../components/ui/tooltip.js';
 const ThemeContext = createContext(null);
 const STORAGE_KEY = 'moldable-theme';
 function getSystemTheme() {

package/docs/README.md

@@ -12,6 +12,7 @@ feels at home on macOS without imitating private platform implementation.
 - [App anatomy](./app-anatomy.md)
 - [Standalone app windows](./standalone-app-windows.md)
 - [Component catalog](./component-catalog.md)
+- [Visual and accessibility regression](./visual-regression.md)
 - [Accessibility](./accessibility.md)
 - [Native integration](./native-integration.md)
 - [Component guide template](./component-guide-template.md)

package/docs/design-tokens.md

@@ -28,6 +28,11 @@ The default UI font is the platform sans-serif stack. Monospaced text uses the
 platform monospace stack. Prefer `Text` for normal interface copy; the token
 utilities are useful for display-scale titles and highly composed canvases.
 
+The native UI scale is deliberately small: `--text-11` for captions and
+metadata, `--text-13` for body and control text, `--text-16` for emphasized
+titles, `--text-18` for secondary headings, and `--text-24` for primary
+headings. Long-form Markdown keeps its prose scale.
+
 | Role    | CSS token          | Tailwind utility  | Use                                |
 | ------- | ------------------ | ----------------- | ---------------------------------- |
 | Display | `--type-display-*` | `text-ui-display` | One dominant app or document title |
@@ -109,15 +114,32 @@ disabled, and invalid states. Disabled wins over pointer states. Focus remains
 visible when combined with selected or invalid. Selection is durable state;
 hover is not a substitute for it.
 
+Focus rings use the neutral translucent `--ring` token at one pixel. Never use
+plain `focus:` ring utilities or accent colors for keyboard focus.
+
 Do not use state-layer colors as arbitrary fills. Prefer the shared component
 when one exists.
 
 ## Shape and materials
 
-Use `rounded-control`, `rounded-container`, and `rounded-overlay` to keep
-related objects visually consistent. `rounded-window` is host-informed and
-normally only useful in previews; the native host owns the actual window
-shape.
+Use `rounded-control`, `rounded-checkbox`, `rounded-popover`, `rounded-card`,
+`rounded-group`, `rounded-panel`, `rounded-dialog`, and `rounded-pill` to keep
+geometry tied to its role. The 4px checkbox role keeps a 16px checkbox
+visually square while ordinary controls retain their softer 10px corners.
+`rounded-container` and `rounded-overlay` remain compatibility aliases for
+card and popover geometry. `rounded-window` is host-informed and normally only
+useful in previews; the native host owns the actual window shape. Increased
+contrast reduces authored radii and uses inset borders instead of drop
+shadows.
+
+## Data series
+
+Charts consume `--chart-1` through `--chart-5` (and the matching
+`chart-1`…`chart-5` Tailwind aliases). The defaults intentionally reuse the
+info, success, pending, neutral, and accent support families so data graphics
+stay theme-aware and do not inherit Moldable's legacy brand orange. Apps may
+override the complete series palette at a theme boundary, but chart
+components and stories should never embed raw series colors.
 
 Adaptive material has two semantic variants. Each includes fill, fallback,
 border, highlight, blur, and saturation tokens:
@@ -125,8 +147,8 @@ border, highlight, blur, and saturation tokens:
 - `--material-regular-*` supports normal toolbar and control chrome.
 - `--material-clear-*` supports compact controls over media or a richly
   colored canvas.
-- `shadow-panel`, `shadow-overlay`, and `shadow-window` provide elevation
-  independently from translucency.
+- `shadow-panel`, `shadow-overlay`, `shadow-dialog`, and `shadow-window`
+  provide elevation independently from translucency.
 
 Use `Material` and `MaterialGroup` instead of assembling those tokens in app
 markup. `MaterialGroup` owns one sampled layer for a related control cluster;

package/docs/foundations.md

@@ -54,5 +54,7 @@ springy, and do not animate layout merely to make a screen feel active.
 
 ## Focus
 
-Keyboard focus must remain visible against every surface. Do not remove a
-focus ring unless the replacement is at least as clear.
+Keyboard focus uses a thin, neutral system-chrome ring. Apply it only through
+`focus-visible`; pointer and programmatic focus must not paint a ring. Dialogs
+focus their content container on open so the first Tab reaches the first
+control with the keyboard indicator.

package/docs/visual-regression.md

@@ -0,0 +1,78 @@
+# Visual and accessibility regression
+
+The phase 1 runner exercises every authored story in the core component
+catalog. It does not start the desktop shell or any Moldable-managed app.
+
+## What runs
+
+`visual-host/` is a small Vite entry that renders one story at a time:
+
+```text
+?story=controls/button&theme=dark&width=360
+```
+
+Unique bare story ids are also accepted. Optional
+`transparency=reduced` and `contrast=increased` parameters set the same
+manual accessibility attributes used by the catalog. The host bundles Inter
+and Roboto Mono, waits for `document.fonts.ready`, and disables animations,
+transitions, scrolling, and the caret under `data-motion="reduced"`.
+
+The Playwright runner builds and serves that static host, blocks non-host
+network requests, freezes time and randomness, and tests Chromium at:
+
+- light and dark themes;
+- 360 × 720 and 960 × 720 viewports;
+- rest plus the browser-driven states declared by an exemplar story.
+
+A story opts into browser-driven states with `liveStates` and marks exactly
+one element:
+
+```tsx
+<Button data-state-target="hover focus pressed">Continue</Button>
+```
+
+Playwright performs real hover, focus, and held-pointer interactions on that
+element. Button, segmented control, and toggle stories are the phase 1
+exemplars.
+
+Every captured case also receives an axe WCAG 2 A/AA and WCAG 2.1 A/AA scan.
+Serious and critical violations fail. Per-story suppressions belong in
+`visual-tests/visual-matrix.ts` and must include a reason. Global
+suppressions are intentionally unsupported.
+
+## Local commands
+
+Install the pinned Chromium build once:
+
+```bash
+pnpm -C packages/ui exec playwright install chromium
+```
+
+Run against committed baselines:
+
+```bash
+pnpm -C packages/ui test:visual
+```
+
+Create or intentionally update baselines after reviewing the UI change:
+
+```bash
+pnpm -C packages/ui test:visual:update
+```
+
+Baseline PNGs live in `visual-tests/baselines/`. Failures emit actual,
+expected, diff, and trace artifacts in the gitignored `.visual-results/`
+directory.
+
+## Determinism and skips
+
+Stories must use fixed inputs and no live data, network, wall-clock timers, or
+unseeded randomness. Add an unavoidable phase 1 skip to
+`deterministicStorySkips` in `visual-tests/visual-matrix.ts` with a specific
+reason. Skips are reported in the runner summary; silent conditional skips
+are not allowed.
+
+## CI
+
+The `ui-regression` CI job installs Chromium and its Linux dependencies,
+builds only `@moldable-ai/ui`, then runs the combined visual and axe suite.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moldable-ai/ui",
-  "version": "0.2.21",
+  "version": "0.2.24",
   "description": "Shared UI components for Moldable applications",
   "author": "Desiderata LLC",
   "license": "SEE LICENSE IN LICENSE",
@@ -37,16 +37,22 @@
     "dist",
     "docs",
     "src/components/ui/*.md",
+    "src/lib/*.md",
     "src/styles",
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && node ./scripts/rewrite-relative-imports.mjs",
+    "build:visual-host": "vite build --config vite.visual.config.ts",
     "dev": "tsc --watch",
     "lint": "eslint . --ext .ts,.tsx --max-warnings 0",
     "format": "prettier --write . --ignore-path ../../.prettierignore",
-    "check-types": "tsc --noEmit",
-    "test": "vitest run"
+    "check-types": "tsc --noEmit && tsc --noEmit -p tsconfig.visual.json",
+    "test": "vitest run",
+    "test:visual": "pnpm build:visual-host && playwright test --config playwright.visual.config.ts",
+    "test:visual:update": "pnpm build:visual-host && playwright test --config playwright.visual.config.ts --update-snapshots",
+    "filmstrip:orb-spawn": "node scripts/render-orb-spawn-filmstrip.mjs",
+    "visual:serve": "vite preview --config vite.visual.config.ts --host 127.0.0.1 --port 4179 --strictPort"
   },
   "dependencies": {
     "@base-ui/react": "^1.1.0",
@@ -105,14 +111,19 @@
     "zod": "^4.3.5"
   },
   "devDependencies": {
+    "@axe-core/playwright": "^4.12.1",
+    "@fontsource/inter": "^5.3.0",
+    "@fontsource/roboto-mono": "^5.3.0",
     "@moldable-ai/eslint-config": "workspace:*",
     "@moldable-ai/prettier-config": "workspace:*",
     "@moldable-ai/typescript-config": "workspace:*",
+    "@playwright/test": "^1.62.0",
     "@types/node": "^24.0.3",
     "@types/react": "^19.1.6",
     "@types/react-dom": "^19.1.6",
     "jsdom": "^26.1.0",
     "typescript": "^5.8.3",
+    "vite": "^6.4.3",
     "vitest": "^4.1.8"
   },
   "peerDependencies": {

package/src/components/ui/alert-dialog.md

@@ -25,6 +25,33 @@ shown. The default error deliberately avoids exposing internal details.
 host safe area. Use `AlertDialogBody` when explanation or affected-item content
 can grow. Keep the consequence visible while the action is pending.
 
+For composed alert dialogs, put `loading` on `AlertDialogAction` while its
+request is in flight. This forwards the standard `Button` busy state, blocks
+duplicate activation, and preserves the action label width and accessible name.
+Use `pending` with `pendingLabel` when maintaining the confirmation-specific
+status-label pattern; `ConfirmDialog` manages that state automatically. Disable
+the surrounding form only when its other controls must not change during the
+request.
+
+Mark one confirming action with `primary` to enable Command+Enter on macOS or
+Control+Enter on other platforms. The shortcut does not run without a marked
+action, while that action is loading or disabled, during key composition or
+repeat, or when a focused control consumes the event with `preventDefault()`.
+Plain Enter remains native and Escape remains the Radix cancel behavior.
+
+```tsx
+<AlertDialogFooter>
+  <span className="text-muted-foreground mr-auto inline-flex items-center gap-1 text-xs">
+    Confirm <Kbd>⌘</Kbd>
+    <Kbd>Enter</Kbd>
+  </span>
+  <AlertDialogCancel>Cancel</AlertDialogCancel>
+  <AlertDialogAction primary loading={isDeleting}>
+    Delete recording
+  </AlertDialogAction>
+</AlertDialogFooter>
+```
+
 Use concrete labels such as “Delete recording,” not “OK.” Put the safe,
 reversible action first in keyboard order and the confirming action last. Do
 not use an alert dialog for ordinary navigation, long forms, or success

package/src/components/ui/button.md

@@ -25,9 +25,15 @@ import { RefreshCw } from 'lucide-react'
 >
   <RefreshCw />
 </Button>
+
+<Button type="submit" loading={isSaving}>
+  Save changes
+</Button>
 ```
 
-Keep toolbar actions compact (`xs`, `sm`, `icon-xs`, or `icon-sm`). Reserve `default` or `lg` for the primary action in a form, setup state, or focused control dock. While an async action is running, disable the button, preserve its width, and show a small spinner beside a short status label.
+Keep toolbar actions compact (`xs`, `sm`, `icon-xs`, or `icon-sm`). Reserve `default` or `lg` for the primary action in a form, setup state, or focused control dock. Set `loading` while that button's async action is in flight. The button blocks pointer and keyboard activation, exposes `aria-busy`, keeps its accessible label mounted, and centers a width-stable spinner.
+
+Use `loading` for the action that started the request. Disable the whole form only when editing during the request would be unsafe or would invalidate the submitted payload; do not disable unrelated controls merely to communicate progress.
 
 For links that should look like buttons:
 
@@ -42,13 +48,14 @@ For links that should look like buttons:
 - `variant`: `default`, `destructive`, `outline`, `secondary`, `ghost`, or `link`. Defaults to `default`.
 - `size`: `default`, `xs`, `sm`, `lg`, `icon`, `icon-xs`, `icon-sm`, or `icon-lg`. Defaults to `default`.
 - `asChild`: renders a Radix `Slot` so the child owns the element and semantics.
+- `loading`: blocks activation, applies disabled behavior and `aria-busy`, and overlays the shared `Spinner` without unmounting or resizing the label. Defaults to `false`.
 - Accepts native button props, including `type`, `disabled`, `aria-*`, and event handlers.
 - `buttonVariants` is exported for cases that need the same visual treatment on another component.
 
 ## Do
 
 - Set `type="button"` unless the control intentionally submits a form.
-- Add `cursor-pointer`; use the real `disabled` attribute for unavailable or busy actions.
+- Add `cursor-pointer`; use the real `disabled` attribute for unavailable actions and `loading` for an in-flight action.
 - Give icon-only buttons an `aria-label` and a tooltip.
 - Use a specific Lucide icon that names the action.
 - Put one visually primary action in a local action group.
@@ -60,7 +67,7 @@ For links that should look like buttons:
 - Do not rely on color alone to explain a destructive or selected action.
 - Do not use raw color classes, decorative gradients, or oversized call-to-action styling.
 - Do not use `Sparkles` as a generic AI marker.
-- Do not leave a busy button clickable or allow repeated submission.
+- Do not use `disabled` alone as the progress signal; use `loading` so progress is announced and the label width stays stable.
 - Do not hide essential actions behind hover-only icon buttons.
 
 ## Moldable considerations

package/src/components/ui/confirm-dialog.md

@@ -0,0 +1,97 @@
+# Confirm dialog
+
+## Purpose
+
+`ConfirmDialog` asks for explicit confirmation before a consequential action
+and owns the pending and error states of an asynchronous confirmation.
+
+Use it for destructive or difficult-to-reverse actions, security-sensitive
+changes, and operations with a meaningful external effect. Do not interrupt
+routine, reversible actions; use undo or inline feedback instead. Use the
+lower-level `AlertDialog` family when the body needs custom media or layout.
+
+## Usage patterns
+
+```tsx
+import { Button, ConfirmDialog } from '@moldable-ai/ui'
+
+function DeleteRecordingDialog() {
+  return (
+    <ConfirmDialog
+      title="Delete recording?"
+      description="The audio and transcript will be permanently removed."
+      trigger={<Button variant="destructive">Delete recording</Button>}
+      confirmLabel="Delete"
+      pendingLabel="Deleting…"
+      variant="destructive"
+      size="sm"
+      onConfirm={() => deleteRecording(recordingId)}
+      onConfirmError={reportDeleteError}
+      getErrorMessage={() => 'The recording could not be deleted.'}
+    />
+  )
+}
+```
+
+For a controlled dialog, pass `open` and `onOpenChange`. Omit `trigger` when
+another event owns opening.
+
+## Anatomy
+
+`ConfirmDialog` composes `AlertDialog` with a required title and description,
+a cancel action, and one primary confirm action. It shows a shared spinner and
+`pendingLabel` while `onConfirm` is unresolved, then closes only after success.
+Rejected confirmation remains open and renders an alert message.
+
+## API summary
+
+- `title`, `description`, and `onConfirm` are required.
+- `trigger` accepts one React element.
+- `confirmLabel`, `pendingLabel`, and `cancelLabel` accept React content and
+  default to “Confirm”, “Working…”, and “Cancel”.
+- `variant` is `"default" | "destructive"` and defaults to `"default"`.
+- `size` is `"sm" | "default" | "lg"` and defaults to `"default"`.
+- `open`, `defaultOpen`, and `onOpenChange` support controlled or uncontrolled
+  disclosure.
+- `onConfirmError` receives the rejected value. `getErrorMessage` maps it to
+  rendered React content.
+
+## States and interaction
+
+While `onConfirm` is pending, both actions are disabled, repeated confirmation
+is ignored, and close requests are blocked. Success closes the dialog and calls
+`onOpenChange(false)`. Failure clears pending state, keeps the dialog open,
+shows the mapped error or default message, and calls `onConfirmError`.
+
+The surface uses `bg-background`, `border-separator`, `rounded-dialog`, and
+`shadow-dialog`. Description copy uses `text-text-secondary`; failed and
+destructive states use the semantic destructive role. Do not add raw danger
+colors or custom dialog elevation.
+
+## Keyboard and accessibility
+
+The component inherits alert-dialog semantics and focus containment. The
+dialog content receives initial focus; Enter activates the marked primary
+action when appropriate, and pending state prevents dismissal. Write a
+specific title and describe the consequence, not merely “Are you sure?”.
+Error copy is announced with `role="alert"`.
+
+## Do
+
+- Name the action and the affected object in the title or description.
+- Use `variant="destructive"` only for destructive confirmation.
+- Return the action promise from `onConfirm`.
+- Map technical failures to concise, actionable copy with `getErrorMessage`.
+
+## Don't
+
+- Do not confirm harmless, reversible, or high-frequency actions.
+- Do not close optimistically before `onConfirm` succeeds.
+- Do not perform the action from both the trigger and `onConfirm`.
+- Do not expose raw exception text to users.
+
+## Testing
+
+Exercise controlled and uncontrolled opening, success, rejection, repeated
+activation while pending, attempted dismissal while pending, destructive
+styling, all three sizes, and keyboard confirmation.