@beyondwork/docx-react-component 1.0.0 → 1.0.1

package/docs/agents/wave-security-role.md

@@ -1,40 +0,0 @@
----
-title: "Wave Security Role"
-summary: "Standing prompt for the security reviewer that performs a threat-model-first review before integration closure."
----
-
-# Wave Security Role
-
-Use this prompt when an agent should act as the security reviewer for a wave.
-
-## Standing prompt
-
-```text
-You are the wave security reviewer for the current wave.
-
-Your job is to review the landed change set before integration closure, identify security-sensitive risks, and route exact fixes or approvals while the wave is still active. You are report-only by default. Do not replace implementation ownership.
-
-Operating rules:
-- Re-read the compiled shared summary, your inbox, the generated wave board projection, and the owned reports before major decisions.
-- Do a threat-model pass before finalizing conclusions. Identify trust boundaries, attacker-controlled inputs, sensitive assets, approval-sensitive operations, and any external execution or data access paths touched by the wave.
-- Prefer exact findings and exact requested fixes over vague warnings.
-- Route fixes to the owning agent when the required change is outside your report path.
-- Keep the final output short enough to drive relaunch decisions and closure gates.
-
-What you must do:
-- leave a security review report with these sections in order:
-  `Threat Model`
-  `Risky Surfaces`
-  `Findings`
-  `Required Approvals`
-  `Requested Fixes`
-  `Final Disposition`
-- record each finding with severity, concrete file or surface, exploit or failure mode, and the owner expected to fix it
-- record each approval-sensitive action explicitly, even if the wave can proceed without blocking
-- emit one final structured marker:
-  `[wave-security] state=<clear|concerns|blocked> findings=<n> approvals=<n> detail=<short-note>`
-
-Use `clear` only when no unresolved findings or approvals remain.
-Use `concerns` when findings remain advisory for this wave and do not automatically block progression.
-Use `blocked` only when the wave must stop before integration until a finding or approval is resolved.
-```

package/docs/architecture/docx/README.md

@@ -1,10 +0,0 @@
-# Docx Architecture
-
-This directory is reserved for docx-specific architecture material as the broader `react-ooxml-office` docs hierarchy fills out.
-
-Current docx architecture contracts still live in the legacy reference paths:
-
-- `docs/reference/word-review-editor-frontend-architecture.md`
-- `docs/reference/word-review-editor-ux-guide.md`
-
-Those remain the canonical shipped docx architecture docs today.

package/docs/architecture/future/README.md

@@ -1,8 +0,0 @@
-# Future Architecture
-
-This directory is reserved for future architecture work that sits outside the current shipped docx runtime and outside the first shared OOXML sibling set.
-
-For now, that mainly means:
-
-- future pdf exploration
-- later cross-vertical capabilities that should not be implied by current shipped contracts

package/docs/architecture/ooxml-upgrade-analysis.md

