@beyondwork/docx-react-component 1.0.0 → 1.0.2

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

@@ -1,231 +0,0 @@
-# Wave 31 - Realtime Collaboration
-
-**Commit message**: `Build: Yjs collaborative editing with cursors and awareness`
-
-## Project profile
-
-- project: React Word Editor
-- new-project: no
-- oversight-mode: dark-factory
-- lane: main
-
-## Sequencing note
-
-- Final parity wave. Adds Yjs-based collaborative editing. This is additive — the editor must work identically in single-user mode when no ydoc/provider is supplied.
-
-## Reference rule
-
-- Read the reference collaboration module before execution. Preserve single-user mode.
-
-## Component promotions
-
-- realtime-collaboration: baseline-proved
-
-## Context7 defaults
-
-- bundle: word-editor-testing
-- query: "Yjs, y-prosemirror, ySyncPlugin, yCursorPlugin, yUndoPlugin, awareness protocol, collaborative editing"
-
-## 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-31-cont-qa.md
-
-### Prompt
-
-```text
-Primary goal:
-- Verify collaboration works and single-user mode is not broken.
-
-Required context before coding:
-- docs/reference/repository-guidance.md
-- docs/research/agent-context-sources.md
-
-File ownership (only touch these paths):
-- docs/plans/waves/reviews/wave-31-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-31.md
-- .tmp/main-wave-launcher/integration/wave-31.json
-
-### Prompt
-
-```text
-Primary goal:
-- Verify collaboration integrates without breaking runtime-first architecture.
-
-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-31.md
-- .tmp/main-wave-launcher/integration/wave-31.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 for collaboration feature.
-
-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: Yjs Collaboration Integration
-
-### Executor
-
-- profile: implement-claude
-
-### Context7
-
-- bundle: word-editor-testing
-- query: "Yjs, y-prosemirror, ySyncPlugin, yCursorPlugin, yUndoPlugin, XmlFragment, awareness, collaborative cursors"
-
-### Components
-
-- realtime-collaboration
-
-### Deliverables
-
-- src/collaboration/yjs-plugins.ts
-- src/collaboration/cursor-builder.ts
-- src/ui/WordReviewEditor.tsx
-- src/api/public-types.ts
-- test/collaboration/yjs-integration.test.ts
-- .tmp/wave-31-collab-proof/yjs-integration.json
-
-### Proof artifacts
-
-- path: .tmp/wave-31-collab-proof/yjs-integration.json | kind: proof-bundle | required-for: baseline-proved
-
-### Exit contract
-
-- completion: authoritative
-- durability: durable
-- proof: unit
-- doc-impact: owned
-
-### Prompt
-
-```text
-Primary goal:
-- Add Yjs collaborative editing support.
-
-Reference: bwllaming/code (joakim/docx branch) src/collaboration/index.ts
-Access: gh api repos/bwllaming/code/contents/src/ts/packages/docx-editor/src/collaboration/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 for current editor setup.
-
-File ownership (only touch these paths):
-- src/collaboration/yjs-plugins.ts
-- src/collaboration/cursor-builder.ts
-- src/ui/WordReviewEditor.tsx
-- src/api/public-types.ts
-- test/collaboration/yjs-integration.test.ts
-- .tmp/wave-31-collab-proof/yjs-integration.json
-- package.json
-
-Requirements:
-1) Add yjs, y-prosemirror, y-protocols as dependencies.
-2) createCollaborationPlugins(config): returns ySyncPlugin, yCursorPlugin, yUndoPlugin.
-3) Cursor builder: render remote cursors with user name and color.
-4) WordReviewEditor: accept optional ydoc, provider, user props.
-5) When ydoc+provider provided: use Yjs plugins instead of prosemirror-history.
-6) When not provided: single-user mode works exactly as before.
-7) Add DocxEditorUser, CollaborationConfig types to public-types.
-8) Tests: create two Yjs docs, sync changes, verify convergence.
-9) CSS for cursor display and selection highlighting.
-10) CRITICAL: Single-user mode must not change behavior at all.
-
-Validation:
-- pnpm test:repo
-
-Output:
-- Summarize implementation and gaps.
-```

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

