@beyondwork/docx-react-component 1.0.43 → 1.0.46

package/README.md

@@ -216,9 +216,26 @@ Current integration honesty:
 
 - [`docs/maintainers/README.md`](docs/maintainers/README.md)
 - [`docs/ccep-contract-templates/README.md`](docs/ccep-contract-templates/README.md)
+- [`docs/plans/README.md`](docs/plans/README.md) — active development lanes + open-issues register
 
 The CCEP corpus is kept on `main` as a maintainer-safe smoke-doc source set for agreement-heavy validation and wrapper or agent benchmarking.
 
+### Active Development Lanes
+
+Engineering work is organized into 9 lanes (5 active now + 2 later polish + 2 final) — full plan index, status, and worktree map at [`docs/plans/README.md`](docs/plans/README.md). Each lane has a single self-contained doc at `docs/plans/lane-N-<name>.md`:
+
+| Lane | Mission | Status |
+|---|---|---|
+| 1. [**Editing Foundation**](docs/plans/lane-1-editing-foundation.md) | Close I1–I6 + ship the SelectionLayer / EditLayer / StructureLayer / SurfaceLayer split | active |
+| 2. [**Render Performance**](docs/plans/lane-2-render-performance.md) | <32 ms typing P50 + <1 s cold-open on 200-page CCEP; never stuck on loading | active |
+| 3. [**Layout Engine + OOXML Fidelity**](docs/plans/lane-3-layout-engine-ooxml-fidelity.md) | Land P9 anchor-index + P10 incremental relayout + drain O2/O3/O4 round-trip + tables/TOC/page numbers/front pages/image structures | active |
+| 4. [**Collab + CLM/Vallor Integration**](docs/plans/lane-4-collab-clm-vallor.md) | Promote collab plumbing → first-class user mode; wire Sunday CLM × React E2E demo | active |
+| 5. [**Charts (independent)**](docs/plans/lane-5-charts.md) | Move charts from preserve-only opaque preview to Word-accurate native rendering (Stages 1–7) | active |
+| 6. [**Visual Chrome / Layout Polish**](docs/plans/lane-6-visual-chrome-layout-polish.md) | True-to-Word visuals: discrete paper cards, native page chrome, float-wrap, validation bar | LATER |
+| 7. [**Bugs / Gaps / Cross-cutting**](docs/plans/lane-7-bugs-gaps-cross-cutting.md) | Drain V#/O#/X# register; trigger-gated work; infrastructure hardening | LATER |
+| 8. [**API Ergonomics / Errors / Backwards Compatibility**](docs/plans/lane-8-api-ergonomics.md) | Refactor `docs/reference/public-api.md` end-to-end with groups + per-code error catalog + ergonomics fixes; maintain backwards compat | LATER (Tracks A+C shipped 2026-04-19) |
+| 9. [**Shipping**](docs/plans/lane-9-shipping.md) | Production-readiness: API freeze, semver discipline, changelog, telemetry, customer migration guides, doc completeness audit | FINAL |
+
 ### Technical Wiki
 
 - [`docs/wiki/`](docs/wiki/) — Feature-by-feature technical documentation (25+ topics covering OOXML, ProseMirror, runtime, and platform)
