@beyondwork/docx-react-component 1.0.37 → 1.0.38

package/src/runtime/document-runtime.ts

@@ -124,11 +124,16 @@ import {
   findPageForOffset,
 } from "./document-navigation.ts";
 import {
+  createDocxFontLoader,
   createLayoutEngine,
   createLayoutFacet,
+  createMeasurementProvider,
+  type DocxFontLoader,
   type LayoutEngineInstance,
+  type LayoutMeasurementProvider,
   type WordReviewEditorLayoutFacet,
 } from "./layout/index.ts";
+import { createRenderKernel, type RenderKernel } from "./render/index.ts";
 import {
   createDocumentOutlineSnapshot,
   createDocumentSectionSnapshots,
@@ -405,7 +410,20 @@ export function createDocumentRuntime(
   // The engine caches graph + resolved-formatting + fragment mapper keyed on
   // (content, styles, subParts).  It is the single internal source of truth
   // for page composition, story resolution, and layout invalidation.
+  //
+  // R0 measurement wiring: the engine starts with the sync empirical backend
+  // so the runtime is available immediately, then we kick off
+  // `createMeasurementProvider({ preference: "auto", fontLoader })` which
+  // upgrades to the canvas backend once fonts resolve.  `swapMeasurementProvider`
+  // emits `measurement_backend_ready` so chrome consumers can re-read metrics.
   const layoutEngine: LayoutEngineInstance = createLayoutEngine();
+  const fontLoader: DocxFontLoader = createDocxFontLoader(
+    collectFontLoaderInput(state.document),
+  );
+  void upgradeMeasurementProvider(layoutEngine, fontLoader);
+  // `renderKernelRef` is a forward reference so the facet can reach the
+  // kernel after it is created below (kernel creation needs the facet).
+  let renderKernelRef: RenderKernel | null = null;
   const layoutFacet: WordReviewEditorLayoutFacet = createLayoutFacet({
     engine: layoutEngine,
     getQueryInput: () => ({
@@ -416,6 +434,27 @@ export function createDocumentRuntime(
         zoomLevel: viewState.zoomLevel,
       },
     }),
+    renderKernel: () => renderKernelRef,
+    getWorkflowRailInput: () => {
+      if (!workflowOverlay) return null;
+      const activeWorkItemId = workflowOverlay.activeWorkItemId ?? null;
+      const activeWorkItem =
+        activeWorkItemId !== null
+          ? workflowOverlay.workItems?.find(
+              (item) => item.workItemId === activeWorkItemId,
+            )
+          : undefined;
+      return {
+        scopes: workflowOverlay.scopes,
+        candidates: workflowOverlay.candidates,
+        activeWorkItemScopeIds: activeWorkItem?.scopeIds ?? [],
+        activeStory,
+      };
+    },
+  });
+  renderKernelRef = createRenderKernel({
+    facet: layoutFacet,
+    getActiveStory: () => activeStory,
   });
   let cachedSurface:
     | {
@@ -2336,6 +2375,14 @@ export function createDocumentRuntime(
       }
     }
 
+    // Font-loader refresh on subParts identity change — this is the
+    // lightweight proxy for "a change that could affect which fonts the
+    // canvas backend measures against".  Typing edits don't rebuild
+    // subParts; style + font + numbering imports do.
+    if (previous.document.subParts !== state.document.subParts) {
+      fontLoader.refresh(collectFontLoaderInput(state.document));
+    }
+
     cachedRenderSnapshot = refreshRenderSnapshot();
     notify(previous, state, transaction);
   }
@@ -4390,3 +4437,70 @@ function remapProtectionSnapshot(
     preservedRangeCount: nextRanges.filter((range) => !range.enforced).length,
   };
 }
