@beyondwork/docx-react-component 1.0.76 → 1.0.77

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.76",
+  "version": "1.0.77",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
   "type": "module",
   "sideEffects": [

package/src/api/v3/ai/resolve.ts

@@ -24,6 +24,8 @@
 
 import type { RuntimeApiHandle } from "../_runtime-handle.ts";
 import {
+  queryScopeAtPosition,
+  queryScopeInRange,
   resolveReference,
   type ResolveReferenceResult as RuntimeResolveResult,
   type ScopeHandle,
@@ -67,13 +69,85 @@ export const resolveReferenceMetadata: ApiV3FnMetadata = {
     boundedScope: "document",
     auditCategory: "reference-resolve",
     contextPromptShape:
-      "Resolve a natural-language hint or structured ScopeReference into a stable scopeId.",
+      "Resolve a durable ScopeReference (scope-id / semantic-path / natural-language) into a stable ScopeHandle. Positional lookups are NOT accepted here — use ai.queryScopeAtPosition / ai.queryScopeInRange for click-to-scope / hit-test flows.",
   },
   stateClass: "A-canonical",
   persistsTo: "canonical",
   rwdReference: "§AI API § ai.resolveReference",
 };
 
+/**
+ * Input for the one-shot positional query entry points.
+ *
+ * Callers MUST treat the input as transient: the position is resolved
+ * against the *current* document state and the returned handle's
+ * `scopeId` becomes the durable reference. Do not store the `at` /
+ * `from`/`to` values — they are meaningless after any intervening
+ * mutation (KI-P9).
+ */
+export interface QueryScopeAtPositionInput {
+  readonly at: number;
+}
+
+export interface QueryScopeInRangeInput {
+  readonly from: number;
+  readonly to: number;
+}
+
+/**
+ * Result of a one-shot positional query. Either the innermost scope
+ * whose range matches the position/range, or `null` when nothing
+ * matches. No `status` union, no `confidence` field — the caller's
+ * next use of the handle is identity-based (via `handle.scopeId`) and
+ * the query itself does not make durable claims.
+ */
+export interface QueryScopePositionResult {
+  readonly handle: ScopeHandle | null;
+}
+
+export const queryScopeAtPositionMetadata: ApiV3FnMetadata = {
+  name: "ai.queryScopeAtPosition",
+  status: "live-with-adapter",
+  sourceLayer: "semantic-scope-compiler",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ai/query-scope-position.test.ts",
+    commit: "pending",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "reference-resolve",
+    contextPromptShape:
+      "One-shot click-to-scope / hit-test lookup. Returns the innermost scope at the given offset, or null. The handle's scopeId is durable; the offset you passed in is NOT — do not store it.",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§AI API § ai.queryScopeAtPosition. Companion to ai.resolveReference for positional lookups — the position-as-reference surface that was conflated pre-2026-04-24 has been split out so positions can't be accidentally round-tripped as durable references (KI-P9).",
+};
+
+export const queryScopeInRangeMetadata: ApiV3FnMetadata = {
+  name: "ai.queryScopeInRange",
+  status: "live-with-adapter",
+  sourceLayer: "semantic-scope-compiler",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ai/query-scope-position.test.ts",
+    commit: "pending",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "reference-resolve",
+    contextPromptShape:
+      "One-shot selection-to-scope lookup. Returns the innermost scope fully containing [from, to], or null. The handle's scopeId is durable; the positions are NOT — do not store them.",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference: "§AI API § ai.queryScopeInRange",
+};
+
 function asReference(input: ResolveReferenceInput): ScopeReference {
   if ("reference" in input) return input.reference;
   return { kind: "natural-language", hint: input.hint };
@@ -117,9 +191,10 @@ function projectResult(raw: RuntimeResolveResult): ResolveReferenceResult {
 export function createResolveFamily(runtime: RuntimeApiHandle) {
   return {
     resolveReference(input: ResolveReferenceInput): ResolveReferenceResult {
-      // @endStateApi — live-with-adapter. Delegates to the scope-compiler
-      // `resolveReference` over the typed ScopeReference union; NL hints
-      // stay at confidence "low" per Slice 3.
+      // @endStateApi — live-with-adapter. Durable identity lookup via
+      // ScopeReference union (scope-id / semantic-path / natural-
+      // language). Positional references are not accepted here — use
+      // queryScopeAtPosition / queryScopeInRange instead.
       const reference = asReference(input);
       if (reference.kind === "natural-language" && reference.hint.trim().length === 0) {
         return { status: "not-found", confidence: "none", reason: "empty hint" };
@@ -129,5 +204,30 @@ export function createResolveFamily(runtime: RuntimeApiHandle) {
       const raw = resolveReference(reference, { document, overlay });
       return projectResult(raw);
     },
+
+    queryScopeAtPosition(
+      input: QueryScopeAtPositionInput,
+    ): QueryScopePositionResult {
+      // @endStateApi — live-with-adapter. One-shot position-to-scope
+      // query. The input offset is transient — callers must use the
+      // returned handle's scopeId as the durable reference, not the
+      // offset (KI-P9).
+      const document = runtime.getCanonicalDocument();
+      const overlay = runtime.getWorkflowOverlay();
+      const handle = queryScopeAtPosition(input.at, { document, overlay });
+      return { handle };
+    },
+
+    queryScopeInRange(input: QueryScopeInRangeInput): QueryScopePositionResult {
+      // @endStateApi — live-with-adapter. One-shot selection-to-scope
+      // query. Same durable-reference contract as queryScopeAtPosition.
+      const document = runtime.getCanonicalDocument();
+      const overlay = runtime.getWorkflowOverlay();
+      const handle = queryScopeInRange(input.from, input.to, {
+        document,
+        overlay,
+      });
+      return { handle };
+    },
   };
 }

package/src/io/ooxml/parse-bookmark-references.ts

@@ -0,0 +1,123 @@
+/**
+ * Phase 2 bookmark-strip reference scanner.
+ *
+ * Walks the source main-document XML and collects the names of
+ * bookmarks that are LOAD-BEARING — i.e. referenced by:
+ *
+ *   1. A hyperlink anchor (`<w:hyperlink w:anchor="NAME">`). This
+ *      catches `HYPERLINK \l "NAME"` field references too — Word
+ *      always emits the anchor on the surrounding `<w:hyperlink>`
+ *      element regardless of how the field's instrText is shaped.
+ *   2. A `REF` / `PAGEREF` / `NOTEREF` field instruction whose first
+ *      argument is the unquoted bookmark name.
+ *   3. A `TOC` field anywhere in the doc — TOC fields produce
+ *      hyperlinks to generated `_Toc####` anchors at render time, so
+ *      we blanket-retain `_Toc*` whenever a TOC field is present.
+ *
+ * Produces a typed `BookmarkReferenceScan` that the parser consults
+ * at every `<w:bookmarkStart>` / `<w:bookmarkEnd>` emission site to
+ * decide RETAIN vs STRIP under
+ * `ParseMainDocumentOptions.stripCosmeticMarkers`.
+ *
+ * Design note: regex-based (not full XML walk) because the scanner
+ * runs BEFORE the structural parser and only needs name-extraction
+ * accuracy. Greedy patterns are bounded to single elements to avoid
+ * catching XML attribute values inside opaque payloads.
+ *
+ * Reference docs:
+ *   - `services/debug/docs/phase-2-bookmark-strip-audit-2026-04-24.md`
+ *   - `services/debug/docs/l01-bookmark-hyperlink-implementation-plan-2026-04-24.md` § 2.1
+ *   - `docs/architecture/cosmetic-marker-strip.md` § Phase 2
+ */
+
+export interface BookmarkReferenceScan {
+  /**
+   * Names that survive the strip — explicitly referenced or in the
+   * caller-supplied allowlist.
+   */
+  readonly retainedNames: ReadonlySet<string>;
+
+  /**
+   * When `true`, retain ALL `_Toc*` bookmarks unconditionally because
+   * the document contains at least one TOC field (TOC fields produce
+   * hyperlinks to generated `_Toc####` anchors at render time and the
+   * specific anchor names are not knowable until render).
+   */
+  readonly retainAllTocPattern: boolean;
+
+  /**
+   * Defensive blanket-retain. When `true`, retain every bookmark
+   * regardless of name — the document carries an SDT data-binding
+   * (`<w:dataBinding>`) whose xpath could reference bookmarks via
+   * paths we cannot statically analyze. Erring on the side of
+   * preservation is the correct posture; a follow-up can refine to
+   * scan xpath strings for bookmark-ref shape.
+   */
+  readonly retainAll: boolean;
+}
+
+const HYPERLINK_ANCHOR_RE =
+  /<(?:\w+:)?hyperlink\b[^>]*\bw:anchor\s*=\s*"([^"]*)"/gi;
+const INSTR_TEXT_RE =
+  /<(?:\w+:)?instrText\b[^>]*>([\s\S]*?)<\/(?:\w+:)?instrText>/gi;
+const TOC_FIELD_RE = /\bTOC\b/;
+const REFLIKE_FIELD_RE =
+  /\b(?:HYPERLINK|REF|PAGEREF|NOTEREF)\s+([A-Za-z0-9_:.\-]+)/g;
+const DATA_BINDING_RE = /<(?:\w+:)?dataBinding\b/i;
+
+/**
+ * Always-retain prefix check — bookmarks whose name starts with
+ * these are NEVER stripped regardless of the reference scan, because
+ * they are converted to first-class scope markers by
+ * `rewriteScopeMarkerBookmarks` BEFORE the strip even runs. Listing
+ * them here is defense-in-depth.
+ */
+const ALWAYS_RETAIN_PREFIXES: readonly string[] = ["bw:scope:"];
+
+export function scanBookmarkReferences(
+  documentXml: string,
+  callerAllowlist: ReadonlyArray<string> = [],
+): BookmarkReferenceScan {
+  const retained = new Set<string>(callerAllowlist);
+  let retainAllToc = false;
+  const retainAll = DATA_BINDING_RE.test(documentXml);
+
+  // 1. <w:hyperlink w:anchor="NAME">
+  HYPERLINK_ANCHOR_RE.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = HYPERLINK_ANCHOR_RE.exec(documentXml)) !== null) {
+    if (m[1]) retained.add(m[1]);
+  }
+
+  // 2. <w:instrText>...</w:instrText> — split into per-instruction lookups
+  INSTR_TEXT_RE.lastIndex = 0;
+  while ((m = INSTR_TEXT_RE.exec(documentXml)) !== null) {
+    const instrText = m[1] ?? "";
+    if (TOC_FIELD_RE.test(instrText)) retainAllToc = true;
+
+    REFLIKE_FIELD_RE.lastIndex = 0;
+    let r: RegExpExecArray | null;
+    while ((r = REFLIKE_FIELD_RE.exec(instrText)) !== null) {
+      if (r[1]) retained.add(r[1]);
+    }
+  }
+
+  return {
+    retainedNames: retained,
+    retainAllTocPattern: retainAllToc,
+    retainAll,
+  };
+}
+
+export function isRetainedBookmarkName(
+  name: string,
+  scan: BookmarkReferenceScan,
+): boolean {
+  if (scan.retainAll) return true;
+  if (scan.retainedNames.has(name)) return true;
+  if (scan.retainAllTocPattern && name.startsWith("_Toc")) return true;
+  for (const prefix of ALWAYS_RETAIN_PREFIXES) {
+    if (name.startsWith(prefix)) return true;
+  }
+  return false;
+}

package/src/io/ooxml/parse-footnotes.ts

@@ -13,6 +13,7 @@ import type {
   TextMark,
 } from "../../model/canonical-document.ts";
 import { classifyFieldInstruction } from "./parse-fields.ts";
+import { isSafeTableFieldInstruction } from "./table-opaque-preservation.ts";
 import {
   readCellBorders,
   readCellCnfStyle,
@@ -695,6 +696,15 @@ function findChildElementOptional(
 
 // ---- Simple secondary-story table support ----
 
+// Revision + structural-change markup disqualifies a footnote table from
+// supported-roundtrip — tracked-change-aware table editing isn't
+// implemented yet, and SDT / customXml structural wrappers aren't
+// supported at footnote-table scope. Field-bearing elements are handled
+// per-instruction via the shared `isSafeTableFieldInstruction` helper
+// (coord-01 §11 unification, 2026-04-24) — this replaces the pre-unification
+// "reject ALL fldChar/instrText unconditionally" stance so footnote tables
+// with supported field families (REF / DOCPROPERTY / FORMTEXT / etc.) can
+// now parse as structured.
 const RISKY_TABLE_ELEMENT_NAMES = new Set([
   "ins",
   "del",
@@ -706,9 +716,6 @@ const RISKY_TABLE_ELEMENT_NAMES = new Set([
   "rPrChange",
   "pPrChange",
   "sectPrChange",
-  "fldSimple",
-  "fldChar",
-  "instrText",
   "sdt",
   "customXml",
 ]);
@@ -726,6 +733,22 @@ function containsRiskyElement(element: XmlElementNode): boolean {
     if (RISKY_TABLE_ELEMENT_NAMES.has(name)) {
       return true;
     }
+    // Field-bearing elements: defer to the shared table-safety predicate.
+    if (name === "fldSimple" || name === "instrText") {
+      const instruction =
+        readStringAttr(child, "w:instr") ??
+        extractTextContent(child);
+      if (!isSafeTableFieldInstruction(instruction)) {
+        return true;
+      }
+      continue;
+    }
+    if (name === "fldChar") {
+      // `<w:fldChar>` is always safe — the instruction text it brackets
+      // is carried by a sibling `<w:instrText>` that this walker checks
+      // separately.
+      continue;
+    }
     if (name === "tbl") {
       return true;
     }

package/src/io/ooxml/parse-headers-footers.ts

@@ -70,8 +70,21 @@ export interface ParsedHeaderFooterDocument {
   blocks: BlockNode[];
 }
 
+// `blockParser` must stay internal to the header/footer lifecycle — the
+// recursion depth counter + source-xml rebinding around `currentSourceXml`
+// are managed inside this module. External callers never supply one.
 export type ParseHeaderFooterOpts = Omit<ParseDrawingOpts, "blockParser">;
 
+/**
+ * Max depth for shape txbxContent recursion inside header / footer
+ * parts. Matches the `TXBX_BLOCK_STREAM_MAX_DEPTH` guard on the
+ * main-document path — text boxes can legally nest
+ * (drawing → txbx → drawing → txbx → …), and OOXML has no spec-level
+ * bound, so we cap recursion to avoid pathological input hanging the
+ * parser.
+ */
+const HDRFTR_TXBX_MAX_DEPTH = 4;
+
 // ---- XML node types (inline, no external dep) ----
 
 interface XmlElementNode {
@@ -687,6 +700,15 @@ function parseDrawingInlineNode(
     const frame = parseDrawingFrame(rawXml, {
       ...opts,
       relationships: opts.relationships ?? [],
+      // Coord-02 §14 / coord-11 §22 follow-up (2026-04-24): supply a
+      // blockParser so `parseShapeContent` populates `shape.txbxBlocks`
+      // for text-box shapes in headers / footers. Without this, a
+      // footer shape carrying "Copyright CCEP STRICTLY CONFIDENTIAL"
+      // flattens to a shape with `text` summary only — the inner `<w:p>`
+      // chain is lost. The main-document path has always supplied a
+      // blockParser; headers/footers did not until now.
+      blockParser: (xml) =>
+        parseTxbxBlocksForHeaderFooter(xml, opts, 1),
     });
     if (
       frame &&
@@ -705,7 +727,9 @@ function parseDrawingInlineNode(
   }
 
   const shapeXml = legacyDrawingXml ?? rawXml;
-  const legacyShape = parseShapeXml(shapeXml);
+  const legacyShape = parseShapeXml(shapeXml, (xml) =>
+    parseTxbxBlocksForHeaderFooter(xml, opts, 1),
+  );
   if (!legacyShape) {
     return null;
   }
@@ -718,6 +742,77 @@ function parseDrawingInlineNode(
   return legacyShape;
 }
 
+/**
+ * Walk `<w:txbxContent>` inner XML into canonical blocks, for
+ * shapes embedded inside header / footer parts. Mirrors the
+ * main-document `parseBlockStreamFromXml` blockParser pattern but
+ * keeps the full header/footer parser pipeline (paragraph +
+ * simple-table + drawing-inline + SDT) so shape text boxes match
+ * whatever the enclosing story would parse on its own.
+ *
+ * Guards against pathological recursion (shape → txbx → shape
+ * → txbx → …) via `HDRFTR_TXBX_MAX_DEPTH` — same class of guard as
+ * `TXBX_BLOCK_STREAM_MAX_DEPTH` on the main-document side.
+ */
+function parseTxbxBlocksForHeaderFooter(
+  innerXml: string,
+  opts: ParseHeaderFooterOpts,
+  depth: number,
+): ReadonlyArray<{ type: string; [key: string]: unknown }> {
+  if (depth > HDRFTR_TXBX_MAX_DEPTH) return [];
+  let root: XmlElementNode;
+  try {
+    root = parseXml(innerXml) as XmlElementNode;
+  } catch {
+    return [];
+  }
+  // `parseXml` returns a wrapper whose single child is the actual
+  // root element (`<w:txbxContent>`). Find it defensively.
+  const txbxContent =
+    localName(root.name) === "txbxContent"
+      ? root
+      : (root.children.find(
+          (c): c is XmlElementNode =>
+            c.type === "element" && localName(c.name) === "txbxContent",
+        ) ?? null);
+  if (!txbxContent) return [];
+
+  // Rebind module-local `currentSourceXml` to the inner XML for the
+  // duration of this recursive parse so drawing-offset reads inside
+  // the txbx body resolve against the right buffer. Restore on exit.
+  const previousSourceXml = currentSourceXml;
+  currentSourceXml = innerXml;
+  try {
+    const blocks: BlockNode[] = [];
+    for (const child of txbxContent.children) {
+      if (child.type !== "element") continue;
+      const name = localName(child.name);
+      if (name === "p") {
+        blocks.push(parseParagraphElement(child, innerXml, opts));
+      } else if (name === "tbl") {
+        if (isSimpleSecondaryStoryTable(child)) {
+          blocks.push(parseSimpleTableElement(child, innerXml, opts));
+        } else {
+          blocks.push({
+            type: "opaque_block",
+            fragmentId: "fragment:hdrftr-txbx-tbl",
+            warningId: "warning:hdrftr-txbx-opaque-table",
+            rawXml: serializeElementToXml(child),
+          });
+        }
+      }
+      // Other block kinds (sdt, customXml) are rare inside a header/
+      // footer text-box; fall through without emitting.
+    }
+    return blocks as unknown as ReadonlyArray<{
+      type: string;
+      [key: string]: unknown;
+    }>;
+  } finally {
+    currentSourceXml = previousSourceXml;
+  }
+}
+
 function parseBookmarkElement(
   element: XmlElementNode,
 ): Extract<InlineNode, { type: "bookmark_start" | "bookmark_end" }> {