@beyondwork/docx-react-component 1.0.47 → 1.0.48

package/src/io/ooxml/parse-block-structure.ts

@@ -0,0 +1,99 @@
+/**
+ * L7 Phase 2.5 Plan B B.7 — shallow structural probe for `word/document.xml`.
+ *
+ * Emits the ordered (kind, blockId) list for top-level body children without
+ * building the canonical-document model. Used by `customxml-probe` to verify
+ * that a cached laycache envelope's `structuralHash` still matches the
+ * document the envelope was written against.
+ *
+ * **Correctness requirement.** The output must match what
+ * `surface-projection.ts:createSurfaceBlock` emits when walking a
+ * canonical document produced by the full parse pipeline. Specifically:
+ *   - Paragraph blockIds use a GLOBAL counter incremented on every
+ *     `<w:p>` encountered ANYWHERE in the tree (top-level or nested
+ *     inside a table cell). The top-level paragraph's blockId is
+ *     `paragraph-${counter_at_time_of_encounter}`.
+ *   - Table blockIds use a GLOBAL counter incremented on every
+ *     `<w:tbl>` at any depth.
+ *   - Other top-level elements (`<w:sdt>`, `<w:altChunk>`, `<w:sectPr>`)
+ *     are NOT emitted by this probe.
+ *
+ * **Known limitation (2026-04-19 shipping state).** The full parse
+ * promotes certain `<w:p>` elements to `opaque_block` based on their
+ * content — e.g. paragraphs containing structured content controls
+ * (`<w:sdt>`), floating drawings (`<w:drawing>` with `<wp:anchor>`),
+ * or `<mc:AlternateContent>` markup-compat wrappers. The shallow probe
+ * cannot detect these patterns without a deeper walk, so it counts such
+ * paragraphs as plain `paragraph` blocks. On docs where this triggers
+ * (~20% of F-series fixtures; 2 of 3 CCEP templates), the probe's
+ * structural hash diverges from the envelope's → cache is rejected →
+ * safe fallback to the full-parse open path. Plan B warm-cache opt-in
+ * is "clean docs only" under this probe.
+ *
+ * Future improvement: refine the probe to detect `<w:sdt>`,
+ * `<w:drawing w:anchor>`, and `<mc:AlternateContent>` inside top-level
+ * paragraphs and classify them accordingly. Deferred unless real-world
+ * hit rates prove insufficient.
+ *
+ * **Cost budget.** <30 ms on extra-large CCEP (~2.7 MB document.xml).
+ * Single regex walk, O(bytes). No DOM, no full XML parse.
+ *
+ * **Fidelity gate.** `test/io/parse-block-structure.test.ts` compares
+ * probe output against full-parse blockIds on representative fixtures
+ * (F01/F02/F05/F48 for paragraph + table patterns, plus a clean CCEP
+ * template). Docs with opaque-promoting features are covered by a
+ * separate "safe fallback" test rather than the strict match.
+ */
+
+export interface BlockStructureProbe {
+  readonly kind: "paragraph" | "table";
+  readonly blockId: string;
+}
+
+const BODY_RE = /<w:body\b[^>]*>([\s\S]*?)<\/w:body>/u;
+const TAG_RE = /<(\/?)w:(p|tbl)\b[^>]*?(\/?)>/gu;
+
+export function parseBlockStructure(documentXml: string): BlockStructureProbe[] {
+  const bodyMatch = BODY_RE.exec(documentXml);
+  if (!bodyMatch) return [];
+  const body = bodyMatch[1] ?? "";
+
+  const results: BlockStructureProbe[] = [];
+  let paragraphCounter = 0;
+  let tableCounter = 0;
+  let depth = 0;
+
+  TAG_RE.lastIndex = 0;
+  let match: RegExpExecArray | null;
+  while ((match = TAG_RE.exec(body)) !== null) {
+    const closing = match[1] === "/";
+    const tag = match[2] as "p" | "tbl";
+    const selfClose = match[3] === "/";
+
+    if (closing) {
+      depth -= 1;
+      continue;
+    }
+
+    if (depth === 0) {
+      if (tag === "p") {
+        results.push({ kind: "paragraph", blockId: `paragraph-${paragraphCounter}` });
+      } else {
+        results.push({ kind: "table", blockId: `table-${tableCounter}` });
+      }
+    }
+
+    // Global counter bumps (all depths, including top-level).
+    if (tag === "p") {
+      paragraphCounter += 1;
+    } else {
+      tableCounter += 1;
+    }
+
+    if (!selfClose) {
+      depth += 1;
+    }
+  }
+
+  return results;
+}