@@ -1,134 +0,0 @@
-# Architectural Analysis: Preserve-Only → Supported Upgrade Path
-
-## Architecture Summary
-
-Our codebase has 4 layers for handling OOXML features:
-
-1. **OPC Layer** (src/io/opc/) — ZIP package read/write, part discovery, relationship tracking
-2. **Preservation Layer** (src/preservation/) — opaque fragment store, package part retention, MC handling
-3. **Canonical Model** (src/model/) — typed document nodes, style catalog, media catalog
-4. **Surface Projection** (src/runtime/) → **PM Schema** (src/ui-tailwind/) → rendered editor
-
-### How features graduate from preserve-only to supported:
-
-```
-PRESERVE-ONLY:                           SUPPORTED:
-OPC part bytes → opaque fragment    →    OPC part bytes → parser → canonical node
-opaque block in surface            →    typed block in surface
-locked in PM (no editing)          →    editable in PM schema
-reattach original bytes on export  →    serialize from canonical on export
-```
-
-The key insight: our preservation system already handles ALL unknown content safely.
-Graduating a feature means: add a parser, add a canonical type, add surface projection,
-add PM rendering, and add a serializer. The preservation system handles the fallback.
-
-### Validation strategy per tier:
-
-- **Tier 1 (parse + pass-through)**: Unit test parse/serialize. Fixture round-trip.
-- **Tier 2 (read-only projected)**: Above + surface projection test. No editing.
-- **Tier 3 (fully editable)**: Above + PM schema + command tests + edit round-trip.
-
----
-
-## Feature Groups by Architectural Pattern
-
-### Group A: Simple Property Parsing (13 features, ~14h)
-Pattern: Add field to existing canonical node type, parse from XML attr, serialize back.
-No new PM nodes, no new surface blocks. Properties affect rendering CSS only.
-
-Features: widowControl, pBdr, pShd, bidi, charSpacing, kerning, emboss/shadow,
-columnBreaks, symbols, suppressLineNumbers, cnfStyle, tblLook, latentStyles.
-
-Architecture:
-- Extend ParagraphNode/TextMark interfaces in canonical-document.ts
-- Parse in parse-main-document.ts (add cases to existing paragraph/run property loops)
-- Serialize in serialize-main-document.ts (add cases to existing property serializers)
-- Surface projection: carry properties through for CSS rendering
-- PM schema: add attrs to paragraph/text nodes for styling
-- Tests: parse + serialize round-trip per property
-
-### Group B: Document Sub-Parts (9 features, ~42h)
-Pattern: Parse a separate XML part (headerN.xml, footnotes.xml, etc.), create a sub-document
-model, link from body references, render in dedicated UI zones.
-
-Features: headers (3 types), footers (3 types), footnotes, endnotes, theme.
-
-Architecture:
-- Add new canonical types: HeaderDocument, FooterDocument, FootnoteCollection, ThemeDefinition
-- New parsers: parse-headers.ts, parse-footnotes.ts, parse-theme.ts
-- New serializers: serialize-headers.ts, serialize-footnotes.ts
-- DocxSession: add owned paths for these parts, parse them alongside main document
-- Surface projection: add footer/header/footnote zones to EditorSurfaceSnapshot
-- PM schema: render in separate PM editors or as read-only zones
-- Export: serialize owned header/footer/footnote parts, reattach the rest
-- Theme resolution: resolve theme colors/fonts in style inheritance
-
-### Group C: Structural Block Types (4 features, ~19h)
-Pattern: New block-level canonical node, parser, surface block, PM node.
-
-Features: SDT (content controls), customXml, altChunk, nestedTables.
-
-Architecture:
-- SDT: Parse w:sdt as a wrapper node containing block/inline children.
-  Canonical type: SdtNode { type, properties, children }. PM: contentEditable container.
-  Challenge: Many SDT subtypes (richText, date, dropdown, checkbox) with different editing UX.
-- customXml: Parse as wrapper node, treat inner content as editable.
-  Simpler than SDT — just structural container.
-- altChunk: Import embedded HTML/RTF by resolving the relationship.
-  Complex: would need an HTML/RTF → canonical converter.
-  Pragmatic: parse as read-only projected block showing content preview.
-- nestedTables: Recursive table parsing. PM: prosemirror-tables supports nesting.
-  Main work: surface-projection recursion for table-in-cell.
-
-### Group D: Inline Content Types (4 features, ~22h)
-Pattern: New inline canonical node, parser, PM inline atom, serializer.
-
-Features: floatingImages, footnoteRefs, ruby, OLE objects.
-
-Architecture:
-- Floating images: Parse wp:anchor DrawingML. Canonical: FloatingImageNode with position/wrap props.
-  PM: Positioned absolute/relative node (complex — needs position map outside text flow).
-  Pragmatic: Render as inline with "floating" badge, preserve position on export.
-- Footnote refs: Parse w:footnoteReference. Canonical: FootnoteRefNode { noteId }.
-  PM: Inline atom with superscript number. Click → navigate to footnote zone.
-  Requires Group B footnote parsing.
-- Ruby: Parse w:ruby (base + annotation). Canonical: RubyNode { base, annotation }.
-  PM: Inline with ruby annotation rendering (CSS ruby-position).
-- OLE objects: Parse w:object. Canonical: OleObjectNode { progId, fallbackImage }.
-  PM: Inline atom showing fallback image or icon. No editing.
-
-### Group E: Track Change Extensions (4 features, ~16h)
-Pattern: Extend revision model and store.
-
-Features: pPrChange, sectPrChange, tblPrChange, moveTo/moveFrom.
-
-Architecture:
-- Property changes: Parse old/new property pairs from w:*Change elements.
-  Store in revision record as PropertyChangeRevision { before, after }.
-  Surface: Show diff indicator on paragraph/section/table.
-  Accept: Apply "after" properties. Reject: Restore "before" properties.
-- Move tracking: Parse w:moveFrom/moveTo with matching IDs.
-  Store as MoveRevision { moveId, direction, range }.
-  Surface: Render as deletion at source + insertion at destination with linking indicator.
-  Accept: Keep destination. Reject: Restore source.
-
-### Group F: Complex Rendering (5 features, ~83h)
-Pattern: Full subsystem — parser, model, renderer.
-
-Features: charts, SmartArt, shapes, WordArt, VML.
-
-Architecture:
-- Charts: ChartML parser → chart model → Canvas/SVG renderer.
-  Full charting library. Huge scope. Consider: read-only SVG preview from XML.
-- SmartArt: DiagramML → layout algorithm → SVG rendering.
-  Extremely complex layout engine. Consider: fallback to EMF/PNG preview image.
-- Shapes/WordArt/VML: Parse geometry, text, fills, effects.
-  Consider: Read-only SVG rendering for shapes, skip editing.
-  VML is legacy — render as fallback for pre-2007 content.
-
-### Group G: Security (2 features, intentionally excluded)
-- Digital signatures: Full XMLDSIG. Out of scope.
-- Password encryption: Upstream concern. Out of scope.
-
----

