@beyondwork/docx-react-component 1.0.67 → 1.0.70

package/src/runtime/document-search.ts

@@ -28,7 +28,7 @@ import {
   resolveSectionForStoryTarget,
 } from "./document-layout.ts";
 import { createEditorSurfaceSnapshot } from "./surface-projection.ts";
-import { resolveScope } from "./scope-resolver.ts";
+import { resolveScope } from "./workflow/scope-resolver.ts";
 
 export function searchDocument(
   document: CanonicalDocumentEnvelope,

package/src/runtime/edit-ops/index.ts

@@ -1,6 +1,6 @@
 /**
  * R.2 EditLayer — named module for atomic content mutations. See
- * `docs/plans/lane-1-editing-foundation.md` §R.2.
+ * `CLAUDE.md (lane status table)` §R.2.
  *
  * The layer is a thin named seam over the existing pure functions in
  * `src/core/commands/text-commands.ts`. Each method delegates verbatim — no

package/src/runtime/external-send-runtime.ts

@@ -9,7 +9,7 @@ import type {
 import type { CollabSessionBridge } from "./collab-session-bridge.ts";
 import { resignPayload } from "./resign-payload.ts";
 import type { PayloadSigner } from "../io/ooxml/payload-signature.ts";
-import type { TamperGate } from "./tamper-gate.ts";
+import type { TamperGate } from "./workflow/tamper-gate.ts";
 
 /**
  * Runtime-level composition of the P7 pure pipeline with:

package/src/runtime/formatting/document-lookup.ts

@@ -0,0 +1,235 @@
+/**
+ * Layer 03 — canonical-document lookup helpers.
+ *
+ * Pure, side-effect-free utilities for resolving a `NodeRef` (blockId +
+ * runId/inlineId) back to the canonical paragraph/table/inline node. Each
+ * helper mirrors the synthesis conventions used by
+ * `src/runtime/surface-projection.ts`:
+ *
+ *   - `blockId` is `"paragraph-${N}"` / `"table-${N}"` where N counts
+ *     blocks of that type in `doc.content.children` order (see
+ *     `surface-projection.ts:951` + `:572`).
+ *   - `runId` (a.k.a. `segmentId`) is `"${blockId}-segment-${N}"` where N
+ *     counts segments emitted from a paragraph's inline walk (see
+ *     `surface-projection.ts:1225` + surrounding segment pushes).
+ *
+ * These helpers also accept a `"run-${N}"` legacy form for test
+ *  convenience (Slice 1 + 2 test fixtures used it); Slice-4 closure
+ * documents the canonical form in doc comments.
+ */
+
+import type {
+  CanonicalDocument,
+  CanonicalRunFormatting,
+  InlineNode,
+  ParagraphNode,
+  TableNode,
+  TextMark,
+  TextNode,
+} from "../../model/canonical-document.ts";
+
+export interface FoundParagraph {
+  readonly paragraph: ParagraphNode;
+  /** Paragraph-type block index, matching `paragraph-${N}` synthesis. */
+  readonly paragraphIndex: number;
+  /** Flat index into `doc.content.children` (for callers that need it). */
+  readonly childIndex: number;
+}
+
+export interface FoundTable {
+  readonly table: TableNode;
+  readonly tableIndex: number;
+  readonly childIndex: number;
+}
+
+export interface FoundInline {
+  readonly inline: InlineNode;
+  /** Segment index (matches `paragraph.segments[].segmentId` trailing counter). */
+  readonly segmentIndex: number;
+  /** Flat index into `paragraph.children`. */
+  readonly inlineIndex: number;
+}
+
+export function findParagraphByBlockId(
+  doc: CanonicalDocument,
+  blockId: string,
+): FoundParagraph | undefined {
+  const match = /^paragraph-(\d+)$/.exec(blockId);
+  if (!match) return undefined;
+  const target = Number(match[1]);
+  let paragraphIndex = 0;
+  for (let i = 0; i < doc.content.children.length; i += 1) {
+    const child = doc.content.children[i]!;
+    if (child.type !== "paragraph") continue;
+    if (paragraphIndex === target) {
+      return { paragraph: child, paragraphIndex, childIndex: i };
+    }
+    paragraphIndex += 1;
+  }
+  return undefined;
+}
+
+export function findTableByBlockId(
+  doc: CanonicalDocument,
+  blockId: string,
+): FoundTable | undefined {
+  const match = /^table-(\d+)$/.exec(blockId);
+  if (!match) return undefined;
+  const target = Number(match[1]);
+  let tableIndex = 0;
+  for (let i = 0; i < doc.content.children.length; i += 1) {
+    const child = doc.content.children[i]!;
+    if (child.type !== "table") continue;
+    if (tableIndex === target) {
+      return { table: child, tableIndex, childIndex: i };
+    }
+    tableIndex += 1;
+  }
+  return undefined;
+}
+
+/**
+ * Parse the trailing segment counter from a runId, accepting:
+ *   - canonical form `${blockId}-segment-${N}` (matches surface-projection)
+ *   - legacy form `run-${N}` (used by Slice 1–2 tests; deprecated)
+ *   - bare `${N}` (for programmatic lookups in tests)
+ *
+ * Returns `undefined` when no recognized shape matches — callers must
+ * treat that as a hard miss, not as segment 0.
+ */
+export function parseSegmentIndex(runId: string): number | undefined {
+  const segmentMatch = /-segment-(\d+)$/.exec(runId);
+  if (segmentMatch) return Number(segmentMatch[1]);
+  const runMatch = /^run-(\d+)$/.exec(runId);
+  if (runMatch) return Number(runMatch[1]);
+  if (/^\d+$/.test(runId)) return Number(runId);
+  return undefined;
+}
+
+/**
+ * Inlines that do NOT emit surface segments (i.e., they advance no
+ * document-character cursor). Mirrors `surface-projection.ts:1524–1527`:
+ * bookmark start/end and scope marker start/end are pure markers; they
+ * contribute zero to the segment index.
+ */
+function emitsSegment(inline: InlineNode): boolean {
+  switch (inline.type) {
+    case "bookmark_start":
+    case "bookmark_end":
+    case "scope_marker_start":
+    case "scope_marker_end":
+      return false;
+    default:
+      return true;
+  }
+}
+
+/**
+ * Locate the inline at a given segment index within a paragraph. Walks
+ * `paragraph.children` skipping non-segment-emitters; returns the first
+ * inline whose 0-indexed position among segment-emitters matches
+ * `segmentIndex`. For compound inlines (hyperlinks, fields) that expand
+ * to multiple surface segments, this returns the wrapper inline — the
+ * caller's cascade then sees the wrapper's direct formatting (if any).
+ *
+ * Returns `undefined` when the segment index is out of range.
+ */
+export function findInlineBySegmentIndex(
+  paragraph: ParagraphNode,
+  segmentIndex: number,
+): FoundInline | undefined {
+  let s = 0;
+  for (let i = 0; i < paragraph.children.length; i += 1) {
+    const inline = paragraph.children[i]!;
+    if (!emitsSegment(inline)) continue;
+    if (s === segmentIndex) {
+      return { inline, segmentIndex, inlineIndex: i };
+    }
+    s += 1;
+  }
+  return undefined;
+}
+
+/**
+ * Project a canonical `TextNode.marks` union + `markAttrs`-equivalent
+ * into a `CanonicalRunFormatting`. Mirrors
+ * `surface-projection.ts::buildDirectRunFormattingFromMarks` but
+ * consumes the canonical `TextMark[]` discriminated-union form
+ * directly (surface-projection works with the cloned/flattened form).
+ *
+ * Returns `undefined` when the inline has no marks that map to direct
+ * formatting — so `RunResolveInput.direct` stays `undefined` and the
+ * cascade falls through to paragraph/character/docDefaults as designed.
+ */
+export function canonicalMarksToRunFormatting(
+  marks: readonly TextMark[] | undefined,
+): CanonicalRunFormatting | undefined {
+  if (!marks || marks.length === 0) return undefined;
+  const direct: CanonicalRunFormatting = {};
+  for (const mark of marks) {
+    switch (mark.type) {
+      case "bold":
+        direct.bold = true;
+        break;
+      case "italic":
+        direct.italic = true;
+        break;
+      case "underline":
+        direct.underline = "single";
+        break;
+      case "strikethrough":
+        direct.strikethrough = true;
+        break;
+      case "doubleStrikethrough":
+        direct.doubleStrikethrough = true;
+        break;
+      case "vanish":
+        direct.vanish = true;
+        break;
+      case "smallCaps":
+        direct.smallCaps = true;
+        break;
+      case "fontFamily":
+        direct.fontFamily = mark.val;
+        direct.fontFamilyAscii = mark.val;
+        break;
+      case "fontSize":
+        direct.fontSizeHalfPoints = mark.val;
+        break;
+      case "textColor":
+        direct.colorHex = mark.color.replace(/^#/, "");
+        break;
+      case "highlight":
+        direct.highlight = mark.val;
+        break;
+      case "backgroundColor":
+        direct.highlight = mark.color;
+        break;
+      // Marks without direct CanonicalRunFormatting fields are preserved
+      // on the canonical node for round-trip but don't participate in
+      // cascade direct-formatting: charSpacing, kerning, position, lang,
+      // emboss, imprint, shadow, textFill — kept round-trip only.
+      default:
+        break;
+    }
+  }
+  return Object.keys(direct).length > 0 ? direct : undefined;
+}
+
+/**
+ * Convenience: extract direct run formatting for a segmentId lookup.
+ * Returns `undefined` when the segmentId is unparseable, out of range,
+ * or points at a non-text inline (e.g., a hyperlink wrapper).
+ */
+export function resolveDirectRunFormattingAtSegment(
+  paragraph: ParagraphNode,
+  runId: string,
+): CanonicalRunFormatting | undefined {
+  const segmentIndex = parseSegmentIndex(runId);
+  if (segmentIndex === undefined) return undefined;
+  const found = findInlineBySegmentIndex(paragraph, segmentIndex);
+  if (!found) return undefined;
+  if (found.inline.type !== "text") return undefined;
+  const textNode = found.inline as TextNode;
+  return canonicalMarksToRunFormatting(textNode.marks);
+}

package/src/runtime/formatting/field/registry.ts

@@ -0,0 +1,41 @@
+/**
+ * L03 field-registry rebuild entry point.
+ *
+ * L03 owns field resolution (PAGE / NUMPAGES / PAGEREF / REF / STYLEREF —
+ * see `./resolver.ts`). The registry that feeds the resolver is built
+ * from canonical document content by walking every `field`-kind node
+ * and classifying each by family. The walker + classification helpers
+ * live in `src/io/ooxml/parse-fields.ts` because they share FLDCHAR
+ * parsers + TOC-structure builders with the import path; relocating
+ * the whole file would drag io-local machinery into L03 and widen the
+ * F7 purity seam far beyond what the registry needs.
+ *
+ * This module provides the L03-owned entry point so consumers
+ * (`document-runtime.ts`, `session/import/canonical-assembly.ts`)
+ * import from L03, not from io. Internally it delegates to the io
+ * function — a narrow F7 allowlist entry in
+ * `ci-check-formatting-layer-purity.mjs` records the exception.
+ *
+ * Cross-layer coord: discharges `docs/plans/cross-layer-coord-03.md
+ * §7b` (L02 ask to route registry rebuild through L03). A future
+ * follow-up that splits the io-local FLDCHAR parsers out of
+ * `parse-fields.ts` can collapse this wrapper — the public API
+ * (`rebuildFieldRegistry`) stays stable.
+ */
+
+import { buildFieldRegistry } from "../../../io/ooxml/parse-fields.ts";
+import type { CanonicalDocument, FieldRegistry, SubPartsCatalog } from "../../../model/canonical-document.ts";
+
+/**
+ * Rebuild a field registry from the canonical document state. Consumers
+ * call this when the document content has changed (import, merge, edit
+ * commit) so the registry reflects the current field set. Pure
+ * function — no caching, no side effects.
+ */
+export function rebuildFieldRegistry(
+  document: Pick<CanonicalDocument, "content" | "styles"> & {
+    subParts?: SubPartsCatalog;
+  },
+): FieldRegistry {
+  return buildFieldRegistry(document);
+}

package/src/runtime/{field-resolver.ts → formatting/field/resolver.ts}

@@ -12,8 +12,18 @@ import type {
   InlineNode,
   ParagraphNode,
   StylesCatalog,
-} from "../model/canonical-document.ts";
-import type { RuntimePageGraph, RuntimePageNode } from "./layout/page-graph.ts";
+} from "../../../model/canonical-document.ts";
+import type { RuntimePageGraph, RuntimePageNode } from "../../layout/page-graph.ts";
+
+/**
+ * Layer-03 alias for the layout module's `RuntimePageGraph`. Exists so
+ * that other formatting-layer files (`resolve-effective.ts`) can
+ * reference the page-graph shape without breaking the F7/F8 purity
+ * guard's "one file, one layout import" discipline — this file is the
+ * single documented F8 exception. Re-exports preserve structural identity
+ * at the type level; there is no runtime value.
+ */
+export type { RuntimePageGraph as FieldPageGraph } from "../../layout/page-graph.ts";
 
 // ---------------------------------------------------------------------------
 // Public types
@@ -171,6 +181,21 @@ export function createFieldResolver(input: FieldResolverInput): FieldResolver {
         // preserve the existing display text unchanged.
         return undefined;
 
+      case "NOTEREF":
+      case "SECTIONPAGES":
+        // These families are classified as SupportedFieldFamily (see
+        // `src/model/canonical-document.ts::SupportedFieldFamily`) but
+        // are NOT implemented in the resolver yet. Returning
+        // `refreshStatus: "unresolvable"` is the honest answer — the
+        // caller knows the family is recognized but the runtime has
+        // no resolution path. This distinguishes them from TOC
+        // (intentional `undefined` = preserve existing display) and
+        // from PreserveOnlyFieldFamily (parse-only, no refresh slot).
+        // Tracked in L03 audit 2026-04-22 as Task-4 follow-up: implement
+        // NOTEREF via footnote/endnote anchor lookup + SECTIONPAGES via
+        // pageGraph section-scoped page-count walk.
+        return { displayText: "", refreshStatus: "unresolvable" };
+
       default:
         return undefined;
     }

package/src/runtime/formatting/font-resolution.ts

@@ -0,0 +1,83 @@
+/**
+ * ECMA-376 §17.3.2.26 `<w:rFonts>` family-name precedence.
+ *
+ * Walks `ascii → hAnsi → eastAsia → cs` on the effective run cascade,
+ * with a caller-supplied `themeMinorFont` fallback (Word's default body
+ * typeface). The `fontTable` parameter is reserved for Lane 3a's
+ * measurement backend (substitution based on `w:pitch`); kept on the
+ * signature so the single call site does not change when substitution
+ * ships.
+ *
+ * Extracted from `paragraph-style-resolver.ts` in Slice 2 of the
+ * layer-03 refactor. See `docs/plans/refactor/03-formatting-semantics.md`.
+ *
+ * Theme-slot resolution (L03 audit §A2, 2026-04-23): when a run binds
+ * a typeface via `<w:rFonts w:asciiTheme="majorHAnsi"/>` the resolver
+ * resolves the slot through the optional `themeFontScheme` argument
+ * (caller passes `doc.subParts?.canonicalTheme?.fontScheme`). Concrete
+ * names always win over theme slots per ECMA-376; theme slots only
+ * contribute when the concrete name for the same script is absent.
+ *
+ * Limitation: `ThemeFontScheme` today captures only one `majorFont` +
+ * one `minorFont` typeface (Latin-script). Script-specific slots
+ * (`asciiTheme` vs `eastAsiaTheme` vs `csTheme`) all resolve to the
+ * same concrete font within their major/minor family. Extending the
+ * scheme with per-script typefaces is an L02 follow-up.
+ */
+
+import type {
+  CanonicalFontTable,
+  StylesCatalog,
+  ThemeFontScheme,
+  ThemeFontSlot,
+} from "../../model/canonical-document.ts";
+import {
+  resolveEffectiveRunFormatting,
+  type RunResolveInput,
+} from "./paragraph-style-resolver.ts";
+
+export function resolveRunFontFamily(
+  input: RunResolveInput,
+  catalog: StylesCatalog | undefined,
+  themeMinorFont: string | undefined,
+  fontTable?: CanonicalFontTable | undefined,
+  themeFontScheme?: ThemeFontScheme,
+): string | undefined {
+  void fontTable;
+  const resolved = resolveEffectiveRunFormatting(input, catalog);
+
+  // Concrete name → theme slot → convenience alias → caller fallback.
+  // Each script gets its own concrete-vs-theme decision so a run with
+  // `asciiTheme` but concrete `fontFamilyEastAsia` still picks the
+  // concrete East-Asian name over the theme-resolved Ascii name (ECMA-
+  // 376 §17.3.2.26 script precedence: ascii → hAnsi → eastAsia → cs).
+  const ascii =
+    resolved.fontFamilyAscii ?? resolveSlot(resolved.asciiTheme, themeFontScheme);
+  if (ascii) return ascii;
+
+  const hAnsi =
+    resolved.fontFamilyHAnsi ?? resolveSlot(resolved.hAnsiTheme, themeFontScheme);
+  if (hAnsi) return hAnsi;
+
+  const eastAsia =
+    resolved.fontFamilyEastAsia ??
+    resolveSlot(resolved.eastAsiaTheme, themeFontScheme);
+  if (eastAsia) return eastAsia;
+
+  const cs = resolved.fontFamilyCs ?? resolveSlot(resolved.csTheme, themeFontScheme);
+  if (cs) return cs;
+
+  return resolved.fontFamily ?? themeMinorFont;
+}
+
+function resolveSlot(
+  slot: ThemeFontSlot | undefined,
+  scheme: ThemeFontScheme | undefined,
+): string | undefined {
+  if (!slot || !scheme) return undefined;
+  // The slot's `major*` vs `minor*` prefix picks which family face.
+  // Script suffix (`*Ascii`, `*HAnsi`, `*EastAsia`, `*Bidi`) is retained
+  // on the canonical for round-trip + future per-script resolution but
+  // does not change the lookup today (see file-level limitation note).
+  return slot.startsWith("major") ? scheme.majorFont : scheme.minorFont;
+}