package/src/io/ooxml/parse-complex-content.ts

@@ -11,12 +11,22 @@
 
 import type { OpcRelationship } from "./part-manifest.ts";
 import { normalizePartPath, resolveRelationshipTarget } from "./part-manifest.ts";
+import { parseChartSpace } from "./chart/parse-chart-space.ts";
+import type { ChartModel } from "./chart/types.ts";
 
 export interface InlineMediaPart {
   path: string;
   contentType: string;
 }
 
+/**
+ * Callback that resolves a chart relationship id (the `r:id` on a
+ * `<c:chart>` reference) to the chart-part XML body. Returning undefined
+ * skips ChartModel population — the drawing still parses as a
+ * `ParsedChartContent` with `rawXml`, just without `parsedData`.
+ */
+export type ChartPartLookup = (rId: string) => string | undefined;
+
 export interface ParsedChartContent {
   type: "chart_preview";
   /** Media ID of the fallback preview image, if one is present in mc:Fallback. */
@@ -25,6 +35,17 @@ export interface ParsedChartContent {
   previewPackagePartName?: string;
   /** MIME type of the preview media (e.g. `image/png`, `image/svg+xml`). */
   previewContentType?: string;
+  /**
+   * Stage 1 typed chart model, when the chart part XML resolved and
+   * parsed cleanly. Undefined when no chart-part lookup was supplied, the
+   * lookup returned undefined, or `parseChartSpace` threw / returned an
+   * `UnsupportedChartModel` with reason="parse-error".
+   *
+   * A successful `UnsupportedChartModel{reason: "not-yet-implemented"}`
+   * IS attached — the renderer decides whether to fall back; preserve-
+   * only rawXml always survives export.
+   */
+  parsedData?: ChartModel;
   /** Original drawing XML slice for lossless round-trip export. */
   rawXml: string;
 }
@@ -60,6 +81,7 @@ export function parseComplexContentXml(
   relationships: readonly OpcRelationship[],
   mediaParts: ReadonlyMap<string, InlineMediaPart> = new Map(),
   sourcePartPath = "/word/document.xml",
+  chartPartLookup?: ChartPartLookup,
 ): ParsedComplexContent | null {
   const root = parseXml(drawingXml);
   const relationshipMap = new Map(relationships.map((r) => [r.id, r]));
@@ -67,7 +89,14 @@ export function parseComplexContentXml(
   // Look for mc:AlternateContent at any depth
   const altContent = findFirstDescendant(root, "AlternateContent");
   if (altContent) {
-    return parseAlternateContent(altContent, drawingXml, relationshipMap, mediaParts, sourcePartPath);
+    return parseAlternateContent(
+      altContent,
+      drawingXml,
+      relationshipMap,
+      mediaParts,
+      sourcePartPath,
+      chartPartLookup,
+    );
   }
 
   // No mc:AlternateContent — look for direct graphic data
@@ -78,7 +107,10 @@ export function parseComplexContentXml(
 
   const uri = graphicData.attributes.uri ?? graphicData.attributes["uri"] ?? "";
   if (isChartUri(uri)) {
-    return { type: "chart_preview", rawXml: drawingXml };
+    const parsedData = maybeParseChart(root, chartPartLookup);
+    const node: ParsedChartContent = { type: "chart_preview", rawXml: drawingXml };
+    if (parsedData) node.parsedData = parsedData;
+    return node;
   }
   if (isSmartArtUri(uri)) {
     return { type: "smartart_preview", rawXml: drawingXml };
@@ -87,12 +119,43 @@ export function parseComplexContentXml(
   return null;
 }
 
+/**
+ * Attempt to parse the referenced chart part into a ChartModel.
+ *
+ * Walks the drawing for a `<c:chart r:id="…"/>` reference, hands the id to
+ * the lookup callback, and if the callback returns chart-part XML,
+ * invokes `parseChartSpace`. Returns undefined on any failure — the
+ * caller still emits a valid `ParsedChartContent` with `rawXml`, just
+ * without `parsedData`.
+ */
+function maybeParseChart(
+  drawingRoot: XmlElementNode,
+  chartPartLookup: ChartPartLookup | undefined,
+): ChartModel | undefined {
+  if (!chartPartLookup) return undefined;
+  const chartRef = findFirstDescendant(drawingRoot, "chart");
+  if (!chartRef) return undefined;
+  const rId =
+    chartRef.attributes["r:id"] ??
+    chartRef.attributes["id"] ??
+    chartRef.attributes["r:embed"];
+  if (!rId) return undefined;
+  const chartXml = chartPartLookup(rId);
+  if (!chartXml) return undefined;
+  try {
+    return parseChartSpace(chartXml);
+  } catch {
+    return undefined;
+  }
+}
+
 function parseAlternateContent(
   altContent: XmlElementNode,
   fullDrawingXml: string,
   relationshipMap: Map<string, OpcRelationship>,
   mediaParts: ReadonlyMap<string, InlineMediaPart>,
   sourcePartPath: string,
+  chartPartLookup: ChartPartLookup | undefined,
 ): ParsedComplexContent | null {
   const choice = findFirstChild(altContent, "Choice");
   const fallback = findFirstChild(altContent, "Fallback");
@@ -150,6 +213,28 @@ function parseAlternateContent(
     }
   }
 
+  // For chart_preview, try to populate parsedData from the referenced
+  // chart part. parseAlternateContent is called with the AlternateContent
+  // subtree; the <c:chart> reference typically lives in the Choice branch,
+  // so we search from the altContent root (captures both Choice and any
+  // nested graphicData paths).
+  let parsedData: ChartModel | undefined;
+  if (contentType === "chart_preview") {
+    parsedData = maybeParseChart(altContent, chartPartLookup);
+  }
+
+  if (contentType === "chart_preview") {
+    const node: ParsedChartContent = {
+      type: "chart_preview",
+      ...(previewMediaId ? { previewMediaId } : {}),
+      ...(previewPackagePartName ? { previewPackagePartName } : {}),
+      ...(previewContentType ? { previewContentType } : {}),
+      rawXml: fullDrawingXml,
+    };
+    if (parsedData) node.parsedData = parsedData;
+    return node;
+  }
+
   return {
     type: contentType,
     ...(previewMediaId ? { previewMediaId } : {}),

package/src/io/ooxml/parse-main-document.ts

@@ -26,12 +26,13 @@ import type {
   SectionPageBorders,
 } from "../../model/canonical-document.ts";
 import type { OpcRelationship } from "./part-manifest.ts";
+import { SCOPE_MARKER_BOOKMARK_PREFIX } from "./parse-scope-markers.ts";
 import {
   parseInlineMediaXml,
   type InlineMediaPart,
 } from "./parse-inline-media.ts";
 import { toCanonicalNumberingInstanceId } from "./parse-numbering.ts";
-import { parseComplexContentXml } from "./parse-complex-content.ts";
+import { parseComplexContentXml, type ChartPartLookup } from "./parse-complex-content.ts";
 import { parseShapeXml, parseVmlXml } from "./parse-shapes.ts";
 import { classifyFieldInstruction } from "./parse-fields.ts";
 import { resolveHighlightColor } from "./highlight-colors.ts";
@@ -213,6 +214,9 @@ export interface ParsedChartPreviewNode {
   previewMediaId?: string;
   previewPackagePartName?: string;
   previewContentType?: string;
+  /** Typed chart data parsed from the c:chartSpace part. See
+   *  `src/io/ooxml/parse-complex-content.ts` for semantics. */
+  parsedData?: import("./chart/types.ts").ChartModel;
   rawXml: string;
 }
 
@@ -429,11 +433,38 @@ interface MarksParseResult {
 const HYPERLINK_RELATIONSHIP_TYPE =
   "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink";
 
+/**
+ * Request-scoped chart-part lookup. Set by `parseMainDocumentXml` for
+ * the duration of a single top-level parse; read by `parseRun` where
+ * the `<w:drawing>` → `parseComplexContentXml` call site lives. Using a
+ * module variable instead of threading the callback through ~8
+ * intermediate function signatures keeps the call sites readable; the
+ * try/finally in `parseMainDocumentXml` ensures the variable never
+ * leaks across concurrent parses (Node.js is single-threaded; no
+ * re-entrancy since the parser is fully synchronous).
+ */
+let activeChartPartLookup: ChartPartLookup | undefined;
+
 export function parseMainDocumentXml(
   xml: string,
   relationships: readonly OpcRelationship[] = [],
   mediaParts: ReadonlyMap<string, InlineMediaPart> = new Map(),
   sourcePartPath = "/word/document.xml",
+  chartPartLookup?: ChartPartLookup,
+): ParsedMainDocument {
+  activeChartPartLookup = chartPartLookup;
+  try {
+    return parseMainDocumentXmlInner(xml, relationships, mediaParts, sourcePartPath);
+  } finally {
+    activeChartPartLookup = undefined;
+  }
+}
+
+function parseMainDocumentXmlInner(
+  xml: string,
+  relationships: readonly OpcRelationship[],
+  mediaParts: ReadonlyMap<string, InlineMediaPart>,
+  sourcePartPath: string,
 ): ParsedMainDocument {
   const root = parseXml(xml);
   const documentElement = findChildElement(root, "document");
@@ -457,9 +488,91 @@ export function parseMainDocumentXml(
     }
   }
 
+  rewriteScopeMarkerBookmarks(blocks);
+
   return { blocks, finalSectionProperties };
 }
 
+/**
+ * S1 — post-process the parsed block tree in place, converting bookmark
+ * pairs whose `name` starts with `bw:scope:` into `scope_marker_*` inline
+ * nodes. The `bookmarkId` is used to pair start+end; the `scopeId` is
+ * taken from the name after the prefix. Unmatched bookmarks (start without
+ * end or vice versa) stay as regular bookmarks — S1 markers are always
+ * emitted in pairs on export, so an orphan implies upstream corruption
+ * that we preserve rather than drop.
+ */
+function rewriteScopeMarkerBookmarks(blocks: ParsedBlockNode[]): void {
+  const scopeBookmarkIds = new Map<string, string>();
+
+  const scanForStarts = (nodes: readonly { type?: string; [key: string]: unknown }[]): void => {
+    for (const node of nodes) {
+      if (!node || typeof node !== "object") continue;
+      if (node.type === "bookmark_start") {
+        const name = (node as { name?: string }).name ?? "";
+        if (name.startsWith(SCOPE_MARKER_BOOKMARK_PREFIX)) {
+          const bkId = (node as { bookmarkId?: string }).bookmarkId ?? "";
+          const scopeId = name.slice(SCOPE_MARKER_BOOKMARK_PREFIX.length);
+          if (bkId && scopeId) {
+            scopeBookmarkIds.set(bkId, scopeId);
+          }
+        }
+      }
+      const children = (node as { children?: unknown }).children;
+      if (Array.isArray(children)) scanForStarts(children);
+      const rows = (node as { rows?: unknown }).rows;
+      if (Array.isArray(rows)) scanForStarts(rows);
+      const cells = (node as { cells?: unknown }).cells;
+      if (Array.isArray(cells)) scanForStarts(cells);
+    }
+  };
+
+  const rewriteInPlace = (nodes: { type?: string; [key: string]: unknown }[]): void => {
+    for (let i = 0; i < nodes.length; i += 1) {
+      const node = nodes[i]!;
+      if (!node || typeof node !== "object") continue;
+
+      if (node.type === "bookmark_start") {
+        const bkId = (node as { bookmarkId?: string }).bookmarkId ?? "";
+        const scopeId = scopeBookmarkIds.get(bkId);
+        if (scopeId !== undefined) {
+          nodes[i] = { type: "scope_marker_start", scopeId } as typeof node;
+          continue;
+        }
+      }
+
+      if (node.type === "bookmark_end") {
+        const bkId = (node as { bookmarkId?: string }).bookmarkId ?? "";
+        const scopeId = scopeBookmarkIds.get(bkId);
+        if (scopeId !== undefined) {
+          nodes[i] = { type: "scope_marker_end", scopeId } as typeof node;
+          continue;
+        }
+      }
+
+      const children = (node as { children?: unknown }).children;
+      if (Array.isArray(children)) {
+        rewriteInPlace(children as { type?: string; [key: string]: unknown }[]);
+      }
+      const rows = (node as { rows?: unknown }).rows;
+      if (Array.isArray(rows)) {
+        rewriteInPlace(rows as { type?: string; [key: string]: unknown }[]);
+      }
+      const cells = (node as { cells?: unknown }).cells;
+      if (Array.isArray(cells)) {
+        rewriteInPlace(cells as { type?: string; [key: string]: unknown }[]);
+      }
+    }
+  };
+
+  // Two passes: collect all scope-prefixed start IDs, then rewrite both
+  // start + end occurrences. Pairing by id — scope_marker_end may appear
+  // in a later paragraph than its matching scope_marker_start.
+  scanForStarts(blocks as unknown as readonly { [key: string]: unknown }[]);
+  if (scopeBookmarkIds.size === 0) return;
+  rewriteInPlace(blocks as unknown as { [key: string]: unknown }[]);
+}
+
 function parseBodyChild(
   node: XmlElementNode,
   sourceXml: string,
@@ -1911,6 +2024,7 @@ function parseRun(
             relationships,
             mediaParts,
             sourcePartPath,
+            activeChartPartLookup,
           );
           if (complexContent) {
             result.push(complexContent);

package/src/io/ooxml/parse-scope-markers.ts

@@ -0,0 +1,184 @@
+import type {
+  CanonicalDocument,
+  DocumentRootNode,
+  InlineNode,
+} from "../../model/canonical-document.ts";
+
+/**
+ * Reserved OOXML bookmark-name prefix used to discriminate S1 scope markers
+ * from user-authored bookmarks. On export, each scope marker emits as
+ * `<w:bookmarkStart w:name="bw:scope:<scopeId>"/>` / `<w:bookmarkEnd/>`. On
+ * import, any bookmark whose name starts with this prefix is extracted as a
+ * `scope_marker_*` inline node pair and removed from the regular bookmark
+ * list so user-facing bookmark APIs stay clean.
+ */
+export const SCOPE_MARKER_BOOKMARK_PREFIX = "bw:scope:";
+
+export interface ScopeMarkerBookmark {
+  /** Serialized bookmark id (shared between start + end in the OOXML pair). */
+  bookmarkId: string;
+  /** `bw:scope:<scopeId>` — caller applies the prefix via the exported constant. */
+  name: string;
+  boundary: "start" | "end";
+  scopeId: string;
+}
+
+/**
+ * Walk a canonical document in pre-order and return one pair of bookmark
+ * descriptors for each scope-marker pair found. The returned objects are
+ * OOXML-flavor (paired `w:id`, `w:name` on start only, end references id)
+ * so callers can weave them straight into the `<w:bookmarkStart>` /
+ * `<w:bookmarkEnd>` emit path.
+ */
+export function serializeScopeMarkersToBookmarks(
+  document: CanonicalDocument | Pick<CanonicalDocument, "content">,
+): ScopeMarkerBookmark[] {
+  const root = ("content" in document
+    ? (document.content as DocumentRootNode)
+    : (document as unknown as DocumentRootNode));
+  const out: ScopeMarkerBookmark[] = [];
+  let bookmarkIdCounter = 0;
+  const scopeIdToBookmarkId = new Map<string, string>();
+
+  walkInlineNodes(root, (node) => {
+    if (node.type === "scope_marker_start") {
+      const bookmarkId = String(bookmarkIdCounter);
+      bookmarkIdCounter += 1;
+      scopeIdToBookmarkId.set(node.scopeId, bookmarkId);
+      out.push({
+        bookmarkId,
+        name: `${SCOPE_MARKER_BOOKMARK_PREFIX}${node.scopeId}`,
+        boundary: "start",
+        scopeId: node.scopeId,
+      });
+    } else if (node.type === "scope_marker_end") {
+      const bookmarkId = scopeIdToBookmarkId.get(node.scopeId) ?? String(bookmarkIdCounter++);
+      out.push({
+        bookmarkId,
+        name: `${SCOPE_MARKER_BOOKMARK_PREFIX}${node.scopeId}`,
+        boundary: "end",
+        scopeId: node.scopeId,
+      });
+    }
+  });
+
+  return out;
+}
+
+export interface ParsedScopeMarkerPair {
+  scopeId: string;
+  bookmarkId: string;
+  startIndex: number;
+  endIndex: number;
+}
+
+export interface RawBookmark {
+  readonly type: "bookmark_start" | "bookmark_end";
+  readonly bookmarkId: string;
+  readonly name?: string;
+  readonly index: number;
+}
+
+/**
+ * Split an OOXML bookmark list into (a) scope-marker pairs extracted via the
+ * `bw:scope:` prefix convention and (b) the remaining user bookmarks. The
+ * extraction is id-paired — a start with a prefix name pairs with the
+ * matching end by `bookmarkId`.
+ */
+export function parseScopeMarkersFromBookmarks(
+  rawBookmarks: readonly RawBookmark[],
+): { scopeMarkers: ParsedScopeMarkerPair[]; remainingBookmarks: RawBookmark[] } {
+  const scopeStartsById = new Map<
+    string,
+    { scopeId: string; startIndex: number }
+  >();
+  const scopeMarkers: ParsedScopeMarkerPair[] = [];
+  const remainingBookmarks: RawBookmark[] = [];
+
+  for (const bm of rawBookmarks) {
+    if (bm.type === "bookmark_start") {
+      const name = bm.name ?? "";
+      if (name.startsWith(SCOPE_MARKER_BOOKMARK_PREFIX)) {
+        const scopeId = name.slice(SCOPE_MARKER_BOOKMARK_PREFIX.length);
+        scopeStartsById.set(bm.bookmarkId, {
+          scopeId,
+          startIndex: bm.index,
+        });
+        continue;
+      }
+      remainingBookmarks.push(bm);
+      continue;
+    }
+
+    const open = scopeStartsById.get(bm.bookmarkId);
+    if (open) {
+      scopeMarkers.push({
+        scopeId: open.scopeId,
+        bookmarkId: bm.bookmarkId,
+        startIndex: open.startIndex,
+        endIndex: bm.index,
+      });
+      scopeStartsById.delete(bm.bookmarkId);
+      continue;
+    }
+
+    remainingBookmarks.push(bm);
+  }
+
+  return { scopeMarkers, remainingBookmarks };
+}
+
+function walkInlineNodes(
+  node: DocumentRootNode | InlineNode | { children?: unknown; rows?: unknown; cells?: unknown; type?: string },
+  visit: (inline: InlineNode) => void,
+): void {
+  if (!node || typeof node !== "object") return;
+  const nt = (node as { type?: string }).type;
+
+  // Inline leaf node: visit it.
+  if (
+    nt === "text" ||
+    nt === "tab" ||
+    nt === "hard_break" ||
+    nt === "column_break" ||
+    nt === "symbol" ||
+    nt === "image" ||
+    nt === "bookmark_start" ||
+    nt === "bookmark_end" ||
+    nt === "scope_marker_start" ||
+    nt === "scope_marker_end" ||
+    nt === "opaque_inline" ||
+    nt === "footnote_ref" ||
+    nt === "chart_preview" ||
+    nt === "smartart_preview" ||
+    nt === "shape" ||
+    nt === "wordart" ||
+    nt === "vml_shape"
+  ) {
+    visit(node as InlineNode);
+    return;
+  }
+
+  const children = (node as { children?: unknown }).children;
+  if (Array.isArray(children)) {
+    for (const child of children) {
+      walkInlineNodes(child as InlineNode, visit);
+    }
+  }
+
+  if (nt === "table") {
+    const rows = (node as { rows?: unknown }).rows;
+    if (Array.isArray(rows)) {
+      for (const row of rows) {
+        walkInlineNodes(row as InlineNode, visit);
+      }
+    }
+  } else if (nt === "table_row") {
+    const cells = (node as { cells?: unknown }).cells;
+    if (Array.isArray(cells)) {
+      for (const cell of cells) {
+        walkInlineNodes(cell as InlineNode, visit);
+      }
+    }
+  }
+}