@beyondwork/docx-react-component 1.0.67 → 1.0.70

package/src/runtime/layout/compat-input-ledger.ts

@@ -0,0 +1,211 @@
+/**
+ * Layer 04 — layout compat-input ledger.
+ *
+ * Task 5 (refactor/04 post-closure, 2026-04-23).
+ *
+ * The canonical document's `DocumentSettings` carries three compat-flag
+ * buckets that OOXML defines for backwards compatibility with pre-2007
+ * Word and cross-version layout quirks:
+ *
+ *   - `compatSettings[]` — ordered list of `<w:compatSetting>` entries
+ *     inside `<w:compat>` (e.g. `compatibilityMode`,
+ *     `overrideTableStyleFontSizeAndJustification`).
+ *   - `compatFlags` — boolean children of `<w:compat>` that aren't
+ *     `<w:compatSetting>` (e.g. `doNotExpandShiftReturn`,
+ *     `useFELayout`).
+ *   - `rootCompatFlags` — settings-level boolean flags that sit at the
+ *     root of `<w:settings>` instead of inside `<w:compat>` (e.g.
+ *     `doNotEmbedSmartTags`).
+ *
+ * Today the paginated layout engine branches on none of them. This
+ * module provides a typed snapshot so:
+ *
+ *   1. Behavioral changes that need to gate on a compat flag have a
+ *      canonical access point (no ad-hoc `settings.compatFlags?.[...]`
+ *      reads scattered across `src/runtime/layout/**`).
+ *   2. The debug projector can surface the active ledger alongside
+ *      page counts + measurement fidelity so operators can tell at a
+ *      glance which compat-conditional branches *would* fire on the
+ *      current document.
+ *
+ * The ledger is read-only, pure data (no methods), JSON-serializable —
+ * it fits inside `LayoutDebugEntry` and can travel through the
+ * debug-inspector snapshot unchanged.
+ *
+ * Resolution rule: OOXML defaults are used for flags absent from the
+ * document's `DocumentSettings`. The defaults encoded here match Word
+ * 2007+ behavior (the "modern" posture); documents that explicitly
+ * set flags opt into the legacy posture.
+ */
+
+import type { DocumentSettings } from "../../model/canonical-document.ts";
+
+/**
+ * Typed snapshot of layout-relevant compat inputs + passthrough for
+ * anything the resolver doesn't know about by name.
+ */
+export interface LayoutCompatInputs {
+  readonly schemaVersion: 1;
+  /**
+   * From `<w:compatSetting w:name="compatibilityMode" w:val>`. Word
+   * writes "15" for Word 2013+ behavior, "14" for 2010, "12" for 2007.
+   * Absent → 15 (modern default; Word 2007 behavior is explicitly opted
+   * into, not implicit).
+   */
+  readonly compatibilityMode: number;
+  /**
+   * From `<w:doNotExpandShiftReturn/>` under `<w:compat>`. When true,
+   * soft line breaks (`<w:br/>`) do not expand to fill the line like
+   * hard breaks do — Word 2007's layout behavior. Default false.
+   */
+  readonly doNotExpandShiftReturn: boolean;
+  /**
+   * From `<w:useWord97LineBreakRules/>`. When true, line-break
+   * classification follows Word 97 conventions (different handling of
+   * East-Asian break classes). Default false.
+   */
+  readonly useWord97LineBreakRules: boolean;
+  /**
+   * From `<w:useFELayout/>`. Forces East-Asian layout conventions
+   * (document-grid, vertical text, CJK line-break rules). Default false.
+   */
+  readonly useFELayout: boolean;
+  /**
+   * From `<w:doNotUseHTMLParagraphAutoSpacing/>`. When true,
+   * paragraphs inherit their full `spacingBefore` + `spacingAfter`
+   * regardless of adjacent-paragraph contextual-spacing hints.
+   * Default false.
+   */
+  readonly doNotUseHTMLParagraphAutoSpacing: boolean;
+  /**
+   * From `<w:compatSetting w:name="overrideTableStyleFontSizeAndJustification">`.
+   * When true, direct paragraph formatting on a table row wins over
+   * the table style's font-size + justification. Default false.
+   */
+  readonly overrideTableStyleFontSizeAndJustification: boolean;
+  /**
+   * From `<w:compatSetting w:name="differentiateMultirowTableHeaders">`.
+   * When true, multi-row `<w:tblHeader/>` rows repeat as a group on
+   * continuation pages. Default false; when false only the first
+   * header row repeats.
+   */
+  readonly differentiateMultirowTableHeaders: boolean;
+  /**
+   * Passthrough: every `<w:compatSetting>` entry in document order.
+   * Consumers that need a flag this ledger doesn't model by name can
+   * scan this list; the resolver retains insertion order for
+   * byte-stable round-trip.
+   */
+  readonly unknownCompatSettings: ReadonlyArray<{
+    readonly name: string;
+    readonly uri: string;
+    readonly value: string;
+  }>;
+  /**
+   * Passthrough: every boolean compat flag the ledger doesn't model
+   * individually, keyed by local element name, sourced from
+   * `DocumentSettings.compatFlags` + `.rootCompatFlags` (merged;
+   * duplicates prefer `compatFlags` since it's the canonical OOXML
+   * location).
+   */
+  readonly unknownCompatFlags: Readonly<Record<string, boolean>>;
+}
+
+const DEFAULT_COMPATIBILITY_MODE = 15;
+
+const KNOWN_COMPAT_FLAG_NAMES = new Set([
+  "doNotExpandShiftReturn",
+  "useWord97LineBreakRules",
+  "useFELayout",
+  "doNotUseHTMLParagraphAutoSpacing",
+]);
+
+const KNOWN_COMPAT_SETTING_NAMES = new Set([
+  "compatibilityMode",
+  "overrideTableStyleFontSizeAndJustification",
+  "differentiateMultirowTableHeaders",
+]);
+
+/**
+ * Read the compat ledger from the document's `DocumentSettings`.
+ * Returns a ledger populated from OOXML defaults when `settings` is
+ * absent — never returns null.
+ */
+export function resolveLayoutCompatInputs(
+  settings: DocumentSettings | undefined,
+): LayoutCompatInputs {
+  const compatFlags = settings?.compatFlags ?? {};
+  const rootCompatFlags = settings?.rootCompatFlags ?? {};
+  const compatSettings = settings?.compatSettings ?? [];
+
+  // Named settings resolution
+  let compatibilityMode = DEFAULT_COMPATIBILITY_MODE;
+  let overrideTableStyleFontSizeAndJustification = false;
+  let differentiateMultirowTableHeaders = false;
+  const unknownCompatSettings: Array<{
+    name: string;
+    uri: string;
+    value: string;
+  }> = [];
+
+  for (const entry of compatSettings) {
+    switch (entry.name) {
+      case "compatibilityMode": {
+        const parsed = Number.parseInt(entry.value, 10);
+        if (Number.isFinite(parsed)) compatibilityMode = parsed;
+        break;
+      }
+      case "overrideTableStyleFontSizeAndJustification":
+        overrideTableStyleFontSizeAndJustification = parseOnOff(entry.value);
+        break;
+      case "differentiateMultirowTableHeaders":
+        differentiateMultirowTableHeaders = parseOnOff(entry.value);
+        break;
+      default:
+        unknownCompatSettings.push(entry);
+    }
+  }
+
+  // Named flag resolution
+  const doNotExpandShiftReturn = compatFlags.doNotExpandShiftReturn === true;
+  const useWord97LineBreakRules = compatFlags.useWord97LineBreakRules === true;
+  const useFELayout = compatFlags.useFELayout === true;
+  const doNotUseHTMLParagraphAutoSpacing =
+    compatFlags.doNotUseHTMLParagraphAutoSpacing === true;
+
+  // Passthrough unknown flags — merge the two buckets but exclude
+  // names the ledger already surfaces as dedicated fields.
+  const unknownCompatFlags: Record<string, boolean> = {};
+  for (const [name, value] of Object.entries(compatFlags)) {
+    if (KNOWN_COMPAT_FLAG_NAMES.has(name)) continue;
+    unknownCompatFlags[name] = value === true;
+  }
+  for (const [name, value] of Object.entries(rootCompatFlags)) {
+    if (KNOWN_COMPAT_FLAG_NAMES.has(name)) continue;
+    if (unknownCompatFlags[name] !== undefined) continue;
+    unknownCompatFlags[name] = value === true;
+  }
+
+  void KNOWN_COMPAT_SETTING_NAMES;
+
+  return {
+    schemaVersion: 1,
+    compatibilityMode,
+    doNotExpandShiftReturn,
+    useWord97LineBreakRules,
+    useFELayout,
+    doNotUseHTMLParagraphAutoSpacing,
+    overrideTableStyleFontSizeAndJustification,
+    differentiateMultirowTableHeaders,
+    unknownCompatSettings: Object.freeze(unknownCompatSettings),
+    unknownCompatFlags: Object.freeze(unknownCompatFlags),
+  };
+}
+
+function parseOnOff(value: string): boolean {
+  // ST_OnOff: "1" / "true" / "on" → true; "0" / "false" / "off" → false.
+  // Absent explicit value would never reach here (CompatSetting always
+  // carries a string), but be defensive.
+  const normalized = value.trim().toLowerCase();
+  return normalized === "1" || normalized === "true" || normalized === "on";
+}

