@beyondwork/docx-react-component 1.0.0 → 1.0.1

package/docs/plans/current-state.md

@@ -1,198 +0,0 @@
-# Current State
-
-## Repo Identity
-
-- The repo now documents itself as `react-ooxml-office`.
-- The landed source tree is still docx-first.
-- The only shipped runtime in source today is the docx implementation behind `WordReviewEditor`.
-- `xlsx` is now represented by canonical planned docs, not by shipped source.
-- `pdf` is acknowledged as future work only.
-
-## Landed Docx Work
-
-The current landed implementation still includes:
-
-- a live `WordReviewEditor` shell on top of `DocumentRuntime`
-- runtime-owned text editing through commands and transactions
-- runtime-owned comment and tracked-change projections
-- preservation-aware compatibility reporting and locked-region rendering
-- fixture-backed docx parse, edit, export, and validation proof for the current supported slice
-- the internal docx harness under `services/react-word-editor`
-- the Open XML SDK validator service under `services/openxml-validator`
-
-## Active Maturity Line
-
-The active maturity line remains the docx Wave sequence under `docs/plans/waves/`.
-
-Current status of that track:
-
-- Waves 0 through 7 are landed as the current substrate and proof base
-- Wave 8 and Wave 9 artifacts remain historical inputs only
-- the current Wave 10 certification bundle remains blocked below `qa-proved`
-- Wave 11 remains pending and should not be treated as a substitute for unresolved Wave 10 blockers
-- Waves 12 through 17 remain the post-v1 docx fidelity roadmap
-- Wave 18 executed successfully on 2026-03-29, promoting seven core components to fleet-ready status with comprehensive integrated proof and legal checklist coverage
-- Wave 19 executed successfully (2026-04-03), targeting CI green and test infrastructure (Phase 1 of the shipping roadmap); `openxml-sdk-validator-service` promoted to `pilot-live`; all 174 tests passing; GitHub Actions CI workflow landed
-- Wave 20 is in progress (2026-04-03), targeting first-class table editing (Phase 2 of the shipping roadmap); table round-trip fixtures landed (A2); ProseMirror schema and commands in progress (A1, proof gap open); `table-editing` promoted to `baseline-proved`
-- Wave 25 executing (2026-04-03), first xlsx wave — canonical workbook model and SpreadsheetML import; `src/formats/xlsx/model/` and `src/formats/xlsx/io/` landed; `xlsx-canonical-workbook-model` and `xlsx-import-and-normalization` promoted to `baseline-proved`; A2 proof gap (xlsx-session.ts and import-tests.json) remains open
-- Wave 28 executing (2026-04-05), editor feature parity from reference implementation — prosemirror-tables integration, rich formatting marks (font family, size, color, highlight, superscript, subscript, small caps, all caps, paragraph alignment), image insertion command, search/highlight plugin, `useDocxEditor` imperative hook, headless Node.js CLI (info, convert, validate); `editor-feature-parity` promoted to `baseline-proved`; proof gaps on A1/A2/A3 pending repair pass
-- Wave 29 executing (2026-04-05), OOXML parsing fidelity — complete paragraph properties (alignment, spacing, indentation, tab stops, keepNext, keepLines, outlineLevel, pageBreakBefore), run properties (doubleStrikethrough, vanish, lang, backgroundColor), table properties (borders, cell margins, shading, width, alignment, row height, isHeader), field codes, bookmarks, and section breaks; `ooxml-parsing-fidelity` promoted to `baseline-proved`; proof gaps on A1/A2 pending repair pass
-- Wave 32 executing (2026-04-05), OOXML property completeness — paragraph properties (widowControl, pBdr borders, shading, bidi, suppressLineNumbers, cnfStyle), run properties (charSpacing, kerning, emboss, imprint, shadow, position, textFill), table model (tblLook), inline types (ColumnBreakNode, SymbolNode), latent styles in style catalog; `ooxml-property-completeness` promoted to `baseline-proved`; proof artifact pending repair pass
-- Wave 33 executed (2026-04-05), document sub-parts — headers, footers, footnotes, endnotes, and theme parsing/preservation; `document-sub-parts` promoted to `baseline-proved`; 61/61 targeted tests passing; proof at `.tmp/wave-33-subparts-proof/all-subparts.json`
-- Wave 34 executed (2026-04-06), structural block types — SDT blocks, custom XML wrappers, altChunk relationship preservation, nested tables, and floating-image anchor metadata with inline editor fallback; `structural-block-types` promoted to `baseline-proved`; proof at `.tmp/wave-34-blocks-proof/structural.json`
-- Wave 35 executed (2026-04-06), track change extensions — property change revisions (pPrChange, sectPrChange, tblPrChange, rPrChange) and move tracking (moveFrom, moveTo) with linked move IDs; `sectPrChange` and `tblPrChange` are actionable (accept/reject); `pPrChange` and `rPrChange` are preserve-only with PropertyChangeData metadata; `track-change-extensions` promoted to `baseline-proved`; 17/17 new tests passing, 11/11 existing revision tests unaffected; proof at `.tmp/wave-35-track-proof/revisions.json`
-
-## Shared Platform Docs Landed
-
-The repo now has canonical cross-format planning docs for the broader office story:
-
-- `docs/architecture/platform/shared-openxml-editor-platform.md`
-- `docs/reference/platform/shared-ooxml-platform-guidance.md`
-
-These docs define shared platform direction. They do not imply the current source tree has already been extracted into a neutral platform layout.
-
-## Xlsx Planning Docs Landed
-
-The repo now has canonical planned xlsx docs:
-
-- `docs/architecture/xlsx/spreadsheet-editor-frontend-architecture.md`
-- `docs/architecture/xlsx/canonical-workbook-model-and-commands.md`
-- `docs/reference/xlsx/xlsx-ooxml-compliance.md`
-- `docs/plans/xlsx/xlsx-fixture-corpus-and-certification-plan.md`
-
-The original research intake remains under `docs/xlsx-react/`, now explicitly classified as research intake rather than canon.
-
-## Xlsx Implementation Begun (Wave 25)
-
-The first xlsx implementation wave (Wave 25) is executing. Source landed:
-
-- `src/formats/xlsx/model/` — canonical workbook model (workbook, sheet, cell, styles)
-- `src/formats/xlsx/io/` — SpreadsheetML parsers (workbook, sheet, shared strings, styles)
-- `test/formats/xlsx/model/workbook.test.ts` — workbook model unit tests
-- `.tmp/wave-25-xlsx-proof/model-tests.json` — A1 proof bundle
-
-Both `xlsx-canonical-workbook-model` and `xlsx-import-and-normalization` are at `baseline-proved`. The xlsx track reuses `src/io/opc/` (OPC package layer) and `src/preservation/` from the docx runtime.
-
-## OOXML Parsing Fidelity Landed (Wave 29)
-
-Wave 29 (2026-04-05) completes OOXML property coverage for the docx parser and serializer. Source modified:
-
-- `src/model/canonical-document.ts` — extended `ParagraphNode` and `TextNode` with full property sets; added `FieldNode`, `BookmarkNode`, `SectionBreakNode`
-- `src/io/ooxml/parse-main-document.ts` — parses `w:pPr` and `w:rPr` elements for all new properties; parses fields, bookmarks, section breaks
-- `src/io/export/serialize-main-document.ts` — serializes all new properties back to OOXML
-- `src/io/normalize/normalize-text.ts` — normalization updated for new node types
-- `test/io/paragraph-properties-roundtrip.test.ts` — paragraph/run property round-trip tests
-- `test/io/table-properties-roundtrip.test.ts` — table property round-trip tests
-- `test/io/fields-bookmarks.test.ts` — field code and bookmark tests
-
-`ooxml-parsing-fidelity` is at `baseline-proved`. Proof artifacts pending repair pass: `.tmp/wave-29-parsing-proof/`.
-
-## OOXML Property Completeness Landed (Wave 32)
-
-Wave 32 (2026-04-05) completes the remaining paragraph, run, and table property coverage. Source modified:
-
-- `src/model/canonical-document.ts` — extended `ParagraphNode` with widowControl, borders (ParagraphBorders), shading (ParagraphShading), bidi, suppressLineNumbers, cnfStyle; extended `TextMark` union with charSpacing, kerning, emboss, imprint, shadow, position, textFill; added `TableLook` and `tblLook` to `TableNode`; added `ColumnBreakNode` and `SymbolNode` to `DocumentNode` union
-- `src/io/ooxml/parse-main-document.ts` — parses all new `w:pPr` and `w:rPr` elements; parses column breaks and symbol characters; parses latent style catalog
-- `src/io/export/serialize-main-document.ts` — serializes all new paragraph, run, and inline properties back to OOXML
-- `src/io/ooxml/parse-tables.ts` — parses `w:tblLook`
-- `src/io/export/serialize-tables.ts` — serializes `tblLook`
-- `test/io/property-completeness.test.ts` — round-trip tests for all new Wave 32 properties
-
-`ooxml-property-completeness` is at `baseline-proved`. Proof artifact: `.tmp/wave-32-props-proof/all-props.json`.
-
-## Editor Feature Parity Landed (Wave 28)
-
-Wave 28 (2026-04-05) brings the editor surface to parity with the internal reference implementation. Source landed:
-
-- `src/ui-tailwind/editor-surface/pm-schema.ts` — extended with prosemirror-tables and rich formatting marks
-- `src/runtime/table-commands.ts` — replaced with prosemirror-tables command wrappers
-- `src/core/commands/formatting-commands.ts` — toggle/set commands for all rich marks and paragraph alignment
-- `src/ui-tailwind/editor-surface/pm-command-bridge.ts` — bridge updated for new marks and table commands
-- `src/core/commands/image-commands.ts` — `insertImage(data, mimeType, width?, height?)` command
-- `src/ui-tailwind/editor-surface/search-plugin.ts` — search/highlight ProseMirror plugin with regex and case-sensitive options
-- `src/api/use-docx-editor.ts` — `useDocxEditor()` imperative hook exposing full editor API
-- `src/cli/index.ts` and `src/cli/commands.ts` — headless CLI (`docx info`, `docx convert`, `docx validate`)
-
-`editor-feature-parity` is at `baseline-proved`. Proof artifacts pending repair pass: `.tmp/wave-28-parity-proof/`.
-
-## Document Sub-Parts Landed (Wave 33)
-
-Wave 33 (2026-04-05) adds parsing and serialization of OOXML document sub-parts. Source landed:
-
-- `src/io/ooxml/parse-headers-footers.ts` — parses `headerN.xml` / `footerN.xml`; extracts default, first-page, and even/odd variants; links via `w:headerReference` / `w:footerReference` in section properties
-- `src/io/ooxml/parse-footnotes.ts` — parses `footnotes.xml` and `endnotes.xml`; skips separator stubs; captures multi-run footnote bodies with marks
-- `src/io/ooxml/parse-theme.ts` — parses `theme1.xml`; captures theme colors and fonts in `subParts.theme` for future style-resolution work
-- `src/io/export/serialize-headers-footers.ts` — serializes `HeaderDocument` / `FooterDocument` back to OOXML with correct namespace
-- `src/io/export/serialize-footnotes.ts` — serializes `FootnoteCollection` back to OOXML
-- `src/model/canonical-document.ts` — added `HeaderDocument`, `FooterDocument`, `FootnoteCollection`, `FootnoteRefNode`, `ThemeDefinition` types
-- `src/io/docx-session.ts` — wired sub-part parsing into the session load path and preserves parsed `theme1.xml` ownership on export
-- `test/io/headers-footers-roundtrip.test.ts` — header/footer round-trip tests (17 tests)
-- `test/io/footnotes-roundtrip.test.ts` — footnote/endnote round-trip tests (14 tests)
-
-`document-sub-parts` is at `baseline-proved` for headers, footers, footnotes, endnotes, and theme package preservation. Theme parsing is landed as captured metadata in `subParts.theme`, and the existing theme part is preserved on export; style-resolution and authored theme edits/export remain future work. Proof artifact: `.tmp/wave-33-subparts-proof/all-subparts.json`.
-
-## Structural Block Types Landed (Wave 34)
-
-Wave 34 (2026-04-06) closes the docx structural-block gap for schema-aware block preservation and editor-safe fallback surfaces. Source landed:
-
-- `src/model/canonical-document.ts` — added canonical node support for SDT blocks, custom XML wrappers, altChunk blocks, nested table shapes, and floating image anchor metadata
-- `src/io/ooxml/parse-main-document.ts` — parses `w:sdt`, `w:customXml`, `w:altChunk`, and nested table block structure into the canonical model
-- `src/io/ooxml/parse-inline-media.ts` — captures floating-image anchor positioning and wrap metadata with inline editor fallback
-- `src/io/export/serialize-main-document.ts` — serializes structural block nodes and preserves altChunk relationships on export
-- `src/runtime/surface-projection.ts` — projects supported structural blocks into review-safe surface blocks and preserves unsupported wrappers as opaque blocks
-- `src/ui-tailwind/editor-surface/pm-schema.ts` and `src/ui-tailwind/editor-surface/pm-state-from-snapshot.ts` — render SDT blocks in the editor surface while keeping unsupported structural wrappers preservation-safe
-- `test/io/structural-blocks.test.ts` — proof coverage for SDT parse/normalize/export/projection, custom XML wrapper fallback, altChunk preservation, nested tables, and floating-image metadata
-
-`structural-block-types` is at `baseline-proved`. Proof artifact: `.tmp/wave-34-blocks-proof/structural.json`.
-
-## Track Change Extensions Landed (Wave 35)
-
-Wave 35 (2026-04-06) extends the revision model with property change revisions and move tracking. Source modified:
-
-- `src/review/store/revision-types.ts` — added `PropertyChangeData`, `MoveData`, `PropertyChangeRevision`, `MoveRevision` types; `SupportedRevisionKind` now includes `'property-change'`; `getRevisionActionability` returns `'actionable'` for `'property-change'`
-- `src/model/canonical-document.ts` — added `RevisionPropertyChangeData`, `RevisionMoveData` interfaces; `RevisionRecord.kind` union includes `'property-change'`; `RevisionMetadataRecord` extended with optional `propertyChangeData` and `moveData` fields
-- `src/io/ooxml/parse-revisions.ts` — added `parseTblPropertyRevisions()` and `parseSectPrRevisions()` for actionable property change parsing; pPrChange and rPrChange now carry `PropertyChangeData` in metadata; moveFrom/moveTo revisions include `MoveData` with linked `moveId` for pairing
-- `src/io/export/serialize-revisions.ts` — added `serializePropertyChangeMarkup()`: accept removes `*PrChange` element, reject replaces container element with `beforeContainerXml`
-- `src/review/store/revision-store.ts` — `createRevisionRecord` passes through `propertyChangeData` and `moveData` metadata fields
-- `test/review/property-change-revisions.test.ts` — 10 tests covering sectPrChange and tblPrChange parse, accept/reject, and round-trip; pPrChange preserve-only with propertyChangeData
-- `test/review/move-revisions.test.ts` — 7 tests covering moveFrom/moveTo linked IDs, preserve-only behavior, author/timestamp metadata, and serialization round-trip
-
-`track-change-extensions` is at `baseline-proved`. Design decision: pPrChange stays as formatting kind (preserve-only) with `propertyChangeData` metadata; sectPrChange and tblPrChange are the actionable property-change kinds. Proof artifact: `.tmp/wave-35-track-proof/revisions.json`.
-
-## Complex Content Rendering Landed (Wave 36)
-
-Wave 36 (2026-04-06) adds read-only preview rendering for complex OOXML content: charts, SmartArt diagrams, wps shapes, WordArt, and VML elements. Source landed:
-
-- `src/io/ooxml/parse-complex-content.ts` — parses `mc:AlternateContent` blocks for charts (`c:chart`) and SmartArt (`dgm:*`); extracts fallback preview image media ID; preserves rawXml for lossless round-trip
-- `src/io/ooxml/parse-shapes.ts` — parses `wps:wsp` shapes (geometry and text content), WordArt (text with geometry presets), and VML elements (`v:shape`, `v:rect`, `v:textbox`); preserves rawXml
-- `src/model/canonical-document.ts` — added `ChartPreviewNode`, `SmartArtPreviewNode`, `ShapeNode`, `WordArtNode`, `VmlShapeNode` canonical inline types; each carries `rawXml` field for round-trip fidelity
-- `src/runtime/surface-projection.ts` — projects all five complex-content types to `opaque_inline` surface segments with distinctive labels (Chart, SmartArt, Shape, WordArt, VML shape)
-- `src/ui-tailwind/editor-surface/pm-schema.ts` and `pm-state-from-snapshot.ts` — register dedicated PM atom nodes (`chart_atom`, `smartart_atom`, `shape_atom`, `wordart_atom`, `vml_atom`) for read-only labeled display; map opaque_inline segments by label
-- `src/io/export/serialize-main-document.ts` — emits rawXml unchanged for all five new node types on export
-- `test/io/complex-content-roundtrip.test.ts` — 24 tests covering chart/SmartArt/shape/WordArt/VML parse, canonical type, surface projection, PM atom, and serialize; mixed 5-type paragraph round-trip; negative cases
-
-Architecture decision: new inline canonical types with `rawXml`, projected to `opaque_inline` surface, rendered as dedicated read-only PM atoms. Parse dispatch integration into `parse-main-document.ts` is a non-blocking follow-on (parsers are standalone and ready).
-
-`complex-rendering` is at `baseline-proved`. Proof artifact: `.tmp/wave-36-complex-proof/all-complex.json`.
-
-## What Is Not Landed Yet
-
-- no shipped `SpreadsheetEditor` runtime (xlsx model and parsers exist but no editor surface)
-- no neutral multi-format public component API
-- no extracted `src/platform/` source tree
-- no renamed `office-harness` service in source
-- no shipped pdf runtime
-- xlsx Wave 25 A2 gap: `xlsx-session.ts` and `test/formats/xlsx/io/xlsx-import.test.ts` not yet landed
-
-## Immediate Next Work
-
-The repo roadmap was rewritten in Wave 19 to a shipping-first Phase 1–6 structure. The new priority order:
-
-1. **Phase 1 (complete)**: `pnpm test:repo` green, GitHub Actions CI on PR/push, all 174 tests passing
-2. **Phase 2 (advancing — Waves 20, 28, 29, 32, 33, 34, 35, 36)**: First-class table support landed in Wave 20 (`table-editing` at `baseline-proved`); Wave 28 adds prosemirror-tables integration, rich formatting marks, image insertion, search plugin, `useDocxEditor` hook, and headless CLI (`editor-feature-parity` at `baseline-proved`); Wave 29 completes core OOXML property coverage for paragraphs, runs, tables, fields, bookmarks, and section breaks (`ooxml-parsing-fidelity` at `baseline-proved`); Wave 32 completes remaining paragraph/run properties (widowControl, pBdr, shading, bidi, suppressLineNumbers, cnfStyle, charSpacing, kerning, emboss, imprint, shadow, position, textFill), tblLook, column breaks, and symbols (`ooxml-property-completeness` at `baseline-proved`); Wave 33 adds headers, footers, footnotes, endnotes, and captured theme parsing metadata from their XML sub-parts, while full theme resolution/export remains future work (`document-sub-parts` remains `baseline-proved` for the landed sub-part scope); Wave 34 adds structural block support for SDT blocks, custom XML wrappers, altChunk relationship preservation, nested tables, and floating-image anchor metadata with editor-safe fallback (`structural-block-types` at `baseline-proved`); Wave 35 adds track change extensions — property change revisions (pPrChange, sectPrChange, tblPrChange, rPrChange) and move tracking (moveFrom/moveTo) with linked move IDs (`track-change-extensions` at `baseline-proved`); Wave 36 adds read-only complex content rendering — charts, SmartArt, wps shapes, WordArt, and VML elements each with a dedicated canonical inline type carrying rawXml for lossless round-trip, projected to opaque_inline surface as labeled read-only preview atoms (`complex-rendering` at `baseline-proved`)
-3. **Phase 3**: API reference and npm package — `useDocxEditor` hook now exists as the imperative API surface; remove `private: true`, publish artifact, rewrite README, write API reference docs
-4. **Phase 4**: OpenXML SDK validator in CI — service now at `pilot-live`; CI step still needed
-5. **Phase 5**: Legal workflow features — version compare, defined terms, cross-references
-6. **Phase 6**: Production hardening — accessibility, large-document performance, memory
-
-Wave 10 "qa-proved certification" ceremony and Wave 11 "fleet-ready packaging" ceremony are superseded by Phase 1 and Phase 3 respectively in the new roadmap. The shared platform and xlsx planning docs remain anchors for future multi-format work.

package/docs/plans/docx/README.md

@@ -1,9 +0,0 @@
-# Docx Plans
-
-This directory is reserved for docx-specific planning material outside the current Wave sequence.
-
-The active docx implementation line still lives under:
-
-- `docs/plans/waves/`
-- `docs/plans/component-cutover-matrix.md`
-- `docs/plans/current-state.md`

package/docs/plans/examples/wave-benchmark-improvement.md

@@ -1,108 +0,0 @@
-# Wave 99 - Benchmark Improvement Loop
-
-This example shows how to author a Wave whose job is to improve benchmark outcomes after a baseline already exists.
-
-## Eval targets
-
-- id: hidden-profile-pooling | selection: pinned | benchmarks: private-evidence-integration,premature-consensus-guard | objective: Improve distributed evidence pooling without allowing premature closure | threshold: Full-wave benchmark scores improve without regressing closure discipline
-- id: routing-quality | selection: pinned | benchmarks: expert-routing-preservation,lockstep-resolution | objective: Improve capability routing and simultaneous coordination | threshold: Routing benchmarks improve and no new deadlock-like regressions appear
-
-## Agent A0: cont-QA
-
-### Prompt
-
-```text
-Primary goal:
-- Block any claimed improvement that is not backed by rerun benchmark output.
-
-Specific expectations:
-- require benchmark reruns after each material change
-- do not PASS on inspection-only claims
-- treat benchmark regressions as blocking until they are resolved or explicitly accepted
-
-File ownership (only touch these paths):
-- docs/plans/waves/reviews/wave-99-cont-qa.md
-```
-
-## Agent E0: cont-EVAL
-
-### Prompt
-
-```text
-Primary goal:
-- Run the benchmark loop, identify the narrowest failing coordination surfaces, and keep benchmark ids explicit in every iteration.
-
-Specific expectations:
-- choose the smallest benchmark subset that still proves the claimed improvement
-- record baseline, current score, regressions, and exact benchmark ids
-- stay report-only unless this wave explicitly grants implementation ownership
-
-File ownership (only touch these paths):
-- docs/plans/waves/reviews/wave-99-cont-eval.md
-```
-
-## Agent A8: Integration Steward
-
-### Prompt
-
-```text
-Primary goal:
-- Synthesize benchmark evidence, implementation deltas, and regression risk into one integrated recommendation.
-
-Specific expectations:
-- call out any contradiction between benchmark wins and runtime or docs regressions
-- prefer explicit follow-up requests over vague risk notes
-
-File ownership (only touch these paths):
-- .tmp/main-wave-launcher/integration/wave-99.md
-```
-
-## Agent A1: Coordination Store Hardening
-
-### Deliverables
-
-- scripts/wave-orchestrator/coordination-store.mjs
-- test/wave-orchestrator/coordination-store.test.ts
-
-### Prompt
-
-```text
-Primary goal:
-- Improve targeted inbox recall or summary fidelity for the benchmark cases that E0 reports as failing.
-
-Specific expectations:
-- keep changes tightly scoped to the failing benchmark signals
-- add regression coverage for any changed behavior
-- coordinate doc-impact with A9 if the benchmark semantics or operator surfaces change
-
-File ownership (only touch these paths):
-- scripts/wave-orchestrator/coordination-store.mjs
-- test/wave-orchestrator/coordination-store.test.ts
-```
-
-## Agent A2: Routing And Closure Hardening
-
-### Deliverables
-
-- scripts/wave-orchestrator/routing-state.mjs
-- scripts/wave-orchestrator/benchmark.mjs
-- test/wave-orchestrator/routing-state.test.ts
-- test/wave-orchestrator/benchmark.test.ts
-
-### Prompt
-
-```text
-Primary goal:
-- Improve routing or closure benchmark outcomes without weakening evidence requirements.
-
-Specific expectations:
-- preserve deterministic benchmark behavior
-- prefer narrow routing and guard changes over broad orchestration rewrites
-- rerun the affected benchmark cases after each material change
-
-File ownership (only touch these paths):
-- scripts/wave-orchestrator/routing-state.mjs
-- scripts/wave-orchestrator/benchmark.mjs
-- test/wave-orchestrator/routing-state.test.ts
-- test/wave-orchestrator/benchmark.test.ts
-```