@beyondwork/docx-react-component 1.0.0

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

@@ -0,0 +1,299 @@
+# Wave 27 - XLSX Grid Editor Surface And Fixture Certification
+
+**Commit message**: `Build: SpreadsheetEditor component and xlsx fixture certification`
+
+## Project profile
+
+- project: React Word Editor
+- new-project: no
+- oversight-mode: dark-factory
+- lane: main
+
+## Sequencing note
+
+- Third and final xlsx foundation wave. Delivers the embeddable SpreadsheetEditor component and fixture corpus. After this wave, xlsx has the same proof-first baseline as docx.
+
+## Reference rule
+
+- Read the xlsx frontend architecture, fixture plan, and shared platform docs before execution.
+
+## Component promotions
+
+- xlsx-grid-editor-surface: baseline-proved
+- xlsx-fixture-corpus: baseline-proved
+
+## Context7 defaults
+
+- bundle: word-editor-ui
+- query: "React spreadsheet grid, virtual scrolling, cell selection, formula bar, sheet tabs, SpreadsheetEditor component"
+
+## 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-27-cont-qa.md
+
+### Prompt
+
+```text
+Primary goal:
+- Verify SpreadsheetEditor renders, edits cells, and passes all fixtures.
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- docs/architecture/xlsx/spreadsheet-editor-frontend-architecture.md
+- docs/plans/xlsx/xlsx-fixture-corpus-and-certification-plan.md
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-27-cont-qa.md
+
+Output:
+- Summarize the cont-QA verdict.
+```
+
+## 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-27.md
+- .tmp/main-wave-launcher/integration/wave-27.json
+
+### Prompt
+
+```text
+Primary goal:
+- Verify xlsx editor integrates with shared platform and does not break docx.
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- docs/architecture/platform/shared-openxml-editor-platform.md
+- docs/plans/current-state.md
+
+File ownership (only touch these paths):
+- .tmp/main-wave-launcher/integration/wave-27.md
+- .tmp/main-wave-launcher/integration/wave-27.json
+
+Output:
+- Integration verdict 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:
+- Update shared docs to reflect xlsx as a shipped second runtime.
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- docs/plans/current-state.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 for xlsx ship.
+```
+
+## Agent A1: SpreadsheetEditor Component
+
+### Executor
+
+- profile: implement-claude
+
+### Context7
+
+- bundle: word-editor-ui
+- query: "React spreadsheet component, grid viewport, cell selection, formula bar, sheet tabs, virtual scrolling"
+
+### Components
+
+- xlsx-grid-editor-surface
+
+### Deliverables
+
+- src/formats/xlsx/ui/SpreadsheetEditor.tsx
+- src/formats/xlsx/ui/GridViewport.tsx
+- src/formats/xlsx/ui/FormulaBar.tsx
+- src/formats/xlsx/ui/SheetTabs.tsx
+- test/formats/xlsx/ui/spreadsheet-editor.test.tsx
+- .tmp/wave-27-xlsx-proof/editor-tests.json
+
+### Proof artifacts
+
+- path: .tmp/wave-27-xlsx-proof/editor-tests.json | kind: proof-bundle | required-for: baseline-proved
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: unit
+- doc-impact: none
+
+### Prompt
+
+```text
+Primary goal:
+- Build the SpreadsheetEditor React component.
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- docs/architecture/xlsx/spreadsheet-editor-frontend-architecture.md
+- Read src/formats/xlsx/runtime/ for the workbook runtime from Wave 26.
+- Read src/formats/xlsx/model/ for the workbook model from Wave 25.
+- Read src/ui/WordReviewEditor.tsx for how docx does its editor surface.
+
+File ownership (only touch these paths):
+- src/formats/xlsx/ui/SpreadsheetEditor.tsx
+- src/formats/xlsx/ui/GridViewport.tsx
+- src/formats/xlsx/ui/FormulaBar.tsx
+- src/formats/xlsx/ui/SheetTabs.tsx
+- test/formats/xlsx/ui/spreadsheet-editor.test.tsx
+- .tmp/wave-27-xlsx-proof/editor-tests.json
+
+Requirements:
+1) SpreadsheetEditor: uncontrolled component matching WordReviewEditor philosophy.
+2) GridViewport: virtualized cell rendering for large sheets.
+3) FormulaBar: display and edit cell content/formulas.
+4) SheetTabs: switch between sheets.
+5) Cell selection with keyboard navigation (arrow keys, tab, enter).
+6) Cell editing through commands dispatched to workbook runtime.
+7) Tests for rendering, selection, and editing.
+
+Validation:
+- pnpm test:repo
+
+Output:
+- Summarize editor implementation and remaining gaps.
+```
+
+## Agent A2: XLSX Fixture Corpus
+
+### Executor
+
+- profile: implement-fast
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "xlsx test fixtures, minimal workbook, formulas, merges, shared strings, cross-origin exports"
+
+### Components
+
+- xlsx-fixture-corpus
+
+### Deliverables
+
+- test/formats/xlsx/fixtures/README.md
+- test/formats/xlsx/fixtures/minimal-workbook.test.ts
+- test/formats/xlsx/fixtures/formula-sheet.test.ts
+- test/formats/xlsx/fixtures/merge-cells.test.ts
+- .tmp/wave-27-xlsx-proof/fixture-results.json
+
+### Proof artifacts
+
+- path: .tmp/wave-27-xlsx-proof/fixture-results.json | kind: proof-bundle | required-for: baseline-proved
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: none
+
+### Prompt
+
+```text
+Primary goal:
+- Create the xlsx fixture corpus and certification tests.
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- docs/plans/xlsx/xlsx-fixture-corpus-and-certification-plan.md
+- Read src/formats/xlsx/io/ for import/export pipeline.
+- Read src/formats/xlsx/model/ for canonical model.
+
+File ownership (only touch these paths):
+- test/formats/xlsx/fixtures/README.md
+- test/formats/xlsx/fixtures/minimal-workbook.test.ts
+- test/formats/xlsx/fixtures/formula-sheet.test.ts
+- test/formats/xlsx/fixtures/merge-cells.test.ts
+- .tmp/wave-27-xlsx-proof/fixture-results.json
+
+Requirements:
+1) Release-gate fixtures: minimal workbook, cell types, shared strings, formulas, merges.
+2) Each fixture: import → validate canonical → export → re-import → compare.
+3) Preservation test: unknown parts survive round-trip.
+4) Malformed input test: graceful failure.
+5) All tests pass with `pnpm test:repo`.
+
+Validation:
+- pnpm test:repo
+
+Output:
+- Summarize fixture coverage and remaining gaps.
+```

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