+
+// ---------------------------------------------------------------------------
+// Measurement provider wiring (R0)
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the initial input the `DocxFontLoader` needs: a list of font
+ * families the document actively uses, plus any embedded font payloads the
+ * import pipeline may have extracted.
+ *
+ * Walks the document content tree once per call.  Embedded font extraction
+ * is not yet wired into the canonical model; we pass an empty map today and
+ * let the loader register system fonts it finds via
+ * `document.fonts.check(...)`.
+ */
+function collectFontLoaderInput(
+  document: CanonicalDocumentEnvelope,
+): { families: readonly string[] } {
+  try {
+    const families = new Set<string>();
+    const visit = (node: unknown): void => {
+      if (!node || typeof node !== "object") return;
+      const record = node as Record<string, unknown>;
+      const rpr = record["runProperties"] as
+        | Record<string, unknown>
+        | undefined;
+      if (rpr && typeof rpr["fontFamily"] === "string") {
+        families.add(rpr["fontFamily"] as string);
+      }
+      for (const value of Object.values(record)) {
+        if (Array.isArray(value)) value.forEach(visit);
+        else if (value && typeof value === "object") visit(value);
+      }
+    };
+    visit(document.content);
+    if (document.styles) {
+      visit(document.styles);
+    }
+    return { families: Array.from(families) };
+  } catch {
+    return { families: [] };
+  }
+}
+
+/**
+ * Asynchronously upgrade the engine's measurement backend to canvas once
+ * the platform supports it and fonts have resolved.  Errors are swallowed
+ * so a failure in the upgrade path can never break the empirical baseline.
+ */
+async function upgradeMeasurementProvider(
+  engine: LayoutEngineInstance,
+  fontLoader: DocxFontLoader,
+): Promise<void> {
+  try {
+    const provider: LayoutMeasurementProvider = await createMeasurementProvider({
+      preference: "auto",
+      fontLoader,
+    });
+    // If the host is running in SSR or a jsdom test shell, the factory will
+    // fall back to the empirical backend.  In that case swapping is a no-op
+    // but still emits `measurement_backend_ready` with `empirical` which is
+    // informational; chrome consumers use the event to refresh metrics.
+    engine.swapMeasurementProvider(provider);
+  } catch {
+    // fall through — the empirical backend remains in place
+  }
+}

package/src/runtime/layout/default-page-format.ts

