@beyondwork/docx-react-component 1.0.42 → 1.0.45

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)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.42",
+  "version": "1.0.45",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
   "packageManager": "pnpm@10.30.3",
   "type": "module",
@@ -96,7 +96,7 @@
   "scripts": {
     "build": "tsup",
     "test": "bash scripts/run-workspace-tests.sh",
-    "test:repo": "node scripts/run-repo-tests.mjs core",
+    "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",
@@ -165,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": {
@@ -186,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",

package/src/api/editor-state-types.ts

@@ -0,0 +1,110 @@
+/**
+ * Editor-State Persistence Channel (schema 1.2).
+ *
+ * Makes the .docx act as a load/save API for editor-level overlay
+ * state (host annotations, workflow overlay, workflow metadata, work
+ * items, and future subsystems).  Storage policy per subsystem is
+ * host-controlled across three locations:
+ *
+ * - `"in-document"`  — full blob serialized into /customXml/item1.xml
+ * - `"rowstore"`     — doc carries a key reference; host persists the blob
+ * - `"key-only"`     — doc carries only a correlation key; host rehydrates
+ *
+ * See docs/plans/editor-state-persistence.md for the full design.  1.2
+ * extends schema 1.1 additively (unknown namespaces are preserved
+ * opaquely per existing forward-compat rules).
+ */
+export type EditorStateNamespace =
+  | "hostAnnotations"
+  | "workflowOverlay"
+  | "workflowMetadata"
+  | "workItems";
+
+export type EditorStateLocation = "in-document" | "rowstore" | "key-only";
+
+export type EditorStateResolveErrorMode = "block" | "empty" | "retain-last-known";
+
+/**
+ * Host-configured per-namespace persistence policy.  Default (when
+ * absent) is {location: "in-document", onResolveError: "block",
+ * debounceMs: 250}, which preserves current behavior.
+ */
+export interface EditorStatePolicyEntry {
+  location: EditorStateLocation;
+  /** Host-provided correlation key (e.g. review_session_id). Editor generates a UUID if absent. */
+  key?: string;
+  onResolveError?: EditorStateResolveErrorMode;
+  debounceMs?: number;
+}
+
+export type EditorStatePolicy = Partial<
+  Record<EditorStateNamespace, EditorStatePolicyEntry>
+>;
+
+/**
+ * Reference stored in the docx when the subsystem is backed by a
+ * host-owned store.  The editor never interprets entryKey — it round-
+ * trips verbatim via resolver + persister callbacks.
+ */
+export interface EditorStateStorageRef {
+  namespace: EditorStateNamespace;
+  location: Exclude<EditorStateLocation, "in-document">;
+  entryKey: string;
+  schemaVersion: string;
+}
+
+/**
+ * Typed blob the resolver returns and the persister accepts.
+ * `data` is the subsystem-specific payload (e.g. a HostAnnotationOverlay
+ * for the "hostAnnotations" namespace).  Use `schemaVersion` to pin the
+ * blob shape so older hosts don't silently load newer blobs.
+ */
+export interface EditorStateBlob {
+  namespace: EditorStateNamespace;
+  schemaVersion: string;
+  data: unknown;
+}
+
+/**
+ * Host-supplied pull-resolver.  Returns `null` when the entry key is
+ * unknown or revoked.  Matches the ScopeMetadataResolver undefined
+ * convention but allows null explicitly per the design doc §5 for
+ * symmetry with Promise<T | null> idioms.  Either is acceptable as
+ * "not found"; internal code normalizes.
+ */
+export type EditorStateResolver = (
+  namespace: EditorStateNamespace,
+  entryKey: string,
+) => Promise<EditorStateBlob | null>;
+
+/**
+ * Host-supplied persister.  Called after the editor's debounce window
+ * when a subsystem's state has changed under `rowstore` or `key-only`
+ * policy.  Must be idempotent within the debounce window.
+ */
+export type EditorStatePersister = (
+  namespace: EditorStateNamespace,
+  entryKey: string,
+  blob: EditorStateBlob,
+) => Promise<void>;
+
+export interface EditorStatePolicyMigration {
+  namespace: EditorStateNamespace;
+  from: EditorStateLocation;
+  to: EditorStateLocation;
+  key?: string;
+}
+
+export interface EditorStatePartLoadFailure {
+  namespace: EditorStateNamespace;
+  entryKey?: string;
+  error: Error;
+  fallback: "empty" | "retain-last-known";
+}
+
+export interface EditorStatePartPersistFailure {
+  namespace: EditorStateNamespace;
+  entryKey: string;
+  error: Error;
+  attemptCount: number;
+}

package/src/api/public-types.ts

@@ -9,6 +9,20 @@ import type {
   ScopeMetadataResolver,
   ScopeMetadataStorageRef,
 } from "./scope-metadata-resolver-types.ts";
+import type {
+  EditorStateNamespace,
+  EditorStateLocation,
+  EditorStateResolveErrorMode,
+  EditorStatePolicyEntry,
+  EditorStatePolicy,
+  EditorStateStorageRef,
+  EditorStateBlob,
+  EditorStateResolver,
+  EditorStatePersister,
+  EditorStatePolicyMigration,
+  EditorStatePartLoadFailure,
+  EditorStatePartPersistFailure,
+} from "./editor-state-types.ts";
 
 export type {
   MetadataPersistenceMode,
@@ -16,6 +30,20 @@ export type {
   ScopeMetadataResolver,
   ScopeMetadataStorageRef,
 };
+export type {
+  EditorStateNamespace,
+  EditorStateLocation,
+  EditorStateResolveErrorMode,
+  EditorStatePolicyEntry,
+  EditorStatePolicy,
+  EditorStateStorageRef,
+  EditorStateBlob,
+  EditorStateResolver,
+  EditorStatePersister,
+  EditorStatePolicyMigration,
+  EditorStatePartLoadFailure,
+  EditorStatePartPersistFailure,
+};
 
 export type { CanonicalParagraphFormatting, CanonicalRunFormatting };
 
@@ -34,6 +62,8 @@ export type {
   PublicPageRegion,
   PublicPageRegions,
   PublicPageSpan,
+  PublicRegionBlock,
+  PublicRegionKind,
   PublicResolvedPageStories,
   PublicResolvedParagraphFormatting,
   PublicResolvedRunFormatting,
@@ -753,7 +783,7 @@ export type SurfaceInlineSegment =
         textColor?: string;
       };
       hyperlinkHref?: string;
-      /** Cascaded run formatting for this text segment (docDefaults → paragraph style chain → character style → direct). Added in Task 11. TODO Task 15: wire up from resolveEffectiveRunFormatting in surface-projection. */
+      /** Cascaded run formatting for this text segment (docDefaults → paragraph style chain → character style → direct). Populated in `src/runtime/surface-projection.ts` via `resolveEffectiveRunFormatting`. Present only when the resolved cascade has at least one field. */
       resolvedRunFormatting?: CanonicalRunFormatting;
     }
   | {
@@ -787,6 +817,14 @@ export type SurfaceInlineSegment =
       blockedReasonCode?: "workflow_preserve_only" | "workflow_blocked_import";
       presentation?: "inline-chip" | "quiet-marker" | "text-box" | "checkbox";
       displayText?: string;
+      /**
+       * For chart/SmartArt/WordArt/VML opaque inlines, the media-catalog id
+       * of the preview bitmap extracted from `mc:Fallback` (when Word cached
+       * one). Resolved by the surface into a blob URL and rendered by the
+       * corresponding PM atom so reviewers see the chart picture instead of
+       * a text badge. Absent when the object has no cached fallback image.
+       */
+      previewMediaId?: string;
       state: "locked-preserve-only";
     }
   | {
@@ -943,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 {
@@ -959,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 =
@@ -1631,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;
@@ -2299,6 +2365,25 @@ export interface AutosaveConfig {
   debounceMs?: number;
 }
 
+/**
+ * Fired after a plain-text paste or drop has been dispatched through
+ * the runtime-owned input callbacks. Rich-text paste (HTML, Office
+ * clipboard) does NOT produce this event — those payloads still fire
+ * `onBlockedInput` with a distinguishing message.
+ *
+ * See `docs/plans/editor-paste-drop.md` for the full semantics.
+ */
+export interface WordReviewEditorPasteEvent {
+  type: "paste_applied";
+  documentId: string;
+  /** Count of segments dispatched across text + split + hard_break. */
+  segmentCount: number;
+  /** Total character count across all text segments in the payload. */
+  charCount: number;
+  /** Whether the event originated from a paste or a drop. */
+  source: "paste" | "drop";
+}
+
 export type WordReviewEditorEvent =
   | {
       type: "ready";
@@ -2442,6 +2527,7 @@ export type WordReviewEditorEvent =
       command: string;
       reasons: WorkflowBlockedCommandReason[];
     }
+  | WordReviewEditorPasteEvent
   | {
       /**
        * Scope card mode selector fired a mode change. Host relays to the
@@ -2520,8 +2606,82 @@ export type WordReviewEditorEvent =
         version?: number;
       } | null;
       defaultPolicy: MetadataConflictPolicy;
+    }
+  | {
+      /**
+       * Schema 1.2 — emitted when a keyed namespace fails to resolve
+       * during load.  Subsystem fallback behavior is per `onResolveError`
+       * policy.
+       */
+      type: "editor_state_part_load_failed";
+      documentId: string;
+      failure: EditorStatePartLoadFailure;
+    }
+  | {
+      /**
+       * Schema 1.2 — emitted when a debounced persist call fails.
+       * The editor retains the dirty snapshot for retry.
+       */
+      type: "editor_state_part_persist_failed";
+      documentId: string;
+      failure: EditorStatePartPersistFailure;
+    }
+  | {
+      /**
+       * Schema 1.2 — emitted when the saved location in a docx differs
+       * from the current host policy; the current policy wins and the
+       * next serialize honors it.
+       */
+      type: "editor_state_policy_migrated";
+      documentId: string;
+      migration: EditorStatePolicyMigration;
+    }
+  | {
+      /**
+       * Schema 1.2 — emitted when an unknown namespace is encountered
+       * in the payload (forward-compat warning; preserved opaquely).
+       */
+      type: "editor_state_unknown_namespace";
+      documentId: string;
+      namespace: string;
+    }
+  | {
+      /**
+       * Emitted once per load-pipeline stage when the staged loader is
+       * active. Purely observational — hosts can render a progress chip
+       * or ignore entirely. See `docs/plans/fastload.md` for the stage
+       * ordering contract.
+       */
+      type: "load-stage";
+      documentId: string;
+      stage: LoadStage;
+      durationMs: number;
+    }
+  | {
+      /**
+       * Emitted once sub-parts (headers, footers, footnotes, endnotes,
+       * theme, settings) have finished their post-ready idle hydration.
+       * Before this event fires, `canonicalDocument.subParts.*` may be
+       * empty arrays / defaults; after it fires, they carry the parsed
+       * values. Calling `ensureSubPartsHydrated` eagerly forces
+       * hydration synchronously.
+       */
+      type: "subparts-hydrated";
+      documentId: string;
     };
 
+/**
+ * Ordered list of stages emitted by the staged load pipeline. The
+ * skeleton-ready stage corresponds to the `ready` event firing.
+ */
+export type LoadStage =
+  | "opc"
+  | "body"
+  | "styles-numbering-comments"
+  | "skeleton-ready"
+  | "subparts"
+  | "compatibility";
+
 export interface LoadResult {
   source?: ExternalDocumentSource;
 }
@@ -2561,11 +2721,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 {
@@ -2580,11 +2779,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;
@@ -2767,6 +2966,35 @@ export interface WordReviewEditorRef {
    * registered.
    */
   convertScopesToExternal(scopeIds: string[]): Promise<void>;
+  /**
+   * Schema 1.2 — editor-state persistence channel.  Configures which
+   * subsystems persist in-document / rowstore / key-only.  Each call
+   * merges into the current policy map.  Mismatched locations with an
+   * already-loaded docx fire `editor_state_policy_migrated` and
+   * schedule the next serialize to honor the new location.
+   */
+  configureEditorStatePolicy(policy: EditorStatePolicy): void;
+  /**
+   * Register the host's pull-resolver.  Required before the editor
+   * loads a 1.2 docx whose policy includes any keyed location.
+   */
+  registerEditorStateResolver(resolver: EditorStateResolver): void;
+  /**
+   * Register the host's persister.  Required before any subsystem
+   * mutation under keyed policy fires a debounced persist.
+   */
+  registerEditorStatePersister(persister: EditorStatePersister): void;
+  /**
+   * Return the entry key currently associated with a namespace under
+   * keyed policy, or undefined when the namespace is in-document /
+   * key not yet assigned.
+   */
+  getEditorStateKey(namespace: EditorStateNamespace): string | undefined;
+  /**
+   * Re-attempt any persists that failed since the last successful
+   * write.  Pass a namespace to scope the retry; omit to retry all.
+   */
+  retryPendingPersist(namespace?: EditorStateNamespace): Promise<void>;
   setHostAnnotationOverlay(overlay: HostAnnotationOverlay): void;
   clearHostAnnotationOverlay(): void;
   getHostAnnotationSnapshot(): HostAnnotationSnapshot;
@@ -2866,6 +3094,38 @@ export interface WordReviewEditorProps {
   currentUser: EditorUser;
   ydoc?: import('yjs').Doc;
   awareness?: import("y-protocols/awareness").Awareness;
+  /**
+   * Optional collab session built via `createCollabSession(...)`. When
+   * set, the `"collab"` chrome preset mounts the top nav (presence
+   * strip, role + audience chips, tamper banner, negotiation action
+   * bar, send-to-supplier button). P9a–f components are pure
+   * presentational; this prop is what wires them to live state. Pass
+   * `undefined` to keep the chrome in non-collab mode even when
+   * `chromePreset === "collab"`.
+   */
+  collabSession?: import("../runtime/collab-session.ts").CollabSession;
+  /**
+   * Transport status signal for the presence strip + role chip (P9b /
+   * P9c). Optional — defaults to "offline" when omitted.
+   */
+  collabTransportStatus?: "connected" | "syncing" | "offline";
+  /**
+   * Identifier for the currently-focused comment, used by the collab
+   * top nav's audience chip + negotiation action bar (P9c / P9e). The
+   * host derives this from its own selection / rail-focus signal.
+   */
+  activeCommentId?: string;
+  /**
+   * Baseline metadata for the send-to-supplier flow (P9f). Required
+   * to enable the button; when omitted, the button stays present but
+   * the confirmation modal becomes a no-op pass-through.
+   */
+  collabSendBaseline?: {
+    originDocumentId: string;
+    originPayloadId: string;
+    originContentHash: string;
+    payloadXml: string;
+  };
   initialDocx?: Uint8Array | ArrayBuffer;
   initialSessionState?: EditorSessionState;
   initialSnapshot?: PersistedEditorSnapshot;
@@ -2880,6 +3140,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>;
@@ -2904,6 +3178,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) {