@beyondwork/docx-react-component 1.0.0

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

@@ -0,0 +1,313 @@
+# Wave 25 - XLSX Foundation: Workbook Model And SpreadsheetML Import
+
+**Commit message**: `Build: xlsx canonical workbook model and SpreadsheetML import`
+
+## Project profile
+
+- project: React Word Editor
+- new-project: no
+- oversight-mode: dark-factory
+- lane: main
+
+## Sequencing note
+
+- First xlsx wave. Reuses the shared OPC package layer from docx (src/io/opc/) and the preservation system (src/preservation/). Introduces the xlsx-specific canonical model and SpreadsheetML parser.
+
+## Reference rule
+
+- Read the xlsx architecture docs, shared platform architecture, and xlsx compliance docs before execution.
+
+## Component promotions
+
+- xlsx-canonical-workbook-model: baseline-proved
+- xlsx-import-and-normalization: baseline-proved
+
+## Context7 defaults
+
+- bundle: word-editor-testing
+- query: "SpreadsheetML parsing, OPC package, shared strings, cell values, formulas, sparse workbook model, xlsx import"
+
+## 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-25-cont-qa.md
+
+### Prompt
+
+```text
+Primary goal:
+- Verify workbook model and import produce correct canonical state from real .xlsx files.
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- docs/architecture/xlsx/canonical-workbook-model-and-commands.md
+- docs/reference/xlsx/xlsx-ooxml-compliance.md
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-25-cont-qa.md
+
+Requirements:
+1) Run `pnpm test:repo` and verify 0 failures including new xlsx tests.
+2) Verify the canonical workbook model matches the architecture doc.
+
+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-25.md
+- .tmp/main-wave-launcher/integration/wave-25.json
+
+### Prompt
+
+```text
+Primary goal:
+- Verify xlsx foundation correctly reuses shared platform without breaking 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-25.md
+- .tmp/main-wave-launcher/integration/wave-25.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 xlsx track beginning.
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- docs/plans/current-state.md
+- docs/architecture/platform/shared-openxml-editor-platform.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 track opening.
+```
+
+## Agent A1: Canonical Workbook Model
+
+### Executor
+
+- profile: implement-claude
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "sparse workbook model, sheet registry, cell storage, formulas, merges, shared strings, workbook types"
+
+### Components
+
+- xlsx-canonical-workbook-model
+
+### Deliverables
+
+- src/formats/xlsx/model/workbook.ts
+- src/formats/xlsx/model/sheet.ts
+- src/formats/xlsx/model/cell.ts
+- src/formats/xlsx/model/styles.ts
+- test/formats/xlsx/model/workbook.test.ts
+- .tmp/wave-25-xlsx-proof/model-tests.json
+
+### Proof artifacts
+
+- path: .tmp/wave-25-xlsx-proof/model-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 canonical workbook model as defined in the architecture docs.
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- docs/architecture/xlsx/canonical-workbook-model-and-commands.md
+- docs/architecture/platform/shared-openxml-editor-platform.md
+- Read src/io/opc/ for the shared OPC package layer to reuse.
+- Read src/preservation/ for the shared preservation system.
+
+File ownership (only touch these paths):
+- src/formats/xlsx/model/workbook.ts
+- src/formats/xlsx/model/sheet.ts
+- src/formats/xlsx/model/cell.ts
+- src/formats/xlsx/model/styles.ts
+- test/formats/xlsx/model/workbook.test.ts
+- .tmp/wave-25-xlsx-proof/model-tests.json
+
+Requirements:
+1) Sparse workbook model: workbook metadata, sheet registry, sparse cell storage.
+2) Cell value types: string, number, boolean, formula, error, blank.
+3) Shared string table support.
+4) Merge ranges stored as separate collection.
+5) Style references (not full style engine yet).
+6) Model matches docs/architecture/xlsx/canonical-workbook-model-and-commands.md.
+7) Tests for model creation, cell operations, and merge tracking.
+
+Validation:
+- pnpm test:repo
+
+Output:
+- Summarize the workbook model and remaining gaps.
+```
+
+## Agent A2: SpreadsheetML Import
+
+### Executor
+
+- profile: implement-claude
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "SpreadsheetML parsing, xl/workbook.xml, xl/worksheets/sheet1.xml, shared strings, OPC relationships"
+
+### Components
+
+- xlsx-import-and-normalization
+
+### Deliverables
+
+- src/formats/xlsx/io/parse-workbook.ts
+- src/formats/xlsx/io/parse-sheet.ts
+- src/formats/xlsx/io/parse-shared-strings.ts
+- src/formats/xlsx/io/parse-styles.ts
+- src/formats/xlsx/io/xlsx-session.ts
+- test/formats/xlsx/io/xlsx-import.test.ts
+- .tmp/wave-25-xlsx-proof/import-tests.json
+
+### Proof artifacts
+
+- path: .tmp/wave-25-xlsx-proof/import-tests.json | kind: proof-bundle | required-for: baseline-proved
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: none
+
+### Prompt
+
+```text
+Primary goal:
+- Build the SpreadsheetML import pipeline using the shared OPC package layer.
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- docs/reference/xlsx/xlsx-ooxml-compliance.md
+- docs/plans/xlsx/xlsx-fixture-corpus-and-certification-plan.md
+- Read src/io/opc/package-reader.ts for the shared OPC reader to reuse.
+- Read src/io/opc/docx-package.ts for how docx wraps the OPC layer.
+- Read src/preservation/ for preservation patterns to follow.
+
+File ownership (only touch these paths):
+- src/formats/xlsx/io/parse-workbook.ts
+- src/formats/xlsx/io/parse-sheet.ts
+- src/formats/xlsx/io/parse-shared-strings.ts
+- src/formats/xlsx/io/parse-styles.ts
+- src/formats/xlsx/io/xlsx-session.ts
+- test/formats/xlsx/io/xlsx-import.test.ts
+- .tmp/wave-25-xlsx-proof/import-tests.json
+
+Requirements:
+1) Reuse src/io/opc/package-reader.ts for OPC package reading.
+2) Parse xl/workbook.xml for sheet registry and metadata.
+3) Parse xl/worksheets/sheetN.xml for cell data, merges, dimensions.
+4) Parse xl/sharedStrings.xml for the shared string table.
+5) Parse xl/styles.xml for basic style references.
+6) Produce canonical workbook model from parsed data.
+7) Create minimal .xlsx test fixtures.
+8) Tests for import correctness.
+
+Validation:
+- pnpm test:repo
+
+Output:
+- Summarize import implementation and remaining gaps.
+```

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