@@ -691,7 +708,21 @@ Fired when a comment is resolved (via `resolveComment` or the sidebar).
 }
 ```
 
-There is no separate `comment_removed` event — deletions are silent. Query `getComments()` after a `dirty_changed` event if you need to detect deletions.
+For a general-purpose "something about comments changed" signal (covering deletions, reply appends, body edits, reopen, and every other mutation — including Yjs-driven mutations that route through the editor's imperative ref), subscribe to `comments_changed`.
+
+#### `comments_changed`
+
+Fired once per commit whenever the runtime's comment snapshot differs from the previous commit. Use this when you render comments in a sibling component and need to know when to re-fetch via `editorRef.current.getComments()`.
+
+```ts
+{
+  type: "comments_changed";
+  documentId: string;
+  changedCommentIds: string[]; // always non-empty
+}
+```
+
+Covers: `addComment`, `deleteComment`, `resolveComment`, `reopenComment`, `addCommentReply`, `editCommentBody`, and any remote-origin mutation that funnels through the same runtime APIs. Does NOT fire on selection/focus changes.
 
 #### `change_accepted`
 
@@ -927,6 +958,9 @@ function CommentButton({ editorRef }: { editorRef: React.RefObject<WordReviewEdi
       case "comment_resolved":
         console.log("comment resolved:", event.commentId);
         break;
+      case "comments_changed":
+        console.log("comments changed:", event.changedCommentIds);
+        break;
       case "change_accepted":
         console.log("change accepted:", event.changeId);
         break;

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.43",
+  "version": "1.0.46",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
+  "packageManager": "pnpm@10.30.3",
   "type": "module",
   "sideEffects": [
     "**/*.css"
@@ -92,6 +93,35 @@
     "./ui-tailwind/theme/editor-theme.css": "./src/ui-tailwind/theme/editor-theme.css"
   },
   "types": "./src/index.ts",
+  "scripts": {
+    "build": "tsup",
+    "test": "bash scripts/run-workspace-tests.sh",
+    "test:repo": "node scripts/ci-check-layout-engine-version.mjs && node scripts/run-repo-tests.mjs core",
+    "test:repo:all": "node scripts/run-repo-tests.mjs all",
+    "test:repo:optional": "node scripts/run-repo-tests.mjs optional",
+    "test:repo:browser-ui": "node scripts/run-repo-tests.mjs browser-ui",
+    "test:wcag-audit": "node scripts/run-repo-tests.mjs wcag-audit",
+    "test:harness": "pnpm --filter @docx-react-component/react-word-editor-harness test",
+    "test:visual": "VISUAL_SMOKE_PROFILE=bare pnpm exec playwright test --project=chromium",
+    "test:visual:chrome": "VISUAL_SMOKE_PROFILE=chrome-cycle pnpm exec playwright test --project=chromium",
+    "visual:list-runs": "node scripts/visual-smoke-list-runs.mjs",
+    "mcp:visual-smoke": "node scripts/visual-smoke-mcp.mjs",
+    "lint": "pnpm run lint:no-authored-js && pnpm run lint:docs-contracts && pnpm run lint:tsgo && pnpm run lint:tsgo:harness",
+    "lint:docs-contracts": "bash scripts/check-reference-load-contract.sh",
+    "lint:no-authored-js": "bash scripts/check-no-authored-js.sh",
+    "lint:tsgo": "tsgo --noEmit -p tsconfig.build.json",
+    "lint:tsgo:harness": "pnpm --filter @docx-react-component/react-word-editor-harness lint:tsgo",
+    "context7:api-check": "bash scripts/context7-export-env.sh run bash scripts/context7-api-check.sh",
+    "wave:doctor": "bash scripts/context7-export-env.sh run pnpm exec wave doctor --json",
+    "wave:dry-run": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main --dry-run --no-dashboard",
+    "wave:launch": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main",
+    "wave:launch:managed": "bash scripts/wave-launch.sh",
+    "wave:status": "bash scripts/wave-status.sh",
+    "wave:watch": "bash scripts/wave-watch.sh --follow",
+    "wave:dashboard:current": "bash scripts/wave-dashboard-attach.sh current",
+    "wave:dashboard:global": "bash scripts/wave-dashboard-attach.sh global",
+    "harness:dev": "pnpm --filter @docx-react-component/react-word-editor-harness dev"
+  },
   "keywords": [
     "docx",
     "word",
@@ -135,9 +165,9 @@
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "tailwindcss": "^4.2.2",
-    "yjs": "^13.6.0",
     "y-prosemirror": "^1.2.0",
-    "y-protocols": "^1.0.0"
+    "y-protocols": "^1.0.0",
+    "yjs": "^13.6.0"
   },
   "peerDependenciesMeta": {
     "yjs": {
@@ -156,6 +186,7 @@
     "@types/react": "19.2.14",
     "@types/react-dom": "19.2.3",
     "@typescript/native-preview": "7.0.0-dev.20260409.1",
+    "fake-indexeddb": "^6.2.5",
     "jsdom": "^29.0.1",
     "pixelmatch": "^7.1.0",
     "pngjs": "^7.0.0",
@@ -174,33 +205,14 @@
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.30"
   },
-  "scripts": {
-    "build": "tsup",
-    "test": "bash scripts/run-workspace-tests.sh",
-    "test:repo": "node scripts/run-repo-tests.mjs core",
-    "test:repo:all": "node scripts/run-repo-tests.mjs all",
-    "test:repo:optional": "node scripts/run-repo-tests.mjs optional",
-    "test:repo:browser-ui": "node scripts/run-repo-tests.mjs browser-ui",
-    "test:wcag-audit": "node scripts/run-repo-tests.mjs wcag-audit",
-    "test:harness": "pnpm --filter @docx-react-component/react-word-editor-harness test",
-    "test:visual": "VISUAL_SMOKE_PROFILE=bare pnpm exec playwright test --project=chromium",
-    "test:visual:chrome": "VISUAL_SMOKE_PROFILE=chrome-cycle pnpm exec playwright test --project=chromium",
-    "visual:list-runs": "node scripts/visual-smoke-list-runs.mjs",
-    "mcp:visual-smoke": "node scripts/visual-smoke-mcp.mjs",
-    "lint": "pnpm run lint:no-authored-js && pnpm run lint:docs-contracts && pnpm run lint:tsgo && pnpm run lint:tsgo:harness",
-    "lint:docs-contracts": "bash scripts/check-reference-load-contract.sh",
-    "lint:no-authored-js": "bash scripts/check-no-authored-js.sh",
-    "lint:tsgo": "tsgo --noEmit -p tsconfig.build.json",
-    "lint:tsgo:harness": "pnpm --filter @docx-react-component/react-word-editor-harness lint:tsgo",
-    "context7:api-check": "bash scripts/context7-export-env.sh run bash scripts/context7-api-check.sh",
-    "wave:doctor": "bash scripts/context7-export-env.sh run pnpm exec wave doctor --json",
-    "wave:dry-run": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main --dry-run --no-dashboard",
-    "wave:launch": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main",
-    "wave:launch:managed": "bash scripts/wave-launch.sh",
-    "wave:status": "bash scripts/wave-status.sh",
-    "wave:watch": "bash scripts/wave-watch.sh --follow",
-    "wave:dashboard:current": "bash scripts/wave-dashboard-attach.sh current",
-    "wave:dashboard:global": "bash scripts/wave-dashboard-attach.sh global",
-    "harness:dev": "pnpm --filter @docx-react-component/react-word-editor-harness dev"
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild",
+      "sharp"
+    ],
+    "overrides": {
+      "react": "19.2.4",
+      "react-dom": "19.2.4"
+    }
   }
-}
+}

package/src/api/public-types.ts

@@ -981,7 +981,16 @@ export type SurfaceBlockSnapshot =
       detail: string;
       featureKey?: string;
       blockedReasonCode?: "workflow_preserve_only" | "workflow_blocked_import";
-      state: "locked-preserve-only";
+      /**
+       * When set, this opaque_block is a size-preserving placeholder generated
+       * by viewport culling, NOT a real preserved fragment. The PM schema uses
+       * this to claim the original block's position span without rendering
+       * content.
+       *
+       * See docs/plans/lane-2-render-performance.md.
+       */
+      placeholderSize?: number;
+      state: "locked-preserve-only" | "placeholder-culled";
     };
 
 export interface SecondaryStorySurface {
@@ -997,6 +1006,15 @@ export interface EditorSurfaceSnapshot {
   blocks: SurfaceBlockSnapshot[];
   lockedFragmentIds: string[];
   secondaryStories: SecondaryStorySurface[];
+  /**
+   * Block index range rendered as real (non-placeholder) in this snapshot.
+   * Blocks outside this range are placeholder opaque_blocks carrying the
+   * original position range but no content. `null` (default) = all blocks
+   * are real (legacy behavior).
+   *
+   * See docs/plans/lane-2-render-performance.md.
+   */
+  viewportBlockRange: { start: number; end: number } | null;
 }
 
 export type EditorWarningCode =
@@ -1669,6 +1687,16 @@ export interface AddCommentParams {
   authorId?: string;
 }
 
+export interface AddCommentResult {
+  commentId: string;
+  anchor: EditorAnchorProjection;
+}
+
+export interface AddCommentReplyResult {
+  commentId: string;
+  entryId: string;
+}
+
 export interface ExportDocxOptions {
   fileName?: string;
   reason?: string;
@@ -2388,6 +2416,23 @@ export type WordReviewEditorEvent =
       documentId: string;
       commentId: string;
     }
+  | {
+      type: "comments_changed";
+      documentId: string;
+      /**
+       * Stable ids of the comment threads whose state differs between
+       * the previous and current runtime render snapshot. Includes
+       * additions, deletions, body edits, reply appends, and
+       * resolution-state transitions. Consumers can call
+       * `editorRef.current.getComments()` to obtain the full updated
+       * `CommentSidebarSnapshot`.
+       *
+       * The array is always non-empty when this event fires. When the
+       * snapshot's `comments` reference is unchanged between commits,
+       * no event fires.
+       */
+      changedCommentIds: string[];
+    }
   | {
       type: "change_accepted";
       documentId: string;
@@ -2693,11 +2738,50 @@ export interface EditorTelemetryEvent {
   detail?: Record<string, unknown>;
 }
 
+/**
+ * Stage 0B.1 — parameters passed to `EditorHostAdapter.renderChartPreview`
+ * when the importer encounters a `c:chartSpace` that has no cached
+ * `mc:Fallback` bitmap. Hosts receive the raw chart-part XML plus the
+ * theme XML and the intended display size, and return either preview
+ * bytes (typically PNG or SVG) or `null` to fall back to the typed
+ * badge.
+ *
+ * Field stability: only additive changes; no field is ever renamed or
+ * removed. Host implementations should use structural narrowing to
+ * ignore unknown fields in future versions.
+ */
+export interface ChartPreviewResolveParams {
+  /** Chart part body (`word/charts/chartN.xml`). UTF-8 string. */
+  chartXml: string;
+  /** Absolute package path of the chart part (e.g. `/word/charts/chart1.xml`). Useful as a cache key. */
+  chartPartPath: string;
+  /** Body of `theme1.xml` when the package ships one; `undefined` otherwise. */
+  themeXml: string | undefined;
+  /** Intended display width in EMU (extracted from the drawing's `wp:extent`). */
+  widthEmu: number;
+  /** Intended display height in EMU. */
+  heightEmu: number;
+}
+
 export interface EditorHostAdapter {
   load?(params: LoadRequest): Promise<LoadResult>;
   saveSession?(params: SaveSessionParams): Promise<SaveSessionResult>;
   saveExport?(params: SaveExportParams): Promise<SaveExportResult>;
   logEvent?(event: EditorTelemetryEvent): void;
+  /**
+   * Stage 0B.1: render a chart to bitmap/SVG preview bytes. Called at
+   * import time for every `c:chartSpace` that ships without a cached
+   * `mc:Fallback` blip. Return `null` to fall back to the typed badge
+   * (Stage 0 behavior). Return a `Uint8Array` to inject the bytes as
+   * a synthetic `MediaItem` and render the preview through the
+   * existing `chart_atom` path.
+   *
+   * Content type is inferred from the first few bytes: `image/png`
+   * for a PNG magic number, `image/svg+xml` otherwise. Hosts that
+   * need a different content type should extend this contract in a
+   * follow-up.
+   */
+  renderChartPreview?(params: ChartPreviewResolveParams): Promise<Uint8Array | null>;
 }
 
 export interface EditorDatastoreAdapter {
@@ -2712,11 +2796,11 @@ export interface WordReviewEditorRef {
   blur(): void;
   undo(): void;
   redo(): void;
-  addComment(params: AddCommentParams): string;
+  addComment(params: AddCommentParams): AddCommentResult;
   openComment(commentId: string): void;
   resolveComment(commentId: string): void;
   reopenComment(commentId: string): void;
-  addCommentReply(commentId: string, body: string): void;
+  addCommentReply(commentId: string, body: string): AddCommentReplyResult;
   editCommentBody(commentId: string, body: string): void;
   deleteComment(commentId: string): void;
   acceptChange(changeId: string): void;
@@ -3073,6 +3157,20 @@ export interface WordReviewEditorProps {
   chromePreset?: WordReviewEditorChromePreset;
   chromeOptions?: Partial<WordReviewEditorChromeOptions>;
   markupDisplay?: "clean" | "simple" | "all";
+  /**
+   * Harness/debug-only preview toggle for preserve-only features
+   * (charts, SmartArt, shapes, WordArt, VML rendered as typed atoms;
+   * the "N preserve-only features detected" banner; lock-callouts).
+   *
+   * MUST default to `false`. Consumer hosts MUST NOT hard-code `true` —
+   * this is a dev opt-in gated by the harness dev drawer's
+   * `debugMode && showUnsupportedObjectPreviews` AND-gate. Flipping the
+   * default or dropping the AND-gate is a regression that has landed
+   * three times (PRs #124, #131, #160); the invariant is locked by
+   * `test/ui/unsupported-previews-invariant.test.ts`.
+   *
+   * @default false
+   */
   showUnsupportedObjectPreviews?: boolean;
   showReviewPanel?: boolean;
   chromeVisibility?: Partial<WordReviewEditorChromeVisibility>;
@@ -3097,6 +3195,61 @@ export interface WordReviewEditorProps {
    * inline "Comments panel" icon appears only when a callback is wired.
    */
   onReviewSidebarComments?: () => void;
+  /**
+   * Optional: fires when the user invokes the Find shortcut
+   * (Ctrl/Cmd+F) with the editor focused. When a host wires this
+   * callback, the editor treats the shortcut as host-delegated and
+   * suppresses the browser's native Find flow; when omitted, the
+   * shortcut falls through to the browser default. The callback
+   * receives the current selection so the host can pre-populate its
+   * Find panel with the selected text.
+   *
+   * Capability id: `shortcut.find`. See
+   * `src/runtime/editor-surface/capabilities.ts` for the full
+   * capability contract.
+   */
+  onFindRequested?: (context: ShortcutDelegationContext) => void;
+  /**
+   * Optional: fires when the user invokes Print (Ctrl/Cmd+P) with
+   * the editor focused. When wired, the editor calls this callback
+   * and suppresses the browser's native print dialog — the host is
+   * expected to open its own print flow (e.g. a PDF export pipeline
+   * that preserves review chrome). When omitted, Ctrl/Cmd+P falls
+   * through to the browser's print dialog.
+   *
+   * Capability id: `shortcut.print`.
+   */
+  onPrintRequested?: () => void;
+  /**
+   * Optional: fires when the user invokes a zoom shortcut
+   * (Ctrl/Cmd+Plus, Ctrl/Cmd+Minus, Ctrl/Cmd+0). When wired, the
+   * editor suppresses the browser's native zoom and delegates the
+   * direction to the host. When omitted, the browser handles zoom
+   * as usual.
+   *
+   * Capability ids: `shortcut.zoom-in`, `shortcut.zoom-out`,
+   * `shortcut.zoom-reset`.
+   */
+  onZoomRequested?: (direction: "in" | "out" | "reset") => void;
+}
+
+/**
+ * Selection context handed to host-delegated shortcut callbacks
+ * (`onFindRequested`, future `onReplaceRequested`, etc.) so the host
+ * can pre-populate its own UI with the user's current selection.
+ *
+ * - `selectionText` is truncated to the first 500 characters —
+ *   Find / Replace panels typically only need a snippet, and unbounded
+ *   text would be wasteful for large selections.
+ * - `selectionRange` is the same shape exposed via the
+ *   `selection_changed` editor event, so hosts can reuse selection
+ *   plumbing.
+ */
+export interface ShortcutDelegationContext {
+  /** The user-visible text of the selection, truncated to 500 chars. Empty string when collapsed. */
+  selectionText: string;
+  /** The selection range as a SelectionSnapshot. */
+  selectionRange: SelectionSnapshot;
 }
 
 export interface WordReviewEditorChromeVisibility {

package/src/core/commands/formatting-commands.ts

@@ -624,7 +624,13 @@ function applyAlignment(
   return true;
 }
 
-function applyIndentation(paragraph: ParagraphNode, delta: -1 | 1): boolean {
+/**
+ * Adjusts the paragraph's indentation (or list level if the paragraph carries
+ * `numbering`) by ±INDENT_STEP_TWIPS. Mutates `paragraph` in place — caller
+ * must clone first if the source is shared. Returns `false` when no change
+ * occurred (already at the 0 / 8 bound, or no-op).
+ */
+export function applyIndentation(paragraph: ParagraphNode, delta: -1 | 1): boolean {
   if (paragraph.numbering) {
     const nextLevel = clamp(paragraph.numbering.level + delta, 0, 8);
     if (nextLevel === paragraph.numbering.level) {

package/src/core/commands/index.ts

@@ -31,6 +31,7 @@ import {
   insertHardBreak,
   insertTab,
   insertText,
+  outdentParagraphAtSelection,
   splitParagraph,
 } from "./text-commands.ts";
 import type { RevisionRecord as CanonicalRevisionRecord } from "../../model/canonical-document.ts";
@@ -128,6 +129,10 @@ export type EditorCommand =
       type: "text.insert-tab";
       origin?: CommandOrigin;
     }
+  | {
+      type: "text.outdent-tab";
+      origin?: CommandOrigin;
+    }
   | {
       type: "text.insert-hard-break";
       origin?: CommandOrigin;
@@ -367,7 +372,7 @@ export interface TransactionEffects {
   commentAdded?: { commentId: string; anchor: EditorAnchorProjection };
   commentResolved?: { commentId: string };
   commentReopened?: { commentId: string };
-  commentReplyAdded?: { commentId: string };
+  commentReplyAdded?: { commentId: string; entryId: string };
   commentBodyEdited?: { commentId: string };
   changeAccepted?: { changeId: string };
   changeRejected?: { changeId: string };
@@ -513,6 +518,26 @@ export function executeEditorCommand(
         insertTab(document, selection, context),
       );
     }
+    case "text.outdent-tab": {
+      // No suggesting-mode branch: outdent is a paragraph-format change, not a
+      // text-content change, so it bypasses the suggesting/track-changes pipeline.
+      // (If a tracked-changes test fails, copy the suggesting branch from
+      // text.insert-tab.)
+      //
+      // We use `buildDocumentReplaceTransaction` (not `applyTextCommand`) so the
+      // no-op cases — already at zero indent or list paragraph — skip the
+      // transaction entirely and do not bump revisionToken. This matches the
+      // pattern used by the formatting-indent path.
+      const result = outdentParagraphAtSelection(state.document, state.selection, {
+        timestamp: context.timestamp,
+      });
+      return buildDocumentReplaceTransaction(state, context, {
+        changed: result.changed,
+        document: result.document,
+        selection: result.selection,
+        mapping: result.mapping,
+      });
+    }
     case "text.insert-hard-break": {
       const suggestingResult = context.documentMode === "suggesting"
         ? applySuggestingInsertUnit(state, "hard_break", context)
@@ -785,7 +810,7 @@ export function executeEditorCommand(
         {
           historyBoundary: "push",
           markDirty: true,
-          effects: { commentReplyAdded: { commentId: command.commentId } },
+          effects: { commentReplyAdded: { commentId: command.commentId, entryId } },
         },
       );
     }

package/src/core/commands/text-commands.ts

@@ -23,6 +23,8 @@ import {
   resolveParagraphScope,
   type StructuralMutationResult,
 } from "./structural-helpers.ts";
+import { applyIndentation } from "./formatting-commands.ts";
+import { createEmptyMapping, type TransactionMapping } from "../selection/mapping.ts";
 import { createEditorSurfaceSnapshot } from "../../runtime/surface-projection.ts";
 
 export interface TextCommandContext {
@@ -197,6 +199,63 @@ export function insertTab(
   );
 }
 
+/**
+ * Reduce the active paragraph's left indent by one half-inch step (720 twips).
+ * Mirrors Word's Shift+Tab behavior on a non-list paragraph.
+ *
+ * Defensive list-check: if the paragraph carries `numbering`, this is a no-op —
+ * list-level changes are owned by the list-aware dispatcher in
+ * `src/runtime/edit-dispatch/list-aware-dispatch.ts`, which intercepts before
+ * we are called. The runtime command itself never mutates list level.
+ *
+ * No text positions change, so `mapping` is empty and the selection is preserved.
+ */
+export function outdentParagraphAtSelection(
+  document: CanonicalDocumentEnvelope,
+  selection: SelectionSnapshot,
+  context: TextCommandContext,
+): {
+  changed: boolean;
+  document: CanonicalDocumentEnvelope;
+  selection: SelectionSnapshot;
+  mapping: TransactionMapping;
+} {
+  const noop = {
+    changed: false,
+    document,
+    selection,
+    mapping: createEmptyMapping(),
+  };
+
+  const scope = resolveParagraphScope(document, selection);
+  if (!scope) {
+    return noop;
+  }
+
+  // Defensive: list paragraphs are owned by the list-aware dispatcher.
+  if (scope.paragraph.numbering) {
+    return noop;
+  }
+
+  // `resolveParagraphScope` already returns a cloned paragraph, so it is
+  // safe to mutate in place.
+  const changed = applyIndentation(scope.paragraph, -1);
+  if (!changed) {
+    return noop;
+  }
+
+  const nextDocument = replaceParagraphScope(document, scope, [scope.paragraph]);
+  return {
+    changed: true,
+    document: {
+      ...nextDocument,
+      updatedAt: context.timestamp,
+    },
+    selection,
+    mapping: createEmptyMapping(),
+  };
+}
+
 export function insertHardBreak(
   document: CanonicalDocumentEnvelope,
   selection: SelectionSnapshot,