@beyondwork/docx-react-component 1.0.42 → 1.0.43

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

@@ -62,8 +62,12 @@ import {
   type ScopeRailSegment,
 } from "../workflow-rail-segments.ts";
 import { createEditorSurfaceSnapshot } from "../surface-projection.ts";
+import { storyTargetKey } from "../story-targeting.ts";
 import { MAIN_STORY_TARGET } from "../../core/selection/mapping.ts";
-import { createSelectionSnapshot } from "../../core/state/editor-state.ts";
+import {
+  createSelectionSnapshot,
+  type CanonicalDocumentEnvelope,
+} from "../../core/state/editor-state.ts";
 import { resolveTableStyleResolution } from "../table-style-resolver.ts";
 import { buildTableRenderPlan } from "./table-render-plan.ts";
 import { recordPerfSample } from "../../ui-tailwind/editor-surface/perf-probe.ts";
@@ -124,6 +128,13 @@ export interface PublicPageRegions {
   header?: PublicPageRegion;
   footer?: PublicPageRegion;
   columns?: readonly PublicPageRegion[];
+  /**
+   * P8.3 — Footnote regions reserved at the bottom of the page (above the
+   * footer band). Mirrors `RuntimePageRegions.footnotes`. Present only
+   * when at least one allocation on this page produced a fragment — see
+   * `noteAllocations` for per-note metadata. Additive / back-compat safe.
+   */
+  footnotes?: readonly PublicPageRegion[];
 }
 
 export interface PublicPageRegion {
@@ -134,6 +145,15 @@ export interface PublicPageRegion {
   fragmentCount: number;
 }
 
+/**
+ * P8 — Region kind discriminator used by `PublicRegionBlock` and the
+ * `getStoryBlocksForRegion` API.  Mirrors `PublicPageRegion["kind"]` plus
+ * `"endnote-area"`, which is only ever surfaced via
+ * `getDocumentEndnoteBlocks` (endnotes have document-end placement and
+ * never sit on a body page).
+ */
+export type PublicRegionKind = PublicPageRegion["kind"] | "endnote-area";
+
 export interface PublicBlockFragment {
   fragmentId: string;
   blockId: string;
@@ -146,6 +166,29 @@ export interface PublicBlockFragment {
   orderInRegion: number;
 }
 
+/**
+ * P8 — One block snapshot rendered into a region of a page.  Returned by
+ * `WordReviewEditorLayoutFacet.getStoryBlocksForRegion` and
+ * `getDocumentEndnoteBlocks`.
+ *
+ * The `blockSnapshot` field is the same `SurfaceBlockSnapshot` consumed by
+ * the body block renderer (`tw-page-block-view`), so region renderers reuse
+ * body typography verbatim.  For body fragments `runtimeFromOffset`/`To`
+ * mirror the underlying `RuntimeBlockFragment.from`/`to`.  For header /
+ * footer / footnote-area blocks the offsets are local to the host story
+ * (header story, footer story, or note body).
+ */
+export interface PublicRegionBlock {
+  blockId: string;
+  fragmentId: string;
+  pageIndex: number;
+  regionKind: PublicRegionKind;
+  runtimeFromOffset: number;
+  runtimeToOffset: number;
+  heightTwips: number;
+  blockSnapshot: SurfaceBlockSnapshot;
+}
+
 export interface PublicLineBox {
   fragmentId: string;
   lineIndex: number;
@@ -376,6 +419,29 @@ export interface WordReviewEditorLayoutFacet {
   getStoryRegionsOnPage(pageIndex: number): readonly PublicPageRegion[];
   getFragmentsForPage(pageIndex: number): PublicBlockFragment[];
 
+  /**
+   * P8 — Returns per-region block snapshots for a page.  Body resolves the
+   * page's body fragments to their `SurfaceBlockSnapshot`s; header / footer
+   * resolve via the page's active story target + `subParts.headers/footers`
+   * lookup; footnote-area resolves per-page `noteAllocations` against
+   * `subParts.footnoteCollection.footnotes`.  Endnote-area is always empty
+   * per-page — document-end placement is handled by
+   * `getDocumentEndnoteBlocks`.  Column falls through to body (multi-column
+   * splitting is a P10 follow-up).  Cached per revision; busts on
+   * `graph.revision` change.
+   */
+  getStoryBlocksForRegion(
+    pageIndex: number,
+    region: PublicPageRegion["kind"],
+    options?: { columnIndex?: number },
+  ): readonly PublicRegionBlock[];
+
+  /**
+   * P8 — Returns endnote bodies in document order for document-end
+   * placement (per OOXML default `w:endnotePr/w:pos="docEnd"`).
+   */
+  getDocumentEndnoteBlocks(): readonly PublicRegionBlock[];
+
   // Page-format catalog --------------------------------------------------
   getPageFormatCatalog(): readonly PageFormatDefinition[];
   getActivePageFormat(sectionIndex: number): ActivePageFormat | null;
@@ -509,6 +575,13 @@ export interface WordReviewEditorLayoutFacet {
 export interface CreateLayoutFacetInput {
   engine: LayoutEngineInstance;
   getQueryInput: () => LayoutEngineQueryInput;
+  /**
+   * P8 — Canonical document accessor used by `getStoryBlocksForRegion` /
+   * `getDocumentEndnoteBlocks` to resolve header / footer / footnote /
+   * endnote stories in `subParts`.  When omitted the facet falls back to
+   * the document available on the engine query input.
+   */
+  canonicalDocument?: () => CanonicalDocumentEnvelope;
   /**
    * Optional render-kernel accessor.  When supplied, the facet exposes
    * `getRenderFrame` + `getRenderZoom` that delegate to the kernel.
@@ -593,6 +666,151 @@ export function createLayoutFacet(
   // Keep the handle alive; the facet instance lives as long as the runtime.
   void unsubscribeEngine;
 
+  // P8 — per-revision cache for getStoryBlocksForRegion.  Identity is
+  // preserved within a single graph revision so consumers can `===`-compare
+  // results across band renders, and the cache flushes whenever the engine
+  // produces a fresh page graph.
+  let regionBlocksCache: {
+    revision: number;
+    byKey: Map<string, readonly PublicRegionBlock[]>;
+  } = { revision: -1, byKey: new Map() };
+  // P8.2.1 — secondary cache keyed by header/footer story-target identity.
+  // A 38-page doc with one default header projects the story once instead of
+  // 38 times; per-page `PublicRegionBlock[]`s still differ (each carries the
+  // page's `pageIndex`), but the underlying `SurfaceBlockSnapshot[]` and
+  // every `blockSnapshot` reference are shared.  Busts together with
+  // `regionBlocksCache` on `graph.revision` change.
+  let storyProjectionCache: {
+    revision: number;
+    byKey: Map<string, readonly SurfaceBlockSnapshot[]>;
+  } = { revision: -1, byKey: new Map() };
+  // P8 — per-revision cache for getDocumentEndnoteBlocks (single key).
+  let endnoteBlocksCache: {
+    revision: number;
+    blocks: readonly PublicRegionBlock[] | null;
+  } = { revision: -1, blocks: null };
+
+  function resolveCanonicalDocument(): CanonicalDocumentEnvelope {
+    if (input.canonicalDocument) {
+      return input.canonicalDocument();
+    }
+    return getQueryInput().document;
+  }
+
+  /**
+   * Build the body story's `SurfaceBlockSnapshot[]` so body fragment
+   * `blockId`s can be resolved.  Cached against the canonical document
+   * identity to avoid re-walking the body on every region read.
+   */
+  let cachedBodySurface: {
+    document: CanonicalDocumentEnvelope;
+    blocks: readonly SurfaceBlockSnapshot[];
+  } | null = null;
+  function bodySurfaceBlocks(): readonly SurfaceBlockSnapshot[] {
+    const document = resolveCanonicalDocument();
+    if (cachedBodySurface && cachedBodySurface.document === document) {
+      return cachedBodySurface.blocks;
+    }
+    const surface = createEditorSurfaceSnapshot(
+      document,
+      createSelectionSnapshot(0, 0),
+      MAIN_STORY_TARGET,
+    );
+    cachedBodySurface = { document, blocks: surface.blocks };
+    return surface.blocks;
+  }
+
+  function findBodyBlockById(
+    blockId: string,
+  ): SurfaceBlockSnapshot | undefined {
+    return bodySurfaceBlocks().find((b) => b.blockId === blockId);
+  }
+
+  function getRegionBlocksCached(
+    pageIndex: number,
+    region: PublicPageRegion["kind"],
+    columnIndex: number | undefined,
+  ): readonly PublicRegionBlock[] {
+    const graph = currentGraph();
+    if (regionBlocksCache.revision !== graph.revision) {
+      regionBlocksCache = { revision: graph.revision, byKey: new Map() };
+      // P8.2.1 — bust the secondary story-projection cache in lock-step so
+      // shared `SurfaceBlockSnapshot`s never outlive their graph revision.
+      storyProjectionCache = { revision: graph.revision, byKey: new Map() };
+      // Body surface depends on the canonical document; the document
+      // identity check inside `bodySurfaceBlocks` keeps it warm across
+      // pure-layout invalidations (zoom, font, etc.).
+    }
+    const key = `${pageIndex}:${region}:${columnIndex ?? "_"}`;
+    const cached = regionBlocksCache.byKey.get(key);
+    if (cached) return cached;
+    const fresh = computeRegionBlocks(pageIndex, region, columnIndex, graph);
+    regionBlocksCache.byKey.set(key, fresh);
+    return fresh;
+  }
+
+  /**
+   * P8.2.1 — shared projection for a header/footer story.  Returns the same
+   * `SurfaceBlockSnapshot[]` array identity for repeated calls at the same
+   * revision so per-page `PublicRegionBlock[]`s can share every
+   * `blockSnapshot` reference.
+   */
+  function getStoryProjectionCached(
+    storyTarget: EditorStoryTarget,
+    document: CanonicalDocumentEnvelope,
+  ): readonly SurfaceBlockSnapshot[] {
+    const key = storyTargetKey(storyTarget);
+    const cached = storyProjectionCache.byKey.get(key);
+    if (cached) return cached;
+    const surface = createEditorSurfaceSnapshot(
+      document,
+      createSelectionSnapshot(0, 0),
+      storyTarget,
+    );
+    const fresh = surface.blocks;
+    storyProjectionCache.byKey.set(key, fresh);
+    return fresh;
+  }
+
+  function computeRegionBlocks(
+    pageIndex: number,
+    region: PublicPageRegion["kind"],
+    columnIndex: number | undefined,
+    graph: RuntimePageGraph,
+  ): readonly PublicRegionBlock[] {
+    const node = graph.pages[pageIndex];
+    if (!node) return Object.freeze([]);
+    const document = resolveCanonicalDocument();
+    if (region === "body") {
+      return resolveBodyRegionBlocks(node, graph, findBodyBlockById);
+    }
+    if (region === "header" || region === "footer") {
+      const story =
+        region === "header" ? node.stories.header : node.stories.footer;
+      if (!story) return Object.freeze([]);
+      // P8.2.1 — share the projected `SurfaceBlockSnapshot[]` across every
+      // page that renders the same story target.
+      const projectedBlocks = getStoryProjectionCached(story, document);
+      return resolveHeaderFooterRegionBlocks(
+        node.pageIndex,
+        region,
+        story,
+        projectedBlocks,
+      );
+    }
+    if (region === "footnote-area") {
+      return resolveFootnoteAreaRegionBlocks(node, document);
+    }
+    if (region === "column") {
+      // Multi-column body splitting is a P10 follow-up.  For now reuse
+      // the body fragments for the indexed column.
+      void columnIndex;
+      return resolveBodyRegionBlocks(node, graph, findBodyBlockById);
+    }
+    // endnote-area: empty per-page; document-end via getDocumentEndnoteBlocks.
+    return Object.freeze([]);
+  }
+
   return {
     getPageCount() {
       return currentGraph().pages.length;
@@ -732,6 +950,69 @@ export function createLayoutFacet(
       return result;
     },
 
+    getStoryBlocksForRegion(pageIndex, region, options) {
+      return getRegionBlocksCached(pageIndex, region, options?.columnIndex);
+    },
+
+    getDocumentEndnoteBlocks() {
+      const graph = currentGraph();
+      if (endnoteBlocksCache.revision === graph.revision && endnoteBlocksCache.blocks) {
+        return endnoteBlocksCache.blocks;
+      }
+      const document = resolveCanonicalDocument();
+      const collection = document.subParts?.footnoteCollection;
+      const blocks: PublicRegionBlock[] = [];
+      if (collection) {
+        // P8.2.1 — batch every endnote body into one
+        // `createEditorSurfaceSnapshot` call.  Previously we called the
+        // projector once per block (50 endnotes × 1 block → 50 full
+        // projections); now we project the flat concatenation once and
+        // slice the result back into per-note groups using the original
+        // block counts.  `runtimeFromOffset` / `runtimeToOffset` inherit
+        // the projection's cumulative cursor (a stable "all-endnotes"
+        // meta-story offset); fragment ids still scope per-note so
+        // consumers can tell which endnote a block belongs to.
+        const groups: Array<{ noteId: string; count: number }> = [];
+        const flat: import("../../model/canonical-document.ts").BlockNode[] = [];
+        for (const noteId of Object.keys(collection.endnotes)) {
+          const note = collection.endnotes[noteId];
+          if (!note || note.blocks.length === 0) continue;
+          groups.push({ noteId, count: note.blocks.length });
+          for (const block of note.blocks) flat.push(block);
+        }
+        if (flat.length > 0) {
+          const surface = createEditorSurfaceSnapshot(
+            {
+              ...document,
+              content: { type: "doc", children: flat },
+            } as CanonicalDocumentEnvelope,
+            createSelectionSnapshot(0, 0),
+          );
+          let cursor = 0;
+          for (const group of groups) {
+            for (let i = 0; i < group.count; i += 1) {
+              const blockSnapshot = surface.blocks[cursor + i];
+              if (!blockSnapshot) continue;
+              blocks.push({
+                blockId: blockSnapshot.blockId,
+                fragmentId: `endnote-${group.noteId}-${i}`,
+                pageIndex: -1,
+                regionKind: "endnote-area",
+                runtimeFromOffset: blockSnapshot.from,
+                runtimeToOffset: blockSnapshot.to,
+                heightTwips: 0,
+                blockSnapshot,
+              });
+            }
+            cursor += group.count;
+          }
+        }
+      }
+      const frozen = Object.freeze(blocks);
+      endnoteBlocksCache = { revision: graph.revision, blocks: frozen };
+      return frozen;
+    },
+
     getPageFormatCatalog() {
       return PAGE_FORMAT_CATALOG;
     },
@@ -1005,6 +1286,9 @@ function toPublicPageRegions(regions: RuntimePageRegions): PublicPageRegions {
     ...(regions.header ? { header: toPublicPageRegion(regions.header) } : {}),
     ...(regions.footer ? { footer: toPublicPageRegion(regions.footer) } : {}),
     ...(regions.columns ? { columns: regions.columns.map(toPublicPageRegion) } : {}),
+    ...(regions.footnotes && regions.footnotes.length > 0
+      ? { footnotes: regions.footnotes.map(toPublicPageRegion) }
+      : {}),
   };
 }
 
@@ -1648,3 +1932,118 @@ function findCanonicalTableByBlockId(
   }
   return null;
 }
+
+// ---------------------------------------------------------------------------
+// P8 — region-block resolvers
+// ---------------------------------------------------------------------------
+
+function resolveBodyRegionBlocks(
+  node: RuntimePageNode,
+  graph: RuntimePageGraph,
+  findBodyBlockById: (blockId: string) => SurfaceBlockSnapshot | undefined,
+): readonly PublicRegionBlock[] {
+  const fragmentsById = new Map<string, RuntimeBlockFragment>();
+  for (const fragment of graph.fragments) {
+    fragmentsById.set(fragment.fragmentId, fragment);
+  }
+  const blocks: PublicRegionBlock[] = [];
+  for (const fragmentId of node.regions.body.fragmentIds) {
+    const fragment = fragmentsById.get(fragmentId);
+    if (!fragment) continue;
+    const blockSnapshot = findBodyBlockById(fragment.blockId);
+    if (!blockSnapshot) continue;
+    blocks.push({
+      blockId: fragment.blockId,
+      fragmentId,
+      pageIndex: node.pageIndex,
+      regionKind: "body",
+      runtimeFromOffset: fragment.from,
+      runtimeToOffset: fragment.to,
+      heightTwips: fragment.heightTwips,
+      blockSnapshot,
+    });
+  }
+  return Object.freeze(blocks);
+}
+
+function resolveHeaderFooterRegionBlocks(
+  pageIndex: number,
+  regionKind: "header" | "footer",
+  storyTarget: EditorStoryTarget,
+  projectedBlocks: readonly SurfaceBlockSnapshot[],
+): readonly PublicRegionBlock[] {
+  if (storyTarget.kind !== regionKind) return Object.freeze([]);
+  if (projectedBlocks.length === 0) return Object.freeze([]);
+  const fragmentBase = `story-${storyTarget.kind}-${storyTarget.relationshipId}-${storyTarget.variant}-${storyTarget.sectionIndex ?? "_"}`;
+  return Object.freeze(
+    projectedBlocks.map((blockSnapshot, index): PublicRegionBlock => ({
+      blockId: blockSnapshot.blockId,
+      fragmentId: `${fragmentBase}-${index}`,
+      pageIndex,
+      regionKind,
+      runtimeFromOffset: blockSnapshot.from,
+      runtimeToOffset: blockSnapshot.to,
+      // Header/footer fragments aren't measured per-block — consumers read
+      // the region's `heightTwips` from `getStoryRegionsOnPage`.
+      heightTwips: 0,
+      blockSnapshot,
+    })),
+  );
+}
+
+function resolveFootnoteAreaRegionBlocks(
+  node: RuntimePageNode,
+  document: CanonicalDocumentEnvelope,
+): readonly PublicRegionBlock[] {
+  const collection = document.subParts?.footnoteCollection;
+  if (!collection) return Object.freeze([]);
+  // P8.2.1 — batch every allocation's body into one
+  // `createEditorSurfaceSnapshot` call and slice the result back into
+  // per-allocation groups.  Amplification per-page is small (a handful of
+  // footnotes), but this mirrors the endnote batching so both paths take
+  // the same shape.  The existence guard on `note` is sufficient — the
+  // previous `void note;` marker is gone.
+  const groups: Array<{
+    allocation: RuntimeNoteAllocation;
+    count: number;
+  }> = [];
+  const flat: import("../../model/canonical-document.ts").BlockNode[] = [];
+  for (const allocation of node.noteAllocations) {
+    if (allocation.noteKind !== "footnote") continue;
+    const note = collection.footnotes[allocation.noteId];
+    if (!note || note.blocks.length === 0) continue;
+    groups.push({ allocation, count: note.blocks.length });
+    for (const block of note.blocks) flat.push(block);
+  }
+  if (flat.length === 0) return Object.freeze([]);
+  const surface = createEditorSurfaceSnapshot(
+    {
+      ...document,
+      content: { type: "doc", children: flat },
+    } as CanonicalDocumentEnvelope,
+    createSelectionSnapshot(0, 0),
+  );
+  const blocks: PublicRegionBlock[] = [];
+  let cursor = 0;
+  for (const group of groups) {
+    const fragmentBase = group.allocation.fragmentId
+      ?? `note-${node.pageIndex}-${group.allocation.noteId}`;
+    for (let i = 0; i < group.count; i += 1) {
+      const blockSnapshot = surface.blocks[cursor + i];
+      if (!blockSnapshot) continue;
+      blocks.push({
+        blockId: blockSnapshot.blockId,
+        fragmentId: `${fragmentBase}-${i}`,
+        pageIndex: node.pageIndex,
+        regionKind: "footnote-area",
+        runtimeFromOffset: blockSnapshot.from,
+        runtimeToOffset: blockSnapshot.to,
+        heightTwips: group.allocation.reservedHeightTwips,
+        blockSnapshot,
+      });
+    }
+    cursor += group.count;
+  }
+  return Object.freeze(blocks);
+}
+

package/src/runtime/perf-counters.ts

@@ -0,0 +1,28 @@
+/**
+ * Lightweight string-keyed counters for L7 render-perf instrumentation.
+ *
+ * Used by the runtime to prove (in tests and benchmarks) that a given
+ * facet rebuild ran or did not run during a sequence of operations.
+ * Phase 0 wires `refresh.all`; Phase 1 will add `facet.<name>.build`
+ * keyed on the per-facet builder.
+ *
+ * Cost guarantee: a `Map<string, number>` increment is < 100 ns. We do
+ * not need atomic counters — JS is single-threaded — and we deliberately
+ * keep the surface tiny so this module can never become a perf footgun
+ * on its own.
+ */
+export class PerfCounters {
+  private readonly counts = new Map<string, number>();
+
+  increment(key: string, delta = 1): void {
+    this.counts.set(key, (this.counts.get(key) ?? 0) + delta);
+  }
+
+  snapshot(): Record<string, number> {
+    return Object.fromEntries(this.counts);
+  }
+
+  reset(): void {
+    this.counts.clear();
+  }
+}

package/src/runtime/render/render-frame-types.ts

@@ -56,6 +56,23 @@ export interface RenderPageRegions {
   footer?: RenderStoryRegion;
   columns?: readonly RenderStoryRegion[];
   footnoteArea?: RenderStoryRegion;
+  /**
+   * P8.3 — footnote areas reserved at the bottom of the page (above the
+   * footer band). Mirrors the page graph's `RuntimePageRegions.footnotes`
+   * — one entry per allocated region (typically one per page today, but
+   * shape allows for multiple should allocation-splitting land).
+   * Populated only when `PublicPageRegions.footnotes` is non-empty.
+   * Additive — back-compat safe; consumers that ignore this field see no
+   * change.
+   */
+  footnotes?: readonly RenderStoryRegion[];
+  /**
+   * P8.3 — endnote regions. Reserved seam; per-page endnote projection is
+   * NOT populated today (endnotes use document-end placement via
+   * `facet.getDocumentEndnoteBlocks()`). Shape exists so a future
+   * per-section endnote renderer has a stable read surface.
+   */
+  endnotes?: readonly RenderStoryRegion[];
 }
 
 export interface RenderStoryRegion {