@@ -0,0 +1,300 @@
+# Wave 26 - XLSX Export And Command Runtime
+
+**Commit message**: `Build: xlsx export, commands, and round-trip proof`
+
+## Project profile
+
+- project: React Word Editor
+- new-project: no
+- oversight-mode: dark-factory
+- lane: main
+
+## Sequencing note
+
+- Second xlsx wave. Adds SpreadsheetML export and the command/transaction runtime. Round-trip proof: import → edit → export → Excel reopen.
+
+## Reference rule
+
+- Read the xlsx architecture and compliance docs before execution.
+
+## Component promotions
+
+- xlsx-export-and-serialization: baseline-proved
+- xlsx-command-runtime: baseline-proved
+
+## Context7 defaults
+
+- bundle: word-editor-testing
+- query: "SpreadsheetML serialization, xlsx export, workbook commands, cell editing transactions, 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-26-cont-qa.md
+
+### Prompt
+
+```text
+Primary goal:
+- Verify xlsx round-trip works and command runtime is correct.
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- docs/architecture/xlsx/canonical-workbook-model-and-commands.md
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-26-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-26.md
+- .tmp/main-wave-launcher/integration/wave-26.json
+
+### Prompt
+
+```text
+Primary goal:
+- Verify xlsx export and runtime integrate cleanly with shared platform.
+
+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-26.md
+- .tmp/main-wave-launcher/integration/wave-26.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:
+- Keep shared plan docs aligned with Wave 26 xlsx export and runtime 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: SpreadsheetML Export
+
+### Executor
+
+- profile: implement-claude
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "SpreadsheetML serialization, xl/worksheets, shared strings regeneration, OPC package writing, xlsx export"
+
+### Components
+
+- xlsx-export-and-serialization
+
+### Deliverables
+
+- src/formats/xlsx/io/serialize-workbook.ts
+- src/formats/xlsx/io/serialize-sheet.ts
+- src/formats/xlsx/io/serialize-shared-strings.ts
+- src/formats/xlsx/io/serialize-styles.ts
+- test/formats/xlsx/io/xlsx-roundtrip.test.ts
+- .tmp/wave-26-xlsx-proof/export-tests.json
+
+### Proof artifacts
+
+- path: .tmp/wave-26-xlsx-proof/export-tests.json | kind: proof-bundle | required-for: baseline-proved
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: none
+
+### Prompt
+
+```text
+Primary goal:
+- Build the SpreadsheetML export pipeline and prove round-trip fidelity.
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- docs/reference/xlsx/xlsx-ooxml-compliance.md
+- Read src/io/opc/package-writer.ts for the shared OPC writer to reuse.
+- Read src/formats/xlsx/io/ for the import pipeline from Wave 25.
+- Read src/formats/xlsx/model/ for the workbook model from Wave 25.
+
+File ownership (only touch these paths):
+- src/formats/xlsx/io/serialize-workbook.ts
+- src/formats/xlsx/io/serialize-sheet.ts
+- src/formats/xlsx/io/serialize-shared-strings.ts
+- src/formats/xlsx/io/serialize-styles.ts
+- test/formats/xlsx/io/xlsx-roundtrip.test.ts
+- .tmp/wave-26-xlsx-proof/export-tests.json
+
+Requirements:
+1) Reuse src/io/opc/package-writer.ts for OPC package writing.
+2) Serialize canonical workbook model to SpreadsheetML parts.
+3) Regenerate shared strings table.
+4) Preserve unknown parts through round-trip.
+5) Round-trip tests: import .xlsx → canonical → export .xlsx → re-import → compare.
+6) All cell values, merges, and sheet structure survive round-trip.
+
+Validation:
+- pnpm test:repo
+
+Output:
+- Summarize export implementation and round-trip proof status.
+```
+
+## Agent A2: Workbook Command Runtime
+
+### Executor
+
+- profile: implement-claude
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "workbook commands, cell edit transactions, insert row, insert column, merge cells, sheet management"
+
+### Components
+
+- xlsx-command-runtime
+
+### Deliverables
+
+- src/formats/xlsx/runtime/workbook-runtime.ts
+- src/formats/xlsx/runtime/cell-commands.ts
+- src/formats/xlsx/runtime/sheet-commands.ts
+- src/formats/xlsx/runtime/workbook-transaction.ts
+- test/formats/xlsx/runtime/workbook-commands.test.ts
+- .tmp/wave-26-xlsx-proof/runtime-tests.json
+
+### Proof artifacts
+
+- path: .tmp/wave-26-xlsx-proof/runtime-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 workbook command and transaction runtime.
+
+Required context before coding:
+- docs/reference/repository-guidance.md
+- docs/research/agent-context-sources.md
+- docs/architecture/xlsx/canonical-workbook-model-and-commands.md
+- Read src/formats/xlsx/model/ for the workbook model from Wave 25.
+- Read src/core/commands/ and src/core/state/ for docx command patterns to follow.
+
+File ownership (only touch these paths):
+- src/formats/xlsx/runtime/workbook-runtime.ts
+- src/formats/xlsx/runtime/cell-commands.ts
+- src/formats/xlsx/runtime/sheet-commands.ts
+- src/formats/xlsx/runtime/workbook-transaction.ts
+- test/formats/xlsx/runtime/workbook-commands.test.ts
+- .tmp/wave-26-xlsx-proof/runtime-tests.json
+
+Requirements:
+1) Cell edit commands: setCellValue, clearCell, setCellFormula.
+2) Row/column commands: insertRow, insertColumn, deleteRow, deleteColumn.
+3) Merge commands: mergeCells, unmergeCells.
+4) Sheet commands: addSheet, removeSheet, renameSheet, reorderSheets.
+5) Transaction produces mappings for undo/redo.
+6) All commands remap anchors, merges, and references correctly.
+7) Tests for each command type.
+
+Validation:
+- pnpm test:repo
+
+Output:
+- Summarize runtime implementation and remaining gaps.
+```