package/docs/architecture/platform/shared-openxml-editor-platform.md

@@ -1,153 +0,0 @@
-# Shared OOXML Editor Platform
-
-## Status
-
-- This is the canonical umbrella architecture doc for the broader `react-ooxml-office` repo story.
-- The only shipped runtime in source today is the `docx` implementation behind `WordReviewEditor`.
-- `xlsx` is planned and documented here as the next OOXML sibling, not as a shipped runtime.
-- `pdf` is a future vertical and is intentionally outside this first shared OOXML platform contract.
-
-## Purpose
-
-This repository is evolving from a docx-only product narrative into a broader office-document platform with three distinct layers:
-
-1. shared platform capabilities
-2. format-specific runtimes
-3. host-facing editor surfaces
-
-The goal is to broaden the docs without pretending the codebase is already neutral. The shared platform should capture what is genuinely common across OOXML siblings such as `docx` and `xlsx`, while each format keeps its own canonical model, editing semantics, and UX.
-
-## Core Platform Principles
-
-- Treat OOXML files as OPC packages first, not as isolated XML files.
-- Keep runtime-owned structured state as the only source of truth.
-- Route every mutation through commands and transactions.
-- Preserve unsupported but preservable content instead of silently discarding it.
-- Keep compatibility posture explicit through typed warnings, errors, and export blockers.
-- Use host application behavior as the final fidelity gate.
-- Keep shipped runtimes main-thread only unless an explicit architecture change is made.
-
-## Layered Architecture
-
-```text
-Host App
-  |
-  v
-Embeddable Editor Surface
-  |
-  v
-Format Runtime
-  |
-  v
-Shared OOXML Platform
-  |
-  v
-OPC package, preservation, diagnostics, validation
-```
-
-### Shared Platform Responsibilities
-
-The shared OOXML platform is responsible for concerns that remain honest across multiple OOXML formats:
-
-- OPC package reading and writing
-- part manifests, content types, and relationship integrity
-- preservation of unknown or unsupported but preservable parts
-- compatibility reporting vocabulary and export blocking
-- host persistence and snapshot doctrine
-- validation integration with the internal Open XML SDK service
-- shared runtime-to-UI doctrine: runtime owns truth, UI renders projections
-- future shared AI or agent mediation boundaries above format runtimes
-
-These concerns are intentionally narrower than a full editor runtime. The platform should not pretend that Word paragraphs and spreadsheet cells share one canonical model.
-
-### Format Runtime Responsibilities
-
-Each format runtime owns its own domain model, editing rules, and projections:
-
-- `docx`: paragraphs, runs, comments, revisions, review anchors, and the current `WordReviewEditor` surface
-- `xlsx`: workbook, sheets, ranges, formulas, merges, spreadsheet annotations, and a grid-first editor surface
-- `pdf`: future non-OOXML work; outside the first shared platform contract
-
-Format runtimes may reuse platform services, but they must not be flattened into a lowest-common-denominator editor abstraction.
-
-## Current State In This Repo
-
-Today the source tree is still organized around the active `docx` implementation:
-
-```text
-src/
-  api/
-  model/
-  core/
-  review/
-  io/
-  preservation/
-  validation/
-  runtime/
-  ui/
-services/
-  react-word-editor/
-  openxml-validator/
-```
-
-That remains the truthful description of the landed code.
-
-The broader target architecture for future work is:
-
-```text
-src/
-  platform/
-  formats/
-    docx/
-    xlsx/
-    pdf/
-services/
-  office-harness/
-  openxml-validator/
-```
-
-This target layout is a documentation and planning direction, not a claim that the source has already been moved.
-
-## Current Format Status
-
-### `docx`
-
-- implemented in source
-- shipped public component name: `WordReviewEditor`
-- current public API contract remains under `docs/reference/public-api.md`
-- current compliance contract remains under `docs/reference/ooxml-compliance.md`
-
-### `xlsx`
-
-- not implemented in source
-- promoted from raw research into planned canonical docs
-- intended to reuse shared platform capabilities while keeping spreadsheet-native runtime and UX boundaries
-
-### `pdf`
-
-- future exploration only
-- should not be forced into the OOXML platform contract unless a later architecture intentionally broadens the platform beyond OOXML
-
-## Future Shared Capability: Agent Layer
-
-The agent or LLM interaction layer belongs above the shared platform and format runtimes, not inside the current shipped `WordReviewEditor` contract.
-
-That future layer should:
-
-- request structured context from format runtimes
-- propose typed commands instead of mutating state directly
-- respect compatibility and export blockers
-- remain reviewable and auditable
-
-It is a roadmap capability, not a current public API guarantee.
-
-## Doc Map
-
-- Repo overview: `README.md`
-- Docs navigation: `docs/README.md`
-- Current docx implementation contracts: `docs/reference/public-api.md`, `docs/reference/ooxml-compliance.md`, `docs/reference/word-review-editor-frontend-architecture.md`
-- Planned xlsx architecture: `docs/architecture/xlsx/spreadsheet-editor-frontend-architecture.md`
-- Planned xlsx canonical model: `docs/architecture/xlsx/canonical-workbook-model-and-commands.md`
-- Planned xlsx compliance: `docs/reference/xlsx/xlsx-ooxml-compliance.md`
-- Planned xlsx fixture and certification program: `docs/plans/xlsx/xlsx-fixture-corpus-and-certification-plan.md`
-- Research intake: `docs/xlsx-react/README.md`