@@ -1,152 +0,0 @@
-# Wave 32 - OOXML Property Completeness
-
-**Commit message**: `Build: complete paragraph and run property parsing`
-
-## Project profile
-
-- project: React Word Editor
-- new-project: no
-- oversight-mode: dark-factory
-- lane: main
-
-## Sequencing note
-
-- Group A: 13 simple properties that need parse + serialize. No new PM nodes.
-
-## Component promotions
-
-- ooxml-property-completeness: baseline-proved
-
-## Context7 defaults
-
-- bundle: word-editor-testing
-- query: "OOXML paragraph properties, run properties, borders, shading, kerning"
-
-## Agent A0: cont-QA
-
-### Role prompts
-- docs/agents/wave-cont-qa-role.md
-### Executor
-- profile: deep-review
-### Context7
-- bundle: none
-- query: "Architecture evaluation only"
-### Deliverables
-- docs/plans/waves/reviews/wave-32-cont-qa.md
-### Prompt
-```text
-Primary goal: Verify all property round-trips work and existing tests pass.
-Required context before coding:
-- docs/reference/repository-guidance.md
-- docs/research/agent-context-sources.md
-File ownership (only touch these paths):
-- docs/plans/waves/reviews/wave-32-cont-qa.md
-```
-
-## Agent A8: Integration Steward
-
-### Role prompts
-- docs/agents/wave-integration-role.md
-### Executor
-- profile: deep-review
-### Context7
-- bundle: none
-- query: "Integration synthesis only"
-### Capabilities
-- integration
-- docs-shared-plan
-### Deliverables
-- .tmp/main-wave-launcher/integration/wave-32.md
-- .tmp/main-wave-launcher/integration/wave-32.json
-### Prompt
-```text
-Primary goal: Verify property extensions integrate with preservation and export.
-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-32.md
-- .tmp/main-wave-launcher/integration/wave-32.json
-```
-
-## Agent A9: Documentation Steward
-
-### Role prompts
-- docs/agents/wave-documentation-role.md
-### Executor
-- profile: docs-pass
-### Context7
-- bundle: none
-- query: "Shared plan documentation only"
-### 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.
-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
-```
-
-## Agent A1: Paragraph And Run Property Extensions
-
-### Executor
-- profile: implement-claude
-### Context7
-- bundle: word-editor-testing
-- query: "OOXML w:pPr widow control borders shading bidi, w:rPr charSpacing kerning emboss shadow, latent styles, tblLook"
-### Components
-- ooxml-property-completeness
-### Deliverables
-- src/model/canonical-document.ts
-- src/io/ooxml/parse-main-document.ts
-- src/io/export/serialize-main-document.ts
-- test/io/property-completeness.test.ts
-- .tmp/wave-32-props-proof/all-props.json
-### Proof artifacts
-- path: .tmp/wave-32-props-proof/all-props.json | kind: proof-bundle | required-for: baseline-proved
-### Exit contract
-- completion: authoritative
-- durability: durable
-- proof: integration
-- doc-impact: none
-### Prompt
-```text
-Primary goal: Parse and serialize all remaining paragraph and run properties.
-
-Required context before coding:
-- docs/reference/repository-guidance.md
-- docs/research/agent-context-sources.md
-- docs/architecture/ooxml-upgrade-analysis.md
-- Read src/model/canonical-document.ts and src/io/ooxml/parse-main-document.ts.
-
-File ownership (only touch these paths):
-- src/model/canonical-document.ts
-- src/io/ooxml/parse-main-document.ts
-- src/io/export/serialize-main-document.ts
-- test/io/property-completeness.test.ts
-- .tmp/wave-32-props-proof/all-props.json
-
-Requirements:
-1) ParagraphNode: widowControl, borders (pBdr), shading, bidi, suppressLineNumbers, cnfStyle.
-2) TextMark: charSpacing, kerning, emboss, imprint, shadow, position.
-3) Parse w14:textFill as preserved XML string.
-4) Latent styles in style catalog. tblLook on table model.
-5) Column breaks and symbols as inline types.
-6) Round-trip tests for each property.
-7) CRITICAL: All existing tests must pass.
-```

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

@@ -1,147 +0,0 @@
-# Wave 33 - Document Sub-Parts
-
-**Commit message**: `Build: headers, footers, footnotes, endnotes, theme parsing`
-
-## Project profile
-- project: React Word Editor
-- new-project: no
-- oversight-mode: dark-factory
-- lane: main
-
-## Sequencing note
-- Group B: Parse separate XML parts, link from body, render in UI zones.
-
-## Component promotions
-- document-sub-parts: baseline-proved
-
-## Context7 defaults
-- bundle: word-editor-testing
-- query: "OOXML headers footers footnotes endnotes theme section references"
-
-## Agent A0: cont-QA
-### Role prompts
-- docs/agents/wave-cont-qa-role.md
-### Executor
-- profile: deep-review
-### Context7
-- bundle: none
-- query: "Architecture evaluation only"
-### Deliverables
-- docs/plans/waves/reviews/wave-33-cont-qa.md
-### Prompt
-```text
-Primary goal: Verify sub-parts parse and round-trip correctly.
-Required context: docs/reference/repository-guidance.md, docs/research/agent-context-sources.md
-File ownership (only touch these paths):
-- docs/plans/waves/reviews/wave-33-cont-qa.md
-```
-
-## Agent A8: Integration Steward
-### Role prompts
-- docs/agents/wave-integration-role.md
-### Executor
-- profile: deep-review
-### Context7
-- bundle: none
-- query: "Integration synthesis only"
-### Capabilities
-- integration
-- docs-shared-plan
-### Deliverables
-- .tmp/main-wave-launcher/integration/wave-33.md
-- .tmp/main-wave-launcher/integration/wave-33.json
-### Prompt
-```text
-Primary goal: Verify sub-parts integrate with preservation.
-Required context: 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-33.md
-- .tmp/main-wave-launcher/integration/wave-33.json
-```
-
-## Agent A9: Documentation Steward
-### Role prompts
-- docs/agents/wave-documentation-role.md
-### Executor
-- profile: docs-pass
-### Context7
-- bundle: none
-- query: "Shared plan documentation only"
-### 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.
-Required context: 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
-```
-
-## Agent A1: Headers, Footers, Footnotes, Endnotes, Theme
-### Executor
-- profile: implement-claude
-### Context7
-- bundle: word-editor-testing
-- query: "OOXML headerN.xml footerN.xml footnotes.xml endnotes.xml theme1.xml section references theme colors"
-### Components
-- document-sub-parts
-### Deliverables
-- src/io/ooxml/parse-headers-footers.ts
-- src/io/ooxml/parse-footnotes.ts
-- src/io/ooxml/parse-theme.ts
-- src/io/export/serialize-headers-footers.ts
-- src/io/export/serialize-footnotes.ts
-- src/model/canonical-document.ts
-- src/io/docx-session.ts
-- test/io/headers-footers-roundtrip.test.ts
-- test/io/footnotes-roundtrip.test.ts
-- .tmp/wave-33-subparts-proof/all-subparts.json
-### Proof artifacts
-- path: .tmp/wave-33-subparts-proof/all-subparts.json | kind: proof-bundle | required-for: baseline-proved
-### Exit contract
-- completion: authoritative
-- durability: durable
-- proof: integration
-- doc-impact: none
-### Prompt
-```text
-Primary goal: Parse headers, footers, footnotes, endnotes, and theme from their XML parts.
-
-Required context:
-- docs/reference/repository-guidance.md
-- docs/research/agent-context-sources.md
-- docs/architecture/ooxml-upgrade-analysis.md
-- src/io/docx-session.ts, src/io/export/export-session.ts
-
-File ownership (only touch these paths):
-- src/io/ooxml/parse-headers-footers.ts
-- src/io/ooxml/parse-footnotes.ts
-- src/io/ooxml/parse-theme.ts
-- src/io/export/serialize-headers-footers.ts
-- src/io/export/serialize-footnotes.ts
-- src/model/canonical-document.ts
-- src/io/docx-session.ts
-- test/io/headers-footers-roundtrip.test.ts
-- test/io/footnotes-roundtrip.test.ts
-- .tmp/wave-33-subparts-proof/all-subparts.json
-
-Requirements:
-1) HeaderDocument/FooterDocument types. Parse headerN.xml/footerN.xml.
-2) Link via w:headerReference/footerReference in section properties.
-3) Handle default, first-page, even/odd variants.
-4) FootnoteCollection type. Parse footnotes.xml/endnotes.xml.
-5) FootnoteRefNode inline type with superscript number rendering.
-6) ThemeDefinition: parse theme colors and fonts. Resolve in style inheritance.
-7) Add owned paths in export. Serialize all parts.
-8) Round-trip tests. CRITICAL: Do not break existing tests.
-```

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

