@beyondwork/docx-react-component 1.0.35 → 1.0.37

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

@@ -0,0 +1,433 @@
+/**
+ * Runtime-owned page graph — a stable, inspectable representation of the
+ * document's paginated structure.
+ *
+ * Per runtime-owned-paginated-layout-engine.md §4, the graph is the logical
+ * successor to `DocumentPageSnapshot[]`. External read models such as
+ * `DocumentNavigationSnapshot` and `PageLayoutSnapshot` are derived from it.
+ *
+ * Enriched in this revision:
+ *   - `regions` per page (body / header / footer / columns)
+ *   - `lineBoxes` per page with block-fragment back-references
+ *   - `noteAllocations` for footnotes reserved on this page
+ *   - `anchors` for quick offset → page lookup
+ *
+ * The graph is produced by the PaginatedLayoutEngine from canonical document
+ * state.  It is never serialized or exported.
+ */
+
+import type {
+  DocumentPageSnapshot,
+  EditorStoryTarget,
+  PageLayoutSnapshot,
+} from "../../api/public-types";
+import type {
+  ResolvedPageStories,
+} from "./page-story-resolver.ts";
+import type { ResolvedDocumentSection } from "../document-layout.ts";
+
+// ---------------------------------------------------------------------------
+// Enriched graph types
+// ---------------------------------------------------------------------------
+
+export interface RuntimePageGraph {
+  /** Monotonically increasing revision stamp. */
+  revision: number;
+  /** Ordered page nodes. */
+  pages: RuntimePageNode[];
+  /** Flat list of every block fragment produced during pagination. */
+  fragments: RuntimeBlockFragment[];
+  /** Per-offset anchor index for O(log n) lookup. */
+  anchors: RuntimePageAnchor[];
+  /** Section metadata. */
+  sections: ResolvedDocumentSection[];
+  /** Total non-blank page count. */
+  contentPageCount: number;
+}
+
+export interface RuntimePageNode {
+  pageId: string;
+  pageIndex: number;
+  sectionIndex: number;
+  pageInSection: number;
+  startOffset: number;
+  endOffset: number;
+  layout: PageLayoutSnapshot;
+  stories: ResolvedPageStories;
+  /** Sub-regions on the page. */
+  regions: RuntimePageRegions;
+  /** Line boxes rendered in the body region. */
+  lineBoxes: RuntimeLineBox[];
+  /** Footnote allocations reserved at the bottom of the page. */
+  noteAllocations: RuntimeNoteAllocation[];
+  /** Whether this page is a blank filler (from even/odd page breaks). */
+  isBlankFiller: boolean;
+}
+
+export interface RuntimePageRegions {
+  body: RuntimePageRegion;
+  header?: RuntimePageRegion;
+  footer?: RuntimePageRegion;
+  /**
+   * For multi-column bodies, `body.columns` is populated.  For single-column
+   * pages, the top-level body is used and `columns` is undefined.
+   */
+  columns?: RuntimePageRegion[];
+}
+
+export interface RuntimePageRegion {
+  kind: "body" | "header" | "footer" | "column" | "footnote-area";
+  /** Twips offset from page top (header) or similar region-specific origin. */
+  originTwips: number;
+  /** Width in twips. */
+  widthTwips: number;
+  /** Height in twips. */
+  heightTwips: number;
+  /** IDs of block fragments rendered in this region, in order. */
+  fragmentIds: string[];
+}
+
+export interface RuntimeBlockFragment {
+  fragmentId: string;
+  /** Canonical block id the fragment slices. */
+  blockId: string;
+  /** Page this fragment lives on. */
+  pageId: string;
+  /** Zero-based order within the page region. */
+  orderInRegion: number;
+  /** Region id the fragment sits in (matches RuntimePageRegion.kind). */
+  regionKind: RuntimePageRegion["kind"];
+  /** Inclusive from / exclusive to offsets within the main story. */
+  from: number;
+  to: number;
+  /** Height consumed on this page (twips). */
+  heightTwips: number;
+}
+
+export interface RuntimeLineBox {
+  /** Fragment this line belongs to. */
+  fragmentId: string;
+  /** Zero-based line index inside the fragment. */
+  lineIndex: number;
+  /** Baseline twips from the region's origin. */
+  baselineTwips: number;
+  /** Line height twips. */
+  heightTwips: number;
+  /** Approximate inline width consumed on this line. */
+  widthTwips: number;
+}
+
+export interface RuntimeNoteAllocation {
+  noteKind: "footnote" | "endnote";
+  noteId: string;
+  /** Twips reserved at the bottom of the page for this note's content. */
+  reservedHeightTwips: number;
+}
+
+export interface RuntimePageAnchor {
+  /** Story target the anchor is for.  Main story is the common case. */
+  storyKey: string;
+  /** Offset the anchor represents. */
+  offset: number;
+  /** Page id resolved for this offset. */
+  pageId: string;
+  /** Fragment id resolved for this offset, if available. */
+  fragmentId?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Graph construction
+// ---------------------------------------------------------------------------
+
+let graphRevision = 0;
+
+export interface BuildPageGraphInput {
+  pages: readonly DocumentPageSnapshot[];
+  sections: readonly ResolvedDocumentSection[];
+  stories: readonly ResolvedPageStories[];
+  /** Optional block fragments pre-computed by pagination; when omitted the
+   *  graph produces one fragment per page spanning its entire offset range. */
+  fragments?: readonly RuntimeBlockFragment[];
+  /** Optional per-page line boxes. */
+  lineBoxes?: ReadonlyMap<string, RuntimeLineBox[]>;
+  /** Optional per-page note allocations. */
+  noteAllocations?: ReadonlyMap<string, RuntimeNoteAllocation[]>;
+}
+
+export function buildPageGraph(input: BuildPageGraphInput): RuntimePageGraph;
+export function buildPageGraph(
+  pages: readonly DocumentPageSnapshot[],
+  sections: readonly ResolvedDocumentSection[],
+  stories: readonly ResolvedPageStories[],
+): RuntimePageGraph;
+export function buildPageGraph(
+  inputOrPages: BuildPageGraphInput | readonly DocumentPageSnapshot[],
+  sectionsArg?: readonly ResolvedDocumentSection[],
+  storiesArg?: readonly ResolvedPageStories[],
+): RuntimePageGraph {
+  const input: BuildPageGraphInput = Array.isArray(inputOrPages)
+    ? {
+        pages: inputOrPages as readonly DocumentPageSnapshot[],
+        sections: sectionsArg ?? [],
+        stories: storiesArg ?? [],
+      }
+    : (inputOrPages as BuildPageGraphInput);
+
+  graphRevision += 1;
+
+  const pages: RuntimePageNode[] = [];
+  const aggregatedFragments: RuntimeBlockFragment[] = [...(input.fragments ?? [])];
+  const anchors: RuntimePageAnchor[] = [];
+
+  for (let index = 0; index < input.pages.length; index += 1) {
+    const page = input.pages[index]!;
+    const pageId = `page-${graphRevision}-${index}`;
+    const stories: ResolvedPageStories = input.stories[index] ?? {
+      isFirstPage: false,
+      isEvenPage: false,
+      displayPageNumber: index + 1,
+    };
+
+    const pageFragments = aggregatedFragments.filter((f) => f.pageId === pageId);
+    const fragmentIds = pageFragments.map((f) => f.fragmentId);
+
+    // If no 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 = {
+        fragmentId: `${pageId}-body-0`,
+        blockId: "synthetic",
+        pageId,
+        orderInRegion: 0,
+        regionKind: "body",
+        from: page.startOffset,
+        to: page.endOffset,
+        heightTwips: 0,
+      };
+      aggregatedFragments.push(coarse);
+      bodyFragmentIds = [coarse.fragmentId];
+    }
+
+    const node: RuntimePageNode = {
+      pageId,
+      pageIndex: page.pageIndex,
+      sectionIndex: page.sectionIndex,
+      pageInSection: page.pageInSection,
+      startOffset: page.startOffset,
+      endOffset: page.endOffset,
+      layout: page.layout,
+      stories,
+      regions: buildRegions(page.layout, bodyFragmentIds, stories),
+      lineBoxes: input.lineBoxes?.get(pageId) ?? [],
+      noteAllocations: input.noteAllocations?.get(pageId) ?? [],
+      isBlankFiller: page.pageInSection === -1,
+    };
+    pages.push(node);
+
+    anchors.push({
+      storyKey: "main",
+      offset: page.startOffset,
+      pageId,
+      ...(bodyFragmentIds[0] !== undefined ? { fragmentId: bodyFragmentIds[0] } : {}),
+    });
+  }
+
+  return {
+    revision: graphRevision,
+    pages,
+    fragments: aggregatedFragments,
+    anchors,
+    sections: [...input.sections],
+    contentPageCount: pages.filter((p) => !p.isBlankFiller).length,
+  };
+}
+
+function buildRegions(
+  layout: PageLayoutSnapshot,
+  bodyFragmentIds: readonly string[],
+  stories: ResolvedPageStories,
+): RuntimePageRegions {
+  const bodyWidth =
+    layout.pageWidth - layout.marginLeft - layout.marginRight;
+  const bodyHeight =
+    layout.pageHeight - layout.marginTop - layout.marginBottom;
+
+  const body: RuntimePageRegion = {
+    kind: "body",
+    originTwips: layout.marginTop,
+    widthTwips: Math.max(0, bodyWidth),
+    heightTwips: Math.max(0, bodyHeight),
+    fragmentIds: [...bodyFragmentIds],
+  };
+
+  const regions: RuntimePageRegions = { body };
+
+  if (stories.header) {
+    regions.header = {
+      kind: "header",
+      originTwips: layout.headerMargin ?? 720,
+      widthTwips: Math.max(0, bodyWidth),
+      heightTwips: Math.max(0, layout.marginTop - (layout.headerMargin ?? 720)),
+      fragmentIds: [],
+    };
+  }
+  if (stories.footer) {
+    regions.footer = {
+      kind: "footer",
+      originTwips: layout.pageHeight - layout.marginBottom,
+      widthTwips: Math.max(0, bodyWidth),
+      heightTwips: Math.max(0, layout.marginBottom - (layout.footerMargin ?? 720)),
+      fragmentIds: [],
+    };
+  }
+
+  if (layout.columns > 1) {
+    const gap = layout.columnDefinitions?.[0]?.space ?? 720;
+    const perColumnWidth = Math.max(
+      1,
+      Math.floor((bodyWidth - gap * (layout.columns - 1)) / layout.columns),
+    );
+    const columns: RuntimePageRegion[] = [];
+    for (let i = 0; i < layout.columns; i += 1) {
+      columns.push({
+        kind: "column",
+        originTwips: layout.marginTop,
+        widthTwips: perColumnWidth,
+        heightTwips: Math.max(0, bodyHeight),
+        fragmentIds: [],
+      });
+    }
+    regions.columns = columns;
+  }
+
+  return regions;
+}
+
+// ---------------------------------------------------------------------------
+// Graph queries
+// ---------------------------------------------------------------------------
+
+export function findPageNodeForOffset(
+  graph: RuntimePageGraph,
+  offset: number,
+): RuntimePageNode | undefined {
+  for (const node of graph.pages) {
+    if (!node.isBlankFiller && offset < node.endOffset) {
+      return node;
+    }
+  }
+  return graph.pages.length > 0
+    ? graph.pages[graph.pages.length - 1]
+    : undefined;
+}
+
+export function findPagesForSection(
+  graph: RuntimePageGraph,
+  sectionIndex: number,
+): RuntimePageNode[] {
+  return graph.pages.filter((node) => node.sectionIndex === sectionIndex);
+}
+
+export function findPageForStoryTarget(
+  graph: RuntimePageGraph,
+  target: EditorStoryTarget,
+): RuntimePageNode | undefined {
+  if (target.kind === "main") {
+    return graph.pages[0];
+  }
+
+  if (target.kind === "header" || target.kind === "footer") {
+    return graph.pages.find((node) => {
+      const story = target.kind === "header" ? node.stories.header : node.stories.footer;
+      if (
+        story?.kind !== target.kind ||
+        story.variant !== target.variant ||
+        story.relationshipId !== target.relationshipId
+      ) {
+        return false;
+      }
+      if (target.sectionIndex !== undefined) {
+        return node.sectionIndex === target.sectionIndex;
+      }
+      return true;
+    });
+  }
+
+  return undefined;
+}
+
+export function toDocumentPageSnapshots(
+  graph: RuntimePageGraph,
+): DocumentPageSnapshot[] {
+  return graph.pages.map((node) => ({
+    pageIndex: node.pageIndex,
+    sectionIndex: node.sectionIndex,
+    pageInSection: node.pageInSection,
+    startOffset: node.startOffset,
+    endOffset: node.endOffset,
+    layout: node.layout,
+  }));
+}
+
+// ---------------------------------------------------------------------------
+// Incremental graph splicing
+// ---------------------------------------------------------------------------
+
+/**
+ * Produce a new graph by preserving `prior.pages[0..firstDirtyIndex - 1]` by
+ * identity and concatenating `freshPages` for the rest of the document.
+ *
+ * The result:
+ *   - bumps the graph revision
+ *   - rebuilds `anchors` from the combined page list
+ *   - filters `fragments` to those whose pageId still exists in the new graph
+ *   - recomputes `contentPageCount` from the new page list
+ *
+ * Page identity is preserved for indices < `firstDirtyIndex`, which is the
+ * invariant the engine relies on to keep stable pageIds for unaffected pages.
+ */
+export function spliceGraph(
+  prior: RuntimePageGraph,
+  freshPages: readonly RuntimePageNode[],
+  firstDirtyIndex: number,
+): RuntimePageGraph {
+  graphRevision += 1;
+  const clampedFirst = Math.max(0, Math.min(firstDirtyIndex, prior.pages.length));
+  const preserved = prior.pages.slice(0, clampedFirst);
+  const nextPages: RuntimePageNode[] = [...preserved, ...freshPages];
+
+  const survivingPageIds = new Set(nextPages.map((page) => page.pageId));
+  const mergedFragments: RuntimeBlockFragment[] = [];
+  for (const fragment of prior.fragments) {
+    if (survivingPageIds.has(fragment.pageId)) {
+      mergedFragments.push(fragment);
+    }
+  }
+  // Fragments attached to fresh pages land in the graph through their page
+  // node (pageId-prefixed synthetic fragments are created during the fresh
+  // build in the same way as buildPageGraph does).  For now fresh pages may
+  // carry no explicit fragments beyond the synthetic body fragment the
+  // layout engine stamped on them; we keep the merged fragment list as a
+  // superset index so mappers can find fragments by pageId.
+
+  const anchors: RuntimePageAnchor[] = nextPages.map((page) => ({
+    storyKey: "main",
+    offset: page.startOffset,
+    pageId: page.pageId,
+    ...(page.regions.body.fragmentIds[0] !== undefined
+      ? { fragmentId: page.regions.body.fragmentIds[0]! }
+      : {}),
+  }));
+
+  const contentPageCount = nextPages.filter((p) => !p.isBlankFiller).length;
+
+  return {
+    revision: graphRevision,
+    pages: nextPages,
+    fragments: mergedFragments,
+    anchors,
+    sections: [...prior.sections],
+    contentPageCount,
+  };
+}

