@beyondwork/docx-react-component 1.0.0

package/docs/plans/waves/wave-19.md

@@ -0,0 +1,341 @@
+# Wave 19 - CI Green And Test Infrastructure
+
+**Commit message**: `Build: CI green with full test suite passing`
+
+## Project profile
+
+- project: React Word Editor
+- new-project: no
+- oversight-mode: dark-factory
+- lane: main
+
+## Sequencing note
+
+- This wave corresponds to Phase 1 of the shipping roadmap. It is a prerequisite for all subsequent feature waves.
+
+## Reference rule
+
+- Read the roadmap, current-state, and master-plan before execution.
+
+## Component promotions
+
+- openxml-sdk-validator-service: pilot-live
+
+## Context7 defaults
+
+- bundle: word-editor-testing
+- query: "React 19 testing with jsdom, ProseMirror test setup, Node test runner with tsx, CI configuration"
+
+## Agent A0: cont-QA
+
+### Role prompts
+
+- docs/agents/wave-cont-qa-role.md
+
+### Executor
+
+- profile: deep-review
+
+### Context7
+
+- bundle: none
+- query: "Architecture evaluation only; repository docs remain canonical"
+
+### Deliverables
+
+- docs/plans/waves/reviews/wave-19-cont-qa.md
+
+### Prompt
+
+```text
+Primary goal:
+- Verify that all tests pass and CI is properly configured.
+
+Collaboration notes:
+- Collect explicit verdicts from the implementation-facing agents plus A8 and A9 before closing the wave.
+- Do not publish PASS unless the evidence, documentation closure, and integration summary are all coherent.
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- docs/plans/current-state.md
+- docs/plans/master-plan.md
+- docs/roadmap.md
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-19-cont-qa.md
+
+Requirements:
+1) Run `pnpm test:repo` and verify 0 failures across all 155+ tests.
+2) Verify .github/workflows/ci.yml is correct and would run tests on PR.
+3) Record any blocker that later waves must not silently assume away.
+
+Validation:
+- Re-read the changed reports and end the cont-QA report with `Verdict: PASS`, `Verdict: CONCERNS`, or `Verdict: BLOCKED`.
+
+Output:
+- Summarize the cont-QA verdict and the top unresolved cross-cutting risks.
+```
+
+## Agent A8: Integration Steward
+
+### Role prompts
+
+- docs/agents/wave-integration-role.md
+
+### Executor
+
+- profile: deep-review
+
+### Context7
+
+- bundle: none
+- query: "Integration synthesis only; repository docs remain canonical"
+
+### Capabilities
+
+- integration
+- docs-shared-plan
+
+### Deliverables
+
+- .tmp/main-wave-launcher/integration/wave-19.md
+- .tmp/main-wave-launcher/integration/wave-19.json
+
+### Prompt
+
+```text
+Primary goal:
+- Synthesize the final Wave 19 state before documentation and cont-QA closure.
+
+Collaboration notes:
+- Re-read the message board, compiled inboxes, and latest artifacts before final output.
+- Treat contradictions, missing proof, or stale shared-plan assumptions as integration failures.
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- docs/plans/current-state.md
+- docs/plans/master-plan.md
+- docs/roadmap.md
+
+File ownership (only touch these paths):
+- .tmp/main-wave-launcher/integration/wave-19.md
+- .tmp/main-wave-launcher/integration/wave-19.json
+
+Requirements:
+1) Produce a closure-ready summary of claims, conflicts, blockers, and remaining follow-up owners.
+2) Decide whether the wave is `ready-for-doc-closure` or `needs-more-work`.
+
+Validation:
+- Re-read the generated integration artifact and the latest changed proof docs before final output.
+
+Output:
+- Summarize the integration verdict, blockers, and exact closure recommendation.
+```
+
+## Agent A9: Documentation Steward
+
+### Role prompts
+
+- docs/agents/wave-documentation-role.md
+
+### Executor
+
+- profile: docs-pass
+
+### Context7
+
+- bundle: none
+- query: "Shared plan documentation only; repository docs remain canonical"
+
+### Deliverables
+
+- docs/roadmap.md
+- docs/plans/current-state.md
+- docs/plans/master-plan.md
+- docs/plans/migration.md
+- docs/plans/component-cutover-matrix.md
+- docs/plans/component-cutover-matrix.json
+
+### Prompt
+
+```text
+Primary goal:
+- Keep shared plan docs aligned with Wave 19 end-to-end.
+
+Collaboration notes:
+- Coordinate with the implementation-facing agents and A8 before changing shared plan docs.
+- Treat implementation-owned proof docs as owned deliverables; keep shared-plan deltas in your files.
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- docs/plans/current-state.md
+- docs/plans/master-plan.md
+- docs/roadmap.md
+
+File ownership (only touch these paths):
+- docs/roadmap.md
+- docs/plans/current-state.md
+- docs/plans/master-plan.md
+- docs/plans/migration.md
+- docs/plans/component-cutover-matrix.md
+- docs/plans/component-cutover-matrix.json
+
+Requirements:
+1) Track which wave outcomes change shared status, sequencing, ownership, or proof expectations.
+2) Leave an exact-scope closure note when no shared-plan update is required.
+
+Validation:
+- Manual review of shared plan docs against the landed wave deliverables.
+
+Output:
+- Summarize the shared doc updates, deliberate no-change decisions, and remaining follow-ups.
+```
+
+## Agent A1: Fix UI Test Environment
+
+### Executor
+
+- profile: implement-claude
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "React 19 testing with jsdom, Node test runner with tsx, renderToStaticMarkup hooks, ProseMirror test utilities"
+
+### Components
+
+- openxml-sdk-validator-service
+
+### Deliverables
+
+- test/ui/reduced-motion-toggle.test.tsx
+- test/ui/word-review-editor.test.tsx
+- test/ui/word-review-editor.interaction.test.tsx
+- test/ui/word-review-editor.imported-scenarios.test.tsx
+- test/helpers/dom-setup.ts
+
+### Proof artifacts
+
+- path: .tmp/wave-19-ci-proof/test-results.json | kind: proof-bundle | required-for: pilot-live
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: unit
+- doc-impact: none
+
+### Prompt
+
+```text
+Primary goal:
+- Make all 4 failing UI test files pass under `pnpm exec tsx --test`.
+
+Current failure analysis:
+- The tests use renderToStaticMarkup from react-dom/server and jsdom for DOM assertions.
+- React 19 hooks fail in SSR context (useState returns null).
+- Radix UI components may need mocking or a proper React test renderer setup.
+- react and react-dom are now available as devDependencies.
+
+Collaboration notes:
+- Re-read the wave message board before major decisions, before validation, and before final output.
+- Notify Agent A0 when your evidence changes the closure picture.
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- Read the 4 failing test files under test/ui/.
+- Read src/ui/WordReviewEditor.tsx to understand the component being tested.
+- Read package.json for available test dependencies.
+- Read docs/roadmap.md Phase 1 requirements.
+
+File ownership (only touch these paths):
+- test/ui/reduced-motion-toggle.test.tsx
+- test/ui/word-review-editor.test.tsx
+- test/ui/word-review-editor.interaction.test.tsx
+- test/ui/word-review-editor.imported-scenarios.test.tsx
+- test/helpers/dom-setup.ts
+- package.json
+- .tmp/wave-19-ci-proof/test-results.json
+
+Requirements:
+1) If the tests use renderToStaticMarkup with hooks-based components, switch to a proper React testing approach (createRoot + act, or lightweight mocking).
+2) Do NOT add heavy test frameworks (jest, vitest). Stay with Node built-in test runner + tsx.
+3) Minimal changes to make tests pass. Do not rewrite tests that already pass.
+4) Ensure `pnpm test:repo` exits 0 with all tests passing.
+
+Validation:
+- pnpm test:repo
+
+Output:
+- Summarize the landed implementation, proof status, and exact follow-up owners.
+```
+
+## Agent A2: CI Pipeline And Badge
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 30
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "GitHub Actions CI workflow, pnpm setup, Node test runner in CI"
+
+### Components
+
+- openxml-sdk-validator-service
+
+### Deliverables
+
+- .github/workflows/ci.yml
+- README.md
+
+### Proof artifacts
+
+- path: .tmp/wave-19-ci-proof/ci-config-review.md | kind: proof-note | required-for: pilot-live
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: unit
+- doc-impact: owned
+
+### Prompt
+
+```text
+Primary goal:
+- Ensure the GitHub Actions CI workflow runs tests and gates PRs.
+
+Collaboration notes:
+- Re-read the wave message board before major decisions, before validation, and before final output.
+- Notify Agent A0 when your evidence changes the closure picture.
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- Read .github/workflows/ci.yml.
+- Read package.json scripts section.
+- Read README.md.
+
+File ownership (only touch these paths):
+- .github/workflows/ci.yml
+- README.md
+- .tmp/wave-19-ci-proof/ci-config-review.md
+
+Requirements:
+1) CI workflow: checkout, pnpm setup, install, `pnpm test:repo`.
+2) Add CI badge to top of README.md.
+3) The workflow should run on push to main and on PRs to main.
+
+Validation:
+- Manual review of .github/workflows/ci.yml
+
+Output:
+- Summarize the landed implementation, proof status, and exact follow-up owners.
+```

