@beyondwork/docx-react-component 1.0.61 → 1.0.62

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.61",
+  "version": "1.0.62",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
   "type": "module",
   "sideEffects": [

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-object.ts

@@ -22,6 +22,7 @@ import type { OleEmbedNode } from "../../model/canonical-document.ts";
 import type { OpcRelationship } from "./part-manifest.ts";
 import type { XmlElementNode } from "./xml-element.ts";
 import { resolveOleRelationship } from "./parse-ole-relationship.ts";
+import { classifyEmbedding } from "./classify-embedding.ts";
 
 /**
  * Parse a `<w:object>` element into an `OleEmbedNode` if it contains an
@@ -64,6 +65,28 @@ export function parseObject(
     return undefined;
   }
 
+  // hotfix/ole-digestibility-guard — classify the embedding before
+  // constructing a canonical node. When the classifier returns
+  // "store-only" (nested Word docs, PDF OLE, Excel/PowerPoint
+  // embeddings, unknown ProgIDs), return undefined so the caller's
+  // existing opaque-fragment fallback preserves both <w:object> XML
+  // and its r:id verbatim. Binary preservation is unaffected —
+  // collectPreservedPackageParts indexes embedding parts by path, not
+  // by canonical-tree reference.
+  //
+  // TODO(refactor/01 Step 6-7): replace this skip-construction with
+  // extraction + offload via hostAdapter.storeEmbeddedDocument?. See
+  // docs/architecture/01-package-session.md §P8 + docs/plans/refactor/
+  // 01-package-session.md Steps 6-7.
+  const kind = classifyEmbedding({
+    progId,
+    relationshipType: resolved.relationshipType,
+    targetPath: resolved.target,
+  });
+  if (kind !== "digestible") {
+    return undefined;
+  }
+
   const metadata: OleEmbedNode["metadata"] = {};
   if (resolved.originalFilename) {
     metadata.originalFilename = resolved.originalFilename;