@beyondwork/docx-react-component 1.0.36 → 1.0.38

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

@@ -0,0 +1,628 @@
+/**
+ * LayoutEngineInstance — the stateful `PaginatedLayoutEngine` the architecture
+ * spec describes as `DocumentRuntime`-owned.
+ *
+ * Wraps the stateless `buildPageStack` pipeline and adds:
+ *   - cached graph keyed by (content, styles, subParts, viewState)
+ *   - integrated `PageStoryResolver` on every graph build
+ *   - integrated invalidation analysis (`analyzeInvalidation`)
+ *   - field-dirtiness reporting (`computeFieldDirtiness`)
+ *   - stable access to the enriched page graph + fragment mapper
+ *   - pluggable `LayoutMeasurementProvider` (empirical by default, canvas on
+ *     demand)
+ *
+ * This file intentionally stays additive.  It does not refactor the existing
+ * `buildPageStack` / `computePageStack` exports — instead it consumes them
+ * and layers the graph/resolver/invalidation behavior on top.
+ */
+
+import type {
+  DocumentNavigationSnapshot,
+  DocumentPageSnapshot,
+  EditorStoryTarget,
+  EditorSurfaceSnapshot,
+  PageLayoutSnapshot,
+  SelectionSnapshot,
+} from "../../api/public-types";
+import type {
+  CanonicalDocumentEnvelope,
+} from "../../core/state/editor-state.ts";
+import { MAIN_STORY_TARGET } from "../../core/selection/mapping.ts";
+import { createSelectionSnapshot } from "../../core/state/editor-state.ts";
+import {
+  buildResolvedSections,
+  findSectionForPosition,
+  type ResolvedDocumentSection,
+} from "../document-layout.ts";
+import { findNoteReferencePosition } from "../view-state.ts";
+import { createEditorSurfaceSnapshot } from "../surface-projection.ts";
+import { buildHeadingOutline } from "../document-navigation.ts";
+import {
+  analyzeInvalidation,
+  computeFieldDirtiness,
+  type InvalidationResult,
+} from "./layout-invalidation.ts";
+import {
+  buildPageStack,
+  buildPageStackFrom,
+  type LayoutInvalidationReason,
+} from "./paginated-layout-engine.ts";
+import {
+  buildPageGraph,
+  findPageNodeForOffset,
+  spliceGraph,
+  type RuntimePageGraph,
+  type RuntimePageNode,
+} from "./page-graph.ts";
+import { projectSurfaceBlocksToPageFragments } from "./project-block-fragments.ts";
+import {
+  resolvePageStories,
+  resolveTotalPageCount,
+} from "./page-story-resolver.ts";
+import {
+  deriveActivePage,
+  deriveActivePageIndex,
+  deriveActiveSectionIndex,
+  deriveDocumentPageSnapshots,
+  derivePageLayoutSnapshotFromGraph,
+} from "./page-layout-snapshot-adapter.ts";
+import {
+  buildResolvedFormattingState,
+  type ResolvedFormattingState,
+} from "./resolved-formatting-document.ts";
+import {
+  createPageFragmentMapper,
+  rebuildMapper,
+  type PageFragmentMapper,
+} from "./page-fragment-mapper.ts";
+import {
+  createEmpiricalMeasurementProvider,
+  type LayoutMeasurementProvider,
+} from "./layout-measurement-provider.ts";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface LayoutEngineViewState {
+  /** Active story that scopes story-aware queries. */
+  activeStory?: EditorStoryTarget;
+  workspaceMode?: "canvas" | "page";
+  zoomLevel?: number | "pageWidth" | "onePage";
+}
+
+export interface LayoutEngineQueryInput {
+  document: CanonicalDocumentEnvelope;
+  viewState?: LayoutEngineViewState;
+}
+
+export interface LayoutEngineEvent {
+  kind:
+    | "layout_recomputed"
+    | "incremental_relayout"
+    | "page_count_changed"
+    | "page_field_dirtied"
+    | "measurement_backend_ready";
+  revision: number;
+  previousPageCount?: number;
+  currentPageCount?: number;
+  dirtyFieldFamilies?: readonly string[];
+  reason?: LayoutInvalidationReason;
+  fidelity?: LayoutMeasurementProvider["fidelity"];
+  /** First dirty page index for incremental_relayout events. */
+  firstDirtyPageIndex?: number;
+}
+
+export interface LayoutEngineInstance {
+  /** Current measurement provider fidelity. */
+  readonly measurementFidelity: LayoutMeasurementProvider["fidelity"];
+  /** Await until the measurement provider is fully ready. */
+  whenMeasurementReady(): Promise<void>;
+
+  // ---- graph + snapshots ------------------------------------------------
+  getPageGraph(input: LayoutEngineQueryInput): RuntimePageGraph;
+  getResolvedFormattingState(input: LayoutEngineQueryInput): ResolvedFormattingState;
+  getPageStack(input: LayoutEngineQueryInput): DocumentPageSnapshot[];
+  getPageLayoutSnapshot(
+    input: LayoutEngineQueryInput,
+    sectionIndex: number,
+  ): PageLayoutSnapshot | null;
+  getNavigationSnapshot(
+    input: LayoutEngineQueryInput,
+    selection: SelectionSnapshot,
+    activeStory: EditorStoryTarget,
+  ): DocumentNavigationSnapshot;
+
+  // ---- fragment mapping -------------------------------------------------
+  getFragmentMapper(input: LayoutEngineQueryInput): PageFragmentMapper;
+
+  // ---- invalidation -----------------------------------------------------
+  invalidate(reason: LayoutInvalidationReason): void;
+  analyzeInvalidation(reason: LayoutInvalidationReason): InvalidationResult;
+  getDirtyFieldFamilies(): readonly string[];
+  clearDirtyFieldFamilies(families?: readonly string[]): void;
+
+  // ---- events -----------------------------------------------------------
+  subscribe(listener: (event: LayoutEngineEvent) => void): () => void;
+
+  // ---- measurement plumbing --------------------------------------------
+  swapMeasurementProvider(provider: LayoutMeasurementProvider): void;
+}
+
+// ---------------------------------------------------------------------------
+// Cache key
+// ---------------------------------------------------------------------------
+
+interface CacheKey {
+  content: CanonicalDocumentEnvelope["content"];
+  styles: CanonicalDocumentEnvelope["styles"];
+  subParts: CanonicalDocumentEnvelope["subParts"];
+  // Note: view state does not invalidate the graph itself (graph is global).
+}
+
+// ---------------------------------------------------------------------------
+// Perf-probe helper (§6 E.7)
+// ---------------------------------------------------------------------------
+
+/**
+ * Observation-only counter: every full rebuild bumps
+ * `layout.full.by_reason.<reason.kind>` on `window.__DOCX_REACT_PERF_PROBE__`
+ * so the CCEP typing flow can be instrumented without changing invalidation
+ * routing. Safe in Node environments (window guard), and no-op when the perf
+ * probe has not been enabled (`window.__DOCX_REACT_PERF_PROBE__.enabled`).
+ */
+function recordFullRebuildReason(reasonKind: string): void {
+  if (typeof window === "undefined") return;
+  const probe = (window as unknown as {
+    __DOCX_REACT_PERF_PROBE__?: {
+      enabled?: boolean;
+      invalidationCounts?: Record<string, number>;
+    };
+  }).__DOCX_REACT_PERF_PROBE__;
+  if (!probe?.enabled) return;
+  probe.invalidationCounts ??= {};
+  const totalKey = "layout.full.total";
+  const byReasonKey = `layout.full.by_reason.${reasonKind}`;
+  probe.invalidationCounts[totalKey] = (probe.invalidationCounts[totalKey] ?? 0) + 1;
+  probe.invalidationCounts[byReasonKey] =
+    (probe.invalidationCounts[byReasonKey] ?? 0) + 1;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export interface CreateLayoutEngineOptions {
+  /** Optional measurement provider. Defaults to empirical. */
+  measurementProvider?: LayoutMeasurementProvider;
+}
+
+export function createLayoutEngine(
+  options: CreateLayoutEngineOptions = {},
+): LayoutEngineInstance {
+  let measurementProvider: LayoutMeasurementProvider =
+    options.measurementProvider ?? createEmpiricalMeasurementProvider();
+  const dirtyFieldFamilies = new Set<string>();
+  const listeners = new Set<(event: LayoutEngineEvent) => void>();
+  let cachedKey: CacheKey | null = null;
+  let cachedGraph: RuntimePageGraph | null = null;
+  let cachedFormatting: ResolvedFormattingState | null = null;
+  let cachedMapper: PageFragmentMapper | null = null;
+  let previousPageCount = 0;
+  /**
+   * Invalidation reason stashed by `invalidate()` and consumed on the next
+   * `getGraphInternal()` call.  For bounded scopes this is what lets the
+   * engine splice instead of rebuild.
+   */
+  let pendingInvalidation: {
+    reason: LayoutInvalidationReason;
+    result: InvalidationResult;
+  } | null = null;
+
+  function emit(event: LayoutEngineEvent): void {
+    for (const listener of listeners) {
+      try {
+        listener(event);
+      } catch {
+        // never let a listener error interrupt the engine
+      }
+    }
+  }
+
+  function fullRebuild(
+    input: LayoutEngineQueryInput,
+    reason?: LayoutInvalidationReason,
+  ): RuntimePageGraph {
+    // §6 E.7 — observation-only perf probe. Attribute every full rebuild
+    // back to the invalidation reason that triggered it so we can later
+    // narrow specific kinds (numbering/section) without guessing.
+    recordFullRebuildReason(reason?.kind ?? "unknown");
+    const document = input.document;
+    const mainSurface = createEditorSurfaceSnapshot(
+      document,
+      createSelectionSnapshot(0, 0),
+      MAIN_STORY_TARGET,
+    );
+    const sections = buildResolvedSections(document);
+    const pages = buildPageStack(document, sections, mainSurface, measurementProvider);
+    const stories = resolvePageStories(pages);
+    const fragmentsByPageIndex = projectSurfaceBlocksToPageFragments(
+      mainSurface,
+      pages,
+    );
+    const graph = buildPageGraph({
+      pages,
+      sections,
+      stories,
+      fragmentsByPageIndex,
+    });
+
+    // Field dirtiness diff from previous graph
+    const dirtyFamilies = computeFieldDirtiness(cachedGraph, graph);
+    for (const family of dirtyFamilies) {
+      dirtyFieldFamilies.add(family);
+    }
+
+    const formatting = buildResolvedFormattingState(document, mainSurface);
+
+    const currentPageCount = resolveTotalPageCount(pages);
+    if (currentPageCount !== previousPageCount) {
+      emit({
+        kind: "page_count_changed",
+        revision: graph.revision,
+        previousPageCount,
+        currentPageCount,
+      });
+      previousPageCount = currentPageCount;
+    }
+
+    if (dirtyFamilies.length > 0) {
+      emit({
+        kind: "page_field_dirtied",
+        revision: graph.revision,
+        dirtyFieldFamilies: dirtyFamilies,
+      });
+    }
+
+    emit({
+      kind: "layout_recomputed",
+      revision: graph.revision,
+      ...(reason ? { reason } : {}),
+    });
+
+    cachedKey = {
+      content: document.content,
+      styles: document.styles,
+      subParts: document.subParts,
+    };
+    cachedGraph = graph;
+    cachedFormatting = formatting;
+    cachedMapper = createPageFragmentMapper(graph);
+    return graph;
+  }
+
+  function incrementalRelayout(
+    input: LayoutEngineQueryInput,
+    pending: { reason: LayoutInvalidationReason; result: InvalidationResult },
+  ): RuntimePageGraph | null {
+    const priorGraph = cachedGraph;
+    const range = pending.result.dirtyPageRange;
+    if (!priorGraph || !range) return null;
+    const firstDirty = range.firstPageIndex;
+    if (firstDirty < 0 || firstDirty >= priorGraph.pages.length) return null;
+
+    const document = input.document;
+    const mainSurface = createEditorSurfaceSnapshot(
+      document,
+      createSelectionSnapshot(0, 0),
+      MAIN_STORY_TARGET,
+    );
+    const sections = buildResolvedSections(document);
+
+    const dirtyPage = priorGraph.pages[firstDirty]!;
+    const freshSnapshots = buildPageStackFrom(
+      document,
+      sections,
+      mainSurface,
+      {
+        startPageIndex: firstDirty,
+        startOffset: dirtyPage.startOffset,
+      },
+      measurementProvider,
+    );
+
+    // Convert fresh DocumentPageSnapshots into RuntimePageNodes via the
+    // standard buildPageGraph pipeline — this keeps region, story, and
+    // fragment synthesis consistent with the full-rebuild path.  If the
+    // splice would not preserve the previously-held page count contract
+    // (e.g. the tail is empty because the edit deleted everything past
+    // firstDirty) we fall back to a full rebuild to stay safe.
+    if (freshSnapshots.length === 0 && firstDirty > 0) {
+      return null;
+    }
+    const freshStories = resolvePageStories(freshSnapshots);
+    const freshGraph = buildPageGraph({
+      pages: freshSnapshots,
+      sections,
+      stories: freshStories,
+    });
+    const freshNodes = freshGraph.pages;
+
+    const splicedGraph = spliceGraph(priorGraph, freshNodes, firstDirty);
+
+    // Field dirtiness diff and resolved-formatting update run against the
+    // full spliced graph so NUMPAGES/PAGE tracking remains accurate.
+    const dirtyFamilies = computeFieldDirtiness(priorGraph, splicedGraph);
+    for (const family of dirtyFamilies) {
+      dirtyFieldFamilies.add(family);
+    }
+    const formatting = buildResolvedFormattingState(document, mainSurface);
+
+    const currentPageCount = resolveTotalPageCount(
+      deriveDocumentPageSnapshots(splicedGraph),
+    );
+    if (currentPageCount !== previousPageCount) {
+      emit({
+        kind: "page_count_changed",
+        revision: splicedGraph.revision,
+        previousPageCount,
+        currentPageCount,
+      });
+      previousPageCount = currentPageCount;
+    }
+
+    if (dirtyFamilies.length > 0) {
+      emit({
+        kind: "page_field_dirtied",
+        revision: splicedGraph.revision,
+        dirtyFieldFamilies: dirtyFamilies,
+      });
+    }
+
+    emit({
+      kind: "incremental_relayout",
+      revision: splicedGraph.revision,
+      reason: pending.reason,
+      firstDirtyPageIndex: firstDirty,
+    });
+
+    cachedKey = {
+      content: document.content,
+      styles: document.styles,
+      subParts: document.subParts,
+    };
+    cachedGraph = splicedGraph;
+    cachedFormatting = formatting;
+    cachedMapper = rebuildMapper(
+      cachedMapper ?? createPageFragmentMapper(splicedGraph),
+      splicedGraph,
+      firstDirty,
+    );
+    return splicedGraph;
+  }
+
+  function getGraphInternal(input: LayoutEngineQueryInput): RuntimePageGraph {
+    const document = input.document;
+    const keyEqual =
+      cachedGraph !== null &&
+      cachedKey !== null &&
+      cachedKey.content === document.content &&
+      cachedKey.styles === document.styles &&
+      cachedKey.subParts === document.subParts;
+
+    if (keyEqual && pendingInvalidation === null) {
+      return cachedGraph!;
+    }
+
+    const pending = pendingInvalidation;
+    pendingInvalidation = null;
+
+    if (
+      pending !== null &&
+      pending.result.scope === "bounded" &&
+      cachedGraph !== null
+    ) {
+      const spliced = incrementalRelayout(input, pending);
+      if (spliced !== null) {
+        return spliced;
+      }
+      // Incremental path declined to produce a graph — fall through to full
+      // rebuild using the pending reason so listeners still see the cause.
+      return fullRebuild(input, pending.reason);
+    }
+
+    return fullRebuild(input, pending?.reason);
+  }
+
+  function getMapper(input: LayoutEngineQueryInput): PageFragmentMapper {
+    getGraphInternal(input);
+    return cachedMapper!;
+  }
+
+  function getFormatting(input: LayoutEngineQueryInput): ResolvedFormattingState {
+    getGraphInternal(input);
+    return cachedFormatting!;
+  }
+
+  return {
+    get measurementFidelity() {
+      return measurementProvider.fidelity;
+    },
+
+    whenMeasurementReady() {
+      return measurementProvider.whenReady();
+    },
+
+    getPageGraph(input) {
+      return getGraphInternal(input);
+    },
+
+    getResolvedFormattingState(input) {
+      return getFormatting(input);
+    },
+
+    getPageStack(input) {
+      return deriveDocumentPageSnapshots(getGraphInternal(input));
+    },
+
+    getPageLayoutSnapshot(input, sectionIndex) {
+      return derivePageLayoutSnapshotFromGraph(getGraphInternal(input), sectionIndex);
+    },
+
+    getNavigationSnapshot(input, selection, activeStory) {
+      const graph = getGraphInternal(input);
+      const selectionHead = selection.head;
+      const nav = buildNavigationFromGraph(
+        graph,
+        input.document,
+        activeStory,
+        selectionHead,
+      );
+      return nav;
+    },
+
+    getFragmentMapper(input) {
+      return getMapper(input);
+    },
+
+    invalidate(reason) {
+      const result = analyzeInvalidation(reason, cachedGraph);
+      for (const family of result.dirtyFieldFamilies) {
+        dirtyFieldFamilies.add(family);
+      }
+
+      if (result.scope === "bounded") {
+        // Retain the cache — the next getGraphInternal() call will splice
+        // fresh pages into the preserved prefix.  Only record the pending
+        // reason so the splice path can run.
+        pendingInvalidation = { reason, result };
+      } else {
+        // Full rebuild or field-only refresh: drop the cached graph as
+        // before.  Field families were added above so downstream consumers
+        // still observe a refresh signal for field-only reasons.
+        cachedKey = null;
+        cachedGraph = null;
+        cachedFormatting = null;
+        cachedMapper = null;
+        pendingInvalidation = { reason, result };
+      }
+      // No event emitted here. fullRebuild() and incrementalRelayout() are
+      // the sole emitters of relayout events; they fire once each on the
+      // next getGraphInternal() call with the correct post-recompute
+      // revision.
+    },
+
+    analyzeInvalidation(reason) {
+      return analyzeInvalidation(reason, cachedGraph);
+    },
+
+    getDirtyFieldFamilies() {
+      return Array.from(dirtyFieldFamilies);
+    },
+
+    clearDirtyFieldFamilies(families) {
+      if (!families) {
+        dirtyFieldFamilies.clear();
+        return;
+      }
+      for (const family of families) {
+        dirtyFieldFamilies.delete(family);
+      }
+    },
+
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+
+    swapMeasurementProvider(provider) {
+      measurementProvider = provider;
+      emit({
+        kind: "measurement_backend_ready",
+        revision: cachedGraph?.revision ?? 0,
+        fidelity: provider.fidelity,
+      });
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Navigation derivation from graph
+// ---------------------------------------------------------------------------
+
+function buildNavigationFromGraph(
+  graph: RuntimePageGraph,
+  document: CanonicalDocumentEnvelope,
+  activeStory: EditorStoryTarget,
+  selectionHead: number,
+): DocumentNavigationSnapshot {
+  const pages = deriveDocumentPageSnapshots(graph);
+  const sections = graph.sections;
+  const mainSurface = createEditorSurfaceSnapshot(
+    document,
+    createSelectionSnapshot(0, 0),
+    MAIN_STORY_TARGET,
+  );
+  const headings = buildHeadingOutline(document, mainSurface, sections, pages);
+
+  if (activeStory.kind === "main") {
+    const activePageIndex = deriveActivePageIndex(graph, selectionHead);
+    return {
+      pageCount: pages.length,
+      pages,
+      headings,
+      activePageIndex,
+      activeSectionIndex: deriveActiveSectionIndex(graph, selectionHead),
+    };
+  }
+
+  if (activeStory.kind === "header" || activeStory.kind === "footer") {
+    const sectionIndex =
+      "sectionIndex" in activeStory && typeof activeStory.sectionIndex === "number"
+        ? activeStory.sectionIndex
+        : 0;
+    const firstPage = graph.pages.findIndex((p) => p.sectionIndex === sectionIndex);
+    return {
+      pageCount: pages.length,
+      pages,
+      headings,
+      activePageIndex: firstPage >= 0 ? firstPage : 0,
+      activeSectionIndex: sectionIndex,
+    };
+  }
+
+  if (activeStory.kind === "footnote" || activeStory.kind === "endnote") {
+    const referencePosition = findNoteReferencePosition(mainSurface, activeStory);
+    const activePageIndex = deriveActivePageIndex(graph, referencePosition);
+    return {
+      pageCount: pages.length,
+      pages,
+      headings,
+      activePageIndex,
+      activeSectionIndex:
+        graph.pages[activePageIndex]?.sectionIndex ??
+        findSectionForPosition(sections, referencePosition).index,
+    };
+  }
+
+  return {
+    pageCount: pages.length,
+    pages,
+    headings,
+    activePageIndex: 0,
+    activeSectionIndex: 0,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Convenience: find the active page node directly
+// ---------------------------------------------------------------------------
+
+export function findActivePageNode(
+  graph: RuntimePageGraph,
+  selectionHead: number,
+): RuntimePageNode | undefined {
+  return deriveActivePage(graph, selectionHead) ?? findPageNodeForOffset(graph, selectionHead);
+}