@beyondwork/docx-react-component 1.0.60 → 1.0.62

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

@@ -62,6 +62,7 @@
  */
 
 import type {
+  ClrSchemeMappingSlot,
   CompatSetting,
   DocumentSettings,
 } from "../../model/canonical-document.ts";
@@ -81,6 +82,21 @@ export const WORD_SETTINGS_CONTENT_TYPE =
 const WORDPROCESSINGML_2006_MAIN_NS =
   "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
 
+const CLRSCHEME_MAPPING_EMIT_ORDER: readonly ClrSchemeMappingSlot[] = [
+  "bg1",
+  "t1",
+  "bg2",
+  "t2",
+  "accent1",
+  "accent2",
+  "accent3",
+  "accent4",
+  "accent5",
+  "accent6",
+  "hlink",
+  "followedHyperlink",
+];
+
 /**
  * Render a complete `<w:settings>` XML document from canonical
  * `DocumentSettings`. The output is the standard XML declaration plus a
@@ -89,9 +105,13 @@ const WORDPROCESSINGML_2006_MAIN_NS =
  * Emit order is OOXML-schema-friendly to maximize Word's tolerance:
  *   1. <w:evenAndOddHeaders>
  *   2. <w:zoom>
- *   3. root-level compat-adjacent flags (e.g. <w:doNotEmbedSmartTags/>)
- *   4. <w:compat> wrapping flags then compatSetting triples
- *   5. <w:themeFontLang>
+ *   3. <w:defaultTabStop>
+ *   4. <w:footnotePr>
+ *   5. <w:endnotePr>
+ *   6. root-level compat-adjacent flags (e.g. <w:doNotEmbedSmartTags/>)
+ *   7. <w:compat> wrapping flags then compatSetting triples
+ *   8. <w:themeFontLang>
+ *   9. <w:clrSchemeMapping>
  *
  * Insertion order of `compatSettings` array entries and `compatFlags` /
  * `rootCompatFlags` / `themeFontLang` keys is preserved so a byte-stable
@@ -112,9 +132,13 @@ function synthesizeSettingsXml(settings: DocumentSettings): string {
   const parts: string[] = [];
   parts.push(emitEvenAndOddHeaders(settings));
   parts.push(emitZoom(settings));
+  parts.push(emitDefaultTabStop(settings));
+  parts.push(emitFootnoteLikeProperties("w:footnotePr", settings.footnotePr));
+  parts.push(emitFootnoteLikeProperties("w:endnotePr", settings.endnotePr));
   parts.push(emitRootCompatFlags(settings));
   parts.push(emitCompatBlock(settings));
   parts.push(emitThemeFontLang(settings));
+  parts.push(emitClrSchemeMapping(settings));
 
   const body = parts.filter((p) => p.length > 0).join("");
   return [
@@ -195,6 +219,24 @@ function graftSettingsXml(
   ) {
     appendedParts.push(emitZoom(settings));
   }
+  if (
+    !emittedTopLevel.has("defaultTabStop") &&
+    settings.defaultTabStop !== undefined
+  ) {
+    appendedParts.push(emitDefaultTabStop(settings));
+  }
+  if (
+    !emittedTopLevel.has("footnotePr") &&
+    settings.footnotePr !== undefined
+  ) {
+    appendedParts.push(emitFootnoteLikeProperties("w:footnotePr", settings.footnotePr));
+  }
+  if (
+    !emittedTopLevel.has("endnotePr") &&
+    settings.endnotePr !== undefined
+  ) {
+    appendedParts.push(emitFootnoteLikeProperties("w:endnotePr", settings.endnotePr));
+  }
   // Any rootCompatFlags entries that didn't have a source counterpart.
   for (const [name, value] of pendingRootFlags) {
     appendedParts.push(emitOnOffElement(name, value));
@@ -209,6 +251,12 @@ function graftSettingsXml(
   ) {
     appendedParts.push(emitThemeFontLang(settings));
   }
+  if (
+    !emittedTopLevel.has("clrSchemeMapping") &&
+    settings.clrSchemeMapping !== undefined
+  ) {
+    appendedParts.push(emitClrSchemeMapping(settings));
+  }
 
   return (
     blueprint.prelude +
@@ -229,8 +277,12 @@ function graftSettingsXml(
 const MODELLED_TOP_LEVEL_NAMES: ReadonlySet<string> = new Set([
   "evenAndOddHeaders",
   "zoom",
+  "defaultTabStop",
+  "footnotePr",
+  "endnotePr",
   "compat",
   "themeFontLang",
+  "clrSchemeMapping",
 ]);
 
 type ChildReplacement =
@@ -282,6 +334,36 @@ function computeChildReplacement(
       const xml = emitZoom(settings);
       return xml.length > 0 ? { kind: "replace", xml } : { kind: "drop" };
     }
+    case "defaultTabStop": {
+      if (
+        emitDefaultTabStop(parseModelledChild(child.rawXml)) ===
+        emitDefaultTabStop(settings)
+      ) {
+        return { kind: "keep" };
+      }
+      const xml = emitDefaultTabStop(settings);
+      return xml.length > 0 ? { kind: "replace", xml } : { kind: "drop" };
+    }
+    case "footnotePr": {
+      if (
+        emitFootnoteLikeProperties("w:footnotePr", parseModelledChild(child.rawXml).footnotePr) ===
+        emitFootnoteLikeProperties("w:footnotePr", settings.footnotePr)
+      ) {
+        return { kind: "keep" };
+      }
+      const xml = emitFootnoteLikeProperties("w:footnotePr", settings.footnotePr);
+      return xml.length > 0 ? { kind: "replace", xml } : { kind: "drop" };
+    }
+    case "endnotePr": {
+      if (
+        emitFootnoteLikeProperties("w:endnotePr", parseModelledChild(child.rawXml).endnotePr) ===
+        emitFootnoteLikeProperties("w:endnotePr", settings.endnotePr)
+      ) {
+        return { kind: "keep" };
+      }
+      const xml = emitFootnoteLikeProperties("w:endnotePr", settings.endnotePr);
+      return xml.length > 0 ? { kind: "replace", xml } : { kind: "drop" };
+    }
     case "compat": {
       if (
         emitCompatBlock(parseModelledChild(child.rawXml)) ===
@@ -302,6 +384,16 @@ function computeChildReplacement(
       const xml = emitThemeFontLang(settings);
       return xml.length > 0 ? { kind: "replace", xml } : { kind: "drop" };
     }
+    case "clrSchemeMapping": {
+      if (
+        emitClrSchemeMapping(parseModelledChild(child.rawXml)) ===
+        emitClrSchemeMapping(settings)
+      ) {
+        return { kind: "keep" };
+      }
+      const xml = emitClrSchemeMapping(settings);
+      return xml.length > 0 ? { kind: "replace", xml } : { kind: "drop" };
+    }
   }
   // Root compat flag?
   if (ROOT_COMPAT_FLAG_NAMES.has(child.localName)) {
@@ -361,6 +453,28 @@ function emitZoom(settings: DocumentSettings): string {
   return "";
 }
 
+function emitDefaultTabStop(settings: DocumentSettings): string {
+  const { defaultTabStop } = settings;
+  if (defaultTabStop === undefined || !Number.isFinite(defaultTabStop)) return "";
+  return `<w:defaultTabStop w:val="${Math.round(defaultTabStop)}"/>`;
+}
+
+function emitFootnoteLikeProperties(
+  elementName: "w:footnotePr" | "w:endnotePr",
+  props: DocumentSettings["footnotePr"] | DocumentSettings["endnotePr"],
+): string {
+  if (!props) return "";
+  const parts: string[] = [];
+  if (props.pos) parts.push(`<w:pos w:val="${escapeXmlAttribute(props.pos)}"/>`);
+  if (props.numFmt) parts.push(`<w:numFmt w:val="${escapeXmlAttribute(props.numFmt)}"/>`);
+  if (props.numStart !== undefined && Number.isFinite(props.numStart)) {
+    parts.push(`<w:numStart w:val="${Math.round(props.numStart)}"/>`);
+  }
+  if (props.numRestart) parts.push(`<w:numRestart w:val="${escapeXmlAttribute(props.numRestart)}"/>`);
+  if (parts.length === 0) return "";
+  return `<${elementName}>${parts.join("")}</${elementName}>`;
+}
+
 function emitRootCompatFlags(settings: DocumentSettings): string {
   const flags = settings.rootCompatFlags;
   if (!flags) return "";
@@ -410,6 +524,19 @@ function emitThemeFontLang(settings: DocumentSettings): string {
   return `<w:themeFontLang${attrs}/>`;
 }
 
+function emitClrSchemeMapping(settings: DocumentSettings): string {
+  const mapping = settings.clrSchemeMapping;
+  if (!mapping) return "";
+  const attrs = CLRSCHEME_MAPPING_EMIT_ORDER
+    .map((slot) => {
+      const value = mapping[slot];
+      return value ? ` w:${slot}="${escapeXmlAttribute(value)}"` : "";
+    })
+    .join("");
+  if (attrs.length === 0) return "";
+  return `<w:clrSchemeMapping${attrs}/>`;
+}
+
 /**
  * Emit a ST_OnOff element. true → bare self-closing tag; false → explicit
  * `w:val="false"` so the parser doesn't infer the default-true. Symmetric

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

@@ -260,13 +260,17 @@ function normalizeParagraph(
       : {}),
     ...(paragraph.indentation ? { indentation: paragraph.indentation } : {}),
     ...(paragraph.tabStops && paragraph.tabStops.length > 0 ? { tabStops: paragraph.tabStops } : {}),
-    ...(paragraph.keepNext ? { keepNext: paragraph.keepNext } : {}),
-    ...(paragraph.keepLines ? { keepLines: paragraph.keepLines } : {}),
+    ...(paragraph.keepNext !== undefined ? { keepNext: paragraph.keepNext } : {}),
+    ...(paragraph.keepLines !== undefined ? { keepLines: paragraph.keepLines } : {}),
     ...(paragraph.outlineLevel !== undefined ? { outlineLevel: paragraph.outlineLevel } : {}),
-    ...(paragraph.pageBreakBefore ? { pageBreakBefore: paragraph.pageBreakBefore } : {}),
-    ...(paragraph.bidi ? { bidi: paragraph.bidi } : {}),
+    ...(paragraph.pageBreakBefore !== undefined ? { pageBreakBefore: paragraph.pageBreakBefore } : {}),
+    ...(paragraph.widowControl !== undefined ? { widowControl: paragraph.widowControl } : {}),
+    ...(paragraph.bidi !== undefined ? { bidi: paragraph.bidi } : {}),
     ...(paragraph.borders ? { borders: paragraph.borders } : {}),
     ...(paragraph.shading ? { shading: paragraph.shading } : {}),
+    ...(paragraph.suppressLineNumbers !== undefined
+      ? { suppressLineNumbers: paragraph.suppressLineNumbers }
+      : {}),
     // A.7: preserve w14:paraId / w14:textId across import → export so
     // downstream tools that diff documents by paragraph id stay stable.
     ...(paragraph.wordExtensionIds

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

@@ -0,0 +1,193 @@
+/**
+ * Embedded-object classifier (hotfix/ole-digestibility-guard).
+ *
+ * Decides how the session layer should handle each `<w:object>` /
+ * `w:altChunk` / embedded package encountered during parse, given its
+ * ProgID, relationship type, and content-type. Three outcomes:
+ *
+ * - **digestible** — the runtime currently renders this as an inline
+ *   `OleEmbedNode` with a `[Embedded object: progId]` placeholder, with
+ *   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.
+ *
+ * - **store-only** — complex binary or undigestible content (PDF,
+ *   legacy binary Office, package-embedded docx with icon aspect,
+ *   unknown ProgIDs). The parser returns undefined from `parseObject`
+ *   and the existing opaque-fragment fallback in `parse-main-document`
+ *   preserves both the `<w:object>` XML and its relationship id.
+ *
+ * Policy (opt-in to store-only):
+ * - Default: **digestible** for ProgIDs the hotfix does not recognize
+ *   as problematic. This preserves today's behavior for benign OLE
+ *   content that has not been reported as breaking — placeholder
+ *   rendering + byte-preserved round-trip. Graduating an embedding to
+ *   store-only is an explicit decision made against a real-world
+ *   crash report.
+ * - ProgID prefix matching: `Word.Document.*`, `Excel.*`, `PowerPoint.*`,
+ *   `AcroExch.Document.*`, exact `Package` → store-only. These are the
+ *   ProgIDs most likely to break the editor (either because the
+ *   payload is a nested OPC package whose downstream processing can
+ *   fail mid-mount, or because the binary's rendering is out of scope
+ *   for v1).
+ * - Content-type override: if the relationship points at a
+ *   `application/vnd.openxmlformats-officedocument.wordprocessingml.document`
+ *   (or analogous OOXML/PDF content-type), it is store-only regardless
+ *   of ProgID. Catches the real-world CCEP "master agreement with
+ *   sub-agreement inside" case.
+ * - Target-path extension match: if the relationship target ends in
+ *   `.docx`/`.xlsx`/`.pptx`/`.pdf` (including macro-enabled and
+ *   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.
+ *
+ * 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).
+  "Word.Document.",
+  "Word.DocumentMacroEnabled.",
+  "Word.Template.",
+  // Spreadsheet embeddings. Excel.Sheet.12 + Excel.Worksheet.12 are
+  // the common ProgIDs; Excel.Chart.* less so.
+  "Excel.Sheet.",
+  "Excel.SheetMacroEnabled.",
+  "Excel.SheetBinaryMacroEnabled.",
+  "Excel.Worksheet.",
+  "Excel.Chart.",
+  "Excel.ChartMacroEnabled.",
+  // Presentations.
+  "PowerPoint.Slide.",
+  "PowerPoint.SlideMacroEnabled.",
+  "PowerPoint.Show.",
+  "PowerPoint.ShowMacroEnabled.",
+  "PowerPoint.Document.",
+  "PowerPoint.Template.",
+  // PDF via Adobe Acrobat.
+  "AcroExch.Document.",
+];
+
+const STORE_ONLY_PROGID_EXACT: ReadonlySet<string> = new Set([
+  // Generic OLE container — ambiguous payload, fail closed.
+  "Package",
+  "Packager.Package",
+]);
+
+/**
+ * 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.
+ */
+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.
+  "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",
+  "application/pdf",
+];
+
+export type EmbeddingKind = "digestible" | "offloadable" | "store-only";
+
+export interface ClassifyEmbeddingInput {
+  /** ProgID on the `<o:OLEObject>` element, if any. */
+  progId?: string;
+  /**
+   * Full OOXML relationship Type URI — e.g.
+   * `http://schemas.openxmlformats.org/officeDocument/2006/relationships/oleObject`
+   * or `.../relationships/package`.
+   */
+  relationshipType?: string;
+  /**
+   * Content-type of the embedding's target package part (from
+   * `[Content_Types].xml` override or inferred default).
+   */
+  contentType?: string;
+  /**
+   * Relationship target path — e.g. `embeddings/Microsoft_Word_Document.docx`.
+   * Used as a weak signal when progId + contentType are both absent.
+   */
+  targetPath?: string;
+}
+
+/**
+ * Classify an embedding. Fails closed: returns `"store-only"` when the
+ * classifier cannot prove `"digestible"`.
+ */
+export function classifyEmbedding(
+  input: ClassifyEmbeddingInput,
+): EmbeddingKind {
+  const progId = input.progId?.trim() ?? "";
+  const contentType = input.contentType?.trim().toLowerCase() ?? "";
+  const targetPath = input.targetPath?.toLowerCase() ?? "";
+
+  // Exact ProgID match.
+  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.
+  if (progId) {
+    for (const prefix of STORE_ONLY_PROGID_PREFIXES) {
+      if (progId.startsWith(prefix)) {
+        return "store-only";
+      }
+    }
+  }
+
+  // Content-type override.
+  if (contentType) {
+    for (const ct of STORE_ONLY_CONTENT_TYPES) {
+      if (contentType === ct || contentType.startsWith(`${ct};`)) {
+        return "store-only";
+      }
+    }
+  }
+
+  // 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.
+  if (targetPath) {
+    const storeOnlyExtensions = [".docx", ".docm", ".dotx", ".dotm",
+      ".xlsx", ".xlsm", ".xltx", ".xltm",
+      ".pptx", ".pptm", ".potx", ".potm",
+      ".pdf"];
+    for (const ext of storeOnlyExtensions) {
+      if (targetPath.endsWith(ext)) {
+        return "store-only";
+      }
+    }
+  }
+
+  // No known-problematic signal matched — keep today's behavior.
+  // parseObject will construct an OleEmbedNode; render-path continues
+  // to show a placeholder for the embedding.
+  return "digestible";
+}
+
+/**
+ * Exposed for tests. Not part of the public API.
+ */
+export const __internal = {
+  STORE_ONLY_PROGID_PREFIXES,
+  STORE_ONLY_PROGID_EXACT,
+  STORE_ONLY_CONTENT_TYPES,
+} as const;

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