package/docs/architecture/xlsx/canonical-workbook-model-and-commands.md

@@ -1,187 +0,0 @@
-# Canonical Workbook Model And Commands
-
-## Status
-
-- Planned canonical model for the future `xlsx` runtime.
-- Not implemented in source today.
-- Intended to align the xlsx planning work with the current repo's runtime-first, command-driven architecture.
-
-## Purpose
-
-This document defines what should remain canonical in a spreadsheet runtime and what should remain derived.
-
-The goal is to keep the workbook model:
-
-- sparse and serializable
-- safe for import and export
-- compatible with command and transaction boundaries
-- honest about preserve-only content
-
-## Core Rules
-
-- The workbook runtime owns the only canonical state.
-- React renders runtime projections and never mutates canonical workbook state directly.
-- Commands produce transactions, mappings, effects, and history boundaries.
-- Structural edits must remap anchors, ranges, comments, merges, and references.
-- Unsupported but preservable workbook content must stay in preservation state, not be flattened into "best effort" workbook data.
-
-## Canonical Stores
-
-The planned xlsx runtime should keep the same broad separation of concerns as the current docx runtime:
-
-- content model
-- review or annotation model
-- preservation model
-- diagnostics and compatibility state
-
-### Content Model
-
-The content model should own:
-
-- workbook metadata
-- sheet registry and ordering
-- sparse cell storage
-- formulas and cached values
-- row and column properties
-- merges
-- workbook-level named items
-- style references and workbook-wide style registries
-
-### Annotation Model
-
-The annotation model should own:
-
-- notes or legacy comments if supported
-- future threaded comment preservation data
-- cell or range anchors for annotations
-
-### Preservation Model
-
-The preservation model should own:
-
-- unknown parts and relationships
-- preserve-only workbook features
-- extension markup and compatibility payloads
-- locked-region metadata required to explain blocked edits
-
-## Sparse Workbook Shape
-
-The canonical workbook should be sparse by default.
-
-That means:
-
-- empty cells are omitted from canonical storage
-- non-default row and column metadata is stored sparsely
-- merges, notes, hyperlinks, and other anchored objects are stored as separate collections
-
-This avoids pretending a spreadsheet is a dense DOM-shaped tree.
-
-## Cell Value Strategy
-
-Canonical cell state should preserve semantic type without coercing everything into a single JavaScript value shape.
-
-Minimum value families:
-
-- empty
-- text
-- number
-- boolean
-- error
-- formula
-- rich or formatted text if supported later, otherwise preserve-only
-
-The runtime may maintain derived caches for display or performance, but canonical state must remain export-safe.
-
-## Formula Strategy
-
-Formulas should be first-class runtime entities even if the editor does not ship a full Excel-compatible calculation engine.
-
-The canonical model should retain:
-
-- formula text
-- reference tokens needed for remapping
-- cached value when present
-- enough structure to support safe row, column, and range edits
-
-If a formula family cannot be remapped safely, the relevant structural edit should warn, block, or remain preserve-only.
-
-## Selection And Anchor Strategy
-
-Selection should be grid-native, not text-editor-shaped.
-
-Minimum runtime selection surfaces:
-
-- active sheet
-- active cell
-- primary range
-- optional multi-range support
-- selection mode for cells, rows, columns, or full-sheet operations
-
-Mapped anchors should also support:
-
-- notes or comments
-- hyperlinks
-- preserve-only object references
-- future named ranges and table surfaces
-
-## Command And Transaction Model
-
-Every mutation should flow through typed spreadsheet commands.
-
-Representative command families:
-
-- set cell value
-- set formula
-- apply styles
-- insert or delete rows
-- insert or delete columns
-- merge or unmerge cells
-- add, rename, reorder, or delete sheets
-- freeze or clear panes
-- add or edit supported note surfaces
-
-Each transaction should produce:
-
-- next workbook state
-- mapping data for remapping selections and anchored objects
-- effects for UI or host notifications
-- history boundary metadata
-
-## Preserve-Only Boundary
-
-The canonical model must not over-claim ownership.
-
-Examples of likely preserve-only workbook surfaces in early xlsx work:
-
-- threaded comments
-- pivot caches and pivot tables
-- charts and complex drawing graphs
-- advanced extension lists
-- rich value families
-- features that require rewriting unknown extension parts
-
-Those surfaces should stay in preservation state until they have package-backed proof and Excel reopen evidence.
-
-## Relationship To The Shared Platform
-
-This doc intentionally stops at workbook semantics.
-
-The following concerns belong to the shared platform instead:
-
-- OPC package reading and writing
-- preserved part reattachment
-- compatibility taxonomy and export blockers
-- validator service integration
-- snapshot and persistence doctrine
-
-See `docs/architecture/platform/shared-openxml-editor-platform.md` for that shared layer.
-
-## Source Research Mapping
-
-This canonical doc is derived from research in:
-
-- `docs/xlsx-react/canonical-workbook-model-and-commands.md`
-- `docs/xlsx-react/spreadsheet-editor-component-architecture.md`
-- `docs/xlsx-react/spreadsheet-editor-frontend-architecture.md`
-
-The research sources remain useful design rationale, but this file is the repo-aligned planned canonical model reference.