@@ -0,0 +1,368 @@
+# Wave 28 - Editor Feature Parity
+
+**Commit message**: `Build: rich formatting, prosemirror-tables, image insert, search, hook API, CLI`
+
+## Project profile
+
+- project: React Word Editor
+- new-project: no
+- oversight-mode: dark-factory
+- lane: main
+
+## Sequencing note
+
+- Adopts proven patterns from an internal reference implementation.
+
+## Reference rule
+
+- Read the roadmap and reference implementation before execution.
+
+## Component promotions
+
+- editor-feature-parity: baseline-proved
+
+## Context7 defaults
+
+- bundle: word-editor-testing
+- query: "prosemirror-tables, ProseMirror marks, font formatting, image insertion, search plugin, React imperative handle, headless CLI"
+
+## 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-28-cont-qa.md
+
+### Prompt
+
+```text
+Primary goal:
+- Verify all 6 feature areas work and all tests pass.
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- docs/roadmap.md
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-28-cont-qa.md
+
+Output:
+- Summarize the cont-QA verdict.
+```
+
+## 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-28.md
+- .tmp/main-wave-launcher/integration/wave-28.json
+
+### Prompt
+
+```text
+Primary goal:
+- Verify new features integrate cleanly with existing runtime and preservation.
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- docs/plans/current-state.md
+
+File ownership (only touch these paths):
+- .tmp/main-wave-launcher/integration/wave-28.md
+- .tmp/main-wave-launcher/integration/wave-28.json
+
+Output:
+- Integration verdict 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:
+- Update shared plan docs to reflect feature parity work.
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- docs/plans/current-state.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.
+```
+
+## Agent A1: prosemirror-tables And Rich Formatting Marks
+
+### Executor
+
+- profile: implement-claude
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "prosemirror-tables plugin, tableEditing, ProseMirror mark specs, font family, font size, text color, highlight, superscript, subscript, alignment"
+
+### Components
+
+- editor-feature-parity
+
+### Deliverables
+
+- src/ui-tailwind/editor-surface/pm-schema.ts
+- src/runtime/table-commands.ts
+- src/core/commands/formatting-commands.ts
+- src/ui-tailwind/editor-surface/pm-command-bridge.ts
+- test/core/formatting-commands.test.ts
+- .tmp/wave-28-parity-proof/tables-formatting.json
+
+### Proof artifacts
+
+- path: .tmp/wave-28-parity-proof/tables-formatting.json | kind: proof-bundle | required-for: baseline-proved
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: unit
+- doc-impact: none
+
+### Prompt
+
+```text
+Primary goal:
+- Replace custom table commands with prosemirror-tables and add rich formatting marks.
+
+Reference: bwllaming/code repo (joakim/docx branch), src/ts/packages/docx-editor/.
+Access schema: gh api repos/bwllaming/code/contents/src/ts/packages/docx-editor/src/schema/index.ts?ref=joakim/docx --jq '.content' | base64 -d
+Access formatting: gh api repos/bwllaming/code/contents/src/ts/packages/docx-editor/src/plugins/formatting.ts?ref=joakim/docx --jq '.content' | base64 -d
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- Read src/ui-tailwind/editor-surface/pm-schema.ts and src/runtime/table-commands.ts.
+
+File ownership (only touch these paths):
+- src/ui-tailwind/editor-surface/pm-schema.ts
+- src/runtime/table-commands.ts
+- src/core/commands/formatting-commands.ts
+- src/ui-tailwind/editor-surface/pm-command-bridge.ts
+- test/core/formatting-commands.test.ts
+- .tmp/wave-28-parity-proof/tables-formatting.json
+- package.json
+
+Requirements:
+1) Add prosemirror-tables dependency, use tableEditing() plugin.
+2) Replace custom table commands with prosemirror-tables equivalents.
+3) Add marks: font_family, font_size, text_color, highlight, superscript, subscript, small_caps, all_caps.
+4) Add paragraph alignment attr (left/center/right/justify).
+5) Toggle/set commands for each. Tests for all.
+
+Validation:
+- pnpm test:repo
+
+Output:
+- Summarize implementation and gaps.
+```
+
+## Agent A2: Image Insertion And Search Plugin
+
+### Executor
+
+- profile: implement-claude
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "ProseMirror image node, insertImage command, search plugin, decorations, highlights"
+
+### Components
+
+- editor-feature-parity
+
+### Deliverables
+
+- src/core/commands/image-commands.ts
+- src/ui-tailwind/editor-surface/search-plugin.ts
+- test/core/image-commands.test.ts
+- test/ui-tailwind/search-plugin.test.ts
+- .tmp/wave-28-parity-proof/image-search.json
+
+### Proof artifacts
+
+- path: .tmp/wave-28-parity-proof/image-search.json | kind: proof-bundle | required-for: baseline-proved
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: unit
+- doc-impact: none
+
+### Prompt
+
+```text
+Primary goal:
+- Add image insertion and a search/highlight plugin.
+
+Reference: bwllaming/code (joakim/docx branch), src/plugins/search.ts and src/plugins/formatting.ts.
+Access: gh api repos/bwllaming/code/contents/src/ts/packages/docx-editor/src/plugins/search.ts?ref=joakim/docx --jq '.content' | base64 -d
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- Read src/ui-tailwind/editor-surface/pm-schema.ts and src/model/canonical-document.ts.
+
+File ownership (only touch these paths):
+- src/core/commands/image-commands.ts
+- src/ui-tailwind/editor-surface/search-plugin.ts
+- test/core/image-commands.test.ts
+- test/ui-tailwind/search-plugin.test.ts
+- .tmp/wave-28-parity-proof/image-search.json
+
+Requirements:
+1) insertImage(data, mimeType, width?, height?) command.
+2) Search plugin with performSearch, clearSearch, decorations.
+3) Options: case sensitive, regex, highlight color.
+4) Tests for both.
+
+Validation:
+- pnpm test:repo
+
+Output:
+- Summarize implementation and gaps.
+```
+
+## Agent A3: useDocxEditor Hook And Headless CLI
+
+### Executor
+
+- profile: implement-claude
+
+### Context7
+
+- bundle: word-editor-contracts
+- query: "React useImperativeHandle, imperative editor API, Node.js CLI, headless docx processing"
+
+### Components
+
+- editor-feature-parity
+
+### Deliverables
+
+- src/api/use-docx-editor.ts
+- src/cli/index.ts
+- src/cli/commands.ts
+- test/api/use-docx-editor.test.ts
+- test/cli/cli.test.ts
+- .tmp/wave-28-parity-proof/hook-cli.json
+
+### Proof artifacts
+
+- path: .tmp/wave-28-parity-proof/hook-cli.json | kind: proof-bundle | required-for: baseline-proved
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: unit
+- doc-impact: owned
+
+### Prompt
+
+```text
+Primary goal:
+- Create useDocxEditor() hook and headless CLI.
+
+Reference: bwllaming/code (joakim/docx branch).
+Access hook: gh api repos/bwllaming/code/contents/src/ts/packages/docx-editor/src/component/use-docx-editor.ts?ref=joakim/docx --jq '.content' | base64 -d
+Access CLI: gh api repos/bwllaming/code/contents/src/ts/packages/docx-editor/src/cli/index.ts?ref=joakim/docx --jq '.content' | base64 -d
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- Read src/ui/WordReviewEditor.tsx and src/api/public-types.ts.
+
+File ownership (only touch these paths):
+- src/api/use-docx-editor.ts
+- src/cli/index.ts
+- src/cli/commands.ts
+- test/api/use-docx-editor.test.ts
+- test/cli/cli.test.ts
+- .tmp/wave-28-parity-proof/hook-cli.json
+
+Requirements:
+1) useDocxEditor() hook: getDocx, getComments, getRevisions, addComment, removeComment, focus, isDirty, getFormatState, all formatting toggles, table commands, search, acceptRevision, rejectRevision, focusPosition.
+2) onReady callback pattern.
+3) CLI: docx info, docx convert (extract text), docx validate.
+4) CLI tests enforce API parity with hook.
+5) Export from package.json.
+
+Validation:
+- pnpm test:repo
+
+Output:
+- Summarize implementation and gaps.
+```