@beyondwork/docx-react-component 1.0.52 → 1.0.54

package/package.json

@@ -1,9 +1,8 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.52",
+  "version": "1.0.54",
   "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"
@@ -93,35 +92,6 @@
     "./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",
@@ -205,14 +175,35 @@
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.30"
   },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "esbuild",
-      "sharp"
-    ],
-    "overrides": {
-      "react": "19.2.4",
-      "react-dom": "19.2.4"
-    }
+  "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",
+    "generate:token-reference": "node scripts/generate-token-reference.mjs",
+    "check:token-reference": "node scripts/generate-token-reference.mjs --check",
+    "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"
   }
 }

package/src/api/public-types.ts

@@ -892,6 +892,13 @@ export interface SurfaceTableCellSnapshot {
   borderRight?: string | null;
   borderBottom?: string | null;
   borderLeft?: string | null;
+  /**
+   * R3.a Phase 2: per-cell text-flow direction copied from
+   * `TableCellNode.textDirection`. The node-view maps these to CSS
+   * `writing-mode` (`tbRl` → `vertical-rl`, `btLr` → `vertical-lr`, `lrTb` →
+   * unset / horizontal default). Cells with no direction stay horizontal.
+   */
+  textDirection?: "lrTb" | "tbRl" | "btLr" | null;
   /**
    * R2a: space-joined CSS class names from the resolved table-style conditional
    * regions (e.g. "band-firstRow band-band1Horz"). Consumers apply these to the
@@ -985,6 +992,31 @@ export type SurfaceBlockSnapshot =
         noHBand?: boolean;
         noVBand?: boolean;
       };
+      /**
+       * R3.a Phase 2: resolved table-level properties (width / layoutMode /
+       * cellSpacing / borders) projected from the canonical TableNode + its
+       * resolved table-style cascade. Borders carry the typed `BorderSpec`
+       * per side; the node-view converts top/right/bottom/left to CSS
+       * shorthand. insideH / insideV are stamped here for round-trip and
+       * future renderer use, but at render time their visual effect is
+       * realized through per-cell borders on the cell snapshot (CSS has no
+       * direct "table-inside-border" property).
+       */
+      tableResolved?: {
+        width?: number | null;
+        widthType?: "auto" | "dxa" | "pct" | "nil" | null;
+        layoutMode?: "fixed" | "autofit" | null;
+        cellSpacing?: number | null;
+        cellSpacingType?: "auto" | "dxa" | "pct" | "nil" | null;
+        borders?: {
+          top?: { value?: string; size?: number; space?: number; color?: string } | null;
+          right?: { value?: string; size?: number; space?: number; color?: string } | null;
+          bottom?: { value?: string; size?: number; space?: number; color?: string } | null;
+          left?: { value?: string; size?: number; space?: number; color?: string } | null;
+          insideH?: { value?: string; size?: number; space?: number; color?: string } | null;
+          insideV?: { value?: string; size?: number; space?: number; color?: string } | null;
+        } | null;
+      };
       rows: SurfaceTableRowSnapshot[];
     }
   | {
@@ -3026,12 +3058,16 @@ export interface WordReviewEditorRef {
   setWorkflowOverlay(overlay: WorkflowOverlay): void;
   clearWorkflowOverlay(): void;
   /**
-   * Read the current runtime-backed `WorkflowOverlay`, or `null` when no
-   * overlay is active.  Hosts use this for read-modify-write flows against
-   * `setWorkflowOverlay(...)` — notably to preserve engine-authored scopes
-   * minted via `addScope(...)` when updating candidates / work items.
-   * Returns a defensive clone; mutating the returned object does not affect
-   * runtime state.
+   * Return a structural clone of the currently-registered workflow
+   * overlay, or `null` when no overlay has been set (or
+   * `clearWorkflowOverlay` has been called). Intended for the canonical
+   * host read-before-write pattern — read current, merge host-owned
+   * fields (e.g. `candidates`), write back via `setWorkflowOverlay`
+   * without clobbering engine-authored `scopes`, `workItems`, or the
+   * overlay-level `metadataPersistence` default. `setWorkflowOverlay`
+   * replaces the overlay wholesale; passing `scopes: []` will drop
+   * every scope registered via `addScope` and cause subsequent
+   * `replaceText` calls to block with `workflow_comment_only`.
    */
   getWorkflowOverlay(): WorkflowOverlay | null;
   setSharedWorkflowState(state: SharedWorkflowState | null): void;
@@ -3272,7 +3308,31 @@ export interface WordReviewEditorProps {
   suggestionsEnabled?: boolean;
   chromePreset?: WordReviewEditorChromePreset;
   chromeOptions?: Partial<WordReviewEditorChromeOptions>;
-  markupDisplay?: "clean" | "simple" | "all";
+  /**
+   * Controls how tracked changes and comments render.  Accepts Word's
+   * 4-mode grammar (`"all-markup" | "simple-markup" | "no-markup" | "original"`)
+   * or the legacy triple (`"all" | "simple" | "clean"`), which maps 1:1
+   * onto the first three canonical names.  `"original"` is new in 6d.N2:
+   * insertions are hidden, deletions render as plain body text so the
+   * reviewer sees the pre-change state.
+   */
+  markupDisplay?:
+    | "all-markup"
+    | "simple-markup"
+    | "no-markup"
+    | "original"
+    | "clean"
+    | "simple"
+    | "all";
+  /**
+   * L6d.N2 — invoked when the user picks a different display mode from
+   * the in-chrome selector.  Values are always emitted in the canonical
+   * Word grammar (`"all-markup" | "simple-markup" | "no-markup" | "original"`),
+   * not the legacy aliases.
+   */
+  onMarkupDisplayChange?: (
+    value: "all-markup" | "simple-markup" | "no-markup" | "original",
+  ) => void;
   /**
    * @internal HARNESS-ONLY debug-ports token.
    *

package/src/io/chart-preview-resolver.ts

@@ -138,6 +138,47 @@ export async function resolveChartPreviewsForDocument(
   return applyResolutions(doc, successful);
 }
 
+/**
+ * C3b — Phase A/B deferred chart preview resolution.
+ *
+ * Phase A (cheap, synchronous): check whether there are any unresolved
+ * chart_preview nodes. If not, return immediately without scheduling
+ * anything. The collect walk is O(paragraphs) and takes ~0 ms.
+ *
+ * Phase B (deferred): schedule the actual `renderChartPreview` calls
+ * outside the critical load path via requestIdleCallback (browser) or
+ * setTimeout(0) (Node / SSR). Fires `onReady` with the resolved
+ * CanonicalDocument when all charts complete.
+ *
+ * The caller (loadDocxEditorSessionAsync) returns the session without
+ * chart previews. When `onReady` fires, the consumer can update the
+ * runtime's media catalog (e.g. via a follow-up `hydrateChartPreviews`
+ * call, or by accepting the updated CanonicalDocument into a new
+ * progressive render). Expected win: 30–80 ms removed from the warm
+ * cold-open path on extra-large docs with ~12 charts.
+ */
+export function scheduleChartPreviewResolution(
+  doc: CanonicalDocument,
+  pkg: OpcPackage,
+  adapter: EditorHostAdapter | undefined,
+  onReady: (resolved: CanonicalDocument) => void,
+): void {
+  if (!adapter?.renderChartPreview) return;
+  // Phase A: fast collect — avoids scheduling idle work when there are no
+  // unresolved charts (the common case for most non-chart documents).
+  const pending = collectUnresolvedChartPreviews(doc, pkg);
+  if (pending.length === 0) return;
+
+  const schedule =
+    typeof requestIdleCallback !== "undefined"
+      ? (fn: () => void) => { requestIdleCallback(fn); }
+      : (fn: () => void) => { setTimeout(fn, 0); };
+
+  schedule(() => {
+    void resolveChartPreviewsForDocument(doc, pkg, adapter).then(onReady);
+  });
+}
+
 /**
  * Walk the whole content tree and yield one PendingResolution per
  * chart_preview node that (a) has no previewMediaId yet and (b) can

package/src/io/docx-session.ts

@@ -3,6 +3,7 @@ import type {
   EditorError,
   EditorHostAdapter,
   EditorSessionState,
+  EditorSurfaceSnapshot,
   EditorWarning as PublicEditorWarning,
   EditorAnchorProjection as PublicEditorAnchorProjection,
   ExportDocxOptions,
@@ -26,7 +27,13 @@ import type {
   RevisionRecord as RuntimeRevisionRecord,
   EditorWarning as InternalEditorWarning,
 } from "../core/state/editor-state.ts";
-import { createCanonicalDocumentId } from "../core/state/editor-state.ts";
+import {
+  createCanonicalDocumentId,
+  createDefaultCanonicalDocument,
+  createSelectionSnapshot,
+} from "../core/state/editor-state.ts";
+import { createEditorSurfaceSnapshot } from "../runtime/surface-projection.ts";
+import { MAIN_STORY_TARGET } from "../core/selection/mapping.ts";
 import {
   createDetachedAnchor,
   storyTargetsEqual,
@@ -44,7 +51,7 @@ import {
   normalizeParsedTextDocument,
   normalizeParsedTextDocumentAsync,
 } from "./normalize/normalize-text.ts";
-import { createChartPartLookup, resolveChartPreviewsForDocument } from "./chart-preview-resolver.ts";
+import { createChartPartLookup, resolveChartPreviewsForDocument, scheduleChartPreviewResolution } from "./chart-preview-resolver.ts";
 import { type LoadScheduler } from "./load-scheduler.ts";
 import type { CacheEnvelope } from "../runtime/prerender/cache-envelope.ts";
 import {
@@ -60,13 +67,12 @@ import {
   getDocumentBackedWorkflowMetadata,
   parseWorkflowPayloadEnvelopeFromPackage,
   resolvePayloadPartPath,
+  resolveWorkflowPayloadPartPaths,
   WORKFLOW_PAYLOAD_CONTENT_TYPE,
   WORKFLOW_PAYLOAD_CUSTOM_PROPS_CONTENT_TYPE,
   WORKFLOW_PAYLOAD_CUSTOM_PROPS_PART_PATH,
   WORKFLOW_PAYLOAD_CUSTOM_PROPS_RELATIONSHIP_TYPE,
   WORKFLOW_PAYLOAD_ITEM_PROPS_CONTENT_TYPE,
-  WORKFLOW_PAYLOAD_ITEM_PROPS_PART_PATH,
-  WORKFLOW_PAYLOAD_PART_PATH,
   WORKFLOW_PAYLOAD_RELATIONSHIP_TYPE,
 } from "./ooxml/workflow-payload.ts";
 import {
@@ -122,6 +128,7 @@ import type {
   SubPartsCatalog,
 } from "../model/canonical-document.ts";
 import { createCanonicalDocumentSignature } from "../model/canonical-document.ts";
+import type { CanonicalDocument } from "../model/canonical-document.ts";
 import type {
   CommentImportDiagnostic,
   ImportedCommentDefinition,
@@ -959,6 +966,53 @@ export interface LoadDocxEditorSessionAsyncOptions extends LoadDocxEditorSession
    * path because their outputs are required by downstream consumers.
    */
   laycacheEnvelope?: CacheEnvelope;
+  /**
+   * L7 Phase 2 Finale C2 — progressive initial mount. When supplied, the
+   * async loader fires this callback exactly once, after the body stage
+   * completes but before styles / sub-parts / compatibility / snapshot
+   * assembly, with a viewport-windowed `EditorSurfaceSnapshot`. The
+   * callback lets UI consumers show the first page's text before the
+   * rest of the load finishes, measurably shrinking perceived cold-open.
+   *
+   * The progressive surface is synthesized from a provisional
+   * `CanonicalDocumentEnvelope`: `content` is the normalized body; all
+   * other catalogs (styles, numbering, media, review, preservation) are
+   * empty. Viewport blocks render live; blocks beyond the viewport
+   * render as placeholders via the existing `cullBuild` flag. Consumers
+   * must treat the progressive surface as provisional — the final
+   * `LoadedDocxEditorSession` (returned from the same `await`) carries
+   * the real styled envelope.
+   *
+   * The callback receives `blocksRealized` (the viewport window size)
+   * and `blocksTotal` (total block count at body-stage time) so the
+   * consumer can size its viewport-commit telemetry.
+   *
+   * Optional. When absent, the async loader does not perform the
+   * provisional-envelope synthesis — no cold-path regression for
+   * consumers that do not opt in.
+   *
+   * Omitted on the Plan B short-circuit path (laycacheEnvelope !== undefined):
+   * the short-circuit is already fast enough that a progressive pre-commit
+   * adds more overhead than it saves.
+   */
+  onProgressiveSnapshot?: (partial: {
+    surface: EditorSurfaceSnapshot;
+    phase: "viewport";
+    blocksRealized: number;
+    blocksTotal: number;
+  }) => void;
+  /**
+   * C3b — deferred chart preview resolution. When supplied, chart preview
+   * rendering (`renderChartPreview()` calls) is removed from the critical
+   * load path: the session returns without chart previews, and this
+   * callback fires later (via requestIdleCallback / setTimeout) with the
+   * CanonicalDocument that has all chart previews resolved. Expected win:
+   * 30–80 ms on extra-large warm-path docs with ~12 charts.
+   *
+   * Consumers that need chart previews on first render should not supply
+   * this callback — the blocking path remains available by omitting it.
+   */
+  onChartPreviewsReady?: (resolvedDoc: CanonicalDocument) => void;
 }
 
 /**
@@ -979,6 +1033,23 @@ export interface LoadDocxEditorSessionAsyncOptions extends LoadDocxEditorSession
  * and SSR. The DOM boundary in `editor-runtime-boundary.ts` calls this
  * async path so the browser can paint the skeleton mid-parse.
  */
+
+/**
+ * L7 Phase 2 Finale C2 — progressive initial mount viewport window size.
+ *
+ * Sized to cover the first page of a typical paginated document (~20
+ * body blocks = ~1 page on CCEP-scale templates at default margins). The
+ * window is intentionally small so the provisional-envelope synthesis +
+ * surface projection stays under ~30 ms — making `firstViewportCommit`
+ * significantly faster than the full load.
+ *
+ * Blocks beyond this window render as `placeholder-culled` entries via
+ * Phase 2.9's cullBuild flag (auto-derived from `!isInViewport`) — they
+ * preserve `from`/`to` offsets for selection stability while costing ~0
+ * style-cascade work.
+ */
+const PROGRESSIVE_VIEWPORT_BLOCKS = 20;
+
 export async function loadDocxEditorSessionAsync(
   options: LoadDocxEditorSessionAsyncOptions,
 ): Promise<LoadedDocxEditorSession> {
@@ -1090,18 +1161,45 @@ export async function loadDocxEditorSessionAsync(
       const protectionSnapshot = buildProtectionSnapshot(documentProtection, []);
 
       // Chart previews (`previewMediaId` is host-dependent) aren't cached
-      // in the envelope, so we still resolve them on the short-circuit.
-      const documentWithChartPreviews = (await resolveChartPreviewsForDocument(
-        canonicalDocument,
-        sourcePackage,
-        options.hostAdapter,
-      )) as CanonicalDocumentEnvelope;
+      // in the envelope. C3b: when onChartPreviewsReady is provided, defer
+      // resolution out of the critical path. Otherwise block (legacy behavior).
+      let documentWithChartPreviews: CanonicalDocumentEnvelope;
+      if (options.onChartPreviewsReady) {
+        scheduleChartPreviewResolution(
+          canonicalDocument,
+          sourcePackage,
+          options.hostAdapter,
+          options.onChartPreviewsReady,
+        );
+        documentWithChartPreviews = canonicalDocument as CanonicalDocumentEnvelope;
+      } else {
+        documentWithChartPreviews = (await resolveChartPreviewsForDocument(
+          canonicalDocument,
+          sourcePackage,
+          options.hostAdapter,
+        )) as CanonicalDocumentEnvelope;
+      }
 
       const timestamp = new Date().toISOString();
-      const compatibility = buildCompatibilityReport({
-        document: documentWithChartPreviews,
-        generatedAt: timestamp,
-      });
+      // Phase 2 Finale C3: skip `buildCompatibilityReport` (60–100 ms on
+      // extra-large) when the envelope carries a pre-computed report.
+      // Pure-function determinism of the report is enforced by
+      // `canonicalDocumentHash` (5th input to `deriveCacheKey`): any
+      // change to the canonical doc flips the hash and rejects the
+      // envelope on load.
+      //
+      // The cached report's `generatedAt` is a fixed sentinel
+      // (`CACHE_NORMALIZED_GENERATED_AT`) for envelope byte-identity.
+      // Swap it for the live ISO8601 timestamp here because downstream
+      // `validatePersistedEditorSnapshot` requires
+      // `$.compatibility.generatedAt` to be ISO 8601.
+      const cachedReport = options.laycacheEnvelope?.compatibilityReport;
+      const compatibility = cachedReport
+        ? { ...cachedReport, generatedAt: timestamp }
+        : buildCompatibilityReport({
+            document: documentWithChartPreviews,
+            generatedAt: timestamp,
+          });
       await scheduler.yield();
 
       const snapshot = createImportedSnapshot({
@@ -1225,6 +1323,64 @@ export async function loadDocxEditorSessionAsync(
     );
     stages.emit("body");
     await scheduler.yield();
+
+    // L7 Phase 2 Finale C2 — progressive initial mount.
+    //
+    // Fire `onProgressiveSnapshot` exactly once, after the body stage and
+    // its post-yield. At this point `normalizedDocument.content` carries
+    // the full block tree with per-block runProperties already resolved
+    // during `normalizeParsedTextDocumentAsync`. We synthesize a
+    // throw-away `CanonicalDocumentEnvelope` using the normalized content
+    // + empty style/review/preservation catalogs, then project a
+    // viewport-windowed `EditorSurfaceSnapshot` (first `PROGRESSIVE_VIEWPORT_BLOCKS`
+    // blocks real, rest as culled placeholders via the Phase 2.9 flag).
+    //
+    // The bench's measured signal: time from `loadDocxEditorSessionAsync`
+    // entry to this callback's fire is `firstViewportCommitMs` — the
+    // metric C2 gates on.
+    //
+    // Skipped on the Plan B short-circuit: `laycacheEnvelope !== undefined`
+    // already completes ~376 ms faster than cold — adding a progressive
+    // synthesis on top costs more than it saves. The short-circuit path
+    // returns the real snapshot fast enough.
+    if (
+      options.onProgressiveSnapshot !== undefined &&
+      options.laycacheEnvelope === undefined
+    ) {
+      const provisionalDoc: CanonicalDocumentEnvelope = {
+        ...createDefaultCanonicalDocument(
+          options.documentId,
+          new Date().toISOString(),
+        ),
+        content: normalizedDocument.content,
+      };
+      const blocksTotal = normalizedDocument.content.children.length;
+      const blocksRealized = Math.min(
+        PROGRESSIVE_VIEWPORT_BLOCKS,
+        blocksTotal,
+      );
+      const progressiveSurface = createEditorSurfaceSnapshot(
+        provisionalDoc,
+        createSelectionSnapshot(0, 0),
+        MAIN_STORY_TARGET,
+        blocksRealized < blocksTotal
+          ? { viewportBlockRange: { start: 0, end: blocksRealized } }
+          : undefined,
+      );
+      try {
+        options.onProgressiveSnapshot({
+          surface: progressiveSurface,
+          phase: "viewport",
+          blocksRealized,
+          blocksTotal,
+        });
+      } catch {
+        // A throwing consumer must not abort the load. Progressive is
+        // a best-effort optimization; errors on the callback side
+        // silently fall through to the normal full-commit path.
+      }
+    }
+
     const commentsPartPath = resolveCommentsPartPath(
       sourcePackage,
       mainDocumentPath,
@@ -1579,11 +1735,24 @@ export async function loadDocxEditorSessionAsync(
     // chart_preview nodes inline so the first snapshot already carries the
     // synthesized `previewMediaId`. Fallback-safe: returning null or throwing
     // is per-chart — the typed badge renders as if the adapter weren't set.
-    const document = (await resolveChartPreviewsForDocument(
-      importedDocument,
-      sourcePackage,
-      options.hostAdapter,
-    )) as CanonicalDocumentEnvelope;
+    // C3b: when onChartPreviewsReady is provided, defer resolution out of
+    // the critical path (same pattern as the short-circuit branch above).
+    let document: CanonicalDocumentEnvelope;
+    if (options.onChartPreviewsReady) {
+      scheduleChartPreviewResolution(
+        importedDocument,
+        sourcePackage,
+        options.hostAdapter,
+        options.onChartPreviewsReady,
+      );
+      document = importedDocument as CanonicalDocumentEnvelope;
+    } else {
+      document = (await resolveChartPreviewsForDocument(
+        importedDocument,
+        sourcePackage,
+        options.hostAdapter,
+      )) as CanonicalDocumentEnvelope;
+    }
     const compatibility = buildCompatibilityReport({
       document,
       generatedAt: timestamp,
@@ -1935,13 +2104,20 @@ function exportDocxEditorSession(
   const hasSettingsSurface =
     Boolean(state.sourceSettingsPartPath) ||
     exportedSubParts?.settings !== undefined;
+  const resolvedWorkflowPayloadPartPaths = resolveWorkflowPayloadPartPaths(
+    state.sourcePackage,
+    sessionState.documentId,
+  );
+  const internalEditorState = (
+    options as { _editorState?: import("./ooxml/workflow-payload.ts").EditorStatePayload } | undefined
+  )?._editorState;
 
   const exportSession = createExportSession(state.sourcePackage, [
     state.sourceDocumentPartPath,
     APP_PROPERTIES_PART_PATH,
     CORE_PROPERTIES_PART_PATH,
-    WORKFLOW_PAYLOAD_PART_PATH,
-    WORKFLOW_PAYLOAD_ITEM_PROPS_PART_PATH,
+    resolvedWorkflowPayloadPartPaths.payloadPartPath,
+    resolvedWorkflowPayloadPartPaths.itemPropsPartPath,
     WORKFLOW_PAYLOAD_CUSTOM_PROPS_PART_PATH,
     numberingPartPath,
     commentsPartPath,
@@ -2190,8 +2366,14 @@ function exportDocxEditorSession(
 
   ensureHostMetadataParts(exportSession, state.sourcePackage, currentDocument);
   // Schema 1.2: pass through editorState payload collected by the runtime channel.
-  const internalEditorState = (options as { _editorState?: import("./ooxml/workflow-payload.ts").EditorStatePayload } | undefined)?._editorState;
-  ensureWorkflowPayloadParts(exportSession, sessionState, currentDocument, state.sourcePackage, internalEditorState);
+  ensureWorkflowPayloadParts(
+    exportSession,
+    sessionState,
+    currentDocument,
+    state.sourcePackage,
+    resolvedWorkflowPayloadPartPaths,
+    internalEditorState,
+  );
 
   return {
     bytes: exportSession.serialize(),
@@ -3917,6 +4099,10 @@ function ensureWorkflowPayloadParts(
   sessionState: EditorSessionState,
   document: CanonicalDocumentEnvelope,
   sourcePackage: OpcPackage,
+  resolvedPartPaths: {
+    payloadPartPath: string;
+    itemPropsPartPath: string;
+  },
   editorState?: import("./ooxml/workflow-payload.ts").EditorStatePayload,
 ): void {
   const payloadParts = buildWorkflowPayloadParts({
@@ -3932,6 +4118,14 @@ function ensureWorkflowPayloadParts(
   if (!payloadParts) {
     return;
   }
+  if (
+    payloadParts.payloadPartPath !== resolvedPartPaths.payloadPartPath ||
+    payloadParts.itemPropsPartPath !== resolvedPartPaths.itemPropsPartPath
+  ) {
+    throw new Error(
+      "Workflow payload export resolved inconsistent customXml paths; export session ownership no longer matches payload serialization.",
+    );
+  }
 
   const payloadPart = sourcePackage.parts.get(payloadParts.payloadPartPath);
   const itemPropsPart = sourcePackage.parts.get(payloadParts.itemPropsPartPath);

package/src/runtime/collab/checkpoint-store.ts

@@ -30,7 +30,7 @@ export interface Checkpoint {
   authorClientId: number;
 }
 
-const CHECKPOINTS_KEY = "checkpoints";
+export const CHECKPOINTS_KEY = "checkpoints";
 
 export interface CreateCheckpointStoreOptions {
   ydoc: Y.Doc;

package/src/runtime/collab/event-types.ts

@@ -141,6 +141,10 @@ export const BROADCAST_COMMAND_TYPES: ReadonlySet<EditorCommand["type"]> = new S
   "section.set-header-footer-link",
   "content.insert-page-break",
   "content.insert-table",
+  // C1: Shift+Tab list/paragraph de-indent — produces a document mutation, must broadcast
+  "text.outdent-tab",
+  // C2: host insertFragment() API — routes through executeEditorCommand same as other mutations
+  "fragment.insert",
 ]);
 
 /**