package/src/runtime/layout/page-layout-snapshot-adapter.ts

@@ -0,0 +1,70 @@
+/**
+ * PageLayoutSnapshotAdapter — derives the public `PageLayoutSnapshot` and
+ * `DocumentPageSnapshot[]` shapes from a `RuntimePageGraph`.
+ *
+ * This is the bridge that lets the legacy public snapshots stay byte-for-byte
+ * backward compatible while their implementations move to the runtime-owned
+ * graph.  Per the spec (§Integration With Existing Runtime Surfaces), the
+ * snapshot types remain public and stable; only the source changes.
+ */
+
+import type {
+  DocumentPageSnapshot,
+  PageLayoutSnapshot,
+} from "../../api/public-types";
+import type {
+  RuntimePageGraph,
+  RuntimePageNode,
+} from "./page-graph.ts";
+
+export function derivePageLayoutSnapshotFromGraph(
+  graph: RuntimePageGraph,
+  sectionIndex: number,
+): PageLayoutSnapshot | null {
+  const node = graph.pages.find((page) => page.sectionIndex === sectionIndex);
+  if (node) return node.layout;
+  // Blank filler pages never own sections; fall back to the first page.
+  return graph.pages[0]?.layout ?? null;
+}
+
+export function deriveDocumentPageSnapshots(
+  graph: RuntimePageGraph,
+): DocumentPageSnapshot[] {
+  return graph.pages.map((node) => ({
+    pageIndex: node.pageIndex,
+    sectionIndex: node.sectionIndex,
+    pageInSection: node.pageInSection,
+    startOffset: node.startOffset,
+    endOffset: node.endOffset,
+    layout: node.layout,
+  }));
+}
+
+export function deriveActivePageIndex(
+  graph: RuntimePageGraph,
+  selectionHead: number,
+): number {
+  for (let i = 0; i < graph.pages.length; i += 1) {
+    const page = graph.pages[i]!;
+    if (!page.isBlankFiller && selectionHead < page.endOffset) {
+      return i;
+    }
+  }
+  return Math.max(0, graph.pages.length - 1);
+}
+
+export function deriveActiveSectionIndex(
+  graph: RuntimePageGraph,
+  selectionHead: number,
+): number {
+  const page = deriveActivePage(graph, selectionHead);
+  return page?.sectionIndex ?? 0;
+}
+
+export function deriveActivePage(
+  graph: RuntimePageGraph,
+  selectionHead: number,
+): RuntimePageNode | undefined {
+  const idx = deriveActivePageIndex(graph, selectionHead);
+  return graph.pages[idx];
+}

