@beyondwork/docx-react-component 1.0.0

package/docs/plans/waves/completed/wave-12.md

@@ -0,0 +1,417 @@
+# Wave 12 - Projection Fidelity, First-Class Tables, And AI Action Contract
+
+**Commit message**: `Build: land projection fidelity, tables, and AI contract`
+
+## Component promotions
+
+- canonical-document-model: fleet-ready
+- command-and-transaction-runtime: fleet-ready
+- comments-and-anchor-mapping: fleet-ready
+- tracked-changes-and-review-actions: fleet-ready
+- docx-import-and-normalization: fleet-ready
+- docx-export-and-serialization: fleet-ready
+- unsupported-ooxml-preservation: fleet-ready
+- compatibility-and-word-validation: fleet-ready
+- react-editor-ui: fleet-ready
+
+## Scope note
+
+Wave 12 starts the post-v1 legal-checklist sequence. It is a capability wave,
+not an automatic continuation of the bounded-v1 maturity staircase.
+
+The goal is to establish the new handling rule for the roadmap: high-value
+content should become `read-only projected` before it stays opaque by default,
+and supported slices should then move to bounded or full ownership.
+
+Tables remain the central owned slice in this wave, but Wave 12 also reserves
+the standard host-controlled AI action contract and keeps browser-font
+approximation honest through explicit trust surfaces.
+
+## Entry criteria
+
+- Wave 11 is closed or frozen enough that the bounded-v1 support boundary is
+  stable.
+- Shared docs already distinguish `read-only projected`, `opaque preserve-only`,
+  `policy locks`, and `compatibility-safety locks`.
+- The mounted shared workspace is the canonical frontend shell for new UX work.
+
+## Promotion conditions
+
+- cell-local edit, export, reload, validator, and Word reopen proof exist for
+  the supported table slice
+- compatibility output distinguishes supported table edits, read-only projected
+  structures, and opaque preserve-only behaviors
+- browser-font approximation never mutates exported OOXML font intent
+- `font_substitution` cues come from runtime truth instead of prototype-only
+  code
+- the AI action contract is reserved consistently across API/runtime/frontend
+  without implying direct model-to-DOM mutation or unreviewed drafting
+
+## Deliverables
+
+- typed table ownership and table-aware selection on the canonical runtime path
+- explicit projection rules for table-adjacent or still-unsupported structures
+  that can be shown safely before they are editable
+- package-backed import, export, reimport, validator, and Word proof for the
+  supported table slice
+- mounted table UI and trust surfaces for supported table editing, projected
+  table visibility, and font substitution
+- shared docs that keep the added projection, table, font, and AI-contract
+  slice bounded and explicit
+
+## Deploy environments
+
+- staging: railway-cli (shared workspace validation environment)
+
+## Context7 defaults
+
+- bundle: word-editor-ooxml
+- query: "projection fidelity, first-class tables, DOCX table import/export, Word reopen proof, browser font substitution, and AI action contract boundaries"
+
+## Agent A0: cont-QA
+
+### Role prompts
+
+- docs/agents/wave-cont-qa-role.md
+
+### Executor
+
+- profile: deep-review
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "projection-first table slice closure, Word reopen proof, compatibility truth, browser-font approximation, and bounded AI contract claims"
+
+### Prompt
+
+```text
+Primary goal:
+- Refuse closure unless the repo has bounded, machine-visible proof for first-class tables and browser-font approximation.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/reference/live-proof-waves.md.
+- Read docs/plans/current-state.md and docs/plans/waves/wave-12.md.
+
+Specific expectations:
+- block closure if supported table ownership is still indistinguishable from preserve-only package survival
+- block closure if the wave still treats preserve-only as a synonym for opaque locked rendering
+- block closure if font-substitution guidance silently mutates OOXML font intent or overclaims browser parity
+- block closure if the AI contract implies direct model-to-DOM edits or skips human confirmation
+- keep the Wave 12 slice explicit and bounded for later compare, semantics, and authoring work
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-12-cont-qa.md
+```
+
+## Agent A8: Integration Steward
+
+### Role prompts
+
+- docs/agents/wave-integration-role.md
+
+### Executor
+
+- profile: deep-review
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "reconciling table runtime proof, projection behavior, compatibility evidence, font substitution, and bounded AI contract behavior"
+
+### Prompt
+
+```text
+Primary goal:
+- Decide whether the repo now owns a bounded first-class table slice without overclaiming beyond it.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/reference/live-proof-waves.md.
+- Read docs/plans/master-plan.md, docs/plans/current-state.md, and docs/plans/waves/wave-12.md.
+
+Specific expectations:
+- block closure if table runtime, import/export, UI, and compatibility evidence disagree
+- block closure if the repo still treats supported cell edits like preserve-only structural survival
+- block closure if the repo cannot distinguish projected surfaces from opaque preserve-only surfaces
+- block closure if docs blur the Wave 12 slice with broader post-v1 compare, semantics, or autonomous AI work
+
+File ownership (only touch these paths):
+- .tmp/main-wave-launcher/integration/wave-12.md
+- .tmp/main-wave-launcher/integration/wave-12.json
+```
+
+## Agent A9: Documentation Steward
+
+### Role prompts
+
+- docs/agents/wave-documentation-role.md
+
+### Executor
+
+- profile: docs-pass
+
+### Context7
+
+- bundle: word-editor-contracts
+- query: "documenting projection fidelity, first-class tables, preserve-only boundaries, browser-font substitution, and the planned AI contract"
+
+### Prompt
+
+```text
+Primary goal:
+- Close the shared-plan docs around the Wave 12 projection, table, font, and AI-contract slice without implying broader legal-checklist ownership than the repo now has.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/reference/ooxml-compliance.md.
+- Read docs/reference/legal-checklist.md.
+- Read docs/plans/master-plan.md, docs/plans/current-state.md, and docs/plans/component-cutover-matrix.md.
+- Read the Wave 12 proof notes.
+
+File ownership (only touch these paths):
+- README.md
+- docs/roadmap.md
+- docs/plans/master-plan.md
+- docs/plans/current-state.md
+- docs/plans/migration.md
+- docs/plans/component-cutover-matrix.md
+- docs/plans/component-cutover-matrix.json
+- docs/reference/ooxml-compliance.md
+- docs/reference/legal-checklist.md
+```
+
+## Agent A1: Table Model, Runtime, And DOCX Ownership
+
+### Executor
+
+- profile: proof-owner
+- retry-policy: sticky
+
+### Context7
+
+- bundle: word-editor-ooxml
+- query: "table nodes, selection, DOCX table parsing and serialization, validator-safe roundtrip behavior, and projected-vs-opaque handling boundaries"
+
+### Skills
+
+- role-implementation
+- domain-editor-architecture
+- domain-docx-compatibility
+
+### Components
+
+- canonical-document-model
+- command-and-transaction-runtime
+- docx-import-and-normalization
+- docx-export-and-serialization
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- src/core/schema/table-schema.ts
+- src/core/selection/table-selection.ts
+- src/io/ooxml/parse-tables.ts
+- src/io/export/serialize-tables.ts
+- test/io/table-roundtrip.test.ts
+- docs/plans/waves/reviews/wave-12-table-runtime-proof.md
+
+### Proof artifacts
+
+- path: .tmp/wave-12-tables/table-runtime-roundtrip-report.json | kind: integration-report | required-for: baseline-proved
+- path: .tmp/wave-12-tables/table-session-edit-report.json | kind: integration-report | required-for: baseline-proved
+- path: .tmp/wave-12-tables/font-package-preservation-report.json | kind: validation-report | required-for: baseline-proved
+
+### Prompt
+
+```text
+Primary goal:
+- Move supported tables onto the canonical runtime path without damaging DOCX fidelity or Word reopen safety.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/reference/ooxml-compliance.md.
+- Read test/fixtures/docx/README.md.
+
+Specific expectations:
+- own typed table structures instead of preserving the supported slice as opaque blocks
+- keep unsupported structural table behaviors explicit and non-destructive
+- prefer read-only projected rendering before opaque fallback whenever mapping is safe
+- never let browser-font approximation mutate exported OOXML font intent
+
+File ownership (only touch these paths):
+- src/core/schema/table-schema.ts
+- src/core/selection/table-selection.ts
+- src/io/ooxml/parse-tables.ts
+- src/io/export/serialize-tables.ts
+- test/io/table-roundtrip.test.ts
+- docs/plans/waves/reviews/wave-12-table-runtime-proof.md
+- .tmp/wave-12-tables/
+```
+
+## Agent A2: Table UI, Review Mapping, And Font/Projection Trust Surfaces
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 50
+
+### Context7
+
+- bundle: word-editor-ui
+- query: "table editing UI, projected table visibility, comment and revision behavior in cells, and browser font-substitution diagnostics"
+
+### Skills
+
+- role-implementation
+- domain-legal-review
+- domain-docx-compatibility
+
+### Components
+
+- comments-and-anchor-mapping
+- tracked-changes-and-review-actions
+- unsupported-ooxml-preservation
+- compatibility-and-word-validation
+- react-editor-ui
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- src/ui-tailwind/editor-surface/tw-table-view.tsx
+- src/ui-tailwind/review/tw-font-substitution-panel.tsx
+- src/review/store/comment-anchors.ts
+- test/ui/table-editor.test.tsx
+- docs/plans/waves/reviews/wave-12-table-ui-proof.md
+
+### Proof artifacts
+
+- path: .tmp/wave-12-tables/table-ui-interaction-report.json | kind: integration-report | required-for: baseline-proved
+- path: .tmp/wave-12-tables/table-compatibility-report.json | kind: compatibility-report | required-for: baseline-proved
+- path: .tmp/wave-12-tables/font-substitution-report.json | kind: compatibility-report | required-for: baseline-proved
+- path: .tmp/wave-12-tables/word-reopen-notes.md | kind: proof-note | required-for: baseline-proved
+
+### Prompt
+
+```text
+Primary goal:
+- Make the supported table slice visible and trustworthy in the shared workspace while keeping browser-font substitution and projected-structure behavior honest.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read DESIGN.md.
+- Read docs/legal-feedback-architecture.md.
+
+Specific expectations:
+- table UI must reflect supported cell-local editing, read-only projected structures, and preserve-only structural limits clearly
+- comments and supported insert/delete revisions in one cell should remain mappable through edits
+- `font_substitution` cues must describe runtime truth rather than approximating Word parity claims
+
+File ownership (only touch these paths):
+- src/ui-tailwind/editor-surface/tw-table-view.tsx
+- src/ui-tailwind/review/tw-font-substitution-panel.tsx
+- src/review/store/comment-anchors.ts
+- test/ui/table-editor.test.tsx
+- docs/plans/waves/reviews/wave-12-table-ui-proof.md
+- .tmp/wave-12-tables/
+```
+
+## Agent A3: API, Runtime, And Frontend AI Action Contract
+
+### Executor
+
+- profile: proof-owner
+- retry-policy: sticky
+
+### Context7
+
+- bundle: word-editor-contracts
+- query: "host-controlled AI action interface, runtime-mediated command application, review confirmation, validation/export workflows, and legal-editor action boundaries"
+
+### Skills
+
+- role-implementation
+- domain-editor-architecture
+- domain-legal-review
+
+### Components
+
+- command-and-transaction-runtime
+- compatibility-and-word-validation
+- react-editor-ui
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- src/api/ai-actions.ts
+- src/runtime/ai-action-runtime.ts
+- src/ui-tailwind/toolbar/tw-ai-action-menu.tsx
+- test/runtime/ai-action-runtime.test.ts
+- docs/plans/waves/reviews/wave-12-ai-contract-proof.md
+
+### Proof artifacts
+
+- path: .tmp/wave-12-ai/ai-action-contract-report.json | kind: integration-report | required-for: baseline-proved
+- path: .tmp/wave-12-ai/ai-action-confirmation-report.json | kind: integration-report | required-for: baseline-proved
+- path: .tmp/wave-12-ai/ai-validate-export-report.json | kind: integration-report | required-for: baseline-proved
+
+### Prompt
+
+```text
+Primary goal:
+- Establish a host-controlled, runtime-mediated AI action contract that can support later drafting and review workflows without bypassing editor safety rules.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/reference/public-api.md.
+- Read docs/reference/ooxml-compliance.md.
+
+Specific expectations:
+- host integrations provide model access; the editor does not ship a baked-in model client
+- the runtime packages canonical context such as selections, anchors, comments, revisions, and compatibility state
+- AI results must return proposals, bounded commands, or workflow intents rather than direct DOM mutation
+- content-changing application requires explicit review confirmation
+- validate/export workflows still go through normal runtime and compatibility gates
+
+File ownership (only touch these paths):
+- src/api/ai-actions.ts
+- src/runtime/ai-action-runtime.ts
+- src/ui-tailwind/toolbar/tw-ai-action-menu.tsx
+- test/runtime/ai-action-runtime.test.ts
+- docs/plans/waves/reviews/wave-12-ai-contract-proof.md
+- .tmp/wave-12-ai/
+```
+
+File ownership (only touch these paths):
+- src/ui-tailwind/editor-surface/tw-table-view.tsx
+- src/ui-tailwind/review/tw-font-substitution-panel.tsx
+- src/review/store/comment-anchors.ts
+- test/ui/table-editor.test.tsx
+- docs/plans/waves/reviews/wave-12-table-ui-proof.md
+- .tmp/wave-12-tables/
+```