@beyondwork/docx-react-component 1.0.48 → 1.0.50

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

@@ -108,8 +108,11 @@ export function parseComplexContentXml(
   const uri = graphicData.attributes.uri ?? graphicData.attributes["uri"] ?? "";
   if (isChartUri(uri)) {
     const parsedData = maybeParseChart(root, chartPartLookup);
-    const node: ParsedChartContent = { type: "chart_preview", rawXml: drawingXml };
-    if (parsedData) node.parsedData = parsedData;
+    const node: ParsedChartContent = {
+      type: "chart_preview",
+      ...(parsedData ? { parsedData } : {}),
+      rawXml: drawingXml,
+    };
     return node;
   }
   if (isSmartArtUri(uri)) {
@@ -229,9 +232,9 @@ function parseAlternateContent(
       ...(previewMediaId ? { previewMediaId } : {}),
       ...(previewPackagePartName ? { previewPackagePartName } : {}),
       ...(previewContentType ? { previewContentType } : {}),
+      ...(parsedData ? { parsedData } : {}),
       rawXml: fullDrawingXml,
     };
-    if (parsedData) node.parsedData = parsedData;
     return node;
   }
 

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

@@ -67,6 +67,37 @@ import {
   readTableStyleId as readSharedTableStyleId,
   readTableWidth as readSharedTableWidth,
 } from "./parse-tables.ts";
+import {
+  buildGrabBagSourceChildFromParsed,
+  capturePropertyGrabBag,
+  type PropertyGrabBagDescriptor,
+} from "./property-grab-bag.ts";
+
+/**
+ * Modelled direct children of `<w:sectPr>` that `parseSectionPropertiesFromElement`
+ * below dispatches into typed fields on `SectionProperties`. Anything else
+ * becomes a grab-bag entry so a parse→serialize round-trip preserves
+ * extension-namespace section properties and Word-internal knobs the
+ * canonical model doesn't understand. Mirrors Slice 1/2 pPr/rPr coverage.
+ */
+const SECT_PR_MODELLED_CHILDREN: ReadonlySet<string> = new Set([
+  "cols",
+  "docGrid",
+  "footerReference",
+  "headerReference",
+  "lnNumType",
+  "pgBorders",
+  "pgMar",
+  "pgNumType",
+  "pgSz",
+  "titlePg",
+  "type",
+]);
+
+const SECT_PR_GRAB_BAG_DESCRIPTOR: PropertyGrabBagDescriptor = {
+  modelledChildNames: SECT_PR_MODELLED_CHILDREN,
+  modelledChildAttributes: new Map(),
+};
 
 export interface ParsedMainDocument {
   blocks: ParsedBlockNode[];
@@ -3170,6 +3201,16 @@ export function parseSectionPropertiesFromElement(
     }
   }
 
+  // Grab-bag capture for unmodelled <w:sectPr> children (O2 Slice 4).
+  const sourceChildren = node.children
+    .filter((child): child is XmlElementNode => child.type === "element")
+    .map((child) => buildGrabBagSourceChildFromParsed(child));
+  const unknown = capturePropertyGrabBag(
+    sourceChildren,
+    SECT_PR_GRAB_BAG_DESCRIPTOR,
+  );
+  if (unknown) props.unknownPropertyChildren = unknown;
+
   return props;
 }
 

package/src/io/ooxml/parse-paragraph-formatting.ts

