@beyondwork/docx-react-component 1.0.0

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

@@ -0,0 +1,303 @@
+# Wave 29 - OOXML Parsing Fidelity
+
+**Commit message**: `Build: complete OOXML parsing — sections, spacing, indentation, tables, fields, bookmarks`
+
+## Project profile
+
+- project: React Word Editor
+- new-project: no
+- oversight-mode: dark-factory
+- lane: main
+
+## Sequencing note
+
+- Extends the parser and canonical model to handle all Word paragraph properties, run properties, table properties, field codes, bookmarks, and section breaks without breaking the existing preservation system.
+
+## Reference rule
+
+- Read the reference implementation types.ts for the complete parsed model before execution.
+
+## Component promotions
+
+- ooxml-parsing-fidelity: baseline-proved
+
+## Context7 defaults
+
+- bundle: word-editor-testing
+- query: "OOXML paragraph properties, run properties, table borders, field codes, bookmarks, section breaks, spacing, indentation"
+
+## 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-29-cont-qa.md
+
+### Prompt
+
+```text
+Primary goal:
+- Verify extended parsing does not break existing round-trip fidelity.
+
+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-29-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-29.md
+- .tmp/main-wave-launcher/integration/wave-29.json
+
+### Prompt
+
+```text
+Primary goal:
+- Verify parsing 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-29.md
+- .tmp/main-wave-launcher/integration/wave-29.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 parsing fidelity 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: Paragraph And Run Property Parsing
+
+### Executor
+
+- profile: implement-claude
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "OOXML paragraph properties, spacing, indentation, tab stops, keep next, outline level, run properties, double strikethrough, vanish, language, background color"
+
+### Components
+
+- ooxml-parsing-fidelity
+
+### Deliverables
+
+- src/model/canonical-document.ts
+- src/io/ooxml/parse-main-document.ts
+- src/io/export/serialize-main-document.ts
+- src/io/normalize/normalize-text.ts
+- test/io/paragraph-properties-roundtrip.test.ts
+- .tmp/wave-29-parsing-proof/paragraph-run.json
+
+### Proof artifacts
+
+- path: .tmp/wave-29-parsing-proof/paragraph-run.json | kind: proof-bundle | required-for: baseline-proved
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: none
+
+### Prompt
+
+```text
+Primary goal:
+- Extend canonical model and parser for complete paragraph and run properties.
+
+Reference: bwllaming/code (joakim/docx branch) src/ts/packages/docx-editor/src/types.ts
+Access: gh api repos/bwllaming/code/contents/src/ts/packages/docx-editor/src/types.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/model/canonical-document.ts for current model.
+- Read src/io/ooxml/parse-main-document.ts for current parser.
+
+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
+- src/io/normalize/normalize-text.ts
+- test/io/paragraph-properties-roundtrip.test.ts
+- .tmp/wave-29-parsing-proof/paragraph-run.json
+
+Requirements:
+1) ParagraphNode: add alignment, spacing (before/after/line/lineRule), indentation (left/right/firstLine/hanging), tabStops, keepNext, keepLines, outlineLevel, pageBreakBefore.
+2) TextNode marks: add doubleStrikethrough, vanish, lang, backgroundColor (separate from highlight).
+3) Parse these from OOXML w:pPr and w:rPr elements.
+4) Serialize back to OOXML on export.
+5) Round-trip tests: parse -> export -> re-parse -> compare.
+6) CRITICAL: Do not break existing tests. All 286+ tests must still pass.
+
+Validation:
+- pnpm test:repo
+
+Output:
+- Summarize implementation and gaps.
+```
+
+## Agent A2: Table Property Parsing And Field Codes
+
+### Executor
+
+- profile: implement-claude
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "OOXML table borders, cell margins, cell shading, row height, header rows, field codes, bookmarks, section breaks, hyperlink runs"
+
+### Components
+
+- ooxml-parsing-fidelity
+
+### Deliverables
+
+- src/io/ooxml/parse-tables.ts
+- src/io/export/serialize-tables.ts
+- src/model/canonical-document.ts
+- src/io/ooxml/parse-fields.ts
+- test/io/table-properties-roundtrip.test.ts
+- test/io/fields-bookmarks.test.ts
+- .tmp/wave-29-parsing-proof/tables-fields.json
+
+### Proof artifacts
+
+- path: .tmp/wave-29-parsing-proof/tables-fields.json | kind: proof-bundle | required-for: baseline-proved
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: none
+
+### Prompt
+
+```text
+Primary goal:
+- Extend table parsing for borders, margins, shading, row headers. Add field code and bookmark parsing.
+
+Reference: bwllaming/code (joakim/docx branch) src/ts/packages/docx-editor/src/types.ts and src/docx/parser.ts
+Access parser: gh api repos/bwllaming/code/contents/src/ts/packages/docx-editor/src/docx/parser.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/io/ooxml/parse-tables.ts and src/io/export/serialize-tables.ts.
+
+File ownership (only touch these paths):
+- src/io/ooxml/parse-tables.ts
+- src/io/export/serialize-tables.ts
+- src/model/canonical-document.ts
+- src/io/ooxml/parse-fields.ts
+- test/io/table-properties-roundtrip.test.ts
+- test/io/fields-bookmarks.test.ts
+- .tmp/wave-29-parsing-proof/tables-fields.json
+
+Requirements:
+1) TableNode: add borders (per-side), cellMargins, width, alignment.
+2) TableCellNode: add borders, shading/background, verticalAlign, width.
+3) TableRowNode: add height, heightRule, isHeader.
+4) Add FieldNode type for w:fldSimple and complex fields with instruction and content.
+5) Add BookmarkNode (start/end) to inline node types.
+6) Add SectionBreakNode to block types.
+7) Parse and serialize all. Round-trip tests.
+8) CRITICAL: Do not break existing tests.
+
+Validation:
+- pnpm test:repo
+
+Output:
+- Summarize implementation and gaps.
+```

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

