npm - @beyondwork/docx-react-component - Versions diffs - 1.0.56 → 1.0.57 - Mend

@beyondwork/docx-react-component 1.0.56 → 1.0.57

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (107) hide show

package/package.json +1 -1
package/src/api/public-types.ts +157 -0
package/src/compare/diff-engine.ts +3 -0
package/src/core/commands/formatting-commands.ts +1 -0
package/src/core/commands/index.ts +17 -11
package/src/core/selection/mapping.ts +18 -1
package/src/core/selection/review-anchors.ts +29 -18
package/src/io/chart-preview-resolver.ts +175 -41
package/src/io/docx-session.ts +57 -2
package/src/io/export/serialize-main-document.ts +82 -0
package/src/io/export/serialize-styles.ts +61 -3
package/src/io/export/table-properties-xml.ts +19 -4
package/src/io/normalize/normalize-text.ts +33 -0
package/src/io/ooxml/parse-anchor.ts +182 -0
package/src/io/ooxml/parse-drawing.ts +319 -0
package/src/io/ooxml/parse-fields.ts +115 -2
package/src/io/ooxml/parse-fill.ts +215 -0
package/src/io/ooxml/parse-font-table.ts +190 -0
package/src/io/ooxml/parse-footnotes.ts +52 -1
package/src/io/ooxml/parse-main-document.ts +241 -1
package/src/io/ooxml/parse-numbering.ts +96 -0
package/src/io/ooxml/parse-picture.ts +107 -0
package/src/io/ooxml/parse-settings.ts +34 -0
package/src/io/ooxml/parse-shapes.ts +87 -0
package/src/io/ooxml/parse-solid-fill.ts +11 -0
package/src/io/ooxml/parse-styles.ts +74 -1
package/src/io/ooxml/parse-theme.ts +60 -0
package/src/io/paste/html-clipboard.ts +449 -0
package/src/io/paste/word-clipboard.ts +5 -1
package/src/legal/_document-root.ts +26 -0
package/src/legal/bookmarks.ts +4 -3
package/src/legal/cross-references.ts +3 -2
package/src/legal/defined-terms.ts +2 -1
package/src/legal/signature-blocks.ts +2 -1
package/src/model/canonical-document.ts +415 -3
package/src/runtime/chart/chart-model-store.ts +73 -10
package/src/runtime/document-runtime.ts +693 -41
package/src/runtime/edit-ops/index.ts +129 -0
package/src/runtime/event-refresh-hints.ts +7 -0
package/src/runtime/field-resolver.ts +341 -0
package/src/runtime/footnote-resolver.ts +55 -0
package/src/runtime/hyperlink-color-resolver.ts +13 -10
package/src/runtime/object-grab/index.ts +51 -0
package/src/runtime/paragraph-style-resolver.ts +105 -0
package/src/runtime/resolved-numbering-geometry.ts +12 -0
package/src/runtime/selection/cursor-ops.ts +186 -15
package/src/runtime/selection/index.ts +17 -1
package/src/runtime/structure-ops/index.ts +77 -0
package/src/runtime/styles-cascade.ts +33 -0
package/src/runtime/surface-projection.ts +186 -12
package/src/runtime/theme-color-resolver.ts +189 -44
package/src/runtime/units.ts +46 -0
package/src/runtime/view-state.ts +13 -2
package/src/ui/WordReviewEditor.tsx +168 -10
package/src/ui/editor-runtime-boundary.ts +94 -1
package/src/ui/editor-shell-view.tsx +1 -1
package/src/ui/runtime-shortcut-dispatch.ts +17 -3
package/src/ui-tailwind/chart/ChartSurface.tsx +36 -10
package/src/ui-tailwind/chart/layout/plot-area.ts +120 -45
package/src/ui-tailwind/chart/render/area.tsx +22 -4
package/src/ui-tailwind/chart/render/bar-column.tsx +37 -11
package/src/ui-tailwind/chart/render/bubble.tsx +6 -2
package/src/ui-tailwind/chart/render/combo.tsx +37 -4
package/src/ui-tailwind/chart/render/line.tsx +28 -5
package/src/ui-tailwind/chart/render/pie.tsx +36 -16
package/src/ui-tailwind/chart/render/progressive-render.ts +8 -1
package/src/ui-tailwind/chart/render/scatter.tsx +9 -4
package/src/ui-tailwind/chrome/avatar-initials.ts +15 -0
package/src/ui-tailwind/chrome/tw-comment-preview.tsx +3 -1
package/src/ui-tailwind/chrome/tw-context-menu.tsx +14 -0
package/src/ui-tailwind/chrome/tw-selection-tool-host.tsx +3 -2
package/src/ui-tailwind/chrome/tw-selection-toolbar.tsx +30 -11
package/src/ui-tailwind/chrome/tw-shortcut-hint.tsx +15 -2
package/src/ui-tailwind/chrome/tw-suggestion-card.tsx +1 -1
package/src/ui-tailwind/chrome/tw-table-context-toolbar.tsx +24 -7
package/src/ui-tailwind/chrome/tw-table-grip-layer.tsx +31 -12
package/src/ui-tailwind/chrome-overlay/page-border-resolver.ts +211 -0
package/src/ui-tailwind/chrome-overlay/tw-chrome-overlay.tsx +1 -0
package/src/ui-tailwind/chrome-overlay/tw-comment-balloon-layer.tsx +74 -0
package/src/ui-tailwind/chrome-overlay/tw-locked-block-layer.tsx +65 -0
package/src/ui-tailwind/chrome-overlay/tw-page-border-overlay.tsx +233 -0
package/src/ui-tailwind/chrome-overlay/tw-page-stack-overlay-layer.tsx +135 -13
package/src/ui-tailwind/chrome-overlay/tw-revision-margin-bar-layer.tsx +51 -0
package/src/ui-tailwind/chrome-overlay/tw-scope-card-layer.tsx +12 -4
package/src/ui-tailwind/chrome-overlay/tw-scope-card.tsx +32 -12
package/src/ui-tailwind/chrome-overlay/tw-toc-outline-sidebar.tsx +133 -0
package/src/ui-tailwind/editor-surface/chart-node-view.tsx +49 -10
package/src/ui-tailwind/editor-surface/float-wrap-resolver.ts +119 -0
package/src/ui-tailwind/editor-surface/pm-command-bridge.ts +236 -9
package/src/ui-tailwind/editor-surface/pm-schema.ts +188 -11
package/src/ui-tailwind/editor-surface/pm-state-from-snapshot.ts +28 -2
package/src/ui-tailwind/editor-surface/shape-renderer.ts +206 -0
package/src/ui-tailwind/editor-surface/surface-layer.ts +66 -0
package/src/ui-tailwind/editor-surface/tw-inline-token.tsx +29 -0
package/src/ui-tailwind/editor-surface/tw-segment-view.tsx +7 -1
package/src/ui-tailwind/page-stack/tw-page-stack-chrome-layer.tsx +22 -6
package/src/ui-tailwind/review/tw-comment-sidebar.tsx +10 -16
package/src/ui-tailwind/review/tw-health-panel.tsx +0 -25
package/src/ui-tailwind/review/tw-rail-card.tsx +38 -17
package/src/ui-tailwind/review/tw-review-rail.tsx +2 -2
package/src/ui-tailwind/review/tw-revision-sidebar.tsx +5 -12
package/src/ui-tailwind/review/tw-workflow-tab.tsx +2 -2
package/src/ui-tailwind/theme/editor-theme.css +1 -0
package/src/ui-tailwind/theme/tokens.css +6 -0
package/src/ui-tailwind/theme/tokens.ts +10 -0
package/src/validation/compatibility-engine.ts +2 -0
package/src/validation/docx-comment-proof.ts +12 -3

