@beyondwork/docx-react-component 1.0.0 → 1.0.1

package/docs/xlsx-react/shared-openxml-editor-platform-docx-xlsx.md

@@ -1,228 +0,0 @@
-# Shared OpenXML Editor Platform for DOCX and XLSX
-
-This research paper is source material.
-
-Canonical repo-aligned platform doc:
-
-- `docs/architecture/platform/shared-openxml-editor-platform.md`
-
-## Interpretation of the problem
-
-You already have a React-based Word-compatible DOCX editor whose core posture is “package-first, runtime-owned truth, command→transaction→commit, and never silently drop preservable content.” That posture is explicitly documented in your repo’s OOXML compliance model and public API contracts.
-
-The ask is to design an XLSX sibling with the same architectural rigor, without pretending spreadsheets are “rich text + cells,” and to define a shared platform layer that both vertical editors can build on without forcing fake abstraction. The platform must treat `.docx`/`.xlsx` as OOXML packages under Open Packaging Conventions (OPC), preserve unsupported-but-preservable content, and keep host application behavior (Word/Excel reopen-without-repair-prompts) as the ultimate acceptance gate.
-
-This memo therefore focuses on: extracting genuinely shared OPC/package/preservation/validation/session scaffolding; aligning the public API philosophy and trust/health model; and drawing hard boundaries around what must remain DOCX-specific vs XLSX-specific (canonical schema, editing primitives, selection model, review semantics, and surface rendering).
-
-## Research plan
-
-The research work followed three lanes, with connector-first priority:
-
-First, I inspected the existing architecture and contracts in `bwllaming/docx-react-component`, concentrating on the pieces that already look “platform-like”: OPC package IO (`src/io/opc/*`), part/relationship modeling (`src/io/ooxml/part-manifest.ts`), export sessions and preserved-part reattachment (`src/io/export/*`), preservation stores and markup compatibility handling (`src/preservation/*`), the diagnostics taxonomy (`src/validation/*` + `docs/reference/ooxml-compliance.md`), the runtime command/transaction spine (`src/core/commands/*` + `src/runtime/*`), the published public API (`docs/reference/public-api.md`), and the React shell contract (“UI is a projection of runtime state”).
-
-Second, I anchored the platform requirements in primary standards references for OOXML packaging and markup compatibility: the OOXML family as published by (ECMA-376) and the ISO/IEC 29500 series published under and. Because the platform is about packaging/preservation invariants, the key normative anchors are “OPC exists and is the packaging model” and “MCE defines forward-compatible markup handling.”
-
-Third, I separated “spec-level correctness” from “host-level correctness” by incorporating’s own guidance on Open XML formats and Excel repair behavior, plus the Open XML SDK validation surface used in your repo (and documented as “necessary but not sufficient”).
-
-## Findings
-
-Your Word editor already contains a surprisingly complete “shared platform” nucleus, even though it lives inside a DOCX vertical today.
-
-At the UI contract level, the repo is explicit that React does not own canonical document truth: UI components render from a runtime-provided snapshot (`RuntimeRenderSnapshot`) via `useSyncExternalStore`, and mutation never happens by “editing the DOM and hoping state follows.” Instead, mutation flows through runtime callbacks that dispatch commands.
-
-At the runtime level, commands are a discriminated union (`EditorCommand`) executed into an `EditorTransaction` that carries `nextState`, mapping info, effects, and explicit history boundaries (“push” vs “skip”). That is the exact “commands → transactions → commit” spine you want to preserve across both DOCX and XLSX; the mechanics are shareable even if the domain command set is not.
-
-The trust/health posture is also already formalized. Your repo’s `SessionCapabilities` are derived purely from runtime state (not component-local copies), and include explicit “exportBlocked”, “preserveOnlyCount”, and “unsupportedFatalCount” surfaces that drive UI behavior (e.g., rail visibility and export enablement). This is a cross-vertical platform concern, not a DOCX-only one.
-
-On the file-format side, the repo treats `.docx` as an OPC package and implements its own package reader/writer, export-session rewriting, and preserved-part reattachment. The export design is structurally platform-grade: an `ExportSession` declares “owned output paths,” forbids owning reserved manifest paths, rewrites only what is owned, then reattaches all non-owned “content” parts from the source package (including package-level relationships).
-
-The DOCX vertical session (`loadDocxEditorSession`) demonstrates the target platform shape for any OOXML editor: read bytes → parse OPC → fail closed on malformed package or broken relationships → import owned parts into canonical runtime state → register non-owned parts into preservation → produce a snapshot and a compatibility report → export by rewriting owned parts into an export session.
-
-Most importantly for “never drop preservable content,” your compliance model is explicit: every feature must be classified as `supported-roundtrip`, `preserve-only`, or `unsupported-fatal`, and “supported-import-only / supported-export-only” are explicitly rejected as dishonest categories. That taxonomy is already enforced in the diagnostics layer and surfaced in runtime health.
-
-The response model is also already named and operational: preserve, lock, warn, block, fail. This gives a shared vocabulary for user experience and for export gating decisions across DOCX and XLSX.
-
-For forward-compatibility markup handling, the repo has dedicated markup-compatibility handling that extracts and preserves root-level markup compatibility attributes (e.g., `xmlns:mc`, `mc:Ignorable`, and related namespace declarations) rather than letting serialization accidentally strip them. That’s directly portable as a platform concern, even if the exact root element differs between Word and Spreadsheet parts.
-
-Your tests demonstrate that preservation isn’t aspirational; it’s asserted. The fixture-style tests explicitly prove that unknown/preserved parts survive export byte-for-byte, that `mc:Ignorable` survives, and that broken relationship targets fail closed with export blocked. This fixture program is exactly the pattern an XLSX sibling will need, with Excel reopen behavior as the gate.
-
-Finally, the repo already integrates Open XML SDK validation as a separate service/CI tool rather than a browser runtime dependency. The OOXML compliance doc explicitly says SDK validation is necessary but not sufficient, and your validator service uses `OpenXmlValidator` to validate a package and emits schema findings. That architecture is inherently shareable and should become a platform capability for both DOCX and XLSX.
-
-From standards and host behavior sources: OOXML’s packaging model and markup compatibility model are standardized under ECMA-376 / ISO/IEC 29500, so “treat `.xlsx` as a package with parts + relationships + content types” is the normative stance, not a design preference. Meanwhile, Excel explicitly has corruption detection and repair flows (automatic recovery and “Open and Repair”), so the platform has to assume that export correctness is judged by whether the host detects corruption and repairs (which can be destructive), not by whether your code “successfully wrote a ZIP.” And Microsoft’s Open XML format guidance distinguishes `.xlsx` (no macros) from macro-enabled formats (e.g., `.xlsm`), which directly impacts what a “spreadsheet editor” can safely claim as in-scope for import/edit/export without silent loss.
-
-## Recommended design / decisions
-
-The core decision is to elevate the pieces that are truly format-agnostic (OPC mechanics, preservation plumbing, diagnostics taxonomy, session lifecycle scaffolding, validation harnessing, and host-facing API philosophy) into a shared “OpenXML Editor Platform,” while explicitly refusing to unify DOCX and XLSX at the canonical-schema and editing-primitive layers.
-
-The platform should be defined as a set of *capabilities* with narrow, typed contracts, not a single “OpenXmlEditorBase” class that both verticals subclass. Your repo already demonstrates the right posture: shared invariants are encoded in stand-alone modules (e.g., diagnostics taxonomy, export sessions, preserved-part reattachment), and vertical code composes them.
-
-Platform modules that should be shared between DOCX and XLSX:
-
-Package/OPC core: everything needed to parse and emit a correct OPC package and to reason about parts and relationships should be shared. In your repo, that includes the package reader/writer (ZIP + content types + rels), the part-manifest modeling, relationship target resolution, and the “reserved-path” discipline in export sessions. Even if XLSX ultimately needs additional ZIP features (compression choices, streaming), the invariants and APIs should stay common.
-
-Preservation plumbing: “reattach all non-owned content parts and package relationships” is not DOCX-specific. It is the platform mechanism that makes “unsupported but preservable content must never be silently dropped” implementable. The DOCX code already does this at the package boundary, and tests lock it in. XLSX will need the same mechanism because spreadsheets have even more peripheral parts (drawings, charts, pivot caches, external connections) that you will likely classify preserve-only early on.
-
-Diagnostics + compatibility taxonomy: the tri-class model (`supported-roundtrip`, `preserve-only`, `unsupported-fatal`) and the export-blocking logic based on “unsupported-fatal or fatal errors” is already implemented and already used by runtime health surfaces. This belongs in the shared platform as the common language for both editors. DOCX and XLSX can (and will) define different feature keys and different classifiers, but the taxonomy and export-block semantics should be shared so hosts see a consistent trust posture across document types.
-
-Session lifecycle scaffolding (import → runtime → export): your DOCX session loader has a clear structure: package read, structural safety checks (broken relationships), owned-part import, preservation registration, compatibility report, and export function that rewrites owned parts only if export is not blocked. This skeleton should be extracted as a platform “session kernel” that DOCX and XLSX implement by providing (a) their owned-part set, (b) their import parser/normalizer, and (c) their export serializer.
-
-Markup compatibility preservation: preserving markup compatibility attributes is a format-agnostic need, but the *filtering rules* are not. The platform should provide generic utilities (“extract root attributes”, “preserve MCE attributes”), while each vertical supplies (a) its root element name(s) and (b) the namespace prefixes it must preserve for safe round-tripping. Your current `filterMarkupCompatibilityAttributes` is Word-root oriented; XLSX must similarly preserve workbook/sheet-level `mc:*` and any ignorable namespaces it encounters.
-
-Read-only diagnostics mode: “fail closed into diagnostics/read-only mode with export blocked” is explicitly part of your compliance contract. This should be a platform capability with a shared runtime interface contract so both editors can surface “this package cannot be safely rewritten” in a consistent, host-friendly way.
-
-Autosave and snapshot contract philosophy: the host-facing persistence model (persist snapshots as JSON checkpoints; manual export checkpoints must save snapshot first; autosave must be debounced and scoped to revision tokens) is not DOCX-only. It’s a platform-level host contract that should remain aligned between editors to avoid “one editor loses work differently than the other.”
-
-Validation harnessing (not runtime): the Open XML SDK validator service should be generalized to validate both Wordprocessing and Spreadsheet packages (and ideally accept `.docx`, `.xlsx`, `.pptx` with explicit gates). The platform should standardize the CI/API integration shape: “package inspection + SDK validation findings + stable tokens for diagnostics,” while keeping it out of the browser bundle.
-
-What must remain document-type-specific (do not share, by design):
-
-Canonical schema: your DOCX `CanonicalDocument` is a linearized story model with review + preservation fields. XLSX needs a workbook model (sheets, cells, shared strings, styles, formula graph, defined names, calc settings). Sharing a canonical schema here will produce “fake abstraction” and break spreadsheet-first correctness.
-
-Editing primitives: DOCX operations are text/paragraph-centric (insert text, split paragraph, etc.). XLSX primitives are grid-centric (edit cell value, fill, cut/paste ranges, insert rows/cols, adjust formulas, recalc dependencies). Forcing shared primitives would either cripple XLSX or contaminate DOCX with irrelevant complexity.
-
-Selection model: DOCX currently uses a flat range/node/detached anchor projection model. XLSX needs 2D selections (cell, range, multi-range, entire row/column, sheet selection), plus active cell vs selection range semantics. This must be vertical-specific, though the *pattern* “selection is runtime-owned and projected to UI” remains shared.
-
-Review semantics and provenance: Word tracked changes and comment anchoring are structurally different from spreadsheet change tracking/comment models and will diverge even more once formulas and structural operations exist. Treat review as a vertical capability with a shared trust/taxonomy surface.
-
-Surface rendering: Word’s “button-per-character” rendering stack is intentionally specialized. A spreadsheet must use virtualization, grid rendering, editing overlays, and significantly different interaction mechanics. Share only the outer shell concepts (runtime snapshot projection, eventing), not the renderer.
-
-Public API philosophy should stay aligned without forcing fake abstraction:
-
-Your current public API has strong, repeatable principles: uncontrolled-by-default; narrow controlled reload via `externalDocumentRevision` + `externalDocSource`; ref is a thin wrapper over runtime (no DOM exposing, no mutable canonical state); and trust/health is explicit via compatibility reports, warnings, and errors. That philosophy should become a platform “API doctrine,” with separate `WordReviewEditor` and `SpreadsheetEditor` components that expose symmetric (not identical) surfaces: `exportDocx` vs `exportXlsx`, DOCX-specific ref methods vs XLSX-specific ones.
-
-The platform should standardize shared host-facing types where they are genuinely common: `PersistedEditorSnapshot` pattern, `CompatibilityReport`, `EditorWarning`, `EditorError`, event stream patterns, autosave config and datastore adapter interface. Then each vertical adds its own specialized snapshot payload and ref commands. This prevents API drift while still being honest about domain differences.
-
-## Risks and open questions
-
-Over-sharing risks: The biggest risk is building a “shared” canonical model or selection abstraction that encodes Word’s linear text assumptions and then trying to retrofit spreadsheets into it. This will either (a) force spreadsheets into a degenerate “text grid” model that can’t correctly handle formulas, range operations, and recalculation, or (b) pollute the shared layer with conditionals until the platform becomes unmaintainable. Your own repo already warns against silent scope widening (e.g., tables require explicit contract revisions). The XLSX sibling needs the same discipline.
-
-Under-sharing risks: Duplicating OPC/package/preservation logic across DOCX and XLSX will almost certainly diverge over time and create inconsistent trust outcomes: one editor preserves unknown parts, the other silently drops; one blocks export on broken relationships, the other “best-efforts” and causes host repair prompts. Given Excel’s repair mechanisms, divergence here will show up as user-visible corruption/repair flows.
-
-Standards-access and exact normative deltas: ECMA-376 / ISO/IEC 29500 define the packaging and MCE rules, but host behavior includes undocumented heuristics and extension points. The open question for the XLSX vertical is: which OOXML extension namespaces and parts must be preserved *exactly* for safe reopen, and which can be normalized without triggering Excel repair flows? The platform should assume “preserve by default; rewrite only owned parts,” but XLSX has more parts that Excel treats as coupled (e.g., calc artifacts, shared strings, styles). This implies an early conservative scope: preserve-only for many features until proven safe with Excel reopen tests.
-
-Macro-enabled and encrypted containers: Microsoft’s own guidance distinguishes macro-free `.xlsx` from macro-enabled formats (e.g., `.xlsm`). If XLSX editing is in-scope, macro preservation and VBA project parts are out-of-scope unless you explicitly support `.xlsm` and can preserve those parts without rewriting hazards. Your DOCX API already excludes encrypted/password-to-open intake as a host responsibility; XLSX should follow the same posture unless you explicitly expand it.
-
-Validation sufficiency: Open XML SDK validation is a schema-level check. It is necessary but does not guarantee Excel/Word won’t repair or reinterpret content. The platform must keep a two-tier gate: schema validation (SDK) plus host reopen certification (Excel/Word).
-
-## Concrete deliverable in the requested format
-
-Decision-ready architecture memo with recommended extraction order:
-
-Proposed repo/module boundaries (target end state)
-
-A two-vertical layout with an explicit platform layer:
-
-```text
-packages/
-openxml-platform/
-opc/
-package-reader.ts
-package-writer.ts
-part-manifest.ts
-corrupt-package.ts            # generalized, not "docx"-named
-preservation/
-preservation-store.ts         # generic structures + vertical classifiers
-markup-compatibility.ts       # generic root-attr extraction + MCE helpers
-preserved-parts.ts            # capture + reattach mechanisms
-session/
-session-kernel.ts             # lifecycle scaffolding + safety checks
-export-session.ts             # owned-part rewrite discipline
-import-diagnostics.ts         # fail-closed diagnostics mode contract
-read-only-diagnostics-runtime.ts
-diagnostics/
-diagnostics.ts                # feature classes, warn/error taxonomy, export block rules
-compatibility-report.ts       # generic report builder scaffolding
-validation/
-openxml-validator-client.ts   # calls validator service
-validation-fixture-runner.ts  # CI harness hooks
-host/
-datastore-adapter.ts          # shared persistence contract
-autosave.ts                   # shared debounce + revision-token scoping logic
-events.ts                     # shared event envelope patterns
-
-docx-editor/
-docx-session.ts                 # DOCX-owned parts import/export
-docx-canonical-schema/          # Word canonical model
-docx-runtime/                   # Word commands, mapping, review semantics
-docx-ui/                        # Word renderer + review workspace
-
-xlsx-editor/
-xlsx-session.ts                 # XLSX-owned parts import/export
-xlsx-canonical-schema/          # Workbook canonical model
-xlsx-runtime/                   # Grid commands, selection, recalculation strategy
-xlsx-ui/                        # Virtualized grid renderer
-services/
-openxml-validator/
-Program.cs                      # extended to accept .xlsx and run OpenXmlValidator
-```
-
-Why these boundaries are honest:
-
-The platform layer contains only what is truly package/session/trust infrastructure: OPC mechanics, preserved part survival, diagnostics taxonomy, session lifecycle, autosave/snapshot scaffolding, and validation harnessing. This directly aligns with the repo’s existing “package-first rules” and “preserve/lock/warn/block/fail” posture and keeps the “host behavior is final standard” gate enforceable.
-
-The vertical layers own canonical schema and editing semantics, because attempting to share those would violate the explicit requirement that spreadsheets not be treated as rich text, and because your current architecture already treats schema expansion as requiring explicit contract revision.
-
-Platform extraction order (recommended sequence)
-
-First extraction: OPC + export-session + preserved-part reattachment
-Move `ExportSession` and `reattachPreservedParts` (and their supporting part/relationship utilities) into `openxml-platform/session` and `openxml-platform/opc`. These modules are already format-agnostic and have strong invariant checks (“cannot own reserved manifest paths,” “cannot rewrite non-owned paths”). This extraction is low-risk and unlocks XLSX immediately because XLSX must be package-first from day one.
-
-Second extraction: diagnostics taxonomy + import diagnostics + read-only diagnostics runtime
-Move `diagnostics.ts` and `import-diagnostics.ts` into `openxml-platform/diagnostics` and `openxml-platform/session`. These are already generic and underpin the cross-vertical response model (preserve/lock/warn/block/fail) and export blocking rules. This allows the XLSX editor to share a consistent trust model from its first non-trivial fixture import.
-
-Third extraction: markup-compatibility utilities as configurable platform primitives
-Move `extractDocumentRootAttributes` and the generic filtering helpers into a platform module, but refactor the filter to accept a vertical-provided allowlist/predicate rather than hardcoding Word namespace prefixes. This prevents Word-specific “xmlns:w14” concerns from bleeding into spreadsheets while preserving the shared MCE intent.
-
-Fourth extraction: host persistence + autosave scaffolding (shell logic)
-Extract datastore adapter types and autosave logic into the platform host module so both components share the same persistence semantics (save snapshot before export checkpoint; autosave keyed by revision token; failures surfaced via events). Then keep DOCX- or XLSX-specific UI surfaces out of that module.
-
-Fifth extraction: validator service generalization
-Extend the Open XML SDK validator service to accept `.xlsx` and validate with `OpenXmlValidator` over `SpreadsheetDocument` (parallel to current WordprocessingDocument validation). Keep it off the browser runtime path. The platform should define a stable response schema that both editors can consume for CI gating and diagnostics enrichment.
-
-Sixth step: build XLSX as a first-class vertical using only platform primitives
-Only after the platform primitives above exist should you start the XLSX work as a true sibling: implement `xlsx-session.ts` by declaring owned parts conservatively, and launch with a fixture corpus that proves (a) package integrity, (b) preserved-part survival, (c) Excel reopen-no-repair on “no-op export,” and (d) “minimal supported-roundtrip edit” (e.g., edit a cell value) without losing preservable content. Excel’s own repair behavior is the acceptance bar, not “we can parse and write XML.”
-
-Shared platform API doctrine (what stays aligned)
-
-Uncontrolled-by-default, narrow controlled reload: keep the pattern “host provides initial source once; host can replace document only via explicit revision token + external source.” This is already codified for DOCX and should be repeated for XLSX without inventing a shared “OpenXmlEditor” prop surface that hides important differences (`exportDocx` vs `exportXlsx`).
-
-Runtime-owned truth, UI as projection: keep the runtime snapshot pattern and session capabilities derivation pattern across both editors. Your repo already encodes and documents these rules clearly; they belong in the platform doctrine and lint/test gates.
-
-Trust/health surfaces: keep `CompatibilityReport` + warning/error model consistent across verticals, so hosts don’t need two different “what does blocked export mean” implementations. The feature keys will differ, but the classes and gating semantics should not.
-
-Release gates (platform + vertical)
-
-Platform gates (must pass before XLSX ships a “v1 edit”): preserved-part survival tests analogous to current DOCX fixtures; fail-closed behavior on broken internal relationships; manifest/content-type correctness; and validator service clean runs.
-
-XLSX vertical gates (minimum honest scope): Excel reopen without repair prompts is the primary gate; schema validation is secondary/necessary. Microsoft explicitly documents repair mechanics when corruption is detected, so triggering repair is treated as a failure unless explicitly accepted as a preserve-only/unsupported-fatal outcome.
-
-## Sources
-
-Internal (GitHub connector: `bwllaming/docx-react-component`)
-
-Public API doctrine and host contract:
-Frontend architecture rules (“UI is projection of runtime snapshot”):
-OOXML compliance model and taxonomy:
-Command → transaction execution spine:
-Session capabilities / trust surfaces:
-DOCX session import/export structure:
-Export session + owned-part rewrite discipline:
-Preserved-part reattachment mechanics:
-Import diagnostics fail-closed mode:
-Diagnostics taxonomy + export blocking semantics:
-Markup-compatibility attribute preservation:
-Preservation roundtrip tests (unknown parts, AlternateContent, broken rels):
-Open XML SDK validator service implementation:
-
-External standards and official documentation
-
-OOXML standard family and parts listing (ECMA-376):
-ISO/IEC 29500-2 (OPC) listing:
-ISO/IEC 29500-3 (Markup Compatibility and Extensibility) listing:
-Library overview and links for MCE/OOXML (helpful cross-reference):
-
-Excel repair behavior (host-level correctness implications):
-Microsoft Open XML format extensions (.docx/.xlsx/.pptx and macro-enabled suffixes):
-
-Open XML SDK validation surface (`OpenXmlValidator`):
-Open XML SDK `SpreadsheetDocument.Open` API surface (used for XLSX validation patterns):