@@ -0,0 +1,307 @@
+# Wave 30 - Editor UX Completeness
+
+**Commit message**: `Build: headings, page breaks, numbering, read-only, dirty tracking, cursor context, event callbacks`
+
+## Project profile
+
+- project: React Word Editor
+- new-project: no
+- oversight-mode: dark-factory
+- lane: main
+
+## Sequencing note
+
+- Completes the editor UX to match the reference implementation. Does NOT include Yjs collaboration (separate wave). All changes must preserve existing rendering and not break the current UX.
+
+## Reference rule
+
+- Read the reference docx-editor.tsx and types.ts before execution. Preserve our runtime-first architecture.
+
+## Component promotions
+
+- editor-ux-completeness: baseline-proved
+
+## Context7 defaults
+
+- bundle: word-editor-ui
+- query: "ProseMirror heading nodes, page break node, numbering prefix, read-only mode, format state, cursor context, dirty tracking, event callbacks, gap cursor, drop cursor"
+
+## 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-30-cont-qa.md
+
+### Prompt
+
+```text
+Primary goal:
+- Verify UX features work without breaking existing editor behavior.
+
+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-30-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-30.md
+- .tmp/main-wave-launcher/integration/wave-30.json
+
+### Prompt
+
+```text
+Primary goal:
+- Verify UX additions preserve 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-30.md
+- .tmp/main-wave-launcher/integration/wave-30.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 UX completeness 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: Headings, Page Breaks, And Numbering Rendering
+
+### Executor
+
+- profile: implement-claude
+
+### Context7
+
+- bundle: word-editor-ui
+- query: "ProseMirror heading node spec, page break node, numbered paragraph prefix computation, multi-level numbering, bullet lists, roman numerals"
+
+### Components
+
+- editor-ux-completeness
+
+### Deliverables
+
+- src/ui-tailwind/editor-surface/pm-schema.ts
+- src/runtime/surface-projection.ts
+- src/runtime/numbering-prefix.ts
+- src/ui-tailwind/editor-surface/pm-state-from-snapshot.ts
+- test/runtime/numbering-prefix.test.ts
+- .tmp/wave-30-ux-proof/headings-numbering.json
+
+### Proof artifacts
+
+- path: .tmp/wave-30-ux-proof/headings-numbering.json | kind: proof-bundle | required-for: baseline-proved
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: unit
+- doc-impact: none
+
+### Prompt
+
+```text
+Primary goal:
+- Add heading nodes, page break visual, and live numbering prefix rendering.
+
+Reference: bwllaming/code (joakim/docx branch) docx-editor.tsx (computeNumberPrefix function) and schema.
+Access schema: gh api repos/bwllaming/code/contents/src/ts/packages/docx-editor/src/schema/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-tailwind/editor-surface/pm-schema.ts for current schema.
+- Read src/runtime/surface-projection.ts for current surface building.
+- Read src/model/canonical-document.ts for numbering types.
+
+File ownership (only touch these paths):
+- src/ui-tailwind/editor-surface/pm-schema.ts
+- src/runtime/surface-projection.ts
+- src/runtime/numbering-prefix.ts
+- src/ui-tailwind/editor-surface/pm-state-from-snapshot.ts
+- test/runtime/numbering-prefix.test.ts
+- .tmp/wave-30-ux-proof/headings-numbering.json
+
+Requirements:
+1) Add h1-h6 heading PM nodes. Map from paragraph styleId (Heading1-6) to heading nodes.
+2) Add page_break PM node with visual CSS separator.
+3) computeNumberPrefix(): compute bullet, decimal, lowerLetter, upperLetter, lowerRoman, upperRoman prefixes for multi-level numbered paragraphs.
+4) Render number prefix as a mark on the first text node of numbered paragraphs.
+5) Wire heading and page_break into surface-projection and pm-state-from-snapshot.
+6) Add gap cursor (prosemirror-gapcursor) and drop cursor (prosemirror-dropcursor) plugins.
+7) CRITICAL: Do not break existing paragraph rendering or tests.
+
+Validation:
+- pnpm test:repo
+
+Output:
+- Summarize implementation and gaps.
+```
+
+## Agent A2: Read-Only Mode, Dirty Tracking, Format State, And Event Callbacks
+
+### Executor
+
+- profile: implement-claude
+
+### Context7
+
+- bundle: word-editor-ui
+- query: "React read-only prop, dirty tracking, format state at cursor, cursor context, debounced onChange, revision click, comment click, highlight events"
+
+### Components
+
+- editor-ux-completeness
+
+### Deliverables
+
+- src/ui/WordReviewEditor.tsx
+- src/runtime/format-state.ts
+- src/api/public-types.ts
+- test/runtime/format-state.test.ts
+- test/ui/editor-readonly.test.tsx
+- .tmp/wave-30-ux-proof/ux-features.json
+
+### Proof artifacts
+
+- path: .tmp/wave-30-ux-proof/ux-features.json | kind: proof-bundle | required-for: baseline-proved
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: unit
+- doc-impact: none
+
+### Prompt
+
+```text
+Primary goal:
+- Add read-only mode, dirty tracking, format state reporting, and event callbacks.
+
+Reference: bwllaming/code (joakim/docx branch) docx-editor.tsx
+Access: gh api repos/bwllaming/code/contents/src/ts/packages/docx-editor/src/component/docx-editor.tsx?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 component.
+- Read src/api/public-types.ts for current types.
+
+File ownership (only touch these paths):
+- src/ui/WordReviewEditor.tsx
+- src/runtime/format-state.ts
+- src/api/public-types.ts
+- test/runtime/format-state.test.ts
+- test/ui/editor-readonly.test.tsx
+- .tmp/wave-30-ux-proof/ux-features.json
+
+Requirements:
+1) readOnly prop: toggle ProseMirror editable().
+2) isDirty(): track whether document has been modified since load.
+3) getFormatState(): return bold/italic/underline/etc state at cursor, with DocxCursorContext (breadcrumb, inTable, inList).
+4) onDocChange callback with configurable debounceDelay.
+5) onRevisionClick / onCommentClick callbacks for inline click targeting.
+6) onHighlightEnter / onHighlightLeave callbacks.
+7) onFormatChange callback on every cursor move.
+8) suggestOnly mode for track changes.
+9) user prop (DocxEditorUser) for authoring identity.
+10) focusPosition(pos) with smooth scroll.
+11) CRITICAL: Do not break existing WordReviewEditor props or rendering.
+
+Validation:
+- pnpm test:repo
+
+Output:
+- Summarize implementation and gaps.
+```