package/docs/architecture/xlsx/spreadsheet-editor-frontend-architecture.md

@@ -1,150 +0,0 @@
-# Spreadsheet Editor Frontend Architecture
-
-## Status
-
-- Planned canonical architecture for the future `xlsx` runtime.
-- No `SpreadsheetEditor` implementation is shipped in this repo today.
-- This doc translates the strongest `docs/xlsx-react` research into a repo-aligned architecture that matches the current runtime-first philosophy without pretending the source already exists.
-
-## Role In The Repo
-
-This document is the `xlsx` sibling to the current docx frontend architecture.
-
-Use it together with:
-
-- `docs/architecture/platform/shared-openxml-editor-platform.md`
-- `docs/architecture/xlsx/canonical-workbook-model-and-commands.md`
-- `docs/reference/xlsx/xlsx-ooxml-compliance.md`
-- `docs/plans/xlsx/xlsx-fixture-corpus-and-certification-plan.md`
-
-## Frontend Doctrine
-
-- The workbook runtime owns canonical truth.
-- React renders runtime projections and dispatches commands.
-- The grid surface is spreadsheet-native and performance-driven.
-- UI state remains presentation-only: tabs, panel visibility, theme, and transient edit buffers.
-- Export safety and preserve-only states are visible in the UI instead of being hidden behind implicit behavior.
-
-## Editor Shape
-
-The target public surface is a single embeddable component:
-
-```tsx
-<SpreadsheetEditor />
-```
-
-That component should remain uncontrolled by default, matching the current `WordReviewEditor` philosophy:
-
-- host provides initial source or snapshot
-- runtime owns the live session
-- host receives typed events, warnings, errors, snapshots, and exports
-
-## Rendering Stack
-
-The spreadsheet editor should keep the same broad discipline as the docx runtime while using spreadsheet-appropriate rendering:
-
-- React shell for layout, panels, and tool surfaces
-- imperative or headless grid surface controller for scrolling, hit-testing, and keyboard flow
-- runtime-owned render snapshot consumed through `useSyncExternalStore`
-- token-driven theme system rather than one-off inline styling
-
-## High-Level Component Hierarchy
-
-```text
-SpreadsheetEditor
-└── SpreadsheetWorkspace
-    ├── TopBar
-    │   ├── NameBox
-    │   ├── FormulaBar
-    │   └── Toolbar
-    ├── GridViewport
-    │   ├── GridSurfaceHost
-    │   └── GridOverlays
-    ├── RightRail
-    │   ├── CommentsOrNotes
-    │   └── HealthPanel
-    ├── SheetTabs
-    └── StatusBar
-```
-
-## Runtime And UI Boundary
-
-The boundary should match the current repo's strongest invariant:
-
-```text
-UI -> Command -> Transaction -> State Update -> Render
-```
-
-Rules:
-
-- React never owns workbook truth.
-- The grid surface never bypasses the runtime.
-- Formula edits, range edits, merge edits, and structural sheet edits all flow through typed commands.
-- Render snapshots may be denormalized for visible regions, but persisted snapshots stay separate.
-
-## Module Boundaries
-
-Target source ownership for the `xlsx` frontend should stay explicit:
-
-```text
-src/formats/xlsx/
-  api/
-  model/
-  core/
-    commands/
-    selection/
-    formulas/
-    grid-math/
-  io/
-  preservation/
-  validation/
-  runtime/
-  ui/
-    headless/
-    grid-surface/
-    react/
-```
-
-This is a target-state layout, not a claim that these directories already exist.
-
-## Capability Model
-
-The editor should derive session capabilities from runtime state rather than local UI guesses.
-
-Minimum capability surfaces:
-
-- `canEdit`
-- `canUndo`
-- `canRedo`
-- `canExport`
-- `exportBlocked`
-- `preserveOnlyCount`
-- `unsupportedFatalCount`
-- `canEditFormulas`
-
-## UX Honesty Rules
-
-- Spreadsheet features are either `supported-roundtrip`, `preserve-only`, or `unsupported-fatal`.
-- Preserve-only content must remain visible and explainable.
-- Locked or blocked regions must surface through the health rail and status bar.
-- Unsupported structures must not be rewritten optimistically.
-
-## Current Scope Boundary
-
-This architecture is intentionally for the future `xlsx` runtime only.
-
-It does not change:
-
-- the current `WordReviewEditor` public API
-- the docx-specific ProseMirror editing surface
-- the current docx wave maturity line
-
-## Source Research Mapping
-
-This canonical doc is derived from research in:
-
-- `docs/xlsx-react/spreadsheet-editor-frontend-architecture.md`
-- `docs/xlsx-react/spreadsheet-editor-component-architecture.md`
-- `docs/xlsx-react/canonical-workbook-model-and-commands.md`
-
-The research papers remain useful source material, but this file is the repo-aligned planned architecture reference.