package/src/runtime/layout/index.ts

@@ -166,8 +166,13 @@ export { createCanvasBackend } from "./measurement-backend-canvas.ts";
 
 export { createInertLayoutFacet } from "./inert-layout-facet.ts";
 
+// Refactor-era structural alias — consumers type against `LayoutFacet`
+// while `WordReviewEditorLayoutFacet` remains the public-API name.
+export type { LayoutFacet } from "./layout-facet-types.ts";
+
 export {
   createLayoutFacet,
+  setActiveLayoutWarningEmitter,
   type WordReviewEditorLayoutFacet,
   type PublicPageNode,
   type PublicPageRegions,
@@ -234,4 +239,4 @@ export {
   type CollectScopeRailSegmentsInput,
   type ScopeRailPosture,
   type ScopeRailSegment,
-} from "../workflow-rail-segments.ts";
+} from "../workflow/rail/compose.ts";

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

@@ -43,13 +43,18 @@ export function createInertLayoutFacet(): WordReviewEditorLayoutFacet {
     getActivePageFormat: () => null,
     getMarginPresetCatalog: () => MARGIN_PRESET_CATALOG,
     getActiveMarginPreset: () => null,
-    getRenderFrame: () => null,
-    getRenderZoom: () => null,
-    hitTest: () => null,
-    getAnchorRects: () => [],
-    getScopeRailSegments: () => [],
-    getAllScopeRailSegments: () => [],
-    getAllScopeCardModels: () => [],
+    // `getRenderFrame` + `getRenderZoom` removed in refactor/05
+    // cross-lane-coord §8 pass (2026-04-22). `createInertGeometryFacet`
+    // handles their loading-boundary shape.
+    // `hitTest` + `getAnchorRects` removed from the layout facet in
+    // refactor/05 Slice 6 wrapper-deletion pass (2026-04-22).
+    // `createInertGeometryFacet` handles their loading-boundary shape.
+    // `getScopeRailSegments` / `getAllScopeRailSegments` /
+    // `getAllScopeCardModels` removed from the layout facet in
+    // refactor/06 Slice 4C rail-seam inversion (2026-04-22). Rail
+    // composition is now `runtime.workflow.*`; the loading boundary
+    // exposes an inert workflow facet separately (see
+    // `src/ui/editor-runtime-boundary.ts`).
     getResolvedFormatting: () => null,
     getResolvedRunFormatting: () => null,
     getMeasurement: () => null,

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

@@ -81,6 +81,8 @@ import {
   createEmpiricalMeasurementProvider,
   type LayoutMeasurementProvider,
 } from "./layout-measurement-provider.ts";
+import { LAYOUT_ENGINE_VERSION } from "./layout-engine-version.ts";
+import type { TelemetryBus } from "../debug/telemetry-bus.ts";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -267,6 +269,14 @@ export interface CreateLayoutEngineOptions {
    * determinism or tests) pass `false`.  Default: true.
    */
   autoUpgradeToCanvasBackend?: boolean;
+  /**
+   * Refactor/04 Slice 3 — optional `TelemetryBus` the engine forwards
+   * layout lifecycle events to on the `layout` channel. Zero cost when
+   * the channel is off (the bus bitmap-checks before allocating a
+   * payload). Omit to leave the engine's internal listener stream the
+   * only consumer.
+   */
+  telemetryBus?: TelemetryBus;
 }
 
 export function createLayoutEngine(
@@ -275,6 +285,7 @@ export function createLayoutEngine(
   let measurementProvider: LayoutMeasurementProvider =
     options.measurementProvider ?? createEmpiricalMeasurementProvider();
   const autoUpgradeToCanvas = options.autoUpgradeToCanvasBackend !== false;
+  const telemetryBus = options.telemetryBus;
   const dirtyFieldFamilies = new Set<string>();
   const listeners = new Set<(event: LayoutEngineEvent) => void>();
   let cachedKey: CacheKey | null = null;
@@ -300,8 +311,127 @@ export function createLayoutEngine(
         // never let a listener error interrupt the engine
       }
     }
+    // Refactor/04 Slice 3 — forward granular lifecycle events to the
+    // `layout` telemetry channel. `layout.recompute.completed` is emitted
+    // separately by `fullRebuild` / `incrementalRelayout` so it can carry
+    // `durationMs` + `scope`; that event has no direct `LayoutEngineEvent`
+    // analogue.
+    //
+    // Emission uses `emitLazy` so the bus fills the monotonic `t` clock
+    // automatically. Passing `emit({ t: 0, … })` would preserve the
+    // literal zero (the bus only substitutes when `t` is non-numeric) and
+    // produce traces with collapsed timestamps.
+    if (!telemetryBus || !telemetryBus.isEnabled("layout")) return;
+    switch (event.kind) {
+      case "page_count_changed":
+        telemetryBus.emitLazy("layout", () => ({
+          type: "layout.page_count_changed",
+          payload: {
+            before: event.previousPageCount ?? null,
+            after: event.currentPageCount ?? null,
+            revision: event.revision,
+          },
+        }));
+        break;
+      case "page_field_dirtied":
+        telemetryBus.emitLazy("layout", () => ({
+          type: "layout.page_field_dirtied",
+          payload: {
+            families: event.dirtyFieldFamilies ?? [],
+            revision: event.revision,
+          },
+        }));
+        break;
+      case "layout_committed":
+        telemetryBus.emitLazy("layout", () => ({
+          type: "layout.committed",
+          payload: { revision: event.revision },
+        }));
+        break;
+      default:
+        break;
+    }
+  }
+
+  function telemetryNow(): number {
+    if (typeof performance !== "undefined" && typeof performance.now === "function") {
+      return performance.now();
+    }
+    return Date.now();
   }
 