package/src/runtime/layout/page-story-resolver.ts

@@ -0,0 +1,195 @@
+/**
+ * Page-story resolver — determines which header/footer/note stories
+ * are active on each page based on section properties.
+ *
+ * In OOXML, headers and footers are section-scoped with three variants:
+ * - "default" — used for most pages
+ * - "first"   — used on the first page of a section (when titlePage is set)
+ * - "even"    — used on even pages (when evenAndOddHeaders setting is set)
+ *
+ * This resolver computes per-page story assignment from the page stack
+ * and section properties, making it engine-owned rather than shell-heuristic.
+ */
+
+import type {
+  DocumentPageSnapshot,
+  EditorStoryTarget,
+  PageLayoutSnapshot,
+} from "../../api/public-types";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ResolvedPageStories {
+  /** Header story target for this page, if any. */
+  header?: EditorStoryTarget;
+  /** Footer story target for this page, if any. */
+  footer?: EditorStoryTarget;
+  /** Whether this is a "first page" in its section (title page behavior). */
+  isFirstPage: boolean;
+  /** Whether this is an even-numbered page (1-indexed for display). */
+  isEvenPage: boolean;
+  /** The effective page number for display (accounting for page numbering settings). */
+  displayPageNumber: number;
+}
+
+// ---------------------------------------------------------------------------
+// Resolver
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve header/footer story assignments for every page in the document.
+ */
+export function resolvePageStories(
+  pages: readonly DocumentPageSnapshot[],
+): ResolvedPageStories[] {
+  const result: ResolvedPageStories[] = [];
+  let runningPageNumber = 1;
+
+  for (const page of pages) {
+    const layout = page.layout;
+
+    // Check if section restarts page numbering
+    if (page.pageInSection === 0 && layout.pageNumbering?.start !== undefined) {
+      runningPageNumber = layout.pageNumbering.start;
+    }
+
+    // Skip blank filler pages (from evenPage/oddPage section breaks)
+    if (page.pageInSection === -1) {
+      result.push({
+        isFirstPage: false,
+        isEvenPage: runningPageNumber % 2 === 0,
+        displayPageNumber: runningPageNumber,
+      });
+      runningPageNumber += 1;
+      continue;
+    }
+
+    const isFirstPage = page.pageInSection === 0 && layout.differentFirstPage;
+    const isEvenPage = runningPageNumber % 2 === 0;
+
+    const header = resolveStoryVariant(
+      "header",
+      layout,
+      isFirstPage,
+      isEvenPage,
+    );
+    const footer = resolveStoryVariant(
+      "footer",
+      layout,
+      isFirstPage,
+      isEvenPage,
+    );
+
+    result.push({
+      header,
+      footer,
+      isFirstPage,
+      isEvenPage,
+      displayPageNumber: runningPageNumber,
+    });
+
+    runningPageNumber += 1;
+  }
+
+  return result;
+}
+
+/**
+ * Resolve the display page number for a given page index.
+ */
+export function resolveDisplayPageNumber(
+  pages: readonly DocumentPageSnapshot[],
+  pageIndex: number,
+): number {
+  let runningPageNumber = 1;
+
+  for (let i = 0; i <= pageIndex && i < pages.length; i++) {
+    const page = pages[i]!;
+    if (page.pageInSection === 0 && page.layout.pageNumbering?.start !== undefined) {
+      runningPageNumber = page.layout.pageNumbering.start;
+    }
+    if (i < pageIndex) {
+      runningPageNumber += 1;
+    }
+  }
+
+  return runningPageNumber;
+}
+
+/**
+ * Resolve total page count for NUMPAGES field.
+ */
+export function resolveTotalPageCount(
+  pages: readonly DocumentPageSnapshot[],
+): number {
+  // Exclude blank filler pages from the count
+  return pages.filter((p) => p.pageInSection !== -1).length;
+}
+
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+
+function resolveStoryVariant(
+  kind: "header" | "footer",
+  layout: PageLayoutSnapshot,
+  isFirstPage: boolean,
+  isEvenPage: boolean,
+): EditorStoryTarget | undefined {
+  const variants = kind === "header" ? layout.headerVariants : layout.footerVariants;
+  if (!variants || variants.length === 0) {
+    return undefined;
+  }
+
+  // First page variant takes priority when applicable
+  if (isFirstPage) {
+    const firstVariant = variants.find((v) => v.variant === "first");
+    if (firstVariant) {
+      return {
+        kind,
+        variant: "first",
+        relationshipId: firstVariant.relationshipId,
+        sectionIndex: layout.sectionIndex,
+      };
+    }
+  }
+
+  // Even page variant when evenAndOddHeaders is active
+  if (isEvenPage && layout.differentOddEvenPages) {
+    const evenVariant = variants.find((v) => v.variant === "even");
+    if (evenVariant) {
+      return {
+        kind,
+        variant: "even",
+        relationshipId: evenVariant.relationshipId,
+        sectionIndex: layout.sectionIndex,
+      };
+    }
+  }
+
+  // Default variant
+  const defaultVariant = variants.find((v) => v.variant === "default");
+  if (defaultVariant) {
+    return {
+      kind,
+      variant: "default",
+      relationshipId: defaultVariant.relationshipId,
+      sectionIndex: layout.sectionIndex,
+    };
+  }
+
+  // Fallback to first available variant
+  const first = variants[0];
+  if (first) {
+    return {
+      kind,
+      variant: first.variant,
+      relationshipId: first.relationshipId,
+      sectionIndex: layout.sectionIndex,
+    };
+  }
+
+  return undefined;
+}