@beyondwork/docx-react-component 1.0.0

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

@@ -0,0 +1,438 @@
+# Wave 2 - Runtime Skeleton, Package Substrate, And Shell
+
+**Commit message**: `Build: land canonical runtime and editor shell substrate`
+
+## Component promotions
+
+- canonical-document-model: baseline-proved
+- command-and-transaction-runtime: baseline-proved
+- docx-import-and-normalization: baseline-proved
+- docx-export-and-serialization: baseline-proved
+- react-editor-ui: baseline-proved
+
+## Context7 defaults
+
+- bundle: word-editor-runtime
+- query: "ProseMirror state, transaction application, runtime orchestration, and React host integration for a schema-first editor"
+
+## Agent A0: cont-QA
+
+### Role prompts
+
+- docs/agents/wave-cont-qa-role.md
+
+### Executor
+
+- profile: deep-review
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "repo-landed maturity checks, ownership boundaries, and deterministic unit-proof expectations"
+
+### Prompt
+
+```text
+Primary goal:
+- Refuse closure if Wave 2 claims more than a repo-landed substrate with deterministic tests.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/reference/wave-planning-lessons.md.
+- Read docs/plans/master-plan.md, docs/plans/current-state.md, and docs/plans/component-cutover-matrix.json.
+- Read docs/plans/waves/wave-1.md.
+- Read docs/plans/waves/specs/wave-1-review-and-ui-contracts.md.
+
+Specific expectations:
+- fail if repo-landed claims depend on manual testing only
+- fail if the runtime and UI still bypass a single dispatch boundary
+- fail if the runtime-owned render contract drifts from the Wave 1 freeze
+- fail if the package IO layer rewrites unsupported parts by default
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-2-cont-qa.md
+```
+
+## Agent A8: Integration Steward
+
+### Role prompts
+
+- docs/agents/wave-integration-role.md
+
+### Executor
+
+- profile: deep-review
+
+### Context7
+
+- bundle: word-editor-runtime
+- query: "integration of state, runtime, IO, and UI shell layers"
+
+### Prompt
+
+```text
+Primary goal:
+- Reconcile the landed substrate so later feature waves build on one runtime rather than parallel ad hoc shells.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/reference/wave-planning-lessons.md.
+- Read docs/plans/master-plan.md, docs/plans/current-state.md, and docs/plans/waves/wave-1.md.
+- Read docs/plans/component-cutover-matrix.md and docs/plans/component-cutover-matrix.json.
+- Read docs/plans/waves/specs/wave-1-review-and-ui-contracts.md.
+
+Specific expectations:
+- call out any second source of truth for document state
+- call out any importer/exporter code path that bypasses canonical snapshots
+- treat RuntimeRenderSnapshot as the authoritative runtime/UI contract and treat narrower UI selectors as derived views, not a second runtime truth
+- reject closure if the public component shell and runtime event model diverge
+
+File ownership (only touch these paths):
+- .tmp/main-wave-launcher/integration/wave-2.md
+- .tmp/main-wave-launcher/integration/wave-2.json
+```
+
+## Agent A9: Documentation Steward
+
+### Role prompts
+
+- docs/agents/wave-documentation-role.md
+
+### Executor
+
+- profile: docs-pass
+
+### Context7
+
+- bundle: word-editor-contracts
+- query: "shared-plan updates for a repo-landed runtime, IO substrate, and editor shell"
+
+### Prompt
+
+```text
+Primary goal:
+- Update shared-plan docs to reflect the landed substrate and the exact proof gap that remains for baseline waves.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/reference/wave-planning-lessons.md.
+- Read docs/plans/master-plan.md, docs/plans/current-state.md, docs/plans/migration.md, and docs/plans/component-cutover-matrix.md.
+- Read docs/plans/waves/wave-2.md.
+
+File ownership (only touch these paths):
+- 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
+```
+
+## Agent A1: Canonical Model And Runtime Envelope
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 45
+
+### Context7
+
+- bundle: word-editor-contracts
+- query: "strict TypeScript data models, canonical snapshots, and immutable document envelopes for structured editors"
+
+### Skills
+
+- role-implementation
+- domain-editor-architecture
+
+### Components
+
+- canonical-document-model
+- command-and-transaction-runtime
+
+### Exit contract
+
+- completion: integrated
+- durability: durable
+- proof: unit
+- doc-impact: owned
+
+### Deliverables
+
+- src/model/cds-1.0.0.ts
+- src/model/canonical-document.ts
+- src/model/snapshot.ts
+- test/model/canonical-document.test.ts
+
+### Prompt
+
+```text
+Primary goal:
+- Land the canonical document envelope and snapshot serialization substrate exactly as frozen in Wave 1.
+
+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/plans/waves/wave-1.md.
+- Read docs/plans/waves/specs/wave-1-runtime-contracts.md.
+
+Specific expectations:
+- keep snapshot serialization deterministic
+- validate schemaVersion and stable identifier domains
+- do not introduce view-state or DOM-derived fields into the canonical envelope
+
+File ownership (only touch these paths):
+- src/model/cds-1.0.0.ts
+- src/model/canonical-document.ts
+- src/model/snapshot.ts
+- test/model/canonical-document.test.ts
+```
+
+## Agent A2: Dispatch, Mapping, And Runtime Core
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 45
+
+### Context7
+
+- bundle: word-editor-runtime
+- query: "editor state, transaction steps, mappings, selections, and runtime subscription models"
+
+### Skills
+
+- role-implementation
+- domain-editor-architecture
+
+### Components
+
+- command-and-transaction-runtime
+- canonical-document-model
+
+### Exit contract
+
+- completion: integrated
+- durability: durable
+- proof: unit
+- doc-impact: owned
+
+### Deliverables
+
+- src/core/state/editor-state.ts
+- src/core/commands/index.ts
+- src/core/selection/mapping.ts
+- src/runtime/document-runtime.ts
+- test/core/mapping.test.ts
+
+### Prompt
+
+```text
+Primary goal:
+- Land the command-dispatch and mapping substrate that every later editing feature will reuse.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/plans/waves/specs/wave-1-component-boundaries.md.
+- Read docs/plans/waves/specs/wave-1-runtime-contracts.md.
+
+Specific expectations:
+- keep one dispatch path for all mutations
+- make mapping output explicit enough for comments, revisions, and opaque fragments to reuse later
+- expose subscriptions through runtime events rather than direct store mutation
+
+File ownership (only touch these paths):
+- src/core/state/editor-state.ts
+- src/core/commands/index.ts
+- src/core/selection/mapping.ts
+- src/runtime/document-runtime.ts
+- test/core/mapping.test.ts
+```
+
+## Agent A3: OPC And OOXML Substrate
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 45
+
+### Context7
+
+- bundle: word-editor-ooxml
+- query: "OPC package manifests, content types, relationships, and document import/export session scaffolding"
+
+### Skills
+
+- role-implementation
+- domain-docx-compatibility
+
+### Components
+
+- docx-import-and-normalization
+- docx-export-and-serialization
+
+### Exit contract
+
+- completion: integrated
+- durability: durable
+- proof: unit
+- doc-impact: owned
+
+### Deliverables
+
+- src/io/opc/package-reader.ts
+- src/io/opc/package-writer.ts
+- src/io/ooxml/part-manifest.ts
+- src/io/export/export-session.ts
+- test/io/package-reader.test.ts
+
+### Prompt
+
+```text
+Primary goal:
+- Land the package-first document IO substrate without yet claiming feature-complete WordprocessingML support.
+
+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/plans/waves/specs/wave-1-ooxml-contracts.md.
+
+Specific expectations:
+- keep untouched parts and relationship manifests visible in the model
+- regenerate only editor-owned output paths
+- block any hidden normalization that would already lose unknown content
+
+File ownership (only touch these paths):
+- src/io/opc/package-reader.ts
+- src/io/opc/package-writer.ts
+- src/io/ooxml/part-manifest.ts
+- src/io/export/export-session.ts
+- test/io/package-reader.test.ts
+```
+
+## Agent A4: Public Component Shell
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 45
+
+### Context7
+
+- bundle: word-editor-ui
+- query: "React refs, uncontrolled editors, shell composition, and compact document-surface-first UI layout"
+
+### Skills
+
+- role-implementation
+- domain-editor-architecture
+- domain-legal-review
+
+### Components
+
+- react-editor-ui
+- command-and-transaction-runtime
+
+### Exit contract
+
+- completion: integrated
+- durability: durable
+- proof: unit
+- doc-impact: owned
+
+### Deliverables
+
+- src/api/public-types.ts
+- src/ui/WordReviewEditor.tsx
+- src/ui/editor-surface/editor-surface.tsx
+- test/ui/word-review-editor.test.tsx
+
+### Prompt
+
+```text
+Primary goal:
+- Land the public React shell that binds to the runtime without making React the source of truth.
+
+Required context before coding:
+- Read DESIGN.md and docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/reference/public-api.md.
+- Read docs/plans/waves/specs/wave-1-review-and-ui-contracts.md.
+
+Specific expectations:
+- keep the canvas central and the chrome secondary
+- preserve the uncontrolled-by-default contract
+- expose imperative ref operations through the runtime, not direct view mutation
+
+File ownership (only touch these paths):
+- src/api/public-types.ts
+- src/ui/WordReviewEditor.tsx
+- src/ui/editor-surface/editor-surface.tsx
+- test/ui/word-review-editor.test.tsx
+```
+
+## Agent A5: Compatibility Report Skeleton
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 35
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "typed compatibility reports, fixture manifests, and unit-friendly validation surface design"
+
+### Skills
+
+- role-implementation
+- domain-docx-compatibility
+
+### Components
+
+- docx-import-and-normalization
+- docx-export-and-serialization
+
+### Exit contract
+
+- completion: contract
+- durability: durable
+- proof: unit
+- doc-impact: owned
+
+### Deliverables
+
+- src/validation/compatibility-report.ts
+- src/validation/diagnostics.ts
+- test/validation/compatibility-report.test.ts
+- test/fixtures/docx/fixtures.manifest.json
+
+### Prompt
+
+```text
+Primary goal:
+- Land the typed compatibility-report substrate and fixture manifest that later proof waves will extend.
+
+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/research/docx-react-component/document_compatibility_and_testing_spec.md.
+
+Specific expectations:
+- keep feature classes explicit and closed
+- keep fixture metadata machine-readable
+- do not overclaim baseline validation before the proof artifacts exist
+
+File ownership (only touch these paths):
+- src/validation/compatibility-report.ts
+- src/validation/diagnostics.ts
+- test/validation/compatibility-report.test.ts
+- test/fixtures/docx/fixtures.manifest.json
+```