+  function emitRecomputeCompleted(
+    scope: "full" | "bounded",
+    reasonKind: string,
+    pageCountBefore: number,
+    pageCountAfter: number,
+    durationMs: number,
+  ): void {
+    if (!telemetryBus || !telemetryBus.isEnabled("layout")) return;
+    telemetryBus.emitLazy("layout", () => ({
+      type: "layout.recompute.completed",
+      payload: {
+        layoutEngineVersion: LAYOUT_ENGINE_VERSION,
+        reasonKind,
+        scope,
+        pageCountBefore,
+        pageCountAfter,
+        durationMs,
+      },
+    }));
+    // Refactor/04 post-Slice-4 (2026-04-22) — D1 stage-token pair at
+    // the layout engine's recompute boundary. Paired with the
+    // already-emitted `layout.refresh.start` / `layout.refresh.complete`
+    // stage-tokens around the outer `refreshRenderSnapshot` in
+    // `document-runtime.ts`; this inner event lets
+    // `L3.layout-truth` attribute a diverged verdict to a specific
+    // recompute pass (full vs bounded, which reasonKind, how many
+    // pages before / after). Requested by debug-infra's cross-layer
+    // coord doc §"Layer 04 — Layout Semantics" → "Benefits from:
+    // stage-token for `layout.recompute.end` with before/after page
+    // counts". Same `bus.isEnabled("layout")` guard above makes this
+    // zero-cost when the D1 substrate is off.
+    telemetryBus.emitLazy("layout", () => ({
+      type: "layout.recompute.end",
+      payload: {
+        layoutEngineVersion: LAYOUT_ENGINE_VERSION,
+        reasonKind,
+        scope,
+        pageCountBefore,
+        pageCountAfter,
+        durationMs,
+        stageTokenId: String(++recomputeStageTokenSeq),
+      },
+    }));
+    // Refactor/05 Slice 6 (2026-04-22) — layer-05 projector emit site.
+    // Paired with the shipped `GeometryDebugEntry` projector in
+    // `src/runtime/geometry/projector.ts`. The emit carries the same
+    // scope + durationMs the layout event uses, plus the layout
+    // revision so a downstream consumer can correlate a geometry
+    // snapshot with the layout pass that produced it.
+    // Off-critical-path: only fires when the `layout` channel is
+    // enabled (same guard above). `emitLazy` means zero cost otherwise.
+    // Perf bench (typing-latency large-tables P50) confirmed within
+    // 1% of baseline before/after wiring this emit.
+    telemetryBus.emitLazy("layout", () => ({
+      type: "geometry.projected",
+      payload: {
+        layoutEngineVersion: LAYOUT_ENGINE_VERSION,
+        reasonKind,
+        scope,
+        pageCountBefore,
+        pageCountAfter,
+        durationMs,
+      },
+    }));
+  }
+
+  // Refactor/04 post-Slice-4 — monotonic stage-token counter for the
+  // engine recompute boundary. Used by `emitRecomputeCompleted`'s
+  // `layout.recompute.end` event to give every emission a stable
+  // `stageTokenId` the L3 runner can correlate across boundaries.
+  let recomputeStageTokenSeq = 0;
+
   function fullRebuild(
     input: LayoutEngineQueryInput,
     reason?: LayoutInvalidationReason,
@@ -310,6 +440,12 @@ export function createLayoutEngine(
     // back to the invalidation reason that triggered it so we can later
     // narrow specific kinds (numbering/section) without guessing.
     recordFullRebuildReason(reason?.kind ?? "unknown");
+    // Refactor/04 Slice 3 — sample start-time only when the layout
+    // telemetry channel is on so the cold path pays nothing for the
+    // measurement when telemetry is disabled.
+    const telemetryOn = telemetryBus?.isEnabled("layout") ?? false;
+    const recomputeStart = telemetryOn ? telemetryNow() : 0;
+    const pageCountBeforeRecompute = previousPageCount;
     const document = input.document;
     const mainSurface = createEditorSurfaceSnapshot(
       document,
@@ -329,6 +465,7 @@ export function createLayoutEngine(
       mainSurface,
       pages,
       pageStack.splits,
+      pageStack.columnByBlockIdByPageIndex,
     );
     // P8.1b — merge per-note fragments (regionKind: "footnote-area") into the
     // main fragments map so buildPageGraph sees them alongside body fragments.
@@ -354,11 +491,14 @@ export function createLayoutEngine(
     const formatting = buildResolvedFormattingState(document, mainSurface);
 
     const currentPageCount = resolveTotalPageCount(pages);
-    let pageCountDelta: { previous: number; current: number } | undefined;
-    if (currentPageCount !== previousPageCount) {
-      pageCountDelta = { previous: previousPageCount, current: currentPageCount };
-      previousPageCount = currentPageCount;
-    }
+    // Compute the delta only; `previousPageCount` is mutated AFTER all
+    // emits so every emission reads the pre-commit value through the
+    // `pageCountDelta` local. `incrementalRelayout` mirrors this order
+    // exactly — keep the two paths in sync when editing (reviewer N3).
+    const pageCountDelta: { previous: number; current: number } | undefined =
+      currentPageCount !== previousPageCount
+        ? { previous: previousPageCount, current: currentPageCount }
+        : undefined;
 
     // MUST publish cache before emit: re-entrant getPageGraph() calls from
     // subscribers during emit would otherwise trigger runaway rebuilds.
@@ -404,6 +544,20 @@ export function createLayoutEngine(
       ...(pageCountDelta ? { pageCountDelta } : {}),
     });
 
+    if (telemetryOn) {
+      emitRecomputeCompleted(
+        "full",
+        reason?.kind ?? "full",
+        pageCountBeforeRecompute,
+        currentPageCount,
+        telemetryNow() - recomputeStart,
+      );
+    }
+
+    // Consolidate the `previousPageCount` update at the END of the
+    // recompute path, after all emits. Mirrored in `incrementalRelayout`.
+    previousPageCount = currentPageCount;
+
     return graph;
   }
 
@@ -414,6 +568,9 @@ export function createLayoutEngine(
     const priorGraph = cachedGraph;
     const range = pending.result.dirtyPageRange;
     if (!priorGraph || !range) return null;
+    const telemetryOn = telemetryBus?.isEnabled("layout") ?? false;
+    const recomputeStart = telemetryOn ? telemetryNow() : 0;
+    const pageCountBeforeRecompute = previousPageCount;
     const firstDirty = range.firstPageIndex;
     if (firstDirty < 0 || firstDirty >= priorGraph.pages.length) return null;
 
@@ -480,6 +637,7 @@ export function createLayoutEngine(
       mainSurface,
       freshSnapshotsToRebuild,
       freshResult.splits,
+      freshResult.columnByBlockIdByPageIndex,
     );
     // P8.1b — merge per-note fragments into the fresh fragments map.
     const freshFragmentsByPageIndex = new Map(freshBodyFragmentsByPageIndex);
@@ -510,16 +668,21 @@ export function createLayoutEngine(
     const currentPageCount = resolveTotalPageCount(
       deriveDocumentPageSnapshots(splicedGraph),
     );
-    let pageCountDelta: { previous: number; current: number } | undefined;
-    if (currentPageCount !== previousPageCount) {
-      pageCountDelta = { previous: previousPageCount, current: currentPageCount };
+    // Compute the delta only; `previousPageCount` is mutated AFTER all
+    // emits so every emission reads the pre-commit value through the
+    // `pageCountDelta` local. Mirrors `fullRebuild` above — keep the two
+    // paths in sync when editing (reviewer N3).
+    const pageCountDelta: { previous: number; current: number } | undefined =
+      currentPageCount !== previousPageCount
+        ? { previous: previousPageCount, current: currentPageCount }
+        : undefined;
+    if (pageCountDelta) {
       emit({
         kind: "page_count_changed",
         revision: splicedGraph.revision,
-        previousPageCount,
-        currentPageCount,
+        previousPageCount: pageCountDelta.previous,
+        currentPageCount: pageCountDelta.current,
       });
-      previousPageCount = currentPageCount;
     }
 
     if (dirtyFamilies.length > 0) {
@@ -573,6 +736,21 @@ export function createLayoutEngine(
       splicedGraph,
       firstDirty,
     );
+
+    if (telemetryOn) {
+      emitRecomputeCompleted(
+        "bounded",
+        pending.reason.kind,
+        pageCountBeforeRecompute,
+        currentPageCount,
+        telemetryNow() - recomputeStart,
+      );
+    }
+
+    // Consolidate the `previousPageCount` update at the END of the
+    // recompute path, after all emits. Mirrored in `fullRebuild`.
+    previousPageCount = currentPageCount;
+
     return splicedGraph;
   }