@beyondwork/docx-react-component 1.0.40 → 1.0.42

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

@@ -45,35 +45,12 @@ export interface DocxFontLoader {
   refresh(input: FontLoaderInput): void;
 }
 
-interface MinimalFontFace {
-  load(): Promise<MinimalFontFace>;
-}
-
-interface MinimalFontFaceDescriptors {
-  weight?: string;
-  style?: string;
-}
-
-interface MinimalFontFaceConstructor {
-  new (
-    family: string,
-    source: ArrayBuffer | ArrayBufferView | string,
-    descriptors?: MinimalFontFaceDescriptors,
-  ): MinimalFontFace;
-}
-
-interface MinimalFontFaceSet {
-  add(face: MinimalFontFace): void;
-  check(font: string): boolean;
-  ready: Promise<MinimalFontFaceSet>;
-}
-
 export function createDocxFontLoader(initial: FontLoaderInput): DocxFontLoader {
-  const globalDocument = (globalThis as { document?: { fonts?: MinimalFontFaceSet } }).document;
   const supported =
-    globalDocument !== undefined &&
+    typeof document !== "undefined" &&
     typeof (globalThis as { FontFace?: unknown }).FontFace !== "undefined" &&
-    Boolean(globalDocument.fonts);
+    // 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>;
@@ -81,7 +58,7 @@ export function createDocxFontLoader(initial: FontLoaderInput): DocxFontLoader {
 
   function run(input: FontLoaderInput): Promise<void> {
     if (!supported) return Promise.resolve();
-    const fontSet = globalDocument?.fonts;
+    const fontSet = (document as Document & { fonts?: FontFaceSet }).fonts;
     if (!fontSet) return Promise.resolve();
 
     const pending: Array<Promise<unknown>> = [];
@@ -93,8 +70,10 @@ export function createDocxFontLoader(initial: FontLoaderInput): DocxFontLoader {
 
         for (const [descriptor, data] of variantsOf(variants)) {
           try {
-            const FontFaceCtor = (globalThis as { FontFace?: MinimalFontFaceConstructor }).FontFace;
-            if (!FontFaceCtor) continue;
+            // 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) => {
@@ -109,6 +88,8 @@ export function createDocxFontLoader(initial: FontLoaderInput): DocxFontLoader {
       }
     }
 
+    // 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`;
@@ -146,7 +127,7 @@ export function createDocxFontLoader(initial: FontLoaderInput): DocxFontLoader {
 
 function* variantsOf(
   variants: EmbeddedFontBytes,
-): IterableIterator<[MinimalFontFaceDescriptors, ArrayBuffer]> {
+): IterableIterator<[FontFaceDescriptors, ArrayBuffer]> {
   if (variants.regular) {
     yield [{ weight: "400", style: "normal" }, variants.regular];
   }

package/src/runtime/layout/inert-layout-facet.ts

@@ -35,6 +35,7 @@ export function createInertLayoutFacet(): WordReviewEditorLayoutFacet {
     getDisplayPageNumber: () => null,
     getLineBoxes: () => [],
     getLineBoxesForRegion: () => [],
+    getStoryRegionsOnPage: () => [],
     getFragmentsForPage: () => [],
     getPageFormatCatalog: () => PAGE_FORMAT_CATALOG,
     getActivePageFormat: () => null,
@@ -54,6 +55,7 @@ export function createInertLayoutFacet(): WordReviewEditorLayoutFacet {
     whenMeasurementReady: () => Promise.resolve(),
     getFirstPageIndexForBlock: () => null,
     swapMeasurementProvider: () => undefined,
+    invalidateMeasurementCache: () => undefined,
     getTableRenderPlan: () => null,
     getDirtyFieldFamilies: () => [],
     getFieldDirtinessReport: () => emptyReport,

package/src/runtime/layout/layout-engine-instance.ts

@@ -104,7 +104,19 @@ export interface LayoutEngineEvent {
     | "incremental_relayout"
     | "page_count_changed"
     | "page_field_dirtied"
-    | "measurement_backend_ready";
+    | "measurement_backend_ready"
+    /**
+     * P14.b — coalesced "the engine just finished a build" event.  Emitted
+     * exactly once per `fullRebuild` / `incrementalRelayout` AFTER the
+     * granular events, carrying the union of dirty-field families, page-
+     * count delta, and page-range info.  Subscribers that only need to
+     * react to "something layout-affecting changed" can listen to this
+     * single event and skip the multi-event subscription pattern that
+     * triggered N React re-renders per applyPatch.  The granular events
+     * still fire for backward compat with consumers (TwStatusBar fidelity
+     * badge, etc.) that care about specific kinds.
+     */
+    | "layout_committed";
   revision: number;
   previousPageCount?: number;
   currentPageCount?: number;
@@ -113,6 +125,17 @@ export interface LayoutEngineEvent {
   fidelity?: LayoutMeasurementProvider["fidelity"];
   /** First dirty page index for incremental_relayout events. */
   firstDirtyPageIndex?: number;
+  /**
+   * P14.b — page-count delta for `layout_committed`.  Present when the
+   * commit produced a different total page count than the prior graph.
+   */
+  pageCountDelta?: { previous: number; current: number };
+  /**
+   * P14.b — when `layout_committed` came from a bounded incremental
+   * relayout, the page range that was re-paginated.  Absent for full
+   * rebuilds.
+   */
+  pageRange?: { fromPageIndex: number; toPageIndex: number };
 }
 
 export interface LayoutEngineInstance {
@@ -149,6 +172,16 @@ export interface LayoutEngineInstance {
 
   // ---- measurement plumbing --------------------------------------------
   swapMeasurementProvider(provider: LayoutMeasurementProvider): void;
+  /**
+   * Invalidate the active measurement provider's internal caches (canvas
+   * glyph / run-width LRU) AND clear the engine's cached page graph so
+   * the next query re-paginates with fresh measurements.  Host runtime
+   * calls this after `docxFontLoader.refresh(...)` registers new
+   * FontFace families — without this call the canvas backend's glyph
+   * cache keeps returning pre-refresh widths for already-measured
+   * glyphs, and the cached page graph keeps its stale page boundaries.
+   */
+  invalidateMeasurementCache(): void;
 }
 
 // ---------------------------------------------------------------------------
@@ -284,14 +317,30 @@ export function createLayoutEngine(
     const formatting = buildResolvedFormattingState(document, mainSurface);
 
     const currentPageCount = resolveTotalPageCount(pages);
+    let pageCountDelta: { previous: number; current: number } | undefined;
     if (currentPageCount !== previousPageCount) {
+      pageCountDelta = { previous: previousPageCount, current: currentPageCount };
+      previousPageCount = currentPageCount;
+    }
+
+    // MUST publish cache before emit: re-entrant getPageGraph() calls from
+    // subscribers during emit would otherwise trigger runaway rebuilds.
+    cachedKey = {
+      content: document.content,
+      styles: document.styles,
+      subParts: document.subParts,
+    };
+    cachedGraph = graph;
+    cachedFormatting = formatting;
+    cachedMapper = createPageFragmentMapper(graph);
+
+    if (pageCountDelta) {
       emit({
         kind: "page_count_changed",
         revision: graph.revision,
-        previousPageCount,
-        currentPageCount,
+        previousPageCount: pageCountDelta.previous,
+        currentPageCount: pageCountDelta.current,
       });
-      previousPageCount = currentPageCount;
     }
 
     if (dirtyFamilies.length > 0) {
@@ -308,14 +357,16 @@ export function createLayoutEngine(
       ...(reason ? { reason } : {}),
     });
 
-    cachedKey = {
-      content: document.content,
-      styles: document.styles,
-      subParts: document.subParts,
-    };
-    cachedGraph = graph;
-    cachedFormatting = formatting;
-    cachedMapper = createPageFragmentMapper(graph);
+    emit({
+      kind: "layout_committed",
+      revision: graph.revision,
+      ...(reason ? { reason } : {}),
+      ...(dirtyFamilies.length > 0
+        ? { dirtyFieldFamilies: dirtyFamilies }
+        : {}),
+      ...(pageCountDelta ? { pageCountDelta } : {}),
+    });
+
     return graph;
   }
 
@@ -388,7 +439,9 @@ export function createLayoutEngine(
     const currentPageCount = resolveTotalPageCount(
       deriveDocumentPageSnapshots(splicedGraph),
     );
+    let pageCountDelta: { previous: number; current: number } | undefined;
     if (currentPageCount !== previousPageCount) {
+      pageCountDelta = { previous: previousPageCount, current: currentPageCount };
       emit({
         kind: "page_count_changed",
         revision: splicedGraph.revision,
@@ -413,6 +466,30 @@ export function createLayoutEngine(
       firstDirtyPageIndex: firstDirty,
     });
 
+    // P14.b — coalesced commit event for the bounded-incremental path.
+    //
+    // Page-range semantics: the current `incrementalRelayout` path uses
+    // `buildPageStackFromWithSplits` + `spliceGraph`, which always
+    // re-paginates from `firstDirty` through the document tail (we
+    // discard the prior tail and replace it with the freshly-paginated
+    // pages).  So `toPageIndex = pages.length - 1` is correct for every
+    // commit produced by this path.  Future bounded-middle splices
+    // (e.g., a middle-style change that doesn't touch the tail) would
+    // need to track an explicit upper bound — guard the assumption
+    // here so the contract drift becomes a test failure rather than a
+    // silent over-iteration in consumers (Chrome overlay, render kernel
+    // diff).
+    emit({
+      kind: "layout_committed",
+      revision: splicedGraph.revision,
+      reason: pending.reason,
+      pageRange: { fromPageIndex: firstDirty, toPageIndex: splicedGraph.pages.length - 1 },
+      ...(dirtyFamilies.length > 0
+        ? { dirtyFieldFamilies: dirtyFamilies }
+        : {}),
+      ...(pageCountDelta ? { pageCountDelta } : {}),
+    });
+
     cachedKey = {
       content: document.content,
       styles: document.styles,
@@ -605,13 +682,46 @@ export function createLayoutEngine(
     },
 
     swapMeasurementProvider(provider) {
+      const previousFidelity = measurementProvider.fidelity;
       measurementProvider = provider;
+      // Hardening: a backend swap changes the measurement numerics the
+      // cached graph was built against.  Empirical → canvas typically
+      // reduces line counts (canvas-accurate glyph widths pack more
+      // text per line); canvas → canvas-with-font-loading applies the
+      // correct FontFace metrics for embedded DOCX fonts.  Either way,
+      // the cached graph is stale — invalidate so the next
+      // `getGraph()` query re-paginates with the new provider.  Skip
+      // invalidation when fidelity is unchanged (e.g., an empirical
+      // → empirical swap, or a canvas fallback that resolved back to
+      // the same backend) so we don't churn.
+      if (previousFidelity !== provider.fidelity) {
+        cachedKey = null;
+        cachedGraph = null;
+        cachedFormatting = null;
+        cachedMapper = null;
+      }
       emit({
         kind: "measurement_backend_ready",
         revision: cachedGraph?.revision ?? 0,
         fidelity: provider.fidelity,
       });
     },
+    /**
+     * Invalidate the current measurement provider's internal glyph /
+     * run-width cache.  Called by the host runtime after
+     * `fontLoader.refresh(...)` so canvas-backed measurements re-read
+     * the newly-registered FontFaces instead of returning stale widths
+     * from the pre-refresh glyph cache.  The graph cache itself is
+     * also cleared because a font change can shift line breaks and
+     * therefore page boundaries.
+     */
+    invalidateMeasurementCache() {
+      measurementProvider.invalidateCache();
+      cachedKey = null;
+      cachedGraph = null;
+      cachedFormatting = null;
+      cachedMapper = null;
+    },
   };
 }
 

package/src/runtime/layout/page-graph.ts

@@ -73,6 +73,17 @@ export interface RuntimePageRegions {
    * pages, the top-level body is used and `columns` is undefined.
    */
   columns?: RuntimePageRegion[];
+  /**
+   * P4 — footnote regions reserved at the bottom of the page (above
+   * the footer band) when `noteAllocations` reserved space for one or
+   * more footnote bodies.  Empty until the page-graph builder
+   * populates them, which lands alongside the P8 per-page region
+   * rendering work.  The shape exists now so consumers
+   * (`getStoryRegionsOnPage` / `getLineBoxesForRegion("footnote-area")`)
+   * have a stable seam to read from when the builder catches up —
+   * pre-P8 reads return `[]` because no entries are populated.
+   */
+  footnotes?: RuntimePageRegion[];
 }
 
 export interface RuntimePageRegion {
@@ -158,6 +169,14 @@ export interface RuntimeNoteAllocation {
   noteId: string;
   /** Twips reserved at the bottom of the page for this note's content. */
   reservedHeightTwips: number;
+  /**
+   * P8 — fragment ID of this note's body.  The corresponding
+   * `RuntimeBlockFragment` lives in `RuntimePageGraph.fragments` with
+   * `regionKind: "footnote-area"`.  Undefined when the engine hasn't
+   * yet emitted a fragment for the allocation (back-compat for pre-P8
+   * callers).
+   */
+  fragmentId?: string;
 }
 
 export interface RuntimePageAnchor {
@@ -196,8 +215,15 @@ export interface BuildPageGraphInput {
   >;
   /** Optional per-page line boxes. */
   lineBoxes?: ReadonlyMap<string, RuntimeLineBox[]>;
-  /** Optional per-page note allocations. */
+  /** Optional per-page note allocations keyed by graph-assigned pageId. */
   noteAllocations?: ReadonlyMap<string, RuntimeNoteAllocation[]>;
+  /**
+   * P8 — per-page note allocations keyed by pageIndex (0-based).
+   * Parallel to `fragmentsByPageIndex`; `buildPageGraph` uses the index to
+   * look up allocations without requiring callers to know the graph-internal
+   * `page-${revision}-${index}` pageId in advance.
+   */
+  noteAllocationsByPageIndex?: ReadonlyMap<number, RuntimeNoteAllocation[]>;
 }
 
 export function buildPageGraph(input: BuildPageGraphInput): RuntimePageGraph;
@@ -244,10 +270,15 @@ export function buildPageGraph(
     };
 
     const pageFragments = aggregatedFragments.filter((f) => f.pageId === pageId);
-    const fragmentIds = pageFragments.map((f) => f.fragmentId);
+    // Split fragments into body-region ones (for the body fragmentIds list)
+    // and footnote-area ones (handled by buildRegions via noteAllocations).
+    const bodyPageFragments = pageFragments.filter(
+      (f) => f.regionKind !== "footnote-area",
+    );
+    const fragmentIds = bodyPageFragments.map((f) => f.fragmentId);
 
-    // If no fragments were supplied, synthesize a coarse body fragment so the
-    // graph is still internally consistent.
+    // If no body fragments were supplied, synthesize a coarse body fragment so
+    // the graph is still internally consistent.
     let bodyFragmentIds = fragmentIds;
     if (fragmentIds.length === 0 && page.endOffset > page.startOffset) {
       const coarse: RuntimeBlockFragment = {
@@ -264,6 +295,15 @@ export function buildPageGraph(
       bodyFragmentIds = [coarse.fragmentId];
     }
 
+    // Resolve per-page note allocations: prefer noteAllocationsByPageIndex
+    // (index-based, suitable when the caller doesn't know the graph-internal
+    // pageId) falling back to noteAllocations (pageId-keyed, used by the
+    // engine once it emits allocations).
+    const pageNoteAllocations: RuntimeNoteAllocation[] =
+      input.noteAllocationsByPageIndex?.get(index) ??
+      input.noteAllocations?.get(pageId) ??
+      [];
+
     const node: RuntimePageNode = {
       pageId,
       pageIndex: page.pageIndex,
@@ -273,9 +313,9 @@ export function buildPageGraph(
       endOffset: page.endOffset,
       layout: page.layout,
       stories,
-      regions: buildRegions(page.layout, bodyFragmentIds, stories),
+      regions: buildRegions(page.layout, bodyFragmentIds, stories, pageNoteAllocations),
       lineBoxes: input.lineBoxes?.get(pageId) ?? [],
-      noteAllocations: input.noteAllocations?.get(pageId) ?? [],
+      noteAllocations: pageNoteAllocations,
       isBlankFiller: page.pageInSection === -1,
     };
     pages.push(node);
@@ -302,12 +342,40 @@ function buildRegions(
   layout: PageLayoutSnapshot,
   bodyFragmentIds: readonly string[],
   stories: ResolvedPageStories,
+  noteAllocations: readonly RuntimeNoteAllocation[] = [],
 ): RuntimePageRegions {
   const bodyWidth =
     layout.pageWidth - layout.marginLeft - layout.marginRight;
-  const bodyHeight =
+  let bodyHeight =
     layout.pageHeight - layout.marginTop - layout.marginBottom;
 
+  // P8 — footnote area sits at the bottom of the page (above the footer
+  // band). Body height shrinks by the total reserved note height so
+  // band-aware consumers can stack bands without overflowing the paper frame.
+  let footnotesRegion: RuntimePageRegion | undefined;
+  if (noteAllocations.length > 0) {
+    const fragmentIds = noteAllocations
+      .filter(
+        (a): a is RuntimeNoteAllocation & { fragmentId: string } =>
+          Boolean(a.fragmentId),
+      )
+      .map((a) => a.fragmentId);
+    const totalNoteHeight = noteAllocations.reduce(
+      (sum, a) => sum + a.reservedHeightTwips,
+      0,
+    );
+    if (fragmentIds.length > 0) {
+      footnotesRegion = {
+        kind: "footnote-area",
+        originTwips: layout.pageHeight - layout.marginBottom - totalNoteHeight,
+        widthTwips: Math.max(0, bodyWidth),
+        heightTwips: Math.max(0, totalNoteHeight),
+        fragmentIds,
+      };
+      bodyHeight = Math.max(0, bodyHeight - totalNoteHeight);
+    }
+  }
+
   const body: RuntimePageRegion = {
     kind: "body",
     originTwips: layout.marginTop,
@@ -356,6 +424,10 @@ function buildRegions(
     regions.columns = columns;
   }
 
+  if (footnotesRegion) {
+    regions.footnotes = [footnotesRegion];
+  }
+
   return regions;
 }