@@ -17,6 +17,42 @@ import type {
 import { readRunProperties } from "./parse-run-formatting.ts";
 import { findChildOptional, localName, readIntAttr, readIntVal, readOnOff } from "./xml-attr-helpers.ts";
 import type { XmlElementNode } from "./xml-element.ts";
+import {
+  buildGrabBagSourceChildFromParsed,
+  capturePropertyGrabBag,
+  type PropertyGrabBagDescriptor,
+} from "./property-grab-bag.ts";
+
+/**
+ * Modelled direct children of `<w:pPr>` that `readParagraphProperties` below
+ * dispatches into typed fields on `CanonicalParagraphFormatting`. Anything
+ * else becomes a grab-bag entry so a parse→serialize round-trip preserves
+ * extension-namespace properties like `<w15:collapsed>` or Word-internal
+ * knobs like `<w:kinsoku>` that our canonical model doesn't understand.
+ */
+const PPR_MODELLED_CHILDREN: ReadonlySet<string> = new Set([
+  "spacing",
+  "ind",
+  "jc",
+  "pBdr",
+  "shd",
+  "tabs",
+  "keepNext",
+  "keepLines",
+  "widowControl",
+  "pageBreakBefore",
+  "contextualSpacing",
+  "bidi",
+  "suppressLineNumbers",
+  "suppressAutoHyphens",
+  "outlineLvl",
+  "rPr",
+]);
+
+const PPR_GRAB_BAG_DESCRIPTOR: PropertyGrabBagDescriptor = {
+  modelledChildNames: PPR_MODELLED_CHILDREN,
+  modelledChildAttributes: new Map(),
+};
 
 function readSpacing(node: XmlElementNode): ParagraphSpacing | undefined {
   const out: ParagraphSpacing = {};
@@ -184,5 +220,15 @@ export function readParagraphProperties(
   const markRpr = readRunProperties(rPrNode);
   if (markRpr) out.paragraphMarkRunProperties = markRpr;
 
+  // Capture any unmodelled direct children of <w:pPr> so a parse→serialize
+  // round-trip does not silently drop extension-namespace properties
+  // (w15:collapsed, w16cex:..., w:kinsoku, etc.). See Lane 3 O2 plan +
+  // src/io/ooxml/property-grab-bag.ts for the pattern.
+  const sourceChildren = node.children
+    .filter((child): child is XmlElementNode => child.type === "element")
+    .map((child) => buildGrabBagSourceChildFromParsed(child));
+  const unknown = capturePropertyGrabBag(sourceChildren, PPR_GRAB_BAG_DESCRIPTOR);
+  if (unknown) out.unknownPropertyChildren = unknown;
+
   return Object.keys(out).length > 0 ? out : undefined;
 }

package/src/io/ooxml/parse-run-formatting.ts

@@ -1,6 +1,42 @@
 import type { CanonicalRunFormatting } from "../../model/canonical-document.ts";
 import { findChildOptional, readIntVal, readOnOff, readStringAttr } from "./xml-attr-helpers.ts";
 import type { XmlElementNode } from "./xml-element.ts";
+import {
+  buildGrabBagSourceChildFromParsed,
+  capturePropertyGrabBag,
+  type PropertyGrabBagDescriptor,
+} from "./property-grab-bag.ts";
+
+/**
+ * Modelled direct children of `<w:rPr>` that `readRunProperties` dispatches
+ * into typed fields on `CanonicalRunFormatting`. Anything else goes through
+ * the grab-bag helper so a parse→serialize round-trip preserves extension-
+ * namespace properties (e.g. `<w14:textOutline>`, `<w:em>`, `<w:kern>`).
+ */
+const RPR_MODELLED_CHILDREN: ReadonlySet<string> = new Set([
+  "b",
+  "i",
+  "strike",
+  "dstrike",
+  "vanish",
+  "caps",
+  "smallCaps",
+  "u",
+  "vertAlign",
+  "rFonts",
+  "sz",
+  "szCs",
+  "color",
+  "highlight",
+  "spacing",
+  "rStyle",
+  "lang",
+]);
+
+const RPR_GRAB_BAG_DESCRIPTOR: PropertyGrabBagDescriptor = {
+  modelledChildNames: RPR_MODELLED_CHILDREN,
+  modelledChildAttributes: new Map(),
+};
 
 /**
  * Read `<w:rPr>` (run properties) into a `CanonicalRunFormatting` value.
@@ -101,8 +137,14 @@ export function readRunProperties(
     const val = color.attributes["w:val"] ?? color.attributes["val"];
     const theme =
       color.attributes["w:themeColor"] ?? color.attributes["themeColor"];
+    const tint =
+      color.attributes["w:themeTint"] ?? color.attributes["themeTint"];
+    const shade =
+      color.attributes["w:themeShade"] ?? color.attributes["themeShade"];
     if (val) rPr.colorHex = val;
     if (theme) rPr.colorThemeSlot = theme;
+    if (tint) rPr.colorThemeTint = tint;
+    if (shade) rPr.colorThemeShade = shade;
   }
 
   const highlight = findChildOptional(node, "highlight");
@@ -125,5 +167,12 @@ export function readRunProperties(
     if (val) rPr.languageCode = val;
   }
 
+  // Grab-bag capture: unmodelled <w:rPr> children survive round-trip.
+  const sourceChildren = node.children
+    .filter((child): child is XmlElementNode => child.type === "element")
+    .map((child) => buildGrabBagSourceChildFromParsed(child));
+  const unknown = capturePropertyGrabBag(sourceChildren, RPR_GRAB_BAG_DESCRIPTOR);
+  if (unknown) rPr.unknownPropertyChildren = unknown;
+
   return Object.keys(rPr).length > 0 ? rPr : undefined;
 }

package/src/io/ooxml/property-grab-bag.ts

@@ -0,0 +1,211 @@
+/**
+ * Property-level grab-bag primitive for Lane 3 O2.
+ *
+ * LibreOffice captures unmodelled children / attributes on every OOXML
+ * property container (`<w:pPr>`, `<w:rPr>`, `<w:tcPr>`, `<w:trPr>`,
+ * `<w:tblPr>`, `<w:sectPr>`) via per-container "grab bags" keyed by
+ * element name — see `PropertyMap.hxx:82` and
+ * `libreoffice-analysis.md` §2 for the mechanism. On export, every grab
+ * bag re-emits verbatim inside its container so the round-trip pipeline
+ * does not silently drop extension-namespace properties (`w15:collapsed`,
+ * `w16cex:...`, etc.) or attributes Word adds after we parsed its schema.
+ *
+ * This module is a small, framework-free adapter: per-container parsers
+ * supply a descriptor listing modelled child names (and later, modelled
+ * attributes on modelled children); the helper returns everything else as
+ * raw XML in insertion order. The matching emitter is a one-liner that
+ * just joins `rawXml` strings.
+ *
+ * Scope (O2 Slice 1): per-container child diff only — the unknown-attribute
+ * diff on modelled children is a follow-up slice. Today the descriptor's
+ * `modelledChildAttributes` is declared but ignored; the helper emits a
+ * whole-child entry only when the element's localName is NOT in
+ * `modelledChildNames`.
+ */
+
+/**
+ * Input node shape accepted by `capturePropertyGrabBag`. Intentionally
+ * minimal so every caller can adapt their own scanner output — per-file
+ * parsers in `src/io/ooxml/` each carry a slightly different node shape.
+ */
+export interface GrabBagSourceChild {
+  /**
+   * Local element name (no namespace prefix). E.g. `"kinsoku"` for
+   * `<w:kinsoku>`, `"collapsed"` for `<w15:collapsed>`.
+   */
+  localName: string;
+  /**
+   * The source XML for the entire child element, including its opening
+   * tag, all attributes, any children, and its closing tag (or the
+   * self-closing form). Preserved verbatim for re-emission.
+   */
+  rawXml: string;
+}
+
+/**
+ * Interop helper for callers that only carry the parsed `XmlElementNode`
+ * shape used by `src/io/ooxml/xml-element.ts`. Reconstructs a best-effort
+ * `rawXml` string from the parsed tree so parsers that don't track source
+ * offsets can still feed the grab-bag helper.
+ *
+ * The reconstruction preserves element/attribute semantic content and
+ * attribute insertion order (since `Record<string, string>` iteration in
+ * V8 is insertion-ordered for string keys) but does NOT guarantee
+ * byte-identical source preservation: whitespace between elements and
+ * attribute quoting style are normalized. For the Slice 1 scope this is
+ * the correct trade-off — unmodelled children's semantic content
+ * survives, which closes the silent-drop gap.
+ */
+export function buildGrabBagSourceChildFromParsed(node: {
+  name: string;
+  attributes: Record<string, string>;
+  children: Array<{ type: "element"; name: string; attributes: Record<string, string>; children: unknown[] } | { type: "text"; text: string }>;
+}): GrabBagSourceChild {
+  return {
+    localName: localNameOf(node.name),
+    rawXml: serializeElementToString(node),
+  };
+}
+
+function localNameOf(qualified: string): string {
+  const colon = qualified.indexOf(":");
+  return colon < 0 ? qualified : qualified.slice(colon + 1);
+}
+
+function escapeAttr(value: string): string {
+  return value
+    .replace(/&/gu, "&amp;")
+    .replace(/</gu, "&lt;")
+    .replace(/>/gu, "&gt;")
+    .replace(/"/gu, "&quot;");
+}
+
+function escapeText(value: string): string {
+  return value
+    .replace(/&/gu, "&amp;")
+    .replace(/</gu, "&lt;")
+    .replace(/>/gu, "&gt;");
+}
+
+function serializeElementToString(node: {
+  name: string;
+  attributes: Record<string, string>;
+  children: Array<{ type: "element"; name: string; attributes: Record<string, string>; children: unknown[] } | { type: "text"; text: string }>;
+}): string {
+  const attrs = Object.entries(node.attributes)
+    .map(([name, value]) => ` ${name}="${escapeAttr(value)}"`)
+    .join("");
+  if (node.children.length === 0) {
+    return `<${node.name}${attrs}/>`;
+  }
+  const body = node.children
+    .map((child) => {
+      if (child.type === "text") return escapeText(child.text);
+      return serializeElementToString(
+        child as {
+          name: string;
+          attributes: Record<string, string>;
+          children: Array<{ type: "element"; name: string; attributes: Record<string, string>; children: unknown[] } | { type: "text"; text: string }>;
+        },
+      );
+    })
+    .join("");
+  return `<${node.name}${attrs}>${body}</${node.name}>`;
+}
+
+/**
+ * Descriptor a per-container parser supplies to the helper to declare
+ * which child element names it dispatches into its modelled fields.
+ * Children not listed here become grab-bag entries.
+ */
+export interface PropertyGrabBagDescriptor {
+  /**
+   * Set of local names the container parser handles natively. Children
+   * whose `localName` matches one of these are NOT captured.
+   */
+  modelledChildNames: ReadonlySet<string>;
+  /**
+   * Reserved for the follow-up slice: per-modelled-child the set of
+   * attributes the parser consumes. The Slice 1 helper ignores this
+   * field; Slice 2 will use it to emit attribute-level grab entries on
+   * modelled children.
+   *
+   * Note: table containers (tblPr/trPr/tcPr — O2 Slice 3) currently use
+   * a parallel raw-XML mechanism in `src/io/export/table-properties-xml.ts`
+   * (`mergePropertiesXml`) that stores the full container XML as a string
+   * on `TableNode.propertiesXml`/`TableRowNode.propertiesXml`/
+   * `TableCellNode.propertiesXml`. That path cannot participate in the
+   * attribute-level grab-bag slice until it is retrofit to emit
+   * `UnknownPropertyChild[]` through this descriptor. Tracked as a Lane 3
+   * Tier-2 backlog entry — see `docs/plans/lane-3-layout-engine-ooxml-fidelity.md`.
+   */
+  modelledChildAttributes: ReadonlyMap<string, ReadonlySet<string>>;
+}
+
+/**
+ * Single grab-bag entry: an unmodelled top-level child captured verbatim
+ * so the serializer can re-emit it inside its container without any
+ * round-trip loss.
+ */
+export interface UnknownPropertyChild {
+  /**
+   * Qualified element name as it appeared in the source (e.g.
+   * `"w:kinsoku"`, `"w15:collapsed"`). Used for diagnostics and for the
+   * future attribute-level diff so the emitter can re-open the matching
+   * element when needed.
+   */
+  elementName: string;
+  /**
+   * Verbatim XML for the child element.
+   */
+  rawXml: string;
+}
+
+/**
+ * Walk the container's direct children. Return every child whose
+ * `localName` is NOT in `descriptor.modelledChildNames` as a grab-bag
+ * entry in source order. Returns `undefined` when no unmodelled children
+ * were found — callers should prefer `undefined` over an empty array so
+ * the canonical model stays sparse.
+ *
+ * The helper does NOT inspect attributes or grandchildren. That
+ * refinement is reserved for the follow-up slice.
+ */
+export function capturePropertyGrabBag(
+  children: readonly GrabBagSourceChild[],
+  descriptor: PropertyGrabBagDescriptor,
+): UnknownPropertyChild[] | undefined {
+  const bag: UnknownPropertyChild[] = [];
+  for (const child of children) {
+    if (descriptor.modelledChildNames.has(child.localName)) continue;
+    bag.push({
+      elementName: extractQualifiedNameFromRawXml(child.rawXml) ?? child.localName,
+      rawXml: child.rawXml,
+    });
+  }
+  return bag.length > 0 ? bag : undefined;
+}
+
+/**
+ * Emit a grab-bag list back into a property container. Just concatenates
+ * each entry's `rawXml` in insertion order — the source bytes survive
+ * verbatim including attribute order, whitespace inside the element, and
+ * namespace prefixes.
+ */
+export function emitPropertyGrabBag(
+  entries: readonly UnknownPropertyChild[] | undefined,
+): string {
+  if (!entries || entries.length === 0) return "";
+  return entries.map((entry) => entry.rawXml).join("");
+}
+
+/**
+ * Best-effort extraction of the qualified element name from an opening
+ * tag — e.g. `<w15:collapsed w:val="1"/>` → `"w15:collapsed"`. Falls back
+ * to the caller-supplied `localName` when the raw XML doesn't look like
+ * a valid element.
+ */
+function extractQualifiedNameFromRawXml(rawXml: string): string | undefined {
+  const match = rawXml.match(/^<([^\s/>]+)/u);
+  return match?.[1];
+}

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

@@ -0,0 +1,114 @@
+/**
+ * I2 Tier B Slice 2 — Office-clipboard / WordprocessingML paste parser.
+ *
+ * Adapts the authoritative `parseMainDocumentXml` → `normalizeParsedTextDocument`
+ * pipeline to a clipboard-paste payload. Inputs from the browser clipboard under
+ * the Office MIME types (`application/x-docx-fragment`,
+ * `application/vnd.ms-word.wordprocessingml.paste`) arrive either as:
+ *
+ *   - a full `<w:document><w:body>…</w:body></w:document>` wrapper, or
+ *   - a bare `<w:body>…</w:body>` fragment.
+ *
+ * This adapter auto-wraps the bare form, runs the full parse + normalize, and
+ * returns the resulting canonical `BlockNode`s as a `CanonicalDocumentFragment`.
+ * Errors (XML parse failure, missing body) are returned as a structured result
+ * instead of thrown, so `pm-command-bridge.ts` `handlePaste` can gracefully fall
+ * through to HTML or plain-text Tier A.
+ */
+
+import type { CanonicalDocumentFragment } from "../../api/public-types.ts";
+import type { DocumentRootNode } from "../../model/canonical-document.ts";
+import { parseMainDocumentXml } from "../ooxml/parse-main-document.ts";
+import { normalizeParsedTextDocument } from "../normalize/normalize-text.ts";
+import { serializeMainDocument } from "../export/serialize-main-document.ts";
+
+export type ParseCanonicalFragmentResult =
+  | { ok: true; fragment: CanonicalDocumentFragment }
+  | { ok: false; reason: string };
+
+const WORD_NS = `xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"`;
+
+export function parseCanonicalFragmentFromWordML(xml: string): ParseCanonicalFragmentResult {
+  if (typeof xml !== "string" || xml.length === 0) {
+    return { ok: false, reason: "empty WordML payload" };
+  }
+
+  const prepared = ensureDocumentShell(xml);
+
+  try {
+    const parsed = parseMainDocumentXml(prepared);
+    const normalized = normalizeParsedTextDocument(parsed);
+    return {
+      ok: true,
+      fragment: { blocks: normalized.content.children },
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      reason: error instanceof Error ? error.message : "unknown WordML parse error",
+    };
+  }
+}
+
+/**
+ * Normalize the incoming clipboard payload into a full `<w:document><w:body>…`
+ * shell. Handles three shapes:
+ *
+ *   1. Already-wrapped `<w:document>…</w:document>` → pass-through with the XML
+ *      declaration normalized.
+ *   2. Bare `<w:body>…</w:body>` — wrap in `<w:document>…</w:document>`.
+ *   3. Any other fragment — wrap the whole input in `<w:document><w:body>…`.
+ *
+ * Namespace hygiene: if the input lacks the `xmlns:w` declaration on whatever
+ * outer element survives, it's added to the outer `<w:document>` wrapper.
+ */
+function ensureDocumentShell(xml: string): string {
+  const trimmed = xml.trim();
+  const withoutDecl = trimmed.replace(/^<\?xml[^?]*\?>/, "").trim();
+
+  const hasDocumentWrapper = /^<w:document[\s>]/i.test(withoutDecl);
+  if (hasDocumentWrapper) {
+    return ensureXmlDecl(trimmed);
+  }
+
+  const hasBodyWrapper = /^<w:body[\s>]/i.test(withoutDecl);
+  const inner = hasBodyWrapper ? withoutDecl : `<w:body>${withoutDecl}</w:body>`;
+
+  const wrapped = `<w:document ${WORD_NS}>${stripRedundantNs(inner)}</w:document>`;
+  return ensureXmlDecl(wrapped);
+}
+
+function ensureXmlDecl(xml: string): string {
+  if (/^\s*<\?xml/.test(xml)) return xml;
+  return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>${xml}`;
+}
+
+/**
+ * Strip `xmlns:w="…"` from the first child element so the outer
+ * `<w:document>` declaration is the single authoritative binding. The XML
+ * parser accepts both, but removing the duplicate keeps output clean.
+ */
+function stripRedundantNs(xml: string): string {
+  return xml.replace(/\s+xmlns:w="[^"]*"/, "");
+}
+
+/**
+ * I2 Tier B Slice 4a — inverse of `parseCanonicalFragmentFromWordML`. Produces
+ * a full `<w:document><w:body>…</w:body></w:document>` payload suitable for
+ * writing to the system clipboard under the Office MIME types, or for exchange
+ * with agents that expect WordML.
+ *
+ * Implementation reuses the authoritative `serializeMainDocument` pipeline by
+ * wrapping `fragment.blocks` in a synthetic `DocumentRootNode`. The output is
+ * the full document XML — parsers (browsers, Word, our own Slice 2 adapter)
+ * accept the full envelope, so there's no need to strip it down to a bare
+ * `<w:body>` fragment.
+ */
+export function serializeFragmentToWordML(fragment: CanonicalDocumentFragment): string {
+  const root: DocumentRootNode = {
+    type: "doc",
+    children: fragment.blocks,
+  };
+  const serialized = serializeMainDocument(root);
+  return serialized.documentXml;
+}

package/src/model/canonical-document.ts

@@ -472,10 +472,34 @@ export interface CanonicalRunFormatting {
    */
   colorHex?: string;
   colorThemeSlot?: string;
+  /**
+   * `w:themeTint` hex byte (0x00–0xFF) read from `<w:color>`. ECMA-376
+   * §17.18.85. Applied at render/cascade time against `colorThemeSlot`:
+   * luminance mod = (1 - tint/255) * L + tint/255 (shifts hue toward
+   * white; 0xFF means no modulation). Preserved as the raw hex string
+   * for byte-stable round-trip; resolution math lives in the runtime
+   * theme-color resolver.
+   */
+  colorThemeTint?: string;
+  /**
+   * `w:themeShade` hex byte (0x00–0xFF) from `<w:color>`. ECMA-376
+   * §17.18.83. Applied at render/cascade time: luminance mod =
+   * shade/255 * L (darkens toward black; 0xFF means no modulation).
+   */
+  colorThemeShade?: string;
   highlight?: string;
   characterSpacingTwips?: number;
   characterStyleId?: string;
   languageCode?: string;
+  /**
+   * Unmodelled direct children of `<w:rPr>` captured verbatim for round-trip.
+   * See `src/io/ooxml/property-grab-bag.ts` and
+   * `CanonicalParagraphFormatting.unknownPropertyChildren` for the full
+   * pattern. Preserves extension-namespace properties like `<w14:textOutline>`,
+   * `<w:em>`, `<w:kern>` through parse→serialize round-trip even though the
+   * runtime does not model them.
+   */
+  unknownPropertyChildren?: UnknownPropertyChild[];
 }
 
 /** Body of an OOXML `<w:pPr>` (paragraph properties). All fields optional; absence = "not specified at this level". */
@@ -496,6 +520,32 @@ export interface CanonicalParagraphFormatting {
   suppressLineNumbers?: boolean;
   suppressAutoHyphens?: boolean;
   paragraphMarkRunProperties?: CanonicalRunFormatting;
+  /**
+   * Unmodelled direct children of `<w:pPr>` captured verbatim for round-trip.
+   * See `src/io/ooxml/property-grab-bag.ts` for the mechanism and Lane 3 O2
+   * plan for the LibreOffice `PropertyMap.hxx:82` precedent.
+   *
+   * Each entry carries the source XML for an unmodelled child element plus
+   * its qualified name. On export, entries are re-emitted after the
+   * modelled children so Word-extension properties like `<w15:collapsed>`
+   * or `<w:kinsoku>` survive a parse→serialize round-trip even though the
+   * runtime doesn't understand them.
+   */
+  unknownPropertyChildren?: UnknownPropertyChild[];
+}
+
+/**
+ * A single unmodelled direct child of an OOXML property container (pPr,
+ * rPr, tcPr, trPr, tblPr, sectPr). Captured verbatim so the serializer
+ * re-emits source bytes without loss. See `src/io/ooxml/property-grab-bag.ts`
+ * for the helper that computes the diff against a per-container modelled-
+ * child allow-list.
+ */
+export interface UnknownPropertyChild {
+  /** Qualified element name as it appeared in source, e.g. "w15:collapsed". */
+  elementName: string;
+  /** Verbatim source XML for the child element, including closing/self-closing form. */
+  rawXml: string;
 }
 
 /** Body of an OOXML `<w:docDefaults>` — baseline formatting applied before style chain. */
@@ -896,6 +946,15 @@ export interface SectionProperties {
   footerReferences?: HeaderFooterReference[];
   sectionType?: "continuous" | "nextPage" | "evenPage" | "oddPage" | "nextColumn";
   titlePage?: boolean;
+  /**
+   * Unmodelled direct children of `<w:sectPr>` captured verbatim for
+   * round-trip. Mirrors `CanonicalParagraphFormatting.unknownPropertyChildren`
+   * and `CanonicalRunFormatting.unknownPropertyChildren` (Lane 3 O2 Slices
+   * 1+2). Preserves extension-namespace properties like
+   * `<w15:footnoteColumns>` and Word-internal section knobs through a
+   * parse→serialize round-trip when the runtime mutates section properties.
+   */
+  unknownPropertyChildren?: UnknownPropertyChild[];
 }
 
 export interface PageSize {
@@ -1078,10 +1137,17 @@ export interface ChartPreviewNode {
    * (`src/io/ooxml/chart/parse-chart-space.ts`). Undefined when the chart
    * part cannot be located, fails to parse, or has no chart-family match
    * — consumers fall back to the fallback bitmap (`previewMediaId`) or the
-   * typed badge in that case. `rawXml` is the authoritative round-trip
-   * source regardless of whether `parsedData` is populated.
+   * typed badge in that case.
+   *
+   * **`rawXml` is the authoritative round-trip source** regardless of
+   * whether `parsedData` is populated. `parsedData` is a read-only
+   * projection of that rawXml; mutating it would diverge the two fields
+   * and silently degrade export fidelity. The `readonly` modifier
+   * enforces this at the type level — any future collab-replay that
+   * needs to edit a chart must round-trip through `rawXml`, not patch
+   * `parsedData` in place.
    */
-  parsedData?: ChartModel;
+  readonly parsedData?: ChartModel;
   rawXml: string;
 }
 

package/src/runtime/collab/index.ts

@@ -42,3 +42,10 @@ export {
   type RemoteCursorTrackerHandle,
   type RemoteCursorTrackerOptions,
 } from "./remote-cursor-awareness.ts";
+export {
+  createWorkflowShared,
+  type CreateWorkflowSharedOptions,
+  type SharedWorkflowState,
+  type WorkflowSharedHandle,
+  type WorkflowSharedResult,
+} from "./workflow-shared.ts";