@beyondwork/docx-react-component 1.0.0 → 1.0.2

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

@@ -1,303 +0,0 @@
-# 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

@@ -1,307 +0,0 @@
-# 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.
-```