@beyondwork/docx-react-component 1.0.35 → 1.0.37

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

@@ -0,0 +1,705 @@
+/**
+ * Public Layout Facet — the ergonomic surface exposed on
+ * `WordReviewEditorRef.layout`.
+ *
+ * Per the plan (Phase 7), this provides a single coherent object tree for
+ * consumers to walk the layout graph, resolve positions, inspect measurement
+ * state, and observe layout events — without needing to deal with the legacy
+ * opaque JSON snapshots.
+ *
+ * Design rules:
+ *   - Every returned value is a deep-cloned read model.  Internal graph
+ *     identities never escape the facet.
+ *   - Story-aware.  `EditorStoryTarget` is accepted anywhere a position is
+ *     interpreted so header/footer/note queries work cleanly.
+ *   - No DOM.  No PM.  No canonical model leakage.
+ */
+
+import type {
+  EditorStoryTarget,
+  PageLayoutSnapshot,
+  SelectionSnapshot,
+} from "../../api/public-types";
+import type {
+  ResolvedPageStories,
+} from "./page-story-resolver.ts";
+import type {
+  RuntimeBlockFragment,
+  RuntimeLineBox,
+  RuntimeNoteAllocation,
+  RuntimePageGraph,
+  RuntimePageNode,
+  RuntimePageRegion,
+  RuntimePageRegions,
+} from "./page-graph.ts";
+import type {
+  ResolvedFormattingState,
+  ResolvedRunFormatting,
+} from "./resolved-formatting-document.ts";
+import type { ResolvedParagraphFormatting } from "./resolved-formatting-state.ts";
+import type {
+  LayoutEngineEvent,
+  LayoutEngineInstance,
+  LayoutEngineQueryInput,
+} from "./layout-engine-instance.ts";
+import type { PageFragmentMapper } from "./page-fragment-mapper.ts";
+
+// ---------------------------------------------------------------------------
+// Public read model types (shape-stable, cloned at the facet boundary)
+// ---------------------------------------------------------------------------
+
+export interface PublicPageNode {
+  pageId: string;
+  pageIndex: number;
+  sectionIndex: number;
+  pageInSection: number;
+  startOffset: number;
+  endOffset: number;
+  /** Whether this page is a blank filler (e.g. from evenPage/oddPage). */
+  isBlankFiller: boolean;
+  /** Resolved display page number (1-based, honors section restarts). */
+  displayPageNumber: number;
+  /** Whether this is treated as the first page of its section (title page). */
+  isFirstPage: boolean;
+  /** Whether the displayed page number is even. */
+  isEvenPage: boolean;
+  /** Section-derived page layout geometry. */
+  layout: PageLayoutSnapshot;
+  /** Resolved header/footer/note stories active on this page. */
+  stories: PublicResolvedPageStories;
+  /** Sub-regions rendered on the page. */
+  regions: PublicPageRegions;
+  /** Number of line boxes rendered in the body region. */
+  lineBoxCount: number;
+  /** Footnotes reserved at the bottom of the page, if any. */
+  noteAllocations: readonly PublicNoteAllocation[];
+}
+
+export interface PublicResolvedPageStories {
+  header?: EditorStoryTarget;
+  footer?: EditorStoryTarget;
+  isFirstPage: boolean;
+  isEvenPage: boolean;
+  displayPageNumber: number;
+}
+
+export interface PublicPageRegions {
+  body: PublicPageRegion;
+  header?: PublicPageRegion;
+  footer?: PublicPageRegion;
+  columns?: readonly PublicPageRegion[];
+}
+
+export interface PublicPageRegion {
+  kind: "body" | "header" | "footer" | "column" | "footnote-area";
+  originTwips: number;
+  widthTwips: number;
+  heightTwips: number;
+  fragmentCount: number;
+}
+
+export interface PublicBlockFragment {
+  fragmentId: string;
+  blockId: string;
+  pageId: string;
+  pageIndex: number;
+  regionKind: PublicPageRegion["kind"];
+  from: number;
+  to: number;
+  heightTwips: number;
+  orderInRegion: number;
+}
+
+export interface PublicLineBox {
+  fragmentId: string;
+  lineIndex: number;
+  baselineTwips: number;
+  heightTwips: number;
+  widthTwips: number;
+}
+
+export interface PublicNoteAllocation {
+  noteKind: "footnote" | "endnote";
+  noteId: string;
+  reservedHeightTwips: number;
+}
+
+export interface PublicPageAnchor {
+  offset: number;
+  pageId: string;
+  pageIndex: number;
+  fragmentId?: string;
+  regionKind?: PublicPageRegion["kind"];
+}
+
+export interface PublicPageSpan {
+  firstPageIndex: number;
+  lastPageIndex: number;
+  pageCount: number;
+}
+
+export interface PublicSectionNode {
+  sectionIndex: number;
+  startOffset: number;
+  endOffset: number;
+  firstPageIndex: number;
+  lastPageIndex: number;
+  pageCount: number;
+  layout: PageLayoutSnapshot;
+}
+
+export interface PublicResolvedParagraphFormatting {
+  blockId: string;
+  spacingBefore: number;
+  spacingAfter: number;
+  lineHeight: number;
+  lineRule: "auto" | "exact" | "atLeast";
+  indentLeft: number;
+  indentRight: number;
+  firstLineIndent: number;
+  hangingIndent: number;
+  fontSizeHalfPoints: number;
+  averageCharWidthTwips: number;
+  tabStops: readonly {
+    positionTwips: number;
+    alignment: string;
+    leader?: string;
+  }[];
+  keepNext: boolean;
+  keepLines: boolean;
+  pageBreakBefore: boolean;
+  widowControl: boolean;
+  contextualSpacing: boolean;
+}
+
+export interface PublicResolvedRunFormatting {
+  runId: string;
+  blockId: string;
+  fontFamily?: string;
+  fontSizeHalfPoints?: number;
+  bold: boolean;
+  italic: boolean;
+  underline: boolean;
+  strikethrough: boolean;
+  color?: string;
+  highlight?: string;
+  verticalAlign: "baseline" | "superscript" | "subscript";
+}
+
+export interface PublicBlockMeasurement {
+  blockId: string;
+  lineCount: number;
+  /** Total height the block occupies in twips. */
+  heightTwips: number;
+}
+
+export type PublicMeasurementFidelity =
+  | "empirical"
+  | "canvas"
+  | "canvas-with-font-loading";
+
+export interface PublicFieldDirtinessReport {
+  families: readonly string[];
+  revision: number;
+}
+
+export type LayoutFacetEvent =
+  | {
+      kind: "layout_recomputed";
+      revision: number;
+      reason?: LayoutFacetInvalidationReason;
+    }
+  | {
+      kind: "page_count_changed";
+      previous: number;
+      current: number;
+      revision: number;
+    }
+  | {
+      kind: "page_field_dirtied";
+      families: readonly string[];
+      revision: number;
+    }
+  | {
+      kind: "measurement_backend_ready";
+      fidelity: PublicMeasurementFidelity;
+      revision: number;
+    };
+
+export type LayoutFacetInvalidationReason =
+  | { kind: "content-edit"; from: number; to: number }
+  | { kind: "section-change"; sectionIndex: number }
+  | { kind: "styles-change" }
+  | { kind: "theme-change" }
+  | { kind: "numbering-change"; numberingInstanceId?: string }
+  | { kind: "field-refresh"; family?: string }
+  | { kind: "full" };
+
+// ---------------------------------------------------------------------------
+// Facet interface
+// ---------------------------------------------------------------------------
+
+export interface WordReviewEditorLayoutFacet {
+  // Structure ------------------------------------------------------------
+  getPageCount(): number;
+  getPage(pageIndex: number): PublicPageNode | null;
+  getPages(options?: { sectionIndex?: number }): PublicPageNode[];
+  getSection(sectionIndex: number): PublicSectionNode | null;
+  getSections(): PublicSectionNode[];
+
+  // Offset / selection navigation ---------------------------------------
+  getPageForOffset(
+    offset: number,
+    story?: EditorStoryTarget,
+  ): PublicPageNode | null;
+  getPageSpanForSelection(selection: SelectionSnapshot): PublicPageSpan | null;
+  getFragmentForOffset(
+    offset: number,
+    story?: EditorStoryTarget,
+  ): PublicBlockFragment | null;
+  getAnchorForOffset(
+    offset: number,
+    story?: EditorStoryTarget,
+  ): PublicPageAnchor | null;
+
+  // Per-page semantic reads ---------------------------------------------
+  getActiveStoriesOnPage(pageIndex: number): PublicResolvedPageStories | null;
+  getDisplayPageNumber(pageIndex: number): number | null;
+  getLineBoxes(
+    pageIndex: number,
+    options?: { region?: "body" | "header" | "footer" },
+  ): PublicLineBox[];
+  getFragmentsForPage(pageIndex: number): PublicBlockFragment[];
+
+  // Measurement exposure -------------------------------------------------
+  getResolvedFormatting(blockId: string): PublicResolvedParagraphFormatting | null;
+  getResolvedRunFormatting(runId: string): PublicResolvedRunFormatting | null;
+  getMeasurement(blockId: string): PublicBlockMeasurement | null;
+  getMeasurementFidelity(): PublicMeasurementFidelity;
+  whenMeasurementReady(): Promise<void>;
+
+  // Fields ---------------------------------------------------------------
+  getDirtyFieldFamilies(): readonly string[];
+  getFieldDirtinessReport(): PublicFieldDirtinessReport;
+
+  // Events ---------------------------------------------------------------
+  subscribe(listener: (event: LayoutFacetEvent) => void): () => void;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export interface CreateLayoutFacetInput {
+  engine: LayoutEngineInstance;
+  getQueryInput: () => LayoutEngineQueryInput;
+}
+
+export function createLayoutFacet(
+  input: CreateLayoutFacetInput,
+): WordReviewEditorLayoutFacet {
+  const { engine, getQueryInput } = input;
+
+  function currentGraph(): RuntimePageGraph {
+    return engine.getPageGraph(getQueryInput());
+  }
+  function currentMapper(): PageFragmentMapper {
+    return engine.getFragmentMapper(getQueryInput());
+  }
+  function currentFormatting(): ResolvedFormattingState {
+    return engine.getResolvedFormattingState(getQueryInput());
+  }
+
+  const listeners = new Set<(event: LayoutFacetEvent) => void>();
+  const unsubscribeEngine = engine.subscribe((event: LayoutEngineEvent) => {
+    const facetEvent = toFacetEvent(event);
+    if (!facetEvent) return;
+    for (const listener of listeners) {
+      try {
+        listener(facetEvent);
+      } catch {
+        // never let listener errors break the engine
+      }
+    }
+  });
+  // Keep the handle alive; the facet instance lives as long as the runtime.
+  void unsubscribeEngine;
+
+  return {
+    getPageCount() {
+      return currentGraph().pages.length;
+    },
+
+    getPage(pageIndex) {
+      const graph = currentGraph();
+      const node = graph.pages[pageIndex];
+      return node ? toPublicPageNode(node, graph) : null;
+    },
+
+    getPages(options) {
+      const graph = currentGraph();
+      const filtered = options?.sectionIndex !== undefined
+        ? graph.pages.filter((p) => p.sectionIndex === options.sectionIndex)
+        : graph.pages;
+      return filtered.map((node) => toPublicPageNode(node, graph));
+    },
+
+    getSection(sectionIndex) {
+      const graph = currentGraph();
+      return toPublicSectionNode(graph, sectionIndex);
+    },
+
+    getSections() {
+      const graph = currentGraph();
+      return graph.sections
+        .map((section) => toPublicSectionNode(graph, section.index))
+        .filter((node): node is PublicSectionNode => node !== null);
+    },
+
+    getPageForOffset(offset, _story) {
+      const graph = currentGraph();
+      for (const page of graph.pages) {
+        if (!page.isBlankFiller && offset < page.endOffset) {
+          return toPublicPageNode(page, graph);
+        }
+      }
+      const last = graph.pages[graph.pages.length - 1];
+      return last ? toPublicPageNode(last, graph) : null;
+    },
+
+    getPageSpanForSelection(selection) {
+      return currentMapper().mapSelectionToPageSpan(selection);
+    },
+
+    getFragmentForOffset(offset, story) {
+      const mapper = currentMapper();
+      const graph = currentGraph();
+      const location = mapper.mapOffsetToFragment(offset, story);
+      if (!location) return null;
+      const fragment = graph.fragments.find(
+        (f) => f.fragmentId === location.fragmentId,
+      );
+      if (!fragment) return null;
+      return toPublicBlockFragment(fragment, graph);
+    },
+
+    getAnchorForOffset(offset, story) {
+      const mapper = currentMapper();
+      const graph = currentGraph();
+      const anchor = mapper.getAnchorForOffset(offset, story);
+      if (!anchor) return null;
+      const page = graph.pages.find((p) => p.pageId === anchor.pageId);
+      if (!page) return null;
+      const fragmentLocation = mapper.mapOffsetToFragment(offset, story);
+      return {
+        offset: anchor.offset,
+        pageId: anchor.pageId,
+        pageIndex: page.pageIndex,
+        ...(fragmentLocation?.fragmentId !== undefined
+          ? { fragmentId: fragmentLocation.fragmentId }
+          : {}),
+        ...(fragmentLocation?.regionKind !== undefined
+          ? { regionKind: fragmentLocation.regionKind }
+          : {}),
+      };
+    },
+
+    getActiveStoriesOnPage(pageIndex) {
+      const graph = currentGraph();
+      const node = graph.pages[pageIndex];
+      if (!node) return null;
+      return toPublicResolvedPageStories(node.stories);
+    },
+
+    getDisplayPageNumber(pageIndex) {
+      const graph = currentGraph();
+      const node = graph.pages[pageIndex];
+      return node ? node.stories.displayPageNumber : null;
+    },
+
+    getLineBoxes(pageIndex, options) {
+      const graph = currentGraph();
+      const node = graph.pages[pageIndex];
+      if (!node) return [];
+      const region = options?.region ?? "body";
+      // Today all line boxes live on the body.  The region filter is
+      // defensive for when header/footer metrics are also populated.
+      return node.lineBoxes
+        .filter(() => region === "body")
+        .map((box) => toPublicLineBox(box));
+    },
+
+    getFragmentsForPage(pageIndex) {
+      const graph = currentGraph();
+      const node = graph.pages[pageIndex];
+      if (!node) return [];
+      return graph.fragments
+        .filter((f) => f.pageId === node.pageId)
+        .map((f) => toPublicBlockFragment(f, graph));
+    },
+
+    getResolvedFormatting(blockId) {
+      const state = currentFormatting();
+      const formatting = state.paragraphs.get(blockId);
+      if (!formatting) return null;
+      return toPublicParagraphFormatting(blockId, formatting);
+    },
+
+    getResolvedRunFormatting(runId) {
+      const state = currentFormatting();
+      const run = state.runs.get(runId);
+      if (!run) return null;
+      const blockId = runId.split(":")[0] ?? "";
+      return toPublicRunFormatting(runId, blockId, run);
+    },
+
+    getMeasurement(blockId) {
+      const graph = currentGraph();
+      const fragments = graph.fragments.filter((f) => f.blockId === blockId);
+      if (fragments.length === 0) return null;
+      const lineCount = graph.pages.reduce((total, page) => {
+        return (
+          total +
+          page.lineBoxes.filter((line) =>
+            fragments.some((f) => f.fragmentId === line.fragmentId),
+          ).length
+        );
+      }, 0);
+      const heightTwips = fragments.reduce((t, f) => t + f.heightTwips, 0);
+      return {
+        blockId,
+        lineCount,
+        heightTwips,
+      };
+    },
+
+    getMeasurementFidelity() {
+      return engine.measurementFidelity;
+    },
+
+    whenMeasurementReady() {
+      return engine.whenMeasurementReady();
+    },
+
+    getDirtyFieldFamilies() {
+      return engine.getDirtyFieldFamilies();
+    },
+
+    getFieldDirtinessReport() {
+      const graph = currentGraph();
+      return {
+        families: engine.getDirtyFieldFamilies(),
+        revision: graph.revision,
+      };
+    },
+
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Internal: graph → public clones
+// ---------------------------------------------------------------------------
+
+function toPublicPageNode(
+  node: RuntimePageNode,
+  graph: RuntimePageGraph,
+): PublicPageNode {
+  return {
+    pageId: node.pageId,
+    pageIndex: node.pageIndex,
+    sectionIndex: node.sectionIndex,
+    pageInSection: node.pageInSection,
+    startOffset: node.startOffset,
+    endOffset: node.endOffset,
+    isBlankFiller: node.isBlankFiller,
+    displayPageNumber: node.stories.displayPageNumber,
+    isFirstPage: node.stories.isFirstPage,
+    isEvenPage: node.stories.isEvenPage,
+    layout: { ...node.layout },
+    stories: toPublicResolvedPageStories(node.stories),
+    regions: toPublicPageRegions(node.regions),
+    lineBoxCount: node.lineBoxes.length,
+    noteAllocations: node.noteAllocations.map(toPublicNoteAllocation),
+  };
+  void graph; // reserved for future cross-page derivations
+}
+
+function toPublicResolvedPageStories(
+  stories: ResolvedPageStories,
+): PublicResolvedPageStories {
+  return {
+    ...(stories.header ? { header: { ...stories.header } } : {}),
+    ...(stories.footer ? { footer: { ...stories.footer } } : {}),
+    isFirstPage: stories.isFirstPage,
+    isEvenPage: stories.isEvenPage,
+    displayPageNumber: stories.displayPageNumber,
+  };
+}
+
+function toPublicPageRegions(regions: RuntimePageRegions): PublicPageRegions {
+  return {
+    body: toPublicPageRegion(regions.body),
+    ...(regions.header ? { header: toPublicPageRegion(regions.header) } : {}),
+    ...(regions.footer ? { footer: toPublicPageRegion(regions.footer) } : {}),
+    ...(regions.columns ? { columns: regions.columns.map(toPublicPageRegion) } : {}),
+  };
+}
+
+function toPublicPageRegion(region: RuntimePageRegion): PublicPageRegion {
+  return {
+    kind: region.kind,
+    originTwips: region.originTwips,
+    widthTwips: region.widthTwips,
+    heightTwips: region.heightTwips,
+    fragmentCount: region.fragmentIds.length,
+  };
+}
+
+function toPublicBlockFragment(
+  fragment: RuntimeBlockFragment,
+  graph: RuntimePageGraph,
+): PublicBlockFragment {
+  const page = graph.pages.find((p) => p.pageId === fragment.pageId);
+  return {
+    fragmentId: fragment.fragmentId,
+    blockId: fragment.blockId,
+    pageId: fragment.pageId,
+    pageIndex: page?.pageIndex ?? -1,
+    regionKind: fragment.regionKind,
+    from: fragment.from,
+    to: fragment.to,
+    heightTwips: fragment.heightTwips,
+    orderInRegion: fragment.orderInRegion,
+  };
+}
+
+function toPublicLineBox(box: RuntimeLineBox): PublicLineBox {
+  return {
+    fragmentId: box.fragmentId,
+    lineIndex: box.lineIndex,
+    baselineTwips: box.baselineTwips,
+    heightTwips: box.heightTwips,
+    widthTwips: box.widthTwips,
+  };
+}
+
+function toPublicNoteAllocation(note: RuntimeNoteAllocation): PublicNoteAllocation {
+  return {
+    noteKind: note.noteKind,
+    noteId: note.noteId,
+    reservedHeightTwips: note.reservedHeightTwips,
+  };
+}
+
+function toPublicSectionNode(
+  graph: RuntimePageGraph,
+  sectionIndex: number,
+): PublicSectionNode | null {
+  const section = graph.sections.find((s) => s.index === sectionIndex);
+  if (!section) return null;
+  const sectionPages = graph.pages.filter(
+    (p) => p.sectionIndex === sectionIndex,
+  );
+  const firstPage = sectionPages[0];
+  const lastPage = sectionPages[sectionPages.length - 1];
+  if (!firstPage || !lastPage) return null;
+  return {
+    sectionIndex,
+    startOffset: section.start,
+    endOffset: section.end,
+    firstPageIndex: firstPage.pageIndex,
+    lastPageIndex: lastPage.pageIndex,
+    pageCount: sectionPages.length,
+    layout: { ...firstPage.layout },
+  };
+}
+
+function toPublicParagraphFormatting(
+  blockId: string,
+  formatting: ResolvedParagraphFormatting,
+): PublicResolvedParagraphFormatting {
+  return {
+    blockId,
+    spacingBefore: formatting.spacingBefore,
+    spacingAfter: formatting.spacingAfter,
+    lineHeight: formatting.lineHeight,
+    lineRule: formatting.lineRule,
+    indentLeft: formatting.indentLeft,
+    indentRight: formatting.indentRight,
+    firstLineIndent: formatting.firstLineIndent,
+    hangingIndent: formatting.hangingIndent,
+    fontSizeHalfPoints: formatting.fontSizeHalfPoints,
+    averageCharWidthTwips: formatting.averageCharWidthTwips,
+    tabStops: formatting.tabStops.map((tab) => ({
+      positionTwips: tab.position,
+      alignment: tab.align,
+      ...(tab.leader ? { leader: tab.leader } : {}),
+    })),
+    keepNext: formatting.keepNext,
+    keepLines: formatting.keepLines,
+    pageBreakBefore: formatting.pageBreakBefore,
+    widowControl: formatting.widowControl,
+    contextualSpacing: formatting.contextualSpacing,
+  };
+}
+
+function toPublicRunFormatting(
+  runId: string,
+  blockId: string,
+  run: ResolvedRunFormatting,
+): PublicResolvedRunFormatting {
+  return {
+    runId,
+    blockId,
+    ...(run.fontFamily ? { fontFamily: run.fontFamily } : {}),
+    ...(run.fontSizeHalfPoints !== undefined
+      ? { fontSizeHalfPoints: run.fontSizeHalfPoints }
+      : {}),
+    bold: run.bold,
+    italic: run.italic,
+    underline: run.underline,
+    strikethrough: run.strikethrough,
+    ...(run.color ? { color: run.color } : {}),
+    ...(run.highlight ? { highlight: run.highlight } : {}),
+    verticalAlign: run.verticalAlign,
+  };
+}
+
+function toFacetEvent(event: LayoutEngineEvent): LayoutFacetEvent | null {
+  switch (event.kind) {
+    case "layout_recomputed":
+      return {
+        kind: "layout_recomputed",
+        revision: event.revision,
+        ...(event.reason ? { reason: event.reason } : {}),
+      };
+    case "page_count_changed":
+      return {
+        kind: "page_count_changed",
+        previous: event.previousPageCount ?? 0,
+        current: event.currentPageCount ?? 0,
+        revision: event.revision,
+      };
+    case "page_field_dirtied":
+      return {
+        kind: "page_field_dirtied",
+        families: event.dirtyFieldFamilies ?? [],
+        revision: event.revision,
+      };
+    case "measurement_backend_ready":
+      return {
+        kind: "measurement_backend_ready",
+        fidelity:
+          (event.fidelity as PublicMeasurementFidelity | undefined) ?? "empirical",
+        revision: event.revision,
+      };
+    default:
+      return null;
+  }
+}