@beyondwork/docx-react-component 1.0.36 → 1.0.38

package/src/runtime/document-runtime.ts

@@ -47,12 +47,14 @@ import type {
   RuntimeContextAnalyticsQuery,
   RuntimeContextAnalyticsSnapshot,
   RuntimeRenderSnapshot,
+  ScopeTagTouch,
   SelectionSnapshot,
   SnapshotRefreshHints,
   SuggestionsSnapshot,
   SurfaceBlockSnapshot,
   SurfaceInlineSegment,
   StoryTextStreamSnapshot,
+  TextCommandAck,
   TocSnapshot,
   StyleCatalogSnapshot,
   TocRefreshOptions,
@@ -121,6 +123,17 @@ import {
   createDocumentNavigationSnapshot,
   findPageForOffset,
 } from "./document-navigation.ts";
+import {
+  createDocxFontLoader,
+  createLayoutEngine,
+  createLayoutFacet,
+  createMeasurementProvider,
+  type DocxFontLoader,
+  type LayoutEngineInstance,
+  type LayoutMeasurementProvider,
+  type WordReviewEditorLayoutFacet,
+} from "./layout/index.ts";
+import { createRenderKernel, type RenderKernel } from "./render/index.ts";
 import {
   createDocumentOutlineSnapshot,
   createDocumentSectionSnapshots,
@@ -150,6 +163,7 @@ import {
   resolveActiveSection,
 } from "./document-layout.ts";
 import { normalizeHeaderFooterTarget } from "./story-context.ts";
+import { computeAdjustedRange as computeAdjustedRangeImpl } from "./text-ack-range.ts";
 import {
   getStoryBlocks,
   replaceStoryBlocks,
@@ -213,7 +227,7 @@ export interface DocumentRuntime {
   getCanonicalDocument(): CanonicalDocumentEnvelope;
   getSourcePackage(): EditorSessionState["sourcePackage"] | undefined;
   replaceText(text: string, target?: EditorAnchorProjection): void;
-  applyActiveStoryTextCommand(command: ActiveStoryTextCommand): void;
+  applyActiveStoryTextCommand(command: ActiveStoryTextCommand): TextCommandAck;
   dispatch(command: EditorCommand): void;
   emitBlockedCommand(command: string, reasons: WorkflowBlockedCommandReason[]): void;
   undo(): void;
@@ -243,6 +257,12 @@ export interface DocumentRuntime {
   setZoom(level: ZoomLevel): void;
   getPageLayoutSnapshot(): PageLayoutSnapshot | null;
   getDocumentNavigationSnapshot(): DocumentNavigationSnapshot;
+  /**
+   * Runtime-owned layout facet.  Provides graph-aware queries, fragment
+   * resolution, formatting inspection, and layout events.  Prefer this over
+   * the opaque snapshot methods for new integration code.
+   */
+  readonly layout: WordReviewEditorLayoutFacet;
   getCurrentLocation(): DocumentLocationSnapshot | null;
   getLocationForSelection(selection: SelectionSnapshot): DocumentLocationSnapshot | null;
   getLocationForAnchor(
@@ -385,6 +405,57 @@ export function createDocumentRuntime(
     fatalError: options.fatalError as never,
   });
   storySelections.set(storyTargetKey(MAIN_STORY_TARGET), state.selection);
+
+  // Runtime-owned paginated layout engine (Phase 1+ of the layout facet work).
+  // The engine caches graph + resolved-formatting + fragment mapper keyed on
+  // (content, styles, subParts).  It is the single internal source of truth
+  // for page composition, story resolution, and layout invalidation.
+  //
+  // R0 measurement wiring: the engine starts with the sync empirical backend
+  // so the runtime is available immediately, then we kick off
+  // `createMeasurementProvider({ preference: "auto", fontLoader })` which
+  // upgrades to the canvas backend once fonts resolve.  `swapMeasurementProvider`
+  // emits `measurement_backend_ready` so chrome consumers can re-read metrics.
+  const layoutEngine: LayoutEngineInstance = createLayoutEngine();
+  const fontLoader: DocxFontLoader = createDocxFontLoader(
+    collectFontLoaderInput(state.document),
+  );
+  void upgradeMeasurementProvider(layoutEngine, fontLoader);
+  // `renderKernelRef` is a forward reference so the facet can reach the
+  // kernel after it is created below (kernel creation needs the facet).
+  let renderKernelRef: RenderKernel | null = null;
+  const layoutFacet: WordReviewEditorLayoutFacet = createLayoutFacet({
+    engine: layoutEngine,
+    getQueryInput: () => ({
+      document: state.document,
+      viewState: {
+        activeStory,
+        workspaceMode: viewState.workspaceMode,
+        zoomLevel: viewState.zoomLevel,
+      },
+    }),
+    renderKernel: () => renderKernelRef,
+    getWorkflowRailInput: () => {
+      if (!workflowOverlay) return null;
+      const activeWorkItemId = workflowOverlay.activeWorkItemId ?? null;
+      const activeWorkItem =
+        activeWorkItemId !== null
+          ? workflowOverlay.workItems?.find(
+              (item) => item.workItemId === activeWorkItemId,
+            )
+          : undefined;
+      return {
+        scopes: workflowOverlay.scopes,
+        candidates: workflowOverlay.candidates,
+        activeWorkItemScopeIds: activeWorkItem?.scopeIds ?? [],
+        activeStory,
+      };
+    },
+  });
+  renderKernelRef = createRenderKernel({
+    facet: layoutFacet,
+    getActiveStory: () => activeStory,
+  });
   let cachedSurface:
     | {
         revisionToken: string;
@@ -1604,9 +1675,21 @@ export function createDocumentRuntime(
     },
     applyActiveStoryTextCommand(command) {
       try {
-        applyTextCommandInActiveStory(command);
+        return applyTextCommandInActiveStory(command);
       } catch (error) {
-        emitError(toRuntimeError(error));
+        const runtimeError = toRuntimeError(error);
+        emitError(runtimeError);
+        return {
+          kind: "rejected",
+          opId: (command.origin as { opId?: string } | undefined)?.opId,
+          newRevisionToken: "",
+          blockedReasons: [
+            {
+              code: runtimeError.code ?? "runtime_error",
+              message: runtimeError.message,
+            },
+          ],
+        };
       }
     },
     addComment(params) {
@@ -1813,6 +1896,7 @@ export function createDocumentRuntime(
     getDocumentNavigationSnapshot() {
       return getCachedDocumentNavigationSnapshot(state, activeStory);
     },
+    layout: layoutFacet,
     getCurrentLocation() {
       const navigation = getCachedDocumentNavigationSnapshot(state, activeStory);
       return createCurrentLocation({
@@ -2272,6 +2356,33 @@ export function createDocumentRuntime(
     protectionSnapshot = remapProtectionSnapshot(protectionSnapshot, transaction.mapping);
     state = finalizeState(transaction.nextState, transaction.markDirty, clock());
     storySelections.set(storyTargetKey(activeStory), state.selection);
+
+    // Signal a bounded content-edit invalidation to the layout engine so the
+    // next layout query can splice rather than rebuild the full graph.  The
+    // engine analyzes the reason against its cached graph and falls back to
+    // a full rebuild when the edit crosses section boundaries or reaches a
+    // page the engine cannot safely resume from.
+    if (transaction.markDirty && transaction.mapping.steps.length > 0) {
+      let minFrom = Infinity;
+      let maxTo = -Infinity;
+      for (const step of transaction.mapping.steps) {
+        if (step.from < minFrom) minFrom = step.from;
+        const end = step.from + step.insertSize;
+        if (end > maxTo) maxTo = end;
+      }
+      if (minFrom < maxTo) {
+        layoutEngine.invalidate({ kind: "content-edit", from: minFrom, to: maxTo });
+      }
+    }
+
+    // Font-loader refresh on subParts identity change — this is the
+    // lightweight proxy for "a change that could affect which fonts the
+    // canvas backend measures against".  Typing edits don't rebuild
+    // subParts; style + font + numbering imports do.
+    if (previous.document.subParts !== state.document.subParts) {
+      fontLoader.refresh(collectFontLoaderInput(state.document));
+    }
+
     cachedRenderSnapshot = refreshRenderSnapshot();
     notify(previous, state, transaction);
   }
@@ -2455,24 +2566,31 @@ export function createDocumentRuntime(
       selection?: EditorState["selection"];
       blockedCommandName?: string;
     } = {},
-  ): void {
+  ): TextCommandAck {
+    const opId = (command.origin as { opId?: string } | undefined)?.opId;
     const selection = options.selection ?? state.selection;
     if (
       activeStory.kind !== "main" &&
       getEffectiveDocumentMode(selection) === "suggesting" &&
       command.type === "paragraph.split"
     ) {
+      const message = `"${command.type}" is not supported in suggesting mode for this story.`;
       emit({
         type: "command_blocked",
         documentId: state.documentId,
         command: options.blockedCommandName ?? command.type,
         reasons: [{
           code: "suggesting_unsupported",
-          message: `"${command.type}" is not supported in suggesting mode for this story.`,
+          message,
           storyTarget: activeStory,
         }],
       });
-      return;
+      return {
+        kind: "rejected",
+        opId,
+        newRevisionToken: "",
+        blockedReasons: [{ code: "suggesting_unsupported", message }],
+      };
     }
     const blockedReasons = evaluateWorkflowBlockedReasons(selection, command.type);
     if (blockedReasons.length > 0) {
@@ -2482,7 +2600,12 @@ export function createDocumentRuntime(
         command: options.blockedCommandName ?? command.type,
         reasons: blockedReasons,
       });
-      return;
+      return {
+        kind: "rejected",
+        opId,
+        newRevisionToken: "",
+        blockedReasons: blockedReasons.map((r) => ({ code: r.code, message: r.message })),
+      };
     }
 
     const timestamp = command.origin?.timestamp ?? clock();
@@ -2499,8 +2622,15 @@ export function createDocumentRuntime(
         };
 
     if (activeStory.kind === "main") {
-      commit(executeEditorCommand(baseState, command, context));
-      return;
+      const mainTransaction = executeEditorCommand(baseState, command, context);
+      commit(mainTransaction);
+      return classifyAck({
+        command,
+        opId,
+        priorState: baseState,
+        transaction: mainTransaction,
+        newRevisionToken: state.revisionToken,
+      });
     }
 
     const localState = createEditorState({
@@ -2531,7 +2661,11 @@ export function createDocumentRuntime(
         historyBoundary: "skip",
         markDirty: false,
       });
-      return;
+      return {
+        kind: "equivalent",
+        opId,
+        newRevisionToken: state.revisionToken,
+      };
     }
 
     const nextDocument = replaceStoryBlocks(
@@ -2561,12 +2695,87 @@ export function createDocumentRuntime(
       context,
     );
 
-    commit({
+    const mergedTransaction: EditorTransaction = {
       ...fullTransaction,
       effects: mergeTransactionEffects(fullTransaction.effects, localTransaction.effects),
+    };
+    commit(mergedTransaction);
+    return classifyAck({
+      command,
+      opId,
+      priorState: baseState,
+      transaction: mergedTransaction,
+      newRevisionToken: state.revisionToken,
     });
   }
 
+  function classifyAck(params: {
+    command: ActiveStoryTextCommand;
+    opId: string | undefined;
+    priorState: EditorState;
+    transaction: EditorTransaction;
+    newRevisionToken: string;
+  }): TextCommandAck {
+    const { opId, priorState, transaction, newRevisionToken } = params;
+    const meta = transaction.mapping.metadata ?? {};
+    const touches: readonly ScopeTagTouch[] =
+      (meta.scopeTagTouches as readonly ScopeTagTouch[] | undefined) ?? [];
+
+    if (meta.invalidatesStructures) {
+      return {
+        kind: "structural-divergence",
+        opId,
+        newRevisionToken,
+        scopeTagTouches: touches,
+      };
+    }
+
+    // A real touch means the runtime actually changed a tag anchor — not
+    // merely "a text edit happened and might conceivably have touched one".
+    // The coarse `affectsComments` / `affectsRevisions` flags today are set
+    // unconditionally by the text-transaction pipeline, so we cannot trust
+    // them to distinguish equivalent from adjusted. `scopeTagTouches` is the
+    // fine-grained truth that the predicted lane needs.
+    const touchedForAdjusted = touches.some(
+      (t) =>
+        t.behavior === "extended" ||
+        t.behavior === "trimmed" ||
+        t.behavior === "split" ||
+        t.behavior === "detached",
+    );
+
+    if (touchedForAdjusted) {
+      const adjustedRange = computeAdjustedRange(priorState, transaction);
+      return {
+        kind: "adjusted",
+        opId,
+        newRevisionToken,
+        adjustedRange,
+        scopeTagTouches: touches,
+      };
+    }
+
+    return {
+      kind: "equivalent",
+      opId,
+      newRevisionToken,
+      scopeTagTouches: touches,
+    };
+  }
+
+  function computeAdjustedRange(
+    prior: EditorState,
+    transaction: EditorTransaction,
+  ): { fromRuntime: number; toRuntime: number } {
+    return computeAdjustedRangeImpl(
+      { from: prior.selection.anchor, to: prior.selection.head },
+      transaction.mapping.steps.map((step) => ({
+        from: step.from,
+        insertSize: step.insertSize,
+      })),
+    );
+  }
+
   function mergeTransactionEffects(
     base: EditorTransaction["effects"],
     local: EditorTransaction["effects"],
@@ -4228,3 +4437,70 @@ function remapProtectionSnapshot(
     preservedRangeCount: nextRanges.filter((range) => !range.enforced).length,
   };
 }
+
+// ---------------------------------------------------------------------------
+// Measurement provider wiring (R0)
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the initial input the `DocxFontLoader` needs: a list of font
+ * families the document actively uses, plus any embedded font payloads the
+ * import pipeline may have extracted.
+ *
+ * Walks the document content tree once per call.  Embedded font extraction
+ * is not yet wired into the canonical model; we pass an empty map today and
+ * let the loader register system fonts it finds via
+ * `document.fonts.check(...)`.
+ */
+function collectFontLoaderInput(
+  document: CanonicalDocumentEnvelope,
+): { families: readonly string[] } {
+  try {
+    const families = new Set<string>();
+    const visit = (node: unknown): void => {
+      if (!node || typeof node !== "object") return;
+      const record = node as Record<string, unknown>;
+      const rpr = record["runProperties"] as
+        | Record<string, unknown>
+        | undefined;
+      if (rpr && typeof rpr["fontFamily"] === "string") {
+        families.add(rpr["fontFamily"] as string);
+      }
+      for (const value of Object.values(record)) {
+        if (Array.isArray(value)) value.forEach(visit);
+        else if (value && typeof value === "object") visit(value);
+      }
+    };
+    visit(document.content);
+    if (document.styles) {
+      visit(document.styles);
+    }
+    return { families: Array.from(families) };
+  } catch {
+    return { families: [] };
+  }
+}
+
+/**
+ * Asynchronously upgrade the engine's measurement backend to canvas once
+ * the platform supports it and fonts have resolved.  Errors are swallowed
+ * so a failure in the upgrade path can never break the empirical baseline.
+ */
+async function upgradeMeasurementProvider(
+  engine: LayoutEngineInstance,
+  fontLoader: DocxFontLoader,
+): Promise<void> {
+  try {
+    const provider: LayoutMeasurementProvider = await createMeasurementProvider({
+      preference: "auto",
+      fontLoader,
+    });
+    // If the host is running in SSR or a jsdom test shell, the factory will
+    // fall back to the empirical backend.  In that case swapping is a no-op
+    // but still emits `measurement_backend_ready` with `empirical` which is
+    // informational; chrome consumers use the event to refresh metrics.
+    engine.swapMeasurementProvider(provider);
+  } catch {
+    // fall through — the empirical backend remains in place
+  }
+}

package/src/runtime/layout/default-page-format.ts

@@ -0,0 +1,96 @@
+/**
+ * Locale-aware default page format.
+ *
+ * Word historically defaults to US Letter for `en-US` hosts and A4 everywhere
+ * else.  This module is the single place that decides which format a
+ * newly-created document uses when no section carries an explicit `w:pgSz`.
+ *
+ * It never overrides an existing section's page size on import — importers
+ * always preserve what the source document specified.  The default is
+ * consulted in two places:
+ *
+ *   1. `serialize-main-document.ts` when the canonical model carries a
+ *      section with no `pageSize` (e.g. programmatic document construction).
+ *   2. `DocumentRuntime` when rendering a brand-new blank document.
+ */
+
+import {
+  getPageFormatById,
+  type PageFormatDefinition,
+} from "./page-format-catalog.ts";
+
+// ---------------------------------------------------------------------------
+// Locale resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Which BCP-47 language tags should fall back to Letter.
+ *
+ * Anything else defaults to A4.  This intentionally uses a small whitelist
+ * rather than a `startsWith("en")` check — `en-GB`, `en-AU`, `en-IN` all
+ * expect ISO paper sizes, not US Letter.
+ */
+const LETTER_LOCALES = new Set<string>([
+  "en-us",
+  "en-ca",
+  "fr-ca",
+  "es-mx",
+  "es-cl",
+  "fil-ph",
+]);
+
+export interface ResolveDefaultPageFormatOptions {
+  /** Explicit BCP-47 locale (e.g. "en-US", "de-DE"). */
+  locale?: string;
+}
+
+/**
+ * Return the default `PageFormatDefinition` for a given locale.
+ *
+ * When `locale` is omitted the function consults `Intl.DateTimeFormat` to
+ * infer the current locale.  When `Intl` is unavailable (unusual in modern
+ * runtimes) it falls back to A4 as the safer international default.
+ */
+export function resolveDefaultPageFormat(
+  options: ResolveDefaultPageFormatOptions = {},
+): PageFormatDefinition {
+  const raw = options.locale ?? tryResolveHostLocale();
+  if (!raw) {
+    return getPageFormatById("a4");
+  }
+  const normalized = raw.toLowerCase();
+  if (LETTER_LOCALES.has(normalized)) {
+    return getPageFormatById("letter");
+  }
+  // Match just the language-region prefix (e.g. "en-us-1234" → "en-us")
+  const region = normalized.split("-").slice(0, 2).join("-");
+  if (LETTER_LOCALES.has(region)) {
+    return getPageFormatById("letter");
+  }
+  return getPageFormatById("a4");
+}
+
+function tryResolveHostLocale(): string | undefined {
+  try {
+    if (typeof Intl === "undefined" || typeof Intl.DateTimeFormat !== "function") {
+      return undefined;
+    }
+    return new Intl.DateTimeFormat().resolvedOptions().locale;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Return the default `w:pgSz` payload (width/height in twips) for a given
+ * locale.  Convenience wrapper used by the export pipeline.
+ */
+export function resolveDefaultPageSizeTwips(
+  options: ResolveDefaultPageFormatOptions = {},
+): { widthTwips: number; heightTwips: number } {
+  const format = resolveDefaultPageFormat(options);
+  return {
+    widthTwips: format.portraitWidthTwips,
+    heightTwips: format.portraitHeightTwips,
+  };
+}

package/src/runtime/layout/docx-font-loader.ts

@@ -0,0 +1,143 @@
+/**
+ * DocxFontLoader — best-effort registration of the document's declared font
+ * families with the browser's FontFace registry.
+ *
+ * Scope:
+ *   - For each font family the document uses, resolve whether the browser
+ *     can already render it.
+ *   - If the package ships embedded font binary data, register each face via
+ *     `new FontFace(family, data).load()` then `document.fonts.add(face)`.
+ *   - Wait on `document.fonts.ready` to know when layout-affecting fonts are
+ *     available, so the Canvas backend is measuring against real metrics.
+ *
+ * Non-goals:
+ *   - This loader does not attempt to fetch fonts from external CDNs.
+ *   - It does not attempt style-matching with Panose; that belongs in a
+ *     font-substitution pass if we ever need it.
+ *   - SSR and gRPC never run this loader.
+ */
+
+export interface FontLoaderInput {
+  /** Font family names the document actively uses. */
+  families: readonly string[];
+  /**
+   * Optional embedded font payloads keyed by family name (uppercase-insensitive).
+   * Each entry holds binary data for regular / bold / italic / bold-italic
+   * variants.  Callers may omit any variant; the loader will register only
+   * what is provided.
+   */
+  embeddedFontBytes?: Map<string, EmbeddedFontBytes>;
+}
+
+export interface EmbeddedFontBytes {
+  regular?: ArrayBuffer;
+  bold?: ArrayBuffer;
+  italic?: ArrayBuffer;
+  boldItalic?: ArrayBuffer;
+}
+
+export interface DocxFontLoader {
+  whenReady(): Promise<void>;
+  isSupported(): boolean;
+  /** Which families are currently registered or detected as available. */
+  getRegisteredFamilies(): readonly string[];
+  /** Force re-resolution of the ready promise (e.g. after adding more fonts). */
+  refresh(input: FontLoaderInput): void;
+}
+
+export function createDocxFontLoader(initial: FontLoaderInput): DocxFontLoader {
+  const supported =
+    typeof document !== "undefined" &&
+    typeof (globalThis as { FontFace?: unknown }).FontFace !== "undefined" &&
+    // Guard against jsdom which exposes FontFace but not document.fonts
+    Boolean((document as Document & { fonts?: FontFaceSet }).fonts);
+
+  let current: FontLoaderInput = initial;
+  let readyPromise: Promise<void>;
+  const registered = new Set<string>();
+
+  function run(input: FontLoaderInput): Promise<void> {
+    if (!supported) return Promise.resolve();
+    const fontSet = (document as Document & { fonts?: FontFaceSet }).fonts;
+    if (!fontSet) return Promise.resolve();
+
+    const pending: Array<Promise<unknown>> = [];
+
+    if (input.embeddedFontBytes) {
+      for (const [familyRaw, variants] of input.embeddedFontBytes) {
+        const family = familyRaw.trim();
+        if (!family) continue;
+
+        for (const [descriptor, data] of variantsOf(variants)) {
+          try {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const FontFaceCtor = (globalThis as any).FontFace as {
+              new (family: string, source: BufferSource, descriptors?: FontFaceDescriptors): FontFace;
+            };
+            const face = new FontFaceCtor(family, data, descriptor);
+            pending.push(
+              face.load().then((loaded) => {
+                fontSet.add(loaded);
+                registered.add(family);
+              }),
+            );
+          } catch {
+            // Single-face failures should not fail the whole batch.
+          }
+        }
+      }
+    }
+
+    // Mark declared families as registered if the browser already resolves
+    // them (e.g. system fonts like Calibri, Arial).
+    for (const family of input.families) {
+      try {
+        const probe = `12px "${family.replace(/"/g, "'")}", serif`;
+        if (fontSet.check(probe)) {
+          registered.add(family);
+        }
+      } catch {
+        // ignore
+      }
+    }
+
+    return Promise.all(pending)
+      .then(() => fontSet.ready)
+      .then(() => undefined);
+  }
+
+  readyPromise = run(current);
+
+  return {
+    whenReady() {
+      return readyPromise;
+    },
+    isSupported() {
+      return supported;
+    },
+    getRegisteredFamilies() {
+      return Array.from(registered);
+    },
+    refresh(input: FontLoaderInput) {
+      current = input;
+      readyPromise = run(current);
+    },
+  };
+}
+
+function* variantsOf(
+  variants: EmbeddedFontBytes,
+): IterableIterator<[FontFaceDescriptors, ArrayBuffer]> {
+  if (variants.regular) {
+    yield [{ weight: "400", style: "normal" }, variants.regular];
+  }
+  if (variants.bold) {
+    yield [{ weight: "700", style: "normal" }, variants.bold];
+  }
+  if (variants.italic) {
+    yield [{ weight: "400", style: "italic" }, variants.italic];
+  }
+  if (variants.boldItalic) {
+    yield [{ weight: "700", style: "italic" }, variants.boldItalic];
+  }
+}