@@ -0,0 +1,96 @@
+/**
+ * Locale-aware default page format.
+ *
+ * Word historically defaults to US Letter for `en-US` hosts and A4 everywhere
+ * else.  This module is the single place that decides which format a
+ * newly-created document uses when no section carries an explicit `w:pgSz`.
+ *
+ * It never overrides an existing section's page size on import — importers
+ * always preserve what the source document specified.  The default is
+ * consulted in two places:
+ *
+ *   1. `serialize-main-document.ts` when the canonical model carries a
+ *      section with no `pageSize` (e.g. programmatic document construction).
+ *   2. `DocumentRuntime` when rendering a brand-new blank document.
+ */
+
+import {
+  getPageFormatById,
+  type PageFormatDefinition,
+} from "./page-format-catalog.ts";
+
+// ---------------------------------------------------------------------------
+// Locale resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Which BCP-47 language tags should fall back to Letter.
+ *
+ * Anything else defaults to A4.  This intentionally uses a small whitelist
+ * rather than a `startsWith("en")` check — `en-GB`, `en-AU`, `en-IN` all
+ * expect ISO paper sizes, not US Letter.
+ */
+const LETTER_LOCALES = new Set<string>([
+  "en-us",
+  "en-ca",
+  "fr-ca",
+  "es-mx",
+  "es-cl",
+  "fil-ph",
+]);
+
+export interface ResolveDefaultPageFormatOptions {
+  /** Explicit BCP-47 locale (e.g. "en-US", "de-DE"). */
+  locale?: string;
+}
+
+/**
+ * Return the default `PageFormatDefinition` for a given locale.
+ *
+ * When `locale` is omitted the function consults `Intl.DateTimeFormat` to
+ * infer the current locale.  When `Intl` is unavailable (unusual in modern
+ * runtimes) it falls back to A4 as the safer international default.
+ */
+export function resolveDefaultPageFormat(
+  options: ResolveDefaultPageFormatOptions = {},
+): PageFormatDefinition {
+  const raw = options.locale ?? tryResolveHostLocale();
+  if (!raw) {
+    return getPageFormatById("a4");
+  }
+  const normalized = raw.toLowerCase();
+  if (LETTER_LOCALES.has(normalized)) {
+    return getPageFormatById("letter");
+  }
+  // Match just the language-region prefix (e.g. "en-us-1234" → "en-us")
+  const region = normalized.split("-").slice(0, 2).join("-");
+  if (LETTER_LOCALES.has(region)) {
+    return getPageFormatById("letter");
+  }
+  return getPageFormatById("a4");
+}
+
+function tryResolveHostLocale(): string | undefined {
+  try {
+    if (typeof Intl === "undefined" || typeof Intl.DateTimeFormat !== "function") {
+      return undefined;
+    }
+    return new Intl.DateTimeFormat().resolvedOptions().locale;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Return the default `w:pgSz` payload (width/height in twips) for a given
+ * locale.  Convenience wrapper used by the export pipeline.
+ */
+export function resolveDefaultPageSizeTwips(
+  options: ResolveDefaultPageFormatOptions = {},
+): { widthTwips: number; heightTwips: number } {
+  const format = resolveDefaultPageFormat(options);
+  return {
+    widthTwips: format.portraitWidthTwips,
+    heightTwips: format.portraitHeightTwips,
+  };
+}

package/src/runtime/layout/index.ts

@@ -184,5 +184,50 @@ export {
   type PublicFieldDirtinessReport,
   type LayoutFacetEvent,
   type LayoutFacetInvalidationReason,
+  type RenderZoomSummary,
   type CreateLayoutFacetInput,
+  type PageFormatDefinition,
+  type ActivePageFormat,
+  type MarginPresetDefinition,
+  type ActiveMarginPreset,
 } from "./public-facet.ts";
+
+// ---------------------------------------------------------------------------
+// Page-format catalog + margin preset catalog + locale defaults (R0.5)
+// ---------------------------------------------------------------------------
+
+export {
+  PAGE_FORMAT_CATALOG,
+  matchPageFormat,
+  getPageFormatById,
+  type PageFormatId,
+  type PageFormatRegion,
+  type PageFormatLocaleDefault,
+  type PageFormatDisplay,
+  type MatchPageFormatInput,
+} from "./page-format-catalog.ts";
+
+export {
+  MARGIN_PRESET_CATALOG,
+  matchMarginPreset,
+  getMarginPresetById,
+  type MarginPresetId,
+  type MatchMarginPresetInput,
+} from "./margin-preset-catalog.ts";
+
+export {
+  resolveDefaultPageFormat,
+  resolveDefaultPageSizeTwips,
+  type ResolveDefaultPageFormatOptions,
+} from "./default-page-format.ts";
+
+// ---------------------------------------------------------------------------
+// Workflow rail segments (R3a)
+// ---------------------------------------------------------------------------
+
+export {
+  collectScopeRailSegments,
+  type CollectScopeRailSegmentsInput,
+  type ScopeRailPosture,
+  type ScopeRailSegment,
+} from "../workflow-rail-segments.ts";

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

@@ -12,6 +12,8 @@ import type {
   PublicMeasurementFidelity,
   WordReviewEditorLayoutFacet,
 } from "./public-facet.ts";
+import { MARGIN_PRESET_CATALOG } from "./margin-preset-catalog.ts";
+import { PAGE_FORMAT_CATALOG } from "./page-format-catalog.ts";
 
 export function createInertLayoutFacet(): WordReviewEditorLayoutFacet {
   const emptyReport: PublicFieldDirtinessReport = {
@@ -32,12 +34,24 @@ export function createInertLayoutFacet(): WordReviewEditorLayoutFacet {
     getActiveStoriesOnPage: () => null,
     getDisplayPageNumber: () => null,
     getLineBoxes: () => [],
+    getLineBoxesForRegion: () => [],
     getFragmentsForPage: () => [],
+    getPageFormatCatalog: () => PAGE_FORMAT_CATALOG,
+    getActivePageFormat: () => null,
+    getMarginPresetCatalog: () => MARGIN_PRESET_CATALOG,
+    getActiveMarginPreset: () => null,
+    getRenderFrame: () => null,
+    getRenderZoom: () => null,
+    hitTest: () => null,
+    getAnchorRects: () => [],
+    getScopeRailSegments: () => [],
+    getAllScopeRailSegments: () => [],
     getResolvedFormatting: () => null,
     getResolvedRunFormatting: () => null,
     getMeasurement: () => null,
     getMeasurementFidelity: () => fidelity,
     whenMeasurementReady: () => Promise.resolve(),
+    getTableRenderPlan: () => null,
     getDirtyFieldFamilies: () => [],
     getFieldDirtinessReport: () => emptyReport,
     subscribe: (_listener: (event: LayoutFacetEvent) => void) => () => undefined,

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

@@ -36,6 +36,7 @@ import {
 } 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,
@@ -53,6 +54,7 @@ import {
   type RuntimePageGraph,
   type RuntimePageNode,
 } from "./page-graph.ts";
+import { projectSurfaceBlocksToPageFragments } from "./project-block-fragments.ts";
 import {
   resolvePageStories,
   resolveTotalPageCount,
@@ -242,9 +244,18 @@ export function createLayoutEngine(
       MAIN_STORY_TARGET,
     );
     const sections = buildResolvedSections(document);
-    const pages = buildPageStack(document, sections, mainSurface);
+    const pages = buildPageStack(document, sections, mainSurface, measurementProvider);
     const stories = resolvePageStories(pages);
-    const graph = buildPageGraph({ pages, sections, stories });
+    const fragmentsByPageIndex = projectSurfaceBlocksToPageFragments(
+      mainSurface,
+      pages,
+    );
+    const graph = buildPageGraph({
+      pages,
+      sections,
+      stories,
+      fragmentsByPageIndex,
+    });
 
     // Field dirtiness diff from previous graph
     const dirtyFamilies = computeFieldDirtiness(cachedGraph, graph);
@@ -309,10 +320,16 @@ export function createLayoutEngine(
     const sections = buildResolvedSections(document);
 
     const dirtyPage = priorGraph.pages[firstDirty]!;
-    const freshSnapshots = buildPageStackFrom(document, sections, mainSurface, {
-      startPageIndex: firstDirty,
-      startOffset: dirtyPage.startOffset,
-    });
+    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
@@ -543,13 +560,19 @@ function buildNavigationFromGraph(
 ): 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: buildHeadings(graph),
+      headings,
       activePageIndex,
       activeSectionIndex: deriveActiveSectionIndex(graph, selectionHead),
     };
@@ -564,24 +587,19 @@ function buildNavigationFromGraph(
     return {
       pageCount: pages.length,
       pages,
-      headings: buildHeadings(graph),
+      headings,
       activePageIndex: firstPage >= 0 ? firstPage : 0,
       activeSectionIndex: sectionIndex,
     };
   }
 
   if (activeStory.kind === "footnote" || activeStory.kind === "endnote") {
-    const mainSurface = createEditorSurfaceSnapshot(
-      document,
-      createSelectionSnapshot(0, 0),
-      MAIN_STORY_TARGET,
-    );
     const referencePosition = findNoteReferencePosition(mainSurface, activeStory);
     const activePageIndex = deriveActivePageIndex(graph, referencePosition);
     return {
       pageCount: pages.length,
       pages,
-      headings: buildHeadings(graph),
+      headings,
       activePageIndex,
       activeSectionIndex:
         graph.pages[activePageIndex]?.sectionIndex ??
@@ -592,20 +610,12 @@ function buildNavigationFromGraph(
   return {
     pageCount: pages.length,
     pages,
-    headings: buildHeadings(graph),
+    headings,
     activePageIndex: 0,
     activeSectionIndex: 0,
   };
 }
 
-function buildHeadings(graph: RuntimePageGraph) {
-  // Headings are derived elsewhere (createDocumentNavigationSnapshot pipes
-  // them from its own helper).  For engine-native reads we return an empty
-  // list; the existing navigation snapshot keeps its headings pipeline.
-  void graph;
-  return [];
-}
-
 // ---------------------------------------------------------------------------
 // Convenience: find the active page node directly
 // ---------------------------------------------------------------------------

package/src/runtime/layout/margin-preset-catalog.ts

@@ -0,0 +1,178 @@
+/**
+ * Margin preset catalog — the five named Word margin presets (Normal,
+ * Narrow, Moderate, Wide, Mirrored) plus Custom.
+ *
+ * Values mirror Microsoft Word's defaults in twips so a "Narrow" preset
+ * round-trips to `w:top = 720 / w:bottom = 720 / w:left = 720 / w:right = 720`
+ * on export.
+ */
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export type MarginPresetId =
+  | "normal"
+  | "narrow"
+  | "moderate"
+  | "wide"
+  | "mirrored"
+  | "custom";
+
+export interface MarginPresetDefinition {
+  id: MarginPresetId;
+  label: string;
+  topTwips: number;
+  bottomTwips: number;
+  leftTwips: number;
+  rightTwips: number;
+  gutterTwips: number;
+  mirrored: boolean;
+}
+
+export interface ActiveMarginPreset {
+  sectionIndex: number;
+  preset: MarginPresetDefinition;
+  matchesCatalog: boolean;
+  customTwips?: {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+    gutter: number;
+    mirrored: boolean;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Catalog
+// ---------------------------------------------------------------------------
+
+export const MARGIN_PRESET_CATALOG: readonly MarginPresetDefinition[] = Object.freeze([
+  {
+    id: "normal",
+    label: "Normal",
+    topTwips: 1440,
+    bottomTwips: 1440,
+    leftTwips: 1440,
+    rightTwips: 1440,
+    gutterTwips: 0,
+    mirrored: false,
+  },
+  {
+    id: "narrow",
+    label: "Narrow",
+    topTwips: 720,
+    bottomTwips: 720,
+    leftTwips: 720,
+    rightTwips: 720,
+    gutterTwips: 0,
+    mirrored: false,
+  },
+  {
+    id: "moderate",
+    label: "Moderate",
+    topTwips: 1440,
+    bottomTwips: 1440,
+    leftTwips: 1080,
+    rightTwips: 1080,
+    gutterTwips: 0,
+    mirrored: false,
+  },
+  {
+    id: "wide",
+    label: "Wide",
+    topTwips: 1440,
+    bottomTwips: 1440,
+    leftTwips: 2880,
+    rightTwips: 2880,
+    gutterTwips: 0,
+    mirrored: false,
+  },
+  {
+    id: "mirrored",
+    label: "Mirrored",
+    topTwips: 1440,
+    bottomTwips: 1440,
+    leftTwips: 1800,
+    rightTwips: 1440,
+    gutterTwips: 0,
+    mirrored: true,
+  },
+  {
+    id: "custom",
+    label: "Custom",
+    topTwips: 0,
+    bottomTwips: 0,
+    leftTwips: 0,
+    rightTwips: 0,
+    gutterTwips: 0,
+    mirrored: false,
+  },
+]);
+
+const MATCH_TOLERANCE_TWIPS = 1;
+
+// ---------------------------------------------------------------------------
+// Matching
+// ---------------------------------------------------------------------------
+
+export interface MatchMarginPresetInput {
+  sectionIndex: number;
+  topTwips: number;
+  bottomTwips: number;
+  leftTwips: number;
+  rightTwips: number;
+  gutterTwips: number;
+  mirrored: boolean;
+}
+
+export function matchMarginPreset(
+  input: MatchMarginPresetInput,
+): ActiveMarginPreset {
+  const { sectionIndex, topTwips, bottomTwips, leftTwips, rightTwips, gutterTwips, mirrored } = input;
+
+  for (const preset of MARGIN_PRESET_CATALOG) {
+    if (preset.id === "custom") continue;
+    if (preset.mirrored !== mirrored) continue;
+
+    if (
+      near(preset.topTwips, topTwips) &&
+      near(preset.bottomTwips, bottomTwips) &&
+      near(preset.leftTwips, leftTwips) &&
+      near(preset.rightTwips, rightTwips) &&
+      near(preset.gutterTwips, gutterTwips)
+    ) {
+      return {
+        sectionIndex,
+        preset,
+        matchesCatalog: true,
+      };
+    }
+  }
+
+  const custom = MARGIN_PRESET_CATALOG.find((p) => p.id === "custom")!;
+  return {
+    sectionIndex,
+    preset: custom,
+    matchesCatalog: false,
+    customTwips: {
+      top: topTwips,
+      bottom: bottomTwips,
+      left: leftTwips,
+      right: rightTwips,
+      gutter: gutterTwips,
+      mirrored,
+    },
+  };
+}
+
+function near(a: number, b: number): boolean {
+  return Math.abs(a - b) <= MATCH_TOLERANCE_TWIPS;
+}
+
+export function getMarginPresetById(id: string): MarginPresetDefinition {
+  const found = MARGIN_PRESET_CATALOG.find((p) => p.id === id);
+  if (found) return found;
+  return MARGIN_PRESET_CATALOG.find((p) => p.id === "custom")!;
+}