@@ -154,9 +154,13 @@ export function parseEndnotesXml(
     }
   }
 
+  const endnoteSeparators = parseFootnoteSeparators(xml);
+
   return {
     footnotes: existing?.footnotes ?? {},
     endnotes,
+    ...(existing?.footnoteSeparators ? { footnoteSeparators: existing.footnoteSeparators } : {}),
+    ...(Object.keys(endnoteSeparators).length > 0 ? { endnoteSeparators } : {}),
   };
 }
 
@@ -174,7 +178,9 @@ export function parseFootnoteSeparators(xml: string): FootnoteSeparators {
   if (!containerEl) return {};
 
   let separatorContent: string | undefined;
+  let separatorParagraphXml: string | undefined;
   let continuationSeparatorContent: string | undefined;
+  let continuationSeparatorParagraphXml: string | undefined;
 
   for (const child of containerEl.children) {
     if (child.type !== "element") continue;
@@ -186,6 +192,7 @@ export function parseFootnoteSeparators(xml: string): FootnoteSeparators {
 
     const paraEl = findChildElementOptional(child, "p");
     if (!paraEl) continue;
+    const paragraphXml = serializeElementToXml(paraEl);
 
     const runXml = paraEl.children
       .filter((c): c is XmlElementNode => c.type === "element" && localName(c.name) === "r")
@@ -194,14 +201,18 @@ export function parseFootnoteSeparators(xml: string): FootnoteSeparators {
 
     if (rawType === "separator") {
       separatorContent = runXml;
+      separatorParagraphXml = paragraphXml;
     } else {
       continuationSeparatorContent = runXml;
+      continuationSeparatorParagraphXml = paragraphXml;
     }
   }
 
   return {
     ...(separatorContent !== undefined ? { separatorContent } : {}),
+    ...(separatorParagraphXml !== undefined ? { separatorParagraphXml } : {}),
     ...(continuationSeparatorContent !== undefined ? { continuationSeparatorContent } : {}),
+    ...(continuationSeparatorParagraphXml !== undefined ? { continuationSeparatorParagraphXml } : {}),
   };
 }