package/src/io/paste/html-clipboard.ts ADDED Viewed

@@ -0,0 +1,449 @@
+/**
+ * I2 Tier B Slice 3 — HTML paste parser.
+ *
+ * Purpose: when the browser clipboard holds `text/html` but no WordML MIME,
+ * route it through this parser to produce a `CanonicalDocumentFragment`.
+ * Timeboxed to the two fixtures that cover legal-review use cases —
+ * Google Docs and Word web. Outlook / Gmail / raw browser selection follow
+ * when user fixtures surface.
+ *
+ * Implementation: a small handwritten tokenizer + recursive parser. Keeping
+ * the dependency profile minimal (no jsdom / parse5 at runtime) — the HTML
+ * subset we accept is narrow enough that a 200-line tokenizer reads cleaner
+ * than pulling in a 50 KB DOM library.
+ *
+ * What this parser accepts:
+ *   - Block structure: `<p>`, `<div>`, `<h1>`–`<h6>`, `<ul>`/`<ol>` + `<li>`
+ *   - Inline structure: `<span>`, `<b>`/`<strong>`, `<i>`/`<em>`, `<u>`,
+ *     `<s>`/`<del>`, `<a href>`, `<br>`
+ *   - Meta: `<meta>`, `<html>`, `<head>`, `<body>` — passed through
+ *
+ * What this parser drops (sanitizer):
+ *   - `<script>` / `<style>` / `<iframe>` / `<form>` / `<input>` tag CONTENT
+ *   - Event handler attributes (`on*`)
+ *   - `data-*` attributes
+ *   - `javascript:` hrefs (rewritten to `#`)
+ */
+import type { CanonicalDocumentFragment } from "../../api/public-types.ts";
+import type {
+  BlockNode,
+  HyperlinkNode,
+  InlineNode,
+  ParagraphNode,
+  TextMark,
+  TextNode,
+} from "../../model/canonical-document.ts";
+export type ParseCanonicalFragmentFromHtmlResult =
+  | { ok: true; fragment: CanonicalDocumentFragment }
+  | { ok: false; reason: string };
+export function parseCanonicalFragmentFromHtml(
+  html: string,
+): ParseCanonicalFragmentFromHtmlResult {
+  if (typeof html !== "string") {
+    return { ok: false, reason: "html must be a string" };
+  }
+  if (html.length === 0) {
+    return { ok: true, fragment: { blocks: [] } };
+  }
+  try {
+    const sanitized = stripUnsafeRegions(html);
+    const tokens = tokenize(sanitized);
+    const blocks = parseBlocks(tokens);
+    return { ok: true, fragment: { blocks } };
+  } catch (error) {
+    return {
+      ok: false,
+      reason: error instanceof Error ? error.message : "unknown HTML parse error",
+    };
+  }
+}
+// ─── Sanitizer ────────────────────────────────────────────────────────────
+const UNSAFE_REGIONS = /<(script|style|iframe|form|input|object|embed)\b[^>]*>[\s\S]*?<\/\1>/gi;
+const UNSAFE_SELF_CLOSING = /<(script|style|iframe|form|input|object|embed)\b[^>]*\/?>/gi;
+function stripUnsafeRegions(html: string): string {
+  return html.replace(UNSAFE_REGIONS, "").replace(UNSAFE_SELF_CLOSING, "");
+}
+// ─── Tokenizer ────────────────────────────────────────────────────────────
+type Token =
+  | { type: "open"; tag: string; attrs: Record<string, string> }
+  | { type: "close"; tag: string }
+  | { type: "void"; tag: string; attrs: Record<string, string> }
+  | { type: "text"; value: string };
+const VOID_TAGS = new Set(["br", "hr", "img", "meta", "link", "source", "track", "area"]);
+function tokenize(html: string): Token[] {
+  const tokens: Token[] = [];
+  const re = /<([!/]?)([a-zA-Z][a-zA-Z0-9-]*)([^>]*)>|([^<]+)/g;
+  let match: RegExpExecArray | null;
+  while ((match = re.exec(html)) !== null) {
+    const [, prefix, rawTag, attrString, textRun] = match;
+    if (textRun !== undefined) {
+      const decoded = decodeEntities(textRun);
+      if (decoded.length > 0) tokens.push({ type: "text", value: decoded });
+      continue;
+    }
+    if (prefix === "!") continue; // comments / doctypes
+    const tag = rawTag!.toLowerCase();
+    if (prefix === "/") {
+      tokens.push({ type: "close", tag });
+      continue;
+    }
+    const attrs = parseAttrs(attrString ?? "");
+    const isSelfClosing = (attrString ?? "").trim().endsWith("/");
+    if (VOID_TAGS.has(tag) || isSelfClosing) {
+      tokens.push({ type: "void", tag, attrs });
+    } else {
+      tokens.push({ type: "open", tag, attrs });
+    }
+  }
+  return tokens;
+}
+function parseAttrs(attrString: string): Record<string, string> {
+  const attrs: Record<string, string> = {};
+  const re = /([a-zA-Z_:][a-zA-Z0-9_:.-]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g;
+  let match: RegExpExecArray | null;
+  while ((match = re.exec(attrString)) !== null) {
+    const [, name, dq, sq, bare] = match;
+    const lowerName = name!.toLowerCase();
+    // Sanitizer: drop event handlers + data-* attributes.
+    if (lowerName.startsWith("on")) continue;
+    if (lowerName.startsWith("data-")) continue;
+    attrs[lowerName] = (dq ?? sq ?? bare ?? "").trim();
+  }
+  return attrs;
+}
+const ENTITY_MAP: Record<string, string> = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  nbsp: "\u00a0",
+};
+function decodeEntities(text: string): string {
+  return text.replace(/&(#?[a-zA-Z0-9]+);/g, (whole, ent) => {
+    if (ent.startsWith("#")) {
+      const code = ent.startsWith("#x") || ent.startsWith("#X")
+        ? parseInt(ent.slice(2), 16)
+        : parseInt(ent.slice(1), 10);
+      return Number.isFinite(code) ? String.fromCodePoint(code) : whole;
+    }
+    return ENTITY_MAP[ent.toLowerCase()] ?? whole;
+  });
+}
+// ─── Block / inline parser ────────────────────────────────────────────────
+interface ParseContext {
+  marks: TextMark[];
+  hyperlinkHref?: string;
+}
+const BLOCK_TAGS = new Set([
+  "p",
+  "div",
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  "li",
+  "tr",
+]);
+const CONTAINER_TAGS = new Set(["html", "body", "head", "ul", "ol", "b", "strong", "i", "em", "u", "s", "del", "span", "a"]);
+const MARK_TAGS: Record<string, TextMark["type"]> = {
+  b: "bold",
+  strong: "bold",
+  i: "italic",
+  em: "italic",
+  u: "underline",
+  s: "strikethrough",
+  del: "strikethrough",
+};
+const HEADING_STYLES: Record<string, string> = {
+  h1: "Heading1",
+  h2: "Heading2",
+  h3: "Heading3",
+  h4: "Heading4",
+  h5: "Heading5",
+  h6: "Heading6",
+};
+function parseBlocks(tokens: Token[]): BlockNode[] {
+  const blocks: BlockNode[] = [];
+  let cursor = 0;
+  // Accumulate inline nodes for "loose" text that isn't inside a block tag
+  // (e.g. Google Docs wraps content in a `<b>` container; the child `<p>`s
+  // are the real blocks). When we hit a BLOCK_TAGS opener, flush any
+  // pending inline content into a paragraph.
+  let pendingInline: InlineNode[] = [];
+  // v5 A2: track marks from mark tags encountered at block level (outside a
+  // `<p>`/`<div>`). Pre-fix, `<body><b>hello</b></body>` dropped the bold
+  // mark because the block walker descended `<b>` as a transparent container
+  // and the text landed in pendingInline unmarked. We now stack mark contexts
+  // alongside pendingInline and apply them when text tokens arrive.
+  const blockMarkStack: TextMark[][] = [];
+  const currentBlockMarks = (): TextMark[] => {
+    if (blockMarkStack.length === 0) return [];
+    return blockMarkStack.flat();
+  };
+  const flushPendingInline = () => {
+    if (pendingInline.length > 0) {
+      blocks.push({
+        type: "paragraph",
+        children: pendingInline,
+      });
+      pendingInline = [];
+    }
+  };
+  while (cursor < tokens.length) {
+    const token = tokens[cursor]!;
+    if (token.type === "text") {
+      const marks = currentBlockMarks();
+      const inline: TextNode = {
+        type: "text",
+        text: token.value,
+        ...(marks.length > 0 ? { marks: marks.map((m) => ({ ...m })) } : {}),
+      };
+      pendingInline.push(inline);
+      cursor += 1;
+      continue;
+    }
+    if (token.type === "void") {
+      if (token.tag === "br") {
+        pendingInline.push({ type: "hard_break" });
+      }
+      // meta / link / etc. — ignore
+      cursor += 1;
+      continue;
+    }
+    if (token.type === "close") {
+      // Pop a block-level mark context if this close matches an open mark tag.
+      if (MARK_TAGS[token.tag] && blockMarkStack.length > 0) {
+        blockMarkStack.pop();
+      }
+      cursor += 1;
+      continue;
+    }
+    // open
+    const openTag = token.tag;
+    if (BLOCK_TAGS.has(openTag)) {
+      flushPendingInline();
+      // Consume inner content up to matching close, collecting inline nodes.
+      // Seed with any active block-level marks so `<b><p>hello</p></b>`
+      // still produces bold inline nodes inside the paragraph.
+      const { inline, end } = parseInlineUntil(tokens, cursor + 1, openTag, {
+        marks: currentBlockMarks(),
+      });
+      const paragraph: ParagraphNode = {
+        type: "paragraph",
+        children: inline,
+        ...(HEADING_STYLES[openTag] ? { styleId: HEADING_STYLES[openTag] } : {}),
+      };
+      blocks.push(paragraph);
+      cursor = end;
+      continue;
+    }
+    if (openTag === "ul" || openTag === "ol") {
+      // Walk forward until matching close; block children handled via `li`.
+      // Descend — `li` is a BLOCK_TAGS entry.
+      cursor += 1;
+      continue;
+    }
+    if (MARK_TAGS[openTag]) {
+      // v5 A2: mark tag at block level — push onto the block-level mark
+      // stack so bare text tokens (and any subsequent BLOCK_TAGS that flush
+      // pendingInline into a paragraph) pick up the mark.
+      blockMarkStack.push([{ type: MARK_TAGS[openTag]! } as TextMark]);
+      cursor += 1;
+      continue;
+    }
+    if (CONTAINER_TAGS.has(openTag)) {
+      // Descend into the container — keep pendingInline flowing; the mark
+      // parsing happens when we hit text nodes.
+      cursor += 1;
+      continue;
+    }
+    // Unknown tag — skip.
+    cursor += 1;
+  }
+  flushPendingInline();
+  return blocks;
+}
+function parseInlineUntil(
+  tokens: Token[],
+  start: number,
+  untilTag: string,
+  context: ParseContext,
+): { inline: InlineNode[]; end: number } {
+  const inline: InlineNode[] = [];
+  let cursor = start;
+  while (cursor < tokens.length) {
+    const token = tokens[cursor]!;
+    if (token.type === "close" && token.tag === untilTag) {
+      return { inline, end: cursor + 1 };
+    }
+    if (token.type === "text") {
+      const node: TextNode = {
+        type: "text",
+        text: token.value,
+        ...(context.marks.length > 0 ? { marks: context.marks.map((m) => ({ ...m })) } : {}),
+      };
+      if (context.hyperlinkHref) {
+        const hyperlink: HyperlinkNode = {
+          type: "hyperlink",
+          href: context.hyperlinkHref,
+          children: [node],
+        };
+        inline.push(hyperlink);
+      } else {
+        inline.push(node);
+      }
+      cursor += 1;
+      continue;
+    }
+    if (token.type === "void") {
+      if (token.tag === "br") inline.push({ type: "hard_break" });
+      cursor += 1;
+      continue;
+    }
+    if (token.type === "open") {
+      const openTag = token.tag;
+      if (MARK_TAGS[openTag]) {
+        const markType = MARK_TAGS[openTag]!;
+        const nested = parseInlineUntil(tokens, cursor + 1, openTag, {
+          ...context,
+          marks: [...context.marks, { type: markType } as TextMark],
+        });
+        inline.push(...nested.inline);
+        cursor = nested.end;
+        continue;
+      }
+      if (openTag === "a") {
+        const href = sanitizeHref(token.attrs.href ?? "");
+        const nested = parseInlineUntil(tokens, cursor + 1, openTag, {
+          ...context,
+          hyperlinkHref: href,
+        });
+        inline.push(...nested.inline);
+        cursor = nested.end;
+        continue;
+      }
+      if (openTag === "span") {
+        // Google Docs encodes bold/italic via inline `style` on `<span>` rather
+        // than semantic `<b>`/`<i>`. Detect `font-weight:700+` and
+        // `font-style:italic` / `text-decoration:underline` /
+        // `text-decoration:line-through` and inject marks accordingly.
+        const extraMarks = marksFromInlineStyle(token.attrs.style ?? "");
+        const nested = parseInlineUntil(tokens, cursor + 1, openTag, {
+          ...context,
+          marks: extraMarks.length > 0 ? [...context.marks, ...extraMarks] : context.marks,
+        });
+        inline.push(...nested.inline);
+        cursor = nested.end;
+        continue;
+      }
+      // Unknown inline open — descend, passing context through. Use a
+      // loose fallthrough: treat unknown inlines as transparent wrappers.
+      const nested = parseInlineUntil(tokens, cursor + 1, openTag, context);
+      inline.push(...nested.inline);
+      cursor = nested.end;
+      continue;
+    }
+    cursor += 1;
+  }
+  return { inline, end: cursor };
+}
+/**
+ * Parse a CSS `style` string and extract the subset of declarations that
+ * map onto canonical `TextMark`s. Google Docs uses this encoding for every
+ * bold / italic / underline / strikethrough run on `<span>` elements —
+ * without style parsing we'd return an unmarked run where Word users expect
+ * a bold one. Limited to a narrow set of declarations to stay fast and
+ * avoid a full CSS parser.
+ */
+function marksFromInlineStyle(style: string): TextMark[] {
+  if (!style || style.length === 0) return [];
+  const marks: TextMark[] = [];
+  // Split on `;` first; each piece is `name:value`.
+  const decls = style.split(";");
+  for (const raw of decls) {
+    const trimmed = raw.trim();
+    if (trimmed.length === 0) continue;
+    const colonIdx = trimmed.indexOf(":");
+    if (colonIdx < 0) continue;
+    const name = trimmed.slice(0, colonIdx).trim().toLowerCase();
+    const value = trimmed.slice(colonIdx + 1).trim().toLowerCase();
+    switch (name) {
+      case "font-weight": {
+        // Numeric 600+ or keywords "bold"/"bolder" → bold mark.
+        const numeric = Number.parseInt(value, 10);
+        if (Number.isFinite(numeric) && numeric >= 600) {
+          marks.push({ type: "bold" });
+        } else if (value === "bold" || value === "bolder") {
+          marks.push({ type: "bold" });
+        }
+        break;
+      }
+      case "font-style": {
+        if (value === "italic" || value === "oblique") {
+          marks.push({ type: "italic" });
+        }
+        break;
+      }
+      case "text-decoration":
+      case "text-decoration-line": {
+        if (value.includes("underline")) marks.push({ type: "underline" });
+        if (value.includes("line-through")) marks.push({ type: "strikethrough" });
+        break;
+      }
+    }
+  }
+  return marks;
+}
+function sanitizeHref(href: string): string {
+  const trimmed = href.trim().toLowerCase();
+  if (trimmed.startsWith("javascript:") || trimmed.startsWith("data:")) {
+    return "#";
+  }
+  return href;
+}