@@ -1,148 +0,0 @@
-# Wave 34 - Structural Block Types
-
-**Commit message**: `Build: content controls, custom XML, nested tables, floating images`
-
-## Project profile
-- project: React Word Editor
-- new-project: no
-- oversight-mode: dark-factory
-- lane: main
-
-## Sequencing note
-- Group C+D: New block containers and inline types.
-
-## Component promotions
-- structural-block-types: baseline-proved
-
-## Context7 defaults
-- bundle: word-editor-testing
-- query: "OOXML w:sdt content controls w:customXml nested tables floating images wp:anchor"
-
-## Agent A0: cont-QA
-### Role prompts
-- docs/agents/wave-cont-qa-role.md
-### Executor
-- profile: deep-review
-### Context7
-- bundle: none
-- query: "Architecture evaluation only"
-### Deliverables
-- docs/plans/waves/reviews/wave-34-cont-qa.md
-### Prompt
-```text
-Primary goal: Verify structural types work and existing tests pass.
-Required context: docs/reference/repository-guidance.md, docs/research/agent-context-sources.md
-File ownership (only touch these paths):
-- docs/plans/waves/reviews/wave-34-cont-qa.md
-```
-
-## Agent A8: Integration Steward
-### Role prompts
-- docs/agents/wave-integration-role.md
-### Executor
-- profile: deep-review
-### Context7
-- bundle: none
-- query: "Integration synthesis only"
-### Capabilities
-- integration
-- docs-shared-plan
-### Deliverables
-- .tmp/main-wave-launcher/integration/wave-34.md
-- .tmp/main-wave-launcher/integration/wave-34.json
-### Prompt
-```text
-Primary goal: Verify structural types integrate with preservation.
-Required context: 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-34.md
-- .tmp/main-wave-launcher/integration/wave-34.json
-```
-
-## Agent A9: Documentation Steward
-### Role prompts
-- docs/agents/wave-documentation-role.md
-### Executor
-- profile: docs-pass
-### Context7
-- bundle: none
-- query: "Shared plan documentation only"
-### 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.
-Required context: 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
-```
-
-## Agent A1: SDT, Custom XML, AltChunk, Nested Tables, Floating Images
-### Executor
-- profile: implement-claude
-### Context7
-- bundle: word-editor-testing
-- query: "OOXML w:sdt sdtPr sdtContent w:customXml altChunk nested tables wp:anchor floating position wrapping"
-### Components
-- structural-block-types
-### Deliverables
-- src/model/canonical-document.ts
-- src/io/ooxml/parse-main-document.ts
-- src/io/ooxml/parse-tables.ts
-- src/io/ooxml/parse-inline-media.ts
-- src/io/export/serialize-main-document.ts
-- src/io/export/serialize-tables.ts
-- src/runtime/surface-projection.ts
-- src/ui-tailwind/editor-surface/pm-schema.ts
-- src/ui-tailwind/editor-surface/pm-state-from-snapshot.ts
-- test/io/structural-blocks.test.ts
-- .tmp/wave-34-blocks-proof/structural.json
-### Proof artifacts
-- path: .tmp/wave-34-blocks-proof/structural.json | kind: proof-bundle | required-for: baseline-proved
-### Exit contract
-- completion: authoritative
-- durability: durable
-- proof: integration
-- doc-impact: none
-### Prompt
-```text
-Primary goal: Parse SDT, custom XML, altChunk, nested tables, and floating images.
-
-Required context:
-- docs/reference/repository-guidance.md
-- docs/research/agent-context-sources.md
-- docs/architecture/ooxml-upgrade-analysis.md
-
-File ownership (only touch these paths):
-- src/model/canonical-document.ts
-- src/io/ooxml/parse-main-document.ts
-- src/io/ooxml/parse-tables.ts
-- src/io/ooxml/parse-inline-media.ts
-- src/io/export/serialize-main-document.ts
-- src/io/export/serialize-tables.ts
-- src/runtime/surface-projection.ts
-- src/ui-tailwind/editor-surface/pm-schema.ts
-- src/ui-tailwind/editor-surface/pm-state-from-snapshot.ts
-- test/io/structural-blocks.test.ts
-- .tmp/wave-34-blocks-proof/structural.json
-
-Requirements:
-1) SdtNode: { type, properties: {sdtType, alias, tag, lock}, children: BlockNode[] }
-2) CustomXmlNode: { type, uri, element, children: BlockNode[] }
-3) AltChunkNode: read-only block with relationship reference
-4) Nested tables: recursive TableNode in TableCellNode children
-5) FloatingImageNode: parse wp:anchor, position/wrap props, fallback to inline display
-6) PM schema: sdt_block (content: block+), nested table support
-7) Surface projection for all new types
-8) Round-trip tests. CRITICAL: Do not break existing tests.
-```