@beyondwork/docx-react-component 1.0.66 → 1.0.69

package/src/io/export/build-app-properties-xml.ts

@@ -7,7 +7,7 @@
  * content type.
  *
  * Required by:
- *   docs/plans/lane-3-layout-engine-ooxml-fidelity.md §2 A.5
+ *   CLAUDE.md (lane status table) §2 A.5
  *
  * Schema shape (ECMA-376 Part 1, Office Extended properties):
  *   <Properties xmlns="…/extended-properties" xmlns:vt="…/docPropsVTypes">

package/src/io/export/serialize-comments.ts

@@ -23,7 +23,7 @@ interface XmlTextNode {
 
 type XmlNode = XmlElementNode | XmlTextNode;
 
-interface ParagraphBoundaryMap {
+export interface ParagraphBoundaryMap {
   paragraphIndex: number;
   start: number;
   end: number;

package/src/io/export/serialize-headers-footers.ts

@@ -32,11 +32,16 @@ const V_NS = `xmlns:v="urn:schemas-microsoft-com:vml"`;
 const WP_NS = `xmlns:wp="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing"`;
 const WPS_NS = `xmlns:wps="http://schemas.microsoft.com/office/word/2010/wordprocessingShape"`;
 const A_NS = `xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main"`;
+// DrawingML pic namespace — required at the part root because inline-image
+// serialization and preserved rawXml both emit pic:pic / pic:spPr elements.
+// Word tolerates undefined prefixes; LibreOffice strict-parses and rejects
+// ("Namespace prefix pic on spPr is not defined", word/footer1.xml).
+const PIC_NS = `xmlns:pic="http://schemas.openxmlformats.org/drawingml/2006/picture"`;
 const W10_NS = `xmlns:w10="urn:schemas-microsoft-com:office:word"`;
 const W14_NS = `xmlns:w14="http://schemas.microsoft.com/office/word/2010/wordml"`;
 const W15_NS = `xmlns:w15="http://schemas.microsoft.com/office/word/2012/wordml"`;
 const WP14_NS = `xmlns:wp14="http://schemas.microsoft.com/office/word/2010/wordprocessingDrawing"`;
-const EXTENDED_ROOT_ATTRS = `${MC_NS} ${O_NS} ${V_NS} ${WP_NS} ${WPS_NS} ${A_NS} ${W10_NS} ${W14_NS} ${W15_NS} ${WP14_NS} mc:Ignorable="wps wp14 w14 w15"`;
+const EXTENDED_ROOT_ATTRS = `${MC_NS} ${O_NS} ${V_NS} ${WP_NS} ${WPS_NS} ${A_NS} ${PIC_NS} ${W10_NS} ${W14_NS} ${W15_NS} ${WP14_NS} mc:Ignorable="wps wp14 w14 w15"`;
 
 /**
  * Serialize a HeaderDocument into a headerN.xml string.

package/src/io/export/serialize-main-document.ts

@@ -102,12 +102,28 @@ interface ParagraphSerializationResult {
   boundary: RevisionParagraphBoundary;
 }
 
+type SerializeTelemetryBus = import("../../runtime/debug/telemetry-bus.ts").TelemetryBus;
+let activeSerializeTelemetryBus: SerializeTelemetryBus | undefined;
+
+export function setActiveSerializeTelemetryBus(bus: SerializeTelemetryBus | undefined): void {
+  activeSerializeTelemetryBus = bus;
+}
+
+function serializePerformanceNow(): number {
+  if (typeof performance !== "undefined" && typeof performance.now === "function") {
+    return performance.now();
+  }
+  return Date.now();
+}
+
 export function serializeMainDocument(
   content: DocumentRootNode,
   preservation: PreservationStore = { opaqueFragments: {}, packageParts: {} },
   existingRelationships: readonly OpcRelationship[] = [],
   options: SerializeMainDocumentOptions = {},
 ): SerializedMainDocument {
+  const bus = activeSerializeTelemetryBus;
+  const started = bus?.isEnabled("serialize") ? serializePerformanceNow() : 0;
   const nextRelationshipIndex =
     existingRelationships.reduce((maxIndex, relationship) => {
       const match = /^rIdHyperlink(\d+)$/.exec(relationship.id);
@@ -267,6 +283,26 @@ export function serializeMainDocument(
     offsetParagraphBoundary(boundary, prefix.length),
   );
 
+  if (bus?.isEnabled("serialize")) {
+    const blockKindCounts: Record<string, number> = Object.create(null);
+    for (const node of content.children) {
+      const kind = (node as { type?: string }).type ?? "unknown";
+      blockKindCounts[kind] = (blockKindCounts[kind] ?? 0) + 1;
+    }
+    bus.emit({
+      channel: "serialize",
+      type: "serialize.main_document.completed",
+      t: 0,
+      payload: {
+        blockCount: content.children.length,
+        blockKindCounts,
+        documentXmlBytes: documentXml.length,
+        relationshipCount: state.relationships.length,
+        ms: serializePerformanceNow() - started,
+      },
+    });
+  }
+
   return {
     documentXml,
     relationships: state.relationships,
@@ -1664,9 +1700,18 @@ function serializeDocumentAttributes(
     }
   }
 
+  // DrawingML picture namespace — always declare at the document root. Inline-
+  // image serialization (wp:inline…xmlns:pic=…) locally scopes the pic prefix,
+  // so fresh images are self-contained. But preserved rawXml (opaque_block /
+  // complex objects / headers-footers round-trip) may emit pic:pic / pic:spPr
+  // relying on inherited-scope. Without xmlns:pic at the root, LibreOffice
+  // strict-parses and rejects with "Namespace prefix pic on spPr is not
+  // defined". Declared before the `attributes` spread so a source-document
+  // override (should one exist) wins.
   const merged: Record<string, string> = {
     "xmlns:r": ns.r,
     "xmlns:w": ns.w,
+    "xmlns:pic": "http://schemas.openxmlformats.org/drawingml/2006/picture",
     ...extensionXmlns,
     ...(attributes ?? {}),
   };

package/src/io/export/serialize-run-formatting.ts

@@ -30,13 +30,28 @@ export function buildRunPropertiesXml(rPr: CanonicalRunFormatting | undefined):
   // 1. rStyle
   if (rPr.characterStyleId) parts.push(`<w:rStyle w:val="${escXml(rPr.characterStyleId)}"/>`);
 
-  // 2. rFonts
-  if (rPr.fontFamilyAscii || rPr.fontFamilyHAnsi || rPr.fontFamilyEastAsia || rPr.fontFamilyCs) {
+  // 2. rFonts — concrete names + ECMA-376 §17.3.2.26 theme-slot attrs.
+  // The complex-script theme attr is emitted as `w:cstheme` (all
+  // lowercase) to match Word's output.
+  if (
+    rPr.fontFamilyAscii ||
+    rPr.fontFamilyHAnsi ||
+    rPr.fontFamilyEastAsia ||
+    rPr.fontFamilyCs ||
+    rPr.asciiTheme ||
+    rPr.hAnsiTheme ||
+    rPr.eastAsiaTheme ||
+    rPr.csTheme
+  ) {
     const attrs: string[] = [];
     if (rPr.fontFamilyAscii) attrs.push(`w:ascii="${escXml(rPr.fontFamilyAscii)}"`);
     if (rPr.fontFamilyHAnsi) attrs.push(`w:hAnsi="${escXml(rPr.fontFamilyHAnsi)}"`);
     if (rPr.fontFamilyEastAsia) attrs.push(`w:eastAsia="${escXml(rPr.fontFamilyEastAsia)}"`);
     if (rPr.fontFamilyCs) attrs.push(`w:cs="${escXml(rPr.fontFamilyCs)}"`);
+    if (rPr.asciiTheme) attrs.push(`w:asciiTheme="${escXml(rPr.asciiTheme)}"`);
+    if (rPr.hAnsiTheme) attrs.push(`w:hAnsiTheme="${escXml(rPr.hAnsiTheme)}"`);
+    if (rPr.eastAsiaTheme) attrs.push(`w:eastAsiaTheme="${escXml(rPr.eastAsiaTheme)}"`);
+    if (rPr.csTheme) attrs.push(`w:cstheme="${escXml(rPr.csTheme)}"`);
     parts.push(`<w:rFonts ${attrs.join(" ")}/>`);
   }
 

package/src/io/export/twip.ts

@@ -18,7 +18,7 @@
  *   requireTwip(value)  — mandatory numeric: throws on non-finite input.
  *
  * Source:
- *   docs/plans/lane-3-layout-engine-ooxml-fidelity.md §2 A.2
+ *   CLAUDE.md (lane status table) §2 A.2
  */
 
 /**

package/src/io/normalize/normalize-text.ts

@@ -4,7 +4,6 @@ import type {
   CustomXmlNode,
   DiagnosticStore,
   DocumentRootNode,
-  FieldRegistry,
   InlineNode,
   MediaCatalog,
   OpaqueBlockNode,
@@ -37,21 +36,30 @@ import type {
   ParsedTableCellNode,
   ParsedTableRowNode,
 } from "../ooxml/parse-main-document.ts";
-import { classifyFieldInstruction, buildFieldRegistry } from "../ooxml/parse-fields.ts";
+import { classifyFieldInstruction } from "../ooxml/parse-fields.ts";
 import {
   type LoadScheduler,
   nowMs,
   shouldYield,
 } from "../load-scheduler.ts";
 
+/**
+ * Output of `normalizeParsedTextDocument`. Carries content + media +
+ * preservation + diagnostics + the ambient section-properties rider,
+ * and nothing else. The canonical `fieldRegistry` is NOT produced here
+ * because it requires the fully-assembled styles catalog + subParts;
+ * it is constructed inside `createImportedCanonicalDocument` (session
+ * layer) with all three inputs available. Tests that previously
+ * checked `normalized.fieldRegistry` call `buildFieldRegistry` from
+ * `src/io/ooxml/parse-fields.ts` directly — that is the canonical
+ * field-registry factory.
+ */
 export interface NormalizedTextDocument {
   content: DocumentRootNode;
   media: MediaCatalog;
   preservation: PreservationStore;
   diagnostics: DiagnosticStore;
   finalSectionProperties?: ParsedMainDocument["finalSectionProperties"];
-  /** Package-backed field registry built during normalization. */
-  fieldRegistry?: FieldRegistry;
 }
 
 interface NormalizationState {
@@ -67,7 +75,6 @@ interface NormalizationState {
 export function normalizeParsedTextDocument(
   document: ParsedMainDocument,
   packagePartName = "/word/document.xml",
-  options?: { styles?: import("../../model/canonical-document.ts").StylesCatalog },
 ): NormalizedTextDocument {
   const state: NormalizationState = {
     nextFragmentIndex: 1,
@@ -103,13 +110,6 @@ export function normalizeParsedTextDocument(
 
   const content: DocumentRootNode = { type: "doc", children };
 
-  // Build the field registry from normalized content.
-  // When styles are available, the registry includes full TOC heading resolution.
-  // Without styles, it still catalogs all field instances for the supported/preserve-only partition.
-  const styles = options?.styles ?? { paragraphs: {}, characters: {}, tables: {} };
-  const fieldRegistry = buildFieldRegistry({ content, styles });
-  const hasFields = fieldRegistry.supported.length > 0 || fieldRegistry.preserveOnly.length > 0;
-
   return {
     content,
     media: state.media,
@@ -118,7 +118,6 @@ export function normalizeParsedTextDocument(
     ...(document.finalSectionProperties !== undefined
       ? { finalSectionProperties: document.finalSectionProperties }
       : {}),
-    ...(hasFields ? { fieldRegistry } : {}),
   };
 }
 
@@ -138,7 +137,6 @@ export async function normalizeParsedTextDocumentAsync(
   document: ParsedMainDocument,
   packagePartName = "/word/document.xml",
   scheduler: LoadScheduler,
-  options?: { styles?: import("../../model/canonical-document.ts").StylesCatalog },
 ): Promise<NormalizedTextDocument> {
   const state: NormalizationState = {
     nextFragmentIndex: 1,
@@ -184,10 +182,6 @@ export async function normalizeParsedTextDocumentAsync(
 
   const content: DocumentRootNode = { type: "doc", children };
 
-  const styles = options?.styles ?? { paragraphs: {}, characters: {}, tables: {} };
-  const fieldRegistry = buildFieldRegistry({ content, styles });
-  const hasFields = fieldRegistry.supported.length > 0 || fieldRegistry.preserveOnly.length > 0;
-
   return {
     content,
     media: state.media,
@@ -196,7 +190,6 @@ export async function normalizeParsedTextDocumentAsync(
     ...(document.finalSectionProperties !== undefined
       ? { finalSectionProperties: document.finalSectionProperties }
       : {}),
-    ...(hasFields ? { fieldRegistry } : {}),
   };
 }
 
@@ -560,6 +553,18 @@ function normalizeInlineChildren(
           bookmarkId: node.bookmarkId,
         });
         break;
+      case "scope_marker_start":
+        normalized.push({
+          type: "scope_marker_start",
+          scopeId: node.scopeId,
+        });
+        break;
+      case "scope_marker_end":
+        normalized.push({
+          type: "scope_marker_end",
+          scopeId: node.scopeId,
+        });
+        break;
       case "footnote_ref":
         normalized.push({
           type: "footnote_ref",
@@ -672,7 +677,7 @@ function normalizeDrawingFrameNode(
  * surface renderer can resolve `previewMediaId` → `previewSrc` the same
  * way it does for inline images. Chart/SmartArt nodes weren't previously
  * registered because only image nodes walked through `normalizeImageNode`.
- * Needed by docs/plans/lane-5-charts.md Stage 0 (real mc:Fallback bitmaps) and
+ * Needed by CLAUDE.md (lane status table) Stage 0 (real mc:Fallback bitmaps) and
  * Stage 0B (synthesized previews from the demo harness decorator) —
  * without this, previewMediaId sits in the canonical model but
  * `canonicalDocument.media.items` has no corresponding MediaItem and
@@ -850,6 +855,8 @@ function measureNormalizedInlineDisplayLength(nodes: InlineNode[]): number {
         return total + measureNormalizedInlineDisplayLength(node.children);
       case "bookmark_start":
       case "bookmark_end":
+      case "scope_marker_start":
+      case "scope_marker_end":
         return total;
       default:
         return total + 1;

package/src/io/ooxml/chart/parse-series.ts

@@ -22,7 +22,7 @@ import {
 } from "../xml-attr-helpers.ts";
 import type { XmlElementNode } from "../xml-element.ts";
 import { parseXml } from "../xml-parser.ts";
-import { GRADIENT_STOP_UNITS } from "../../../runtime/units.ts";
+import { GRADIENT_STOP_UNITS } from "../units.ts";
 
 import type {
   BubbleSeries,

package/src/io/ooxml/chart/resolve-color.ts

@@ -2,7 +2,7 @@
  * Resolve a `ColorRef` into a concrete sRGB hex string.
  *
  * Implements the second layer of the OOXML chart-color cascade
- * (docs/plans/lane-5-charts.md § 4 Task 2.2): scheme-color and
+ * (CLAUDE.md (lane status table) § 4 Task 2.2): scheme-color and
  * themeLinked references are looked up in `ResolvedTheme.colors`, and
  * OOXML color modifiers (`lumMod`, `lumOff`, `shade`, `tint`, `satMod`,
  * `hueMod`) are applied in declaration order via HSL color math per
@@ -19,7 +19,7 @@
 
 import type { ColorMod, ColorRef } from "./types.ts";
 import type { ResolvedTheme } from "../../../model/canonical-document.ts";
-import { GRADIENT_STOP_UNITS } from "../../../runtime/units.ts";
+import { GRADIENT_STOP_UNITS } from "../units.ts";
 
 const FALLBACK_COLOR = "#808080";
 

package/src/io/ooxml/chart/types.ts

@@ -3,7 +3,7 @@
  *
  * Re-export shim. The canonical chart type definitions live in
  * `src/model/chart-types.ts` — that location avoids the former
- * `model → io` backward dependency (see `docs/plans/architecture-lane.md`
+ * `model → io` backward dependency (see `CLAUDE.md (lane status table)`
  * §F1). io/ooxml/chart and ui-tailwind/chart consumers can continue
  * importing from this path unchanged.
  */

package/src/io/ooxml/classify-embedding.ts

@@ -10,11 +10,16 @@
  *   no side-effects that break the editor. Parser proceeds as today.
  *
  * - **offloadable** — a native OOXML package (Word sub-doc, Excel
- *   workbook) that a host-side storage adapter could extract and
- *   reconstitute. In the hotfix, `offloadable` is treated as
- *   `store-only` (there is no adapter yet); the opaque-fragment path
- *   preserves bytes + XML for round-trip. Graduates when refactor/01
- *   Step 7 lands a `hostAdapter.storeEmbeddedDocument?` callback.
+ *   workbook, PowerPoint presentation) that a host-side storage
+ *   adapter extracts at load (`storeEmbeddedDocument`) and
+ *   reconstitutes at export (`loadEmbeddedDocument`). Refactor/01
+ *   Step 7 activated this classification; the offload pipeline lives
+ *   at `src/session/import/embedded-offload.ts` +
+ *   `src/session/export/embedded-reconstitute.ts`. When the host
+ *   does NOT implement the adapter methods, `offloadable` manifests
+ *   fall through to the opaque-fragment preservation path — the
+ *   bytes still round-trip byte-identical, they just stay on the
+ *   parent package.
  *
  * - **store-only** — complex binary or undigestible content (PDF,
  *   legacy binary Office, package-embedded docx with icon aspect,
@@ -45,38 +50,54 @@
  *   template variants), it is store-only even if ProgID + content-type
  *   were both missing. Weak signal but matches file-type intent.
  *
- * Why no `offloadable` return value today: the host-adapter callback
- * pair (`storeEmbeddedDocument?` + `loadEmbeddedDocument?`) that makes
- * `offloadable` meaningful lands as refactor/01 Step 7. Until then,
- * what would be `offloadable` is folded into `store-only` — the
- * opaque path preserves bytes + XML for the eventual offload.
+ * Classification split (refactor/01 Step 7, 2026-04-22):
+ *   - Native OOXML ProgIDs → `offloadable`:
+ *       Word.Document.*, Word.DocumentMacroEnabled.*, Word.Template.*,
+ *       Excel.Sheet.*, Excel.SheetMacroEnabled.*, Excel.Worksheet.*,
+ *       Excel.Chart.*, Excel.ChartMacroEnabled.*,
+ *       PowerPoint.Slide.*, PowerPoint.SlideMacroEnabled.*,
+ *       PowerPoint.Show.*, PowerPoint.ShowMacroEnabled.*,
+ *       PowerPoint.Document.*, PowerPoint.Template.*
+ *   - Binary / opaque ProgIDs → `store-only`:
+ *       Excel.SheetBinaryMacroEnabled.* (.xlsb),
+ *       AcroExch.Document.* (PDF), exact `Package` / `Packager.Package`
+ *   - Content-type override: native OOXML content types →
+ *     `offloadable`; `application/pdf` → `store-only`.
+ *   - Target-path fallback: `.docx/.docm/.dotx/.dotm` +
+ *     `.xlsx/.xlsm/.xltx/.xltm` + `.pptx/.pptm/.potx/.potm` →
+ *     `offloadable`; `.xlsb` / `.pdf` → `store-only`.
  *
  * See `docs/architecture/01-package-session.md` §P8 for the full
  * contract.
  */
 
-const STORE_ONLY_PROGID_PREFIXES: readonly string[] = [
-  // Nested Word documents — primary real-world crash source (CCEP
-  // "EU & Global IT Services Agreement.docx" type).
+const OFFLOADABLE_PROGID_PREFIXES: readonly string[] = [
+  // Native OOXML Word documents — extractable to host storage with
+  // the Step 7 adapter, reconstituted byte-identical at export.
   "Word.Document.",
   "Word.DocumentMacroEnabled.",
   "Word.Template.",
-  // Spreadsheet embeddings. Excel.Sheet.12 + Excel.Worksheet.12 are
-  // the common ProgIDs; Excel.Chart.* less so.
+  // Native OOXML Excel formats (.xlsx / .xlsm / .xltx / .xltm).
+  // `SheetBinaryMacroEnabled` is .xlsb — binary, not OOXML — and
+  // lives in the store-only list below.
   "Excel.Sheet.",
   "Excel.SheetMacroEnabled.",
-  "Excel.SheetBinaryMacroEnabled.",
   "Excel.Worksheet.",
   "Excel.Chart.",
   "Excel.ChartMacroEnabled.",
-  // Presentations.
+  // Native OOXML presentations (.pptx / .pptm / .potx / .potm).
   "PowerPoint.Slide.",
   "PowerPoint.SlideMacroEnabled.",
   "PowerPoint.Show.",
   "PowerPoint.ShowMacroEnabled.",
   "PowerPoint.Document.",
   "PowerPoint.Template.",
-  // PDF via Adobe Acrobat.
+];
+
+const STORE_ONLY_PROGID_PREFIXES: readonly string[] = [
+  // Excel's legacy binary format — not OOXML, can't be offloaded.
+  "Excel.SheetBinaryMacroEnabled.",
+  // PDF via Adobe Acrobat — binary, store-only.
   "AcroExch.Document.",
 ];
 
@@ -87,20 +108,24 @@ const STORE_ONLY_PROGID_EXACT: ReadonlySet<string> = new Set([
 ]);
 
 /**
- * Content-type patterns that force store-only regardless of ProgID.
- * These are checked against the relationship target's content-type as
- * declared in `[Content_Types].xml` overrides.
+ * Content-type patterns that mark native-OOXML embeddings — eligible
+ * for offload when the host adapter opts in.
  */
-const STORE_ONLY_CONTENT_TYPES: readonly string[] = [
-  // Package-embedded Word document (relationships/package type on a
-  // word/embeddings/*.docx part). Catches the CCEP case even if the
-  // ProgID is missing or atypical.
+const OFFLOADABLE_CONTENT_TYPES: readonly string[] = [
   "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
   "application/vnd.openxmlformats-officedocument.wordprocessingml.template",
   "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
   "application/vnd.openxmlformats-officedocument.spreadsheetml.template",
   "application/vnd.openxmlformats-officedocument.presentationml.presentation",
   "application/vnd.openxmlformats-officedocument.presentationml.template",
+];
+
+/**
+ * Content-type patterns that force store-only — binary formats that
+ * cannot be re-processed by this codebase and must round-trip as
+ * opaque bytes.
+ */
+const STORE_ONLY_CONTENT_TYPES: readonly string[] = [
   "application/pdf",
 ];
 
@@ -138,14 +163,22 @@ export function classifyEmbedding(
   const contentType = input.contentType?.trim().toLowerCase() ?? "";
   const targetPath = input.targetPath?.toLowerCase() ?? "";
 
-  // Exact ProgID match.
+  // Exact ProgID match — ambiguous `Package` / `Packager.Package`
+  // stays store-only (fail-closed: no signal for native OOXML so
+  // host storage extraction isn't safe).
   if (progId && STORE_ONLY_PROGID_EXACT.has(progId)) {
     return "store-only";
   }
 
-  // ProgID prefix match. Handles Word.Document.12, Word.Document.14,
-  // Word.DocumentMacroEnabled.12, Excel.Sheet.12, AcroExch.Document.7, etc.
+  // ProgID prefix match — check offloadable families first so
+  // native-OOXML embeddings are promoted ahead of the binary
+  // fall-through list.
   if (progId) {
+    for (const prefix of OFFLOADABLE_PROGID_PREFIXES) {
+      if (progId.startsWith(prefix)) {
+        return "offloadable";
+      }
+    }
     for (const prefix of STORE_ONLY_PROGID_PREFIXES) {
       if (progId.startsWith(prefix)) {
         return "store-only";
@@ -153,8 +186,15 @@ export function classifyEmbedding(
     }
   }
 
-  // Content-type override.
+  // Content-type override — native-OOXML content types lift to
+  // offloadable regardless of ProgID; binary content types stay
+  // store-only.
   if (contentType) {
+    for (const ct of OFFLOADABLE_CONTENT_TYPES) {
+      if (contentType === ct || contentType.startsWith(`${ct};`)) {
+        return "offloadable";
+      }
+    }
     for (const ct of STORE_ONLY_CONTENT_TYPES) {
       if (contentType === ct || contentType.startsWith(`${ct};`)) {
         return "store-only";
@@ -163,13 +203,21 @@ export function classifyEmbedding(
   }
 
   // Target-path fallback when we have no progId + no content-type.
-  // A `.docx` / `.xlsx` / `.pptx` / `.pdf` extension in the embeddings
-  // folder is a strong signal of a package payload.
+  // A native-OOXML extension in the embeddings folder is a strong
+  // signal of an offloadable package payload. `.xlsb` / `.pdf` stay
+  // store-only.
   if (targetPath) {
-    const storeOnlyExtensions = [".docx", ".docm", ".dotx", ".dotm",
+    const offloadableExtensions = [
+      ".docx", ".docm", ".dotx", ".dotm",
       ".xlsx", ".xlsm", ".xltx", ".xltm",
       ".pptx", ".pptm", ".potx", ".potm",
-      ".pdf"];
+    ];
+    for (const ext of offloadableExtensions) {
+      if (targetPath.endsWith(ext)) {
+        return "offloadable";
+      }
+    }
+    const storeOnlyExtensions = [".xlsb", ".pdf"];
     for (const ext of storeOnlyExtensions) {
       if (targetPath.endsWith(ext)) {
         return "store-only";
@@ -187,7 +235,9 @@ export function classifyEmbedding(
  * Exposed for tests. Not part of the public API.
  */
 export const __internal = {
+  OFFLOADABLE_PROGID_PREFIXES,
   STORE_ONLY_PROGID_PREFIXES,
   STORE_ONLY_PROGID_EXACT,
+  OFFLOADABLE_CONTENT_TYPES,
   STORE_ONLY_CONTENT_TYPES,
 } as const;

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

@@ -17,7 +17,7 @@
  * four fill families.
  */
 
-import { GRADIENT_STOP_UNITS } from "../../runtime/units.ts";
+import { GRADIENT_STOP_UNITS } from "./units.ts";
 import { localName } from "./xml-attr-helpers.ts";
 
 export interface XmlElementNode {

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

@@ -284,6 +284,8 @@ export type ParsedInlineNode =
   | ParsedOleEmbedInlineNode
   | ParsedBookmarkStartInlineNode
   | ParsedBookmarkEndInlineNode
+  | ParsedScopeMarkerStartInlineNode
+  | ParsedScopeMarkerEndInlineNode
   | ParsedFootnoteRefInlineNode
   | ParsedFieldInlineNode
   | ParsedPermStartInlineNode
@@ -425,6 +427,23 @@ export interface ParsedBookmarkEndInlineNode {
   rawXml: string;
 }
 
+/**
+ * Scope-marker inline nodes — produced by `rewriteScopeMarkerBookmarks`
+ * post-parse after it sees the `bw:scope:` bookmark prefix. These survive
+ * the normalization pass and land in the canonical document as
+ * `ScopeMarkerStartNode` / `ScopeMarkerEndNode`. See
+ * `src/io/ooxml/parse-scope-markers.ts` for the prefix contract.
+ */
+export interface ParsedScopeMarkerStartInlineNode {
+  type: "scope_marker_start";
+  scopeId: string;
+}
+
+export interface ParsedScopeMarkerEndInlineNode {
+  type: "scope_marker_end";
+  scopeId: string;
+}
+
 export interface ParsedFootnoteRefInlineNode {
   type: "footnote_ref";
   noteId: string;
@@ -618,6 +637,20 @@ const HYPERLINK_RELATIONSHIP_TYPE =
  */
 let activeChartPartLookup: ChartPartLookup | undefined;
 
+/**
+ * Phase 1 telemetry — optional bus installed by the runtime before a load.
+ * Populated via `setActiveParseTelemetryBus(bus)` from
+ * `src/io/docx-session.ts`. Emits one `parse.main_document.completed`
+ * event per call with element counts. Re-entrancy invariant matches
+ * `activeChartPartLookup` above.
+ */
+type ParseTelemetryBus = import("../../runtime/debug/telemetry-bus.ts").TelemetryBus;
+let activeParseTelemetryBus: ParseTelemetryBus | undefined;
+
+export function setActiveParseTelemetryBus(bus: ParseTelemetryBus | undefined): void {
+  activeParseTelemetryBus = bus;
+}
+
 export function parseMainDocumentXml(
   xml: string,
   relationships: readonly OpcRelationship[] = [],
@@ -626,13 +659,50 @@ export function parseMainDocumentXml(
   chartPartLookup?: ChartPartLookup,
 ): ParsedMainDocument {
   activeChartPartLookup = chartPartLookup;
+  const bus = activeParseTelemetryBus;
+  const started = bus?.isEnabled("parse") ? performanceNow() : 0;
   try {
-    return parseMainDocumentXmlInner(xml, relationships, mediaParts, sourcePartPath);
+    const result = parseMainDocumentXmlInner(xml, relationships, mediaParts, sourcePartPath);
+    if (bus?.isEnabled("parse")) {
+      emitParseSummary(bus, result, sourcePartPath, performanceNow() - started);
+    }
+    return result;
   } finally {
     activeChartPartLookup = undefined;
   }
 }
 
+function performanceNow(): number {
+  if (typeof performance !== "undefined" && typeof performance.now === "function") {
+    return performance.now();
+  }
+  return Date.now();
+}
+
+function emitParseSummary(
+  bus: ParseTelemetryBus,
+  result: ParsedMainDocument,
+  partPath: string,
+  ms: number,
+): void {
+  const counts: Record<string, number> = Object.create(null);
+  for (const block of result.blocks) {
+    const kind = (block as { type?: string }).type ?? "unknown";
+    counts[kind] = (counts[kind] ?? 0) + 1;
+  }
+  bus.emit({
+    channel: "parse",
+    type: "parse.main_document.completed",
+    t: 0,
+    payload: {
+      partPath,
+      blockCount: result.blocks.length,
+      blockKindCounts: counts,
+      ms,
+    },
+  });
+}
+
 /**
  * CO4.5 — Parse a raw `<w:sdt>` XML fragment in isolation, with full drawing-
  * frame support. Used by `parse-picture-sdt.ts` and tests.