package/src/io/paste/word-clipboard.ts CHANGED Viewed

@@ -63,7 +63,11 @@ export function parseCanonicalFragmentFromWordML(xml: string): ParseCanonicalFra
  * outer element survives, it's added to the outer `<w:document>` wrapper.
  */
 function ensureDocumentShell(xml: string): string {
-  const trimmed = xml.trim();
+  // v5 A5: strip UTF-8 BOM before wrapper detection. Modern browsers /
+  // Word clipboards don't emit BOM, but some legacy tools do; a leading
+  // U+FEFF breaks the regex-based wrapper check and causes us to
+  // double-wrap a valid `<w:document>` payload.
+  const trimmed = xml.replace(/^\uFEFF/, "").trim();
   const withoutDecl = trimmed.replace(/^<\?xml[^?]*\?>/, "").trim();
   const hasDocumentWrapper = /^<w:document[\s>]/i.test(withoutDecl);

package/src/legal/_document-root.ts ADDED Viewed

@@ -0,0 +1,26 @@
+import type {
+  CanonicalDocument,
+  DocumentNode,
+  DocumentRootNode,
+} from "../model/canonical-document.ts";
+/**
+ * Accept either a full `CanonicalDocument` (or a Pick of it carrying `content`)
+ * or a raw `DocumentNode`, and return the node to walk.
+ *
+ * `DrawingFrameNode` also carries a `content` property (typed differently), so
+ * `"content" in document` alone is ambiguous; the `.content.type === "doc"`
+ * marker disambiguates since `DocumentRootNode.type === "doc"`.
+ */
+export function resolveWalkableRoot(
+  document: Pick<CanonicalDocument, "content"> | DocumentNode,
+): DocumentNode {
+  // DrawingFrameNode also has a `content` property, so `"content" in document`
+  // alone is ambiguous. Every DocumentNode variant carries a top-level `type`
+  // discriminator; CanonicalDocument (and its Pick) does not — so the absence
+  // of a top-level `type` is a reliable guard.
+  if ("content" in document && !("type" in document)) {
+    return (document as { content: DocumentRootNode }).content;
+  }
+  return document as DocumentNode;
+}

package/src/legal/bookmarks.ts CHANGED Viewed

@@ -7,6 +7,7 @@ import type {
   FieldRegistry,
   FieldRegistryEntry,
 } from "../model/canonical-document.ts";
+import { resolveWalkableRoot } from "./_document-root.ts";
 export interface LegalBookmark {
   bookmarkId: string;
@@ -93,7 +94,7 @@ export function parseBookmarksFromDocumentXml(xml: string): LegalBookmark[] {
 export function collectBookmarksFromCanonicalDocument(
   document: Pick<CanonicalDocument, "content"> | DocumentNode,
 ): LegalBookmark[] {
-  const root = "content" in document ? document.content : document;
+  const root = resolveWalkableRoot(document);
   const sequence: Array<BookmarkStartNode | BookmarkEndNode> = [];
   walkDocument(root, (node) => {
@@ -219,7 +220,7 @@ function compareBookmarks(left: LegalBookmark, right: LegalBookmark): number {
 export function buildBookmarkNameMap(
   document: Pick<CanonicalDocument, "content"> | DocumentNode,
 ): Map<string, { bookmarkId: string; paragraphIndex: number }> {
-  const root = "content" in document ? document.content : document;
+  const root = resolveWalkableRoot(document);
   const map = new Map<string, { bookmarkId: string; paragraphIndex: number }>();
   let paragraphIndex = -1;
@@ -289,7 +290,7 @@ export interface BookmarkRekeyPlan {
 export function detectDuplicateBookmarkIds(
   document: Pick<CanonicalDocument, "content"> | DocumentNode,
 ): BookmarkRekeyPlan {
-  const root = "content" in document ? document.content : document;
+  const root = resolveWalkableRoot(document);
   const seenStarts = new Set<string>();
   const duplicatedIds = new Set<string>();
   let maxNumericId = 0;

package/src/legal/cross-references.ts CHANGED Viewed

@@ -12,6 +12,7 @@ import type {
   ParagraphNode,
   TocEntry,
 } from "../model/canonical-document.ts";
+import { resolveWalkableRoot } from "./_document-root.ts";
 export interface CrossReferencePattern {
   kind: "section" | "clause" | "article" | "schedule" | "exhibit" | "appendix";
@@ -42,7 +43,7 @@ interface FieldReference {
 export function collectFieldReferencesFromCanonicalDocument(
   document: Pick<CanonicalDocument, "content"> | DocumentNode,
 ): Array<{ family: string; target: string; instruction: string; paragraphIndex: number; displayText: string }> {
-  const root = "content" in document ? document.content : document;
+  const root = resolveWalkableRoot(document);
   const results: Array<{ family: string; target: string; instruction: string; paragraphIndex: number; displayText: string }> = [];
   let paragraphIndex = -1;
@@ -175,7 +176,7 @@ export function parseCrossReferencesFromDocumentXml(xml: string): CrossReference
 export function collectCrossReferencesFromCanonicalDocument(
   document: Pick<CanonicalDocument, "content"> | DocumentNode,
 ): CrossReference[] {
-  const root = "content" in document ? document.content : document;
+  const root = resolveWalkableRoot(document);
   const results: CrossReference[] = [];
   let paragraphIndex = -1;

package/src/legal/defined-terms.ts CHANGED Viewed

@@ -4,6 +4,7 @@ import type {
   DocumentNode,
   ParagraphNode,
 } from "../model/canonical-document.ts";
+import { resolveWalkableRoot } from "./_document-root.ts";
 export interface DefinedTermOccurrence {
   paragraphIndex: number;
@@ -43,7 +44,7 @@ export function collectDefinedTermsFromDocumentXml(xml: string): DefinedTerm[] {
 export function collectDefinedTermsFromCanonicalDocument(
   document: Pick<CanonicalDocument, "content"> | DocumentNode,
 ): DefinedTerm[] {
-  const root = "content" in document ? document.content : document;
+  const root = resolveWalkableRoot(document);
   const paragraphs: string[] = [];
   walkDocument(root, (node) => {

package/src/legal/signature-blocks.ts CHANGED Viewed

@@ -4,6 +4,7 @@ import type {
   DocumentNode,
   ParagraphNode,
 } from "../model/canonical-document.ts";
+import { resolveWalkableRoot } from "./_document-root.ts";
 export interface SignatureBlockCandidate {
   startIndex: number;
@@ -39,7 +40,7 @@ const UNDERLINE_PLACEHOLDER_PATTERN = /_{4,}|\.{4,}/;
 export function detectSignatureBlocksFromCanonicalDocument(
   document: Pick<CanonicalDocument, "content" | "preservation"> | DocumentNode,
 ): SignatureBlockReport {
-  const root = "content" in document ? document.content : document;
+  const root = resolveWalkableRoot(document);
   const paragraphs: Array<{ text: string; node: ParagraphNode }> = [];
   const warnings: string[] = [];