package/docs/plans/waves/wave-20.md

@@ -0,0 +1,308 @@
+# Wave 20 - First-Class Tables
+
+**Commit message**: `Build: first-class table editing support`
+
+## Project profile
+
+- project: React Word Editor
+- new-project: no
+- oversight-mode: dark-factory
+- lane: main
+
+## Sequencing note
+
+- Phase 2 of the shipping roadmap. Table model types, parser, and serializer are already landed. This wave completes ProseMirror rendering, editing commands, and round-trip fixtures.
+
+## Reference rule
+
+- Read the roadmap, current-state, and master-plan before execution.
+
+## Component promotions
+
+- table-editing: baseline-proved
+
+## Context7 defaults
+
+- bundle: word-editor-testing
+- query: "ProseMirror table editing, OOXML w:tbl model, merged cells gridSpan verticalMerge, table round-trip fidelity"
+
+## Agent A0: cont-QA
+
+### Role prompts
+
+- docs/agents/wave-cont-qa-role.md
+
+### Executor
+
+- profile: deep-review
+
+### Context7
+
+- bundle: none
+- query: "Architecture evaluation only; repository docs remain canonical"
+
+### Deliverables
+
+- docs/plans/waves/reviews/wave-20-cont-qa.md
+
+### Prompt
+
+```text
+Primary goal:
+- Verify table editing works end-to-end and all tests pass.
+
+Collaboration notes:
+- Collect verdicts from A1, A2, A8, A9 before closing.
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- docs/roadmap.md
+- docs/plans/current-state.md
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-20-cont-qa.md
+
+Requirements:
+1) Run `pnpm test:repo` and verify 0 failures with all new table tests included.
+2) Verify table round-trip: docx import → edit → export → reopen without repair.
+
+Validation:
+- End the cont-QA report with `Verdict: PASS`, `Verdict: CONCERNS`, or `Verdict: BLOCKED`.
+
+Output:
+- Summarize the cont-QA verdict and blocking issues.
+```
+
+## Agent A8: Integration Steward
+
+### Role prompts
+
+- docs/agents/wave-integration-role.md
+
+### Executor
+
+- profile: deep-review
+
+### Context7
+
+- bundle: none
+- query: "Integration synthesis only; repository docs remain canonical"
+
+### Capabilities
+
+- integration
+- docs-shared-plan
+
+### Deliverables
+
+- .tmp/main-wave-launcher/integration/wave-20.md
+- .tmp/main-wave-launcher/integration/wave-20.json
+
+### Prompt
+
+```text
+Primary goal:
+- Synthesize the final Wave 20 state before documentation and cont-QA closure.
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- docs/plans/current-state.md
+- docs/plans/master-plan.md
+- docs/roadmap.md
+
+File ownership (only touch these paths):
+- .tmp/main-wave-launcher/integration/wave-20.md
+- .tmp/main-wave-launcher/integration/wave-20.json
+
+Output:
+- Summarize the integration verdict, blockers, and closure recommendation.
+```
+
+## Agent A9: Documentation Steward
+
+### Role prompts
+
+- docs/agents/wave-documentation-role.md
+
+### Executor
+
+- profile: docs-pass
+
+### Context7
+
+- bundle: none
+- query: "Shared plan documentation only; repository docs remain canonical"
+
+### Deliverables
+
+- docs/roadmap.md
+- docs/plans/current-state.md
+- docs/plans/master-plan.md
+- docs/plans/migration.md
+- docs/plans/component-cutover-matrix.md
+- docs/plans/component-cutover-matrix.json
+
+### Prompt
+
+```text
+Primary goal:
+- Keep shared plan docs aligned with Wave 20 table editing work.
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- docs/plans/current-state.md
+- docs/plans/master-plan.md
+- docs/roadmap.md
+
+File ownership (only touch these paths):
+- docs/roadmap.md
+- docs/plans/current-state.md
+- docs/plans/master-plan.md
+- docs/plans/migration.md
+- docs/plans/component-cutover-matrix.md
+- docs/plans/component-cutover-matrix.json
+
+Output:
+- Summarize shared doc updates and remaining follow-ups.
+```
+
+## Agent A1: ProseMirror Table Schema And Editing
+
+### Executor
+
+- profile: implement-claude
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "ProseMirror table schema, table node views, cell editing, merged cells, table commands"
+
+### Components
+
+- table-editing
+
+### Deliverables
+
+- src/runtime/table-schema.ts
+- src/runtime/table-commands.ts
+- src/ui-tailwind/editor-surface/tw-table-node-view.tsx
+- test/runtime/table-schema.test.ts
+- test/runtime/table-commands.test.ts
+- .tmp/wave-20-table-proof/test-summary.json
+
+### Proof artifacts
+
+- path: .tmp/wave-20-table-proof/test-summary.json | kind: proof-bundle | required-for: baseline-proved
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: unit
+- doc-impact: none
+
+### Prompt
+
+```text
+Primary goal:
+- Complete ProseMirror table schema, node views, and editing commands.
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- Read src/runtime/table-schema.ts (existing table types).
+- Read src/model/canonical-document.ts (TableNode, TableRowNode, TableCellNode).
+- Read src/io/ooxml/parse-tables.ts and src/io/export/serialize-tables.ts.
+- Read src/ui-tailwind/editor-surface/ for ProseMirror integration patterns.
+- Read docs/roadmap.md Phase 2 requirements.
+
+File ownership (only touch these paths):
+- src/runtime/table-schema.ts
+- src/runtime/table-commands.ts
+- src/ui-tailwind/editor-surface/tw-table-node-view.tsx
+- test/runtime/table-schema.test.ts
+- test/runtime/table-commands.test.ts
+- .tmp/wave-20-table-proof/test-summary.json
+
+Requirements:
+1) ProseMirror schema nodes: table, table_row, table_cell, table_header_cell.
+2) Table node view rendering a proper HTML table.
+3) Merged cell support (colspan/rowspan from gridSpan/verticalMerge).
+4) Editing commands: addRowBefore, addRowAfter, addColumnBefore, addColumnAfter, deleteRow, deleteColumn.
+5) Cell content: paragraphs inside cells.
+6) Tests for schema and commands.
+
+Validation:
+- pnpm test:repo
+
+Output:
+- Summarize landed implementation and remaining gaps.
+```
+
+## Agent A2: Table Round-Trip Fixtures
+
+### Executor
+
+- profile: implement-fast
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "OOXML table round-trip, fixture validation, merged cells, table export"
+
+### Components
+
+- table-editing
+
+### Deliverables
+
+- test/io/table-roundtrip.test.ts
+- src/io/ooxml/parse-tables.ts
+- src/io/export/serialize-tables.ts
+- .tmp/wave-20-table-proof/roundtrip-summary.json
+
+### Proof artifacts
+
+- path: .tmp/wave-20-table-proof/roundtrip-summary.json | kind: proof-bundle | required-for: baseline-proved
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: none
+
+### Prompt
+
+```text
+Primary goal:
+- Ensure tables survive complete round-trip with full fidelity.
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- Read src/io/ooxml/parse-tables.ts and src/io/export/serialize-tables.ts.
+- Read existing test/io/ for fixture and round-trip patterns.
+- Read docs/roadmap.md Phase 2 exit criteria.
+
+File ownership (only touch these paths):
+- test/io/table-roundtrip.test.ts
+- src/io/ooxml/parse-tables.ts
+- src/io/export/serialize-tables.ts
+- .tmp/wave-20-table-proof/roundtrip-summary.json
+
+Requirements:
+1) Integration tests: parse table → canonical model → serialize → validate.
+2) Merged cell topology preserved through round-trip.
+3) Cell formatting preserved through round-trip.
+4) Tests pass with `pnpm test:repo`.
+
+Validation:
+- pnpm test:repo
+
+Output:
+- Summarize round-trip proof and remaining gaps.
+```