@beyondwork/docx-react-component 1.0.35 → 1.0.37

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,12 @@ import {
   createDocumentNavigationSnapshot,
   findPageForOffset,
 } from "./document-navigation.ts";
+import {
+  createLayoutEngine,
+  createLayoutFacet,
+  type LayoutEngineInstance,
+  type WordReviewEditorLayoutFacet,
+} from "./layout/index.ts";
 import {
   createDocumentOutlineSnapshot,
   createDocumentSectionSnapshots,
@@ -150,6 +158,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 +222,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 +252,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 +400,23 @@ 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.
+  const layoutEngine: LayoutEngineInstance = createLayoutEngine();
+  const layoutFacet: WordReviewEditorLayoutFacet = createLayoutFacet({
+    engine: layoutEngine,
+    getQueryInput: () => ({
+      document: state.document,
+      viewState: {
+        activeStory,
+        workspaceMode: viewState.workspaceMode,
+        zoomLevel: viewState.zoomLevel,
+      },
+    }),
+  });
   let cachedSurface:
     | {
         revisionToken: string;
@@ -738,7 +770,7 @@ export function createDocumentRuntime(
       });
     }
 
-    if (viewState.documentMode === "viewing") {
+    if (viewState.documentMode === "viewing" || viewState.documentMode === "commenting") {
       reasons.push({
         code: "document_viewing_mode",
         message: "Document is in viewing mode.",
@@ -822,8 +854,8 @@ export function createDocumentRuntime(
   function getEffectiveDocumentMode(
     selection: EditorState["selection"],
   ): DocumentMode {
-    if (viewState.documentMode === "viewing") {
-      return "viewing";
+    if (viewState.documentMode === "viewing" || viewState.documentMode === "commenting") {
+      return viewState.documentMode;
     }
     const matchingScope = getMatchingWorkflowScope(selection);
     if (matchingScope?.mode === "suggest") {
@@ -1529,13 +1561,13 @@ export function createDocumentRuntime(
       }
 
       if (command.type === "history.undo") {
-        if (viewState.documentMode === "viewing") return;
+        if (viewState.documentMode === "viewing" || viewState.documentMode === "commenting") return;
         applyHistory("undo");
         return;
       }
 
       if (command.type === "history.redo") {
-        if (viewState.documentMode === "viewing") return;
+        if (viewState.documentMode === "viewing" || viewState.documentMode === "commenting") return;
         applyHistory("redo");
         return;
       }
@@ -1604,9 +1636,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 +1857,7 @@ export function createDocumentRuntime(
     getDocumentNavigationSnapshot() {
       return getCachedDocumentNavigationSnapshot(state, activeStory);
     },
+    layout: layoutFacet,
     getCurrentLocation() {
       const navigation = getCachedDocumentNavigationSnapshot(state, activeStory);
       return createCurrentLocation({
@@ -2272,6 +2317,25 @@ 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 });
+      }
+    }
+
     cachedRenderSnapshot = refreshRenderSnapshot();
     notify(previous, state, transaction);
   }
@@ -2455,24 +2519,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 +2553,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 +2575,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 +2614,11 @@ export function createDocumentRuntime(
         historyBoundary: "skip",
         markDirty: false,
       });
-      return;
+      return {
+        kind: "equivalent",
+        opId,
+        newRevisionToken: state.revisionToken,
+      };
     }
 
     const nextDocument = replaceStoryBlocks(
@@ -2561,12 +2648,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"],

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];
+  }
+}

package/src/runtime/layout/index.ts

@@ -0,0 +1,188 @@
+/**
+ * Runtime-owned paginated layout engine — internal API surface.
+ *
+ * Runtime consumption (live, wired):
+ *   buildPageStack, computePageStack       — shipped façade
+ *   createLayoutEngine                     — stateful engine owned by DocumentRuntime
+ *   resolvePageStories                     — per-page header/footer variant selection
+ *   buildPageGraph                         — RuntimePageGraph construction
+ *   analyzeInvalidation / computeFieldDirtiness — invalidation + field dirtiness
+ *   createPageFragmentMapper               — offset ↔ fragment ↔ region mapping
+ *
+ * Measurement:
+ *   LayoutMeasurementProvider + empirical and canvas backends
+ *   DocxFontLoader — FontFace registration for canvas fidelity
+ *
+ * Nothing in this module is part of the package's public API.
+ */
+
+// ---------------------------------------------------------------------------
+// Façade (backward-compatible entry point)
+// ---------------------------------------------------------------------------
+
+export {
+  buildPageStack,
+  buildPageStackFrom,
+  computePageStack,
+  requiresFullRecompute,
+  type LayoutInvalidationReason,
+  type PageStackResult,
+} from "./paginated-layout-engine.ts";
+
+// ---------------------------------------------------------------------------
+// Stateful engine (Phase 1)
+// ---------------------------------------------------------------------------
+
+export {
+  createLayoutEngine,
+  findActivePageNode,
+  type LayoutEngineInstance,
+  type LayoutEngineViewState,
+  type LayoutEngineQueryInput,
+  type LayoutEngineEvent,
+  type CreateLayoutEngineOptions,
+} from "./layout-engine-instance.ts";
+
+// ---------------------------------------------------------------------------
+// Formatting resolution
+// ---------------------------------------------------------------------------
+
+export {
+  resolveBlockFormatting,
+  resolveTextWidth,
+  resolveCharsPerLine,
+  calculateParagraphHeight,
+  resolveNumberingPrefixLength,
+  type ResolvedParagraphFormatting,
+  type ResolvedTableRowFormatting,
+  type LayoutTabStop,
+} from "./resolved-formatting-state.ts";
+
+export {
+  buildResolvedFormattingState,
+  collectUsedFontFamilies,
+  populateNumberingInstances,
+  getResolvedParagraph,
+  getResolvedRun,
+  type ResolvedFormattingState,
+  type ResolvedRunFormatting,
+  type ResolvedFontCatalog,
+  type ResolvedFontDescriptor,
+  type ResolvedTabSettings,
+  type ResolvedNumberingGeometry,
+  type ResolvedDocumentSettings,
+  type NumberingInstanceMetadata,
+  type RunId,
+} from "./resolved-formatting-document.ts";
+
+// ---------------------------------------------------------------------------
+// Page story resolution + graph + fragment mapping
+// ---------------------------------------------------------------------------
+
+export {
+  resolvePageStories,
+  resolveDisplayPageNumber,
+  resolveTotalPageCount,
+  type ResolvedPageStories,
+} from "./page-story-resolver.ts";
+
+export {
+  buildPageGraph,
+  spliceGraph,
+  findPageNodeForOffset,
+  findPagesForSection,
+  findPageForStoryTarget,
+  toDocumentPageSnapshots,
+  type RuntimePageGraph,
+  type RuntimePageNode,
+  type RuntimePageRegions,
+  type RuntimePageRegion,
+  type RuntimeBlockFragment,
+  type RuntimeLineBox,
+  type RuntimeNoteAllocation,
+  type RuntimePageAnchor,
+  type BuildPageGraphInput,
+} from "./page-graph.ts";
+
+export {
+  createPageFragmentMapper,
+  rebuildMapper,
+  // Deprecated alias retained for one release after §6 E.5 rename:
+  updateMapperIncremental,
+  type PageFragmentMapper,
+  type PageFragmentLocation,
+  type PageSpan,
+} from "./page-fragment-mapper.ts";
+
+export {
+  derivePageLayoutSnapshotFromGraph,
+  deriveDocumentPageSnapshots,
+  deriveActivePageIndex,
+  deriveActiveSectionIndex,
+  deriveActivePage,
+} from "./page-layout-snapshot-adapter.ts";
+
+// ---------------------------------------------------------------------------
+// Invalidation + field dirtiness
+// ---------------------------------------------------------------------------
+
+export {
+  analyzeInvalidation,
+  computeFieldDirtiness,
+  type InvalidationResult,
+} from "./layout-invalidation.ts";
+
+// ---------------------------------------------------------------------------
+// Measurement provider
+// ---------------------------------------------------------------------------
+
+export {
+  createMeasurementProvider,
+  createEmpiricalMeasurementProvider,
+  type LayoutMeasurementProvider,
+  type MeasurementFidelity,
+  type MeasurementBackendPreference,
+  type CreateMeasurementProviderOptions,
+  type MeasureLineFragmentsInput,
+  type MeasuredLineFragments,
+  type MeasureInlineObjectInput,
+  type MeasuredInlineObject,
+  type MeasureTableBlockInput,
+  type MeasuredTableBlock,
+} from "./layout-measurement-provider.ts";
+
+export {
+  createDocxFontLoader,
+  type DocxFontLoader,
+  type FontLoaderInput,
+  type EmbeddedFontBytes,
+} from "./docx-font-loader.ts";
+
+// ---------------------------------------------------------------------------
+// Public facet (Phase 7)
+// ---------------------------------------------------------------------------
+
+export { createInertLayoutFacet } from "./inert-layout-facet.ts";
+
+export {
+  createLayoutFacet,
+  type WordReviewEditorLayoutFacet,
+  type PublicPageNode,
+  type PublicPageRegions,
+  type PublicPageRegion,
+  type PublicBlockFragment,
+  type PublicLineBox,
+  type PublicNoteAllocation,
+  type PublicPageAnchor,
+  type PublicPageSpan,
+  type PublicSectionNode,
+  type PublicResolvedPageStories,
+  type PublicResolvedParagraphFormatting,
+  type PublicResolvedRunFormatting,
+  type PublicBlockMeasurement,
+  type PublicMeasurementFidelity,
+  type PublicFieldDirtinessReport,
+  type LayoutFacetEvent,
+  type LayoutFacetInvalidationReason,
+  type CreateLayoutFacetInput,
+} from "./public-facet.ts";