@beyondwork/docx-react-component 1.0.52 → 1.0.53

package/package.json

@@ -1,9 +1,8 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.52",
+  "version": "1.0.53",
   "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[];
     }
   | {

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 {
@@ -122,6 +129,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 +967,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 +1034,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 +1162,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 +1324,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 +1736,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,

package/src/runtime/collab/runtime-collab-sync.ts

@@ -11,6 +11,7 @@ import type { BlockNode } from "../../model/canonical-document.ts";
 import type {
   CommandAppliedMeta,
   DocumentRuntime,
+  RemoteCommandEnvelope,
   Unsubscribe,
 } from "../document-runtime.ts";
 import {
@@ -200,6 +201,30 @@ export interface RuntimeCollabSyncOptions {
    * - `"observer"`: all writes refused with `collab_observer_readonly`.
    */
   role?: "author" | "reviewer" | "observer";
+  /**
+   * R1 — coalesce inbound remote-replay events into one commit per
+   * animation frame. When `true` (default), N events arriving within a
+   * single rAF tick (or `setTimeout(0)` in non-DOM contexts) drain via
+   * one `runtime.applyRemoteCommandBatch(...)` call → one
+   * `refreshRenderSnapshot` / one `notify`. Observer semantics change:
+   * subscribers see one `DocumentRuntimeEvent` per burst rather than
+   * one per event. Hosts that depend on per-event semantics (rare —
+   * counted-event tests, granular per-comment-add observers) opt out
+   * with `false`. The whole batch is atomic: any per-command effect
+   * collision falls back to per-event replay automatically.
+   *
+   * Defaults to `true` in both DOM and Node contexts so tests exercise
+   * the coalesced path without ceremony.
+   */
+  coalesceRemoteReplay?: boolean;
+  /**
+   * R1 hook point for R3 idle-priority plumbing. Invoked once per
+   * scheduled drain (NOT per queued event). R3's future implementation
+   * will use this to abort any in-flight idle prerender task on
+   * `src/io/load-scheduler.ts` so the upcoming commit doesn't compete
+   * with idle work. Safe to omit; R1 functions identically without it.
+   */
+  onRemoteReplayScheduled?: () => void;
 }
 
 export interface RuntimeCollabSyncHandle {
@@ -268,6 +293,48 @@ export function createRuntimeCollabSync(
   let readOnly = false;
   let baseDocFingerprint: string | null = null;
 
+  // R1 — coalesced remote-replay scheduler. Default: ON in both DOM and
+  // Node contexts. Falls back to setTimeout(0) when requestAnimationFrame
+  // is missing so tests and non-DOM hosts exercise the same drain path.
+  const useCoalescing = options.coalesceRemoteReplay !== false;
+  const replayQueue: CommandEvent[] = [];
+  let rafHandle: number | null = null;
+  let timeoutHandle: ReturnType<typeof setTimeout> | null = null;
+
+  function scheduleDrain(): void {
+    if (rafHandle !== null || timeoutHandle !== null) return;
+    options.onRemoteReplayScheduled?.();
+    if (typeof requestAnimationFrame === "function") {
+      rafHandle = requestAnimationFrame(() => {
+        rafHandle = null;
+        drainReplayQueue();
+      });
+    } else {
+      timeoutHandle = setTimeout(() => {
+        timeoutHandle = null;
+        drainReplayQueue();
+      }, 0);
+    }
+  }
+
+  function drainReplayQueue(): void {
+    if (replayQueue.length === 0) return;
+    const batch = replayQueue.splice(0, replayQueue.length);
+    const envelopes = batch.map(eventToEnvelope);
+    runtime.applyRemoteCommandBatch(envelopes);
+  }
+
+  function cancelPendingDrain(): void {
+    if (rafHandle !== null) {
+      if (typeof cancelAnimationFrame === "function") cancelAnimationFrame(rafHandle);
+      rafHandle = null;
+    }
+    if (timeoutHandle !== null) {
+      clearTimeout(timeoutHandle);
+      timeoutHandle = null;
+    }
+  }
+
   // Events emitted before any subscriber exists are buffered and flushed
   // to the first subscriber. This lets hosts react to the attach-path
   // base-doc mismatch and schema-version mismatch for pre-existing
@@ -494,6 +561,10 @@ export function createRuntimeCollabSync(
 
   return {
     destroy() {
+      // R1 — drain any queued replay events synchronously before tearing
+      // down so callers don't lose remote events on an early unmount.
+      cancelPendingDrain();
+      drainReplayQueue();
       unsubscribeCommandApplied();
       yEvents.unobserve(onYEventsChange);
       yMeta.unobserve(checkFingerprintAgainstMeta);
@@ -607,19 +678,29 @@ export function createRuntimeCollabSync(
     return true;
   }
 
-  function applyEventToRuntime(event: CommandEvent): void {
-    runtime.applyRemoteCommand(
-      event.command,
-      {
+  function eventToEnvelope(event: CommandEvent): RemoteCommandEnvelope {
+    return {
+      command: event.command,
+      context: {
         timestamp: event.timestamp,
         documentMode: event.context.documentMode,
         defaultAuthorId: event.context.defaultAuthorId ?? event.authorId,
       },
-      {
+      meta: {
         preSelection: event.context.preSelection,
         activeStory: event.context.activeStory,
       },
-    );
+    };
+  }
+
+  function applyEventToRuntime(event: CommandEvent): void {
+    if (useCoalescing) {
+      replayQueue.push(event);
+      scheduleDrain();
+      return;
+    }
+    const env = eventToEnvelope(event);
+    runtime.applyRemoteCommand(env.command, env.context, env.meta);
   }
 }