@beyondwork/docx-react-component 1.0.0 → 1.0.2

package/docs/reference/ooxml-compliance.md

@@ -1,129 +0,0 @@
-# OOXML Compliance
-
-This file captures the shipped compatibility and validation stance for `.docx`.
-
-Within the broader `react-ooxml-office` repo story:
-
-- this remains the live docx compliance contract
-- it should not be read as the shared platform contract for every future format
-- planned xlsx compliance now lives separately in `docs/reference/xlsx/xlsx-ooxml-compliance.md`
-
-## Compliance Model
-
-The editor is an OOXML consumer and producer. `.docx` is treated as an OPC package, not just a single XML file.
-
-Every export must preserve:
-
-- package ZIP integrity
-- required parts and relationships
-- content types
-- supported feature semantics
-- preservable unsupported content
-
-Every supported export must reopen in Word without repair prompts.
-
-## Feature Classes
-
-Every feature must be classified as exactly one of:
-
-- `supported-roundtrip`
-- `preserve-only`
-- `unsupported-fatal`
-
-The v1 repo scope is:
-
-- supported-roundtrip: text, formatting, headings, hyperlinks, lists, inline images, single-paragraph comments, tracked insertions and deletions
-- preserve-only: body-level tables and merged-cell tables on the current live path, sections, headers/footers, notes, fields, SDTs, custom XML, altChunk, embedded objects, unknown OOXML, unknown package parts
-- unsupported-fatal: malformed OOXML and package states the editor cannot preserve safely
-
-`supported-import-only` and `supported-export-only` are not valid v1 classes. If the repo cannot safely edit a feature through import, canonical state, export, and Word reopen, it must stay `preserve-only` or `unsupported-fatal`.
-
-Current correction:
-
-- helper-level XML table tests do not qualify tables as `supported-roundtrip`
-- first-class table support requires package-backed `import -> runtime edit -> export -> reload` proof and Word reopen notes in [docs/plans/waves/wave-12.md](/home/coder/docx-react-component/docs/plans/waves/wave-12.md)
-
-Password-to-open encrypted `.docx` is not one of these feature classes.
-
-It is outside the active editor-owned v1 contract. If an upstream system supports password-to-open Office containers, it must hand the editor a normal decrypted OPC `.docx`.
-
-Document protection and restrict-editing markup remain in-package OOXML behavior and continue to use the normal compatibility taxonomy.
-
-## Package-First Rules
-
-Importer and exporter rules:
-
-- preserve unknown package parts and relationships whenever possible
-- regenerate only editor-owned parts
-- keep relationship IDs stable when practical
-- preserve `mc:Ignorable`, `AlternateContent`, and unknown namespaces
-- lock opaque unsupported regions in the editing surface
-- represent unsupported inline and block OOXML in the canonical story as atomic opaque placeholders backed by preservation records
-- boot `initialDocx` loads through a real OPC session so exports rewrite owned parts instead of echoing source bytes
-
-## Preserve, Lock, Warn, Block, Fail
-
-The editor response model is:
-
-- preserve: keep unsupported but intact OOXML and package surfaces so export can reattach them safely
-- lock: do not allow direct editing inside preserve-only regions; opaque placeholders are atomic
-- warn: require explicit user acknowledgement before destructive actions that would remove preserved content
-- block: stop export or editing actions that would require unsupported semantic rewriting
-- fail: reject malformed packages or continue only in diagnostics/read-only mode when trustworthy preservation is not possible
-
-The editor must never silently discard preservable unsupported content.
-
-## Microsoft SDK Policy
-
-The Microsoft Open XML SDK is used for:
-
-- CI validation
-- internal Railway validation service
-- diagnostics and compatibility reporting inputs
-
-The Microsoft Open XML SDK is not used as:
-
-- the shipped editor runtime
-- the primary OOXML transformation engine
-- a dependency in the browser bundle
-
-`OpenXmlValidator` is a validation surface for packages, parts, and elements in CI or service environments. It does not authorize runtime repair heuristics and it does not replace repo-owned compatibility logic.
-
-## Release Gates
-
-Compatibility release gates require:
-
-- fixture-based import and export tests
-- package integrity checks
-- Open XML SDK validation
-- preserve-only survival checks
-- Word desktop certification
-- Word on the web certification for representative fixtures
-
-Word behavior is the final standard. SDK validation is necessary but not sufficient.
-
-## Fixture program
-
-The minimum v1 fixture corpus is F01-F21 under [test/fixtures/docx/README.md](/home/coder/docx-react-component/test/fixtures/docx/README.md).
-
-- F01-F02 prove the text, whitespace, style, and heading baseline
-- F03-F04 prove supported-roundtrip numbering and list behavior
-- F05-F06 currently prove preserve-only table and merged-cell package survival on the live runtime path
-- F07-F08 prove supported-roundtrip inline images and hyperlinks
-- F09-F14 prove comments and revision behavior, including preserve-only structural revision cases
-- F15-F20 prove preserve-only survival for sections, notes, fields, SDTs, custom XML, unknown OOXML, and unknown package parts
-- F19 currently carries one inherited source SDK finding on its custom XML wrapper markup, so preserve-only proof for that fixture is tracked as source-baseline-neutral until the source artifact is corrected
-- F21 proves unsupported-fatal malformed-package handling
-
-Representative scenario artifacts live under [test/fixtures/scenarios/docx/README.md](/home/coder/docx-react-component/test/fixtures/scenarios/docx/README.md).
-
-- They supplement the frozen minimum corpus and do not replace release-gate fixtures.
-- They track source-vs-export validator deltas because real-world source documents may already contain SDK findings.
-- Word reopen without repair prompts remains the authoritative gate for those scenario artifacts.
-
-Password-to-open Office containers are not part of the active editor-owned v1 fixture program.
-
-- If upstream systems support them, they must hand the editor a normal OPC `.docx`.
-- They do not renumber `F01` through `F21` and are not part of the active Wave 8 through Wave 10 certification gate.
-
-Wave 10 re-runs the full fixture program with Word certification as the authoritative v1 closure gate.

package/docs/reference/ooxml-feature-parity-matrix.md

@@ -1,172 +0,0 @@
-# OOXML WordprocessingML Feature Parity Matrix
-
-Generated: 2026-04-05
-
-## Legend
-- ✅ supported-roundtrip: Parse, edit, export, Word reopen
-- 🔄 wave-planned: Being built in active wave
-- 📋 preserve-only: Survives round-trip as opaque
-- ❌ unsupported: Not handled
-
-## 1. Package (OPC)
-| Feature | Status |
-|---------|--------|
-| ZIP integrity | ✅ |
-| Content types | ✅ |
-| Package rels | ✅ |
-| Part rels | ✅ |
-| Unknown parts | ✅ |
-| Unknown rels | ✅ |
-
-## 2. Block Elements
-| Feature | Element | Status | Wave |
-|---------|---------|--------|------|
-| Paragraphs | w:p | ✅ | — |
-| Tables | w:tbl | 🔄 | 20,28 |
-| Sections | w:sectPr | 🔄 | 29 |
-| SDT | w:sdt | 📋 | — |
-| Custom XML | w:customXml | 📋 | — |
-| AltChunk | w:altChunk | 📋 | — |
-
-## 3. Paragraph Properties
-| Feature | Element | Status | Wave |
-|---------|---------|--------|------|
-| Style ref | w:pStyle | ✅ | — |
-| Alignment | w:jc | 🔄 | 28,30 |
-| Numbering | w:numPr | ✅ | 30 |
-| Indentation | w:ind | 🔄 | 29 |
-| Spacing | w:spacing | 🔄 | 29 |
-| Tab stops | w:tabs | 🔄 | 29 |
-| Keep next | w:keepNext | 🔄 | 29 |
-| Keep lines | w:keepLines | 🔄 | 29 |
-| Page break before | w:pageBreakBefore | 🔄 | 29 |
-| Outline level | w:outlineLvl | 🔄 | 29 |
-| Widow/orphan | w:widowControl | 📋 | — |
-| Borders | w:pBdr | 📋 | — |
-| Shading | w:shd | 📋 | — |
-| Bidi | w:bidi | 📋 | — |
-
-## 4. Run Properties
-| Feature | Element | Status | Wave |
-|---------|---------|--------|------|
-| Bold | w:b | ✅ | — |
-| Italic | w:i | ✅ | — |
-| Underline | w:u | ✅ | — |
-| Strikethrough | w:strike | ✅ | — |
-| Double strike | w:dstrike | 🔄 | 29 |
-| Superscript | w:vertAlign | 🔄 | 28 |
-| Subscript | w:vertAlign | 🔄 | 28 |
-| Small caps | w:smallCaps | 🔄 | 28 |
-| All caps | w:caps | 🔄 | 28 |
-| Font family | w:rFonts | 🔄 | 28 |
-| Font size | w:sz | 🔄 | 28 |
-| Text color | w:color | 🔄 | 28 |
-| Highlight | w:highlight | 🔄 | 28 |
-| Background | w:shd | 🔄 | 29 |
-| Hidden text | w:vanish | 🔄 | 29 |
-| Language | w:lang | 🔄 | 29 |
-| Char spacing | w:spacing | 📋 | — |
-| Kerning | w:kern | 📋 | — |
-| Emboss/Shadow | w:emboss | 📋 | — |
-| Text effects | w14:* | 📋 | — |
-
-## 5. Inline Content
-| Feature | Element | Status | Wave |
-|---------|---------|--------|------|
-| Text runs | w:r/w:t | ✅ | — |
-| Line breaks | w:br | ✅ | — |
-| Page breaks | w:br type=page | 🔄 | 30 |
-| Column breaks | w:br type=column | 📋 | — |
-| Tabs | w:tab | ✅ | — |
-| Hyperlinks | w:hyperlink | ✅ | — |
-| Inline images | wp:inline | ✅ | 28 |
-| Floating images | wp:anchor | 📋 | — |
-| Simple fields | w:fldSimple | 🔄 | 29 |
-| Complex fields | w:fldChar | 🔄 | 29 |
-| Bookmarks | w:bookmarkStart/End | 🔄 | 29 |
-| Symbols | w:sym | 📋 | — |
-| Footnote refs | w:footnoteRef | 📋 | — |
-| Comment markers | w:commentRange | ✅ | — |
-| Ruby | w:ruby | 📋 | — |
-| OLE objects | w:object | 📋 | — |
-
-## 6. Tables
-| Feature | Element | Status | Wave |
-|---------|---------|--------|------|
-| Structure | w:tbl/tr/tc | 🔄 | 20 |
-| Grid | w:tblGrid | 🔄 | 20 |
-| Cell content | w:tc/w:p | 🔄 | 20 |
-| Horiz merge | w:gridSpan | 🔄 | 20 |
-| Vert merge | w:vMerge | 🔄 | 20 |
-| Table borders | w:tblBorders | 🔄 | 29 |
-| Cell borders | w:tcBorders | 🔄 | 29 |
-| Cell shading | w:shd | 🔄 | 29 |
-| Cell margins | w:tblCellMar | 🔄 | 29 |
-| Cell valign | w:vAlign | 🔄 | 29 |
-| Row height | w:trHeight | 🔄 | 29 |
-| Header rows | w:tblHeader | 🔄 | 29 |
-| Table style | w:tblStyle | 📋 | — |
-| Nested tables | — | 📋 | — |
-
-## 7. Styles
-| Feature | Status |
-|---------|--------|
-| Paragraph styles | ✅ |
-| Character styles | ✅ |
-| Style inheritance | ✅ |
-| Default styles | ✅ |
-| Table styles | 📋 |
-| List styles | 📋 |
-| Latent styles | 📋 |
-
-## 8. Numbering
-| Feature | Status | Wave |
-|---------|--------|------|
-| Abstract defs | ✅ | — |
-| Instances | ✅ | — |
-| Multi-level | ✅ | 30 |
-| Num formats | 🔄 | 30 |
-| Overrides | ✅ | — |
-
-## 9. Comments: All ✅
-## 10. Track Changes
-| Feature | Status | Wave |
-|---------|--------|------|
-| Insertions | ✅ | — |
-| Deletions | ✅ | — |
-| Format changes | ✅ | — |
-| Para/section/table changes | 📋 | — |
-| Move from/to | 📋 | — |
-| Accept/reject | 🔄 | 30 |
-
-## 11-13. Headers/Footers/Notes/Settings: All 📋 preserve-only
-## 14. Media: Inline images ✅, rest 📋
-## 15. Compat: MC ✅, unknown ns ✅, rest 📋, signatures/encryption ❌
-
-## 16. Editor Features
-| Feature | Status | Wave |
-|---------|--------|------|
-| ProseMirror surface | ✅ | — |
-| Undo/redo | ✅ | — |
-| prosemirror-tables | 🔄 | 28 |
-| Rich formatting | 🔄 | 28 |
-| Search | 🔄 | 28 |
-| Image insert | 🔄 | 28 |
-| useDocxEditor hook | 🔄 | 28 |
-| CLI | 🔄 | 28 |
-| Headings h1-h6 | 🔄 | 30 |
-| Page break visual | 🔄 | 30 |
-| Numbering prefixes | 🔄 | 30 |
-| Read-only mode | 🔄 | 30 |
-| Format state | 🔄 | 30 |
-| Event callbacks | 🔄 | 30 |
-| Yjs collaboration | 🔄 | 31 |
-| Compatibility report | ✅ | — |
-| Export gating | ✅ | — |
-| SDK validation | ✅ | — |
-
-## Summary
-| | ✅ | 🔄 | 📋 | ❌ | Total |
-|---|---|---|---|---|-------|
-| Now | 45 | 55 | 50 | 2 | 152 |
-| After 28-31 | ~100 | 0 | ~50 | 2 | 152 |

package/docs/reference/platform/shared-ooxml-platform-guidance.md

@@ -1,77 +0,0 @@
-# Shared OOXML Platform Guidance
-
-## Status
-
-- Canonical cross-format guidance for the broader `react-ooxml-office` repo.
-- Applies to shared OOXML platform work and format-planning docs.
-- Does not replace the live docx-specific public API or compliance contracts.
-
-## Purpose
-
-This file captures the rules that should stay consistent across OOXML siblings such as `docx` and `xlsx`.
-
-Use it when writing or reviewing:
-
-- shared package and preservation code
-- cross-format architecture docs
-- future snapshot, diagnostics, or validation contracts
-- roadmap language that needs to distinguish shared versus format-specific work
-
-## Shared Terms
-
-### Support Taxonomy
-
-Every feature should be classified as:
-
-- `supported-roundtrip`
-- `preserve-only`
-- `unsupported-fatal`
-
-This taxonomy is repo-wide for OOXML work. Individual formats still define their own feature lists.
-
-### Response Model
-
-Runtime behavior should remain explicit:
-
-- preserve
-- lock
-- warn
-- block
-- fail
-
-These responses describe how the runtime behaves when a user or host attempts an operation.
-
-## Shared Rules
-
-- Treat OOXML files as OPC packages first.
-- Preserve unknown but preservable parts and relationships whenever possible.
-- Regenerate only the parts a runtime explicitly owns.
-- Keep runtime-owned structured state as the only source of truth.
-- Keep UI state presentation-only.
-- Use typed warnings, errors, and export blockers instead of hidden downgrade behavior.
-- Use Open XML SDK tooling in CI or service environments only, not in shipped browser runtimes.
-- Treat host reopen behavior as the final fidelity bar.
-
-## Boundaries
-
-The shared platform should own:
-
-- package io discipline
-- preservation plumbing
-- compatibility vocabulary
-- validation integration
-- host persistence and snapshot doctrine
-- shared runtime-to-UI rules
-
-The shared platform should not own:
-
-- docx paragraph or review semantics
-- xlsx grid, formula, or workbook semantics
-- pdf or non-OOXML document behavior
-
-## Shipped Versus Planned Contracts
-
-- `docs/reference/public-api.md` remains the shipped docx public API.
-- `docs/reference/ooxml-compliance.md` remains the shipped docx compliance contract.
-- `docs/reference/xlsx/xlsx-ooxml-compliance.md` is the planned xlsx sibling contract.
-- Future format docs should add sibling references instead of silently broadening current docx docs.

package/docs/reference/prototype-agent-prompt-legal-fidelity.md

@@ -1,155 +0,0 @@
-# Prototype Agent Prompt - Legal Fidelity
-
-## Purpose
-
-Use this prompt when working on the internal `/demo` prototype under
-`services/react-word-editor/`. It is designed to help a prototype-focused agent
-improve visual fidelity and table storytelling without drifting away from the
-repo's real architecture, canonical data model, and support boundaries.
-
-This prompt is for the internal prototype route only. It does not authorize the
-agent to widen public support claims.
-
-## Ready-To-Use Prompt
-
-```text
-You are working on the internal WordReviewEditor demo prototype in the repository
-at /home/coder/docx-react-component.
-
-Your job is to improve the `/demo` prototype so it better communicates the future
-legal-review product, especially around tables, trust surfaces, and curated
-browser typography, while staying architecture-true to the real runtime.
-
-Before making changes, read these files first:
-
-- README.md
-- DESIGN.md
-- docs/reference/repository-guidance.md
-- docs/reference/public-api.md
-- docs/reference/ooxml-compliance.md
-- docs/reference/word-review-editor-ux-guide.md
-- docs/legal-feedback-architecture.md
-- docs/plans/waves/deferred/legal-feedback-wave-expansion.md
-- services/react-word-editor/README.md
-- services/react-word-editor/app/demo/page.tsx
-- services/react-word-editor/components/harness-workspace-page.tsx
-- services/react-word-editor/components/harness-editor-session-client.tsx
-- src/ui/review/prototype-review-workspace.tsx
-- services/react-word-editor/lib/demo-fixtures.ts
-- services/react-word-editor/app/api/demo-sessions/route.ts
-- src/ui/WordReviewEditor.tsx
-- src/ui/editor-surface/editor-surface.tsx
-- src/api/public-types.ts
-
-You must treat the prototype as a UX and narrative surface that previews the
-future product while remaining honest about current runtime truth.
-
-Non-negotiable rules:
-
-- Do not treat the prototype as the source of truth for runtime behavior.
-- Do not introduce DOM-owned editing behavior, contenteditable hacks, or ad hoc
-  document mutation that would contradict the command-and-transaction runtime.
-- Do not imply that preserve-only content is freely editable.
-- Do not imply native Word visual parity, exact pagination parity, or native
-  installed-font parity in the browser.
-- Do not widen the public `WordReviewEditor` API to support prototype-only needs.
-- Do not silently convert unsupported OOXML into apparently-supported UI flows.
-
-Architecture alignment requirements:
-
-- Keep the prototype structurally aligned with `src/api/public-types.ts` and the
-  runtime-owned shell in `src/ui/WordReviewEditor.tsx`.
-- Prefer prototype data that mirrors `RuntimeRenderSnapshot` shapes.
-- If you need demo-only additions, keep them explicitly tagged `_prototypeOnly: true`.
-- Any new table storytelling should move the prototype closer to future
-  first-class table blocks rather than inventing a separate table architecture.
-- Any new font work should use curated web-font approximation for readability,
-  not a fake Word-style font picker or native-font promise.
-
-Specific product goals for this pass:
-
-- Make tables feel like serious legal-review objects rather than decorative
-  layout blocks.
-- Improve the visibility of supported vs preserve-only states.
-- Strengthen the relationship between the main document surface and the review rail.
-- Improve typography, spacing, density, and hierarchy so the demo feels more like
-  the future product and less like a mock dashboard.
-- Use a small curated browser typography system that suggests legal-document
-  readability rather than raw Word parity.
-
-Table-specific guidance:
-
-- Prototype tables may be richer than the current runtime, but they must be
-  framed as future runtime-backed table surfaces, not separate demo inventions.
-- If you introduce per-cell affordances, selection cues, comment cues, or change
-  cues, keep them conceptually compatible with a future canonical `TableNode`
-  plus cell-local content model.
-- Do not imply support for tracked structural row or column revisions unless the
-  UI clearly marks them as future or preserve-only.
-
-Typography guidance:
-
-- Use curated web fonts only.
-- Optimize for calm legal readability in browser rendering.
-- Favor a small set of roles such as serif, sans, and mono rather than an
-  unrestricted font menu.
-- If you surface font approximation or substitution, do it as a trust cue, not a
-  blocking failure unless the underlying fixture already represents a blocked state.
-
-Preserve-only and trust guidance:
-
-- Locked or preserve-only regions must remain visibly distinct and honestly labeled.
-- Unsupported or blocked states must read as calm, intentional trust surfaces,
-  not broken UI.
-- Compatibility, health, warning, and export posture must remain consistent with
-  the real runtime philosophy in the repo docs.
-
-Prohibited shortcuts:
-
-- no contenteditable editor shortcuts
-- no DOM-as-source-of-truth state
-- no fake accept/reject behavior that has no model meaning
-- no fake comment anchoring disconnected from runtime-style anchors or decorations
-- no generic marketing polish that hides compatibility limits
-- no prototype-only block or state shapes unless clearly marked and justified
-- no visual choices that make the surface feel like a Word ribbon clone
-
-Preferred implementation approach:
-
-1. Keep route-level framing in the harness layer.
-2. Keep the editor workspace visually convergent with the final `WordReviewEditor`
-   shell.
-3. Model future fidelity improvements through fixture state and projection-driven UI.
-4. Improve affordances, hierarchy, and narrative clarity before inventing new behavior.
-
-Acceptance checks before finishing:
-
-- The prototype still reads as internal and non-production.
-- The demo still maps cleanly onto `RuntimeRenderSnapshot` and the current editor shell.
-- Preserve-only and blocked states remain explicit.
-- Table improvements do not imply unsupported runtime semantics.
-- Font improvements use curated browser typography and do not imply Word parity.
-- Any prototype-only additions are clearly tagged.
-- The result feels more legally credible without contradicting repo constraints.
-
-When you finish, summarize:
-
-- what changed visually
-- how the changes stay aligned with the real runtime/data model
-- what remains explicitly prototype-only
-- any follow-up work needed in the real runtime to make the prototype behavior real
-```
-
-## Notes For Reviewers
-
-Use this prompt when the goal is:
-
-- visual refinement of the `/demo` route
-- stronger table communication in the prototype
-- better trust cues
-- better curated typography in the prototype
-
-Do not use this prompt as a substitute for runtime architecture work. If the task
-requires real canonical table support, runtime selection changes, OOXML import and
-export changes, or new proof-bearing claims, that work belongs in the main runtime
-and wave-planning surfaces rather than the prototype alone.