@beyondwork/docx-react-component 1.0.0 → 1.0.2

package/docs/legal-feedback-architecture.md

@@ -1,498 +0,0 @@
-# Legal Feedback Architecture
-
-## Purpose
-
-This memo captures how the legal feedback maps onto the current `WordReviewEditor`
-architecture, what is already credible to claim, what should remain explicitly
-deferred, and how the repo can expand toward first-class tables plus approximate
-curated web-font rendering without breaking its core invariants.
-
-This is a decision memo, not a scope expansion claim. It distinguishes:
-
-- current runtime truth
-- recommended next architecture
-- proof required before public claims widen
-
-## Governing Inputs
-
-- `README.md`
-- `docs/reference/public-api.md`
-- `docs/reference/ooxml-compliance.md`
-- `docs/plans/master-plan.md`
-- `docs/plans/current-state.md`
-- `docs/plans/waves/README.md`
-- `src/model/canonical-document.ts`
-- `src/io/ooxml/parse-main-document.ts`
-- `src/runtime/surface-projection.ts`
-- `src/ui/WordReviewEditor.tsx`
-- `services/react-word-editor/components/harness-workspace-page.tsx`
-- `services/react-word-editor/components/harness-editor-session-client.tsx`
-- `src/ui/review/prototype-review-workspace.tsx`
-- `services/react-word-editor/lib/demo-fixtures.ts`
-
-## Current Architecture Reality Check
-
-The repo is already pointed in the right product direction. It is not trying to
-be a browser clone of Microsoft Word. It is trying to be a Word-compatible legal
-review system with:
-
-- a canonical schema-based document model
-- command and transaction ownership of edits
-- explicit compatibility reporting
-- preserve-only handling for unsupported OOXML
-- package-safe import and export
-
-That posture is correct and should remain fixed.
-
-The important current constraints are:
-
-- canonical document content currently models `paragraph` and `opaque_block`
-  block-level content, not first-class tables
-- the main document importer currently downgrades non-paragraph body children to
-  `opaque_block`
-- the live surface projection currently renders paragraphs plus preserve-only
-  blocks, not runtime-backed table blocks
-- the current text model does not carry imported DOCX font-family semantics as
-  active canonical editing state
-- `font_substitution` exists as a warning type in the public contracts, but it is
-  not yet an active proved runtime behavior
-
-In other words, the runtime is already strong where the problem is:
-
-- text structure
-- anchoring
-- comments
-- supported insert/delete revisions
-- package preservation
-- explicit trust surfaces
-
-It is not yet strong where the problem is:
-
-- table structure as a first-class editable document object
-- browser rendering based on imported DOCX font intent
-- Word layout parity
-- generated field semantics
-- advanced page-layout or floating-object behavior
-
-## What The Legal Feedback Gets Right
-
-The legal feedback is directionally correct in three important ways.
-
-First, lawyers do not judge credibility by generic rich-text breadth. They judge
-it by whether the editor preserves meaning under review, especially for:
-
-- revisions
-- comments
-- numbering
-- tables
-- references
-- versions
-- controlled editing boundaries
-
-Second, visual fidelity alone is not enough. Stable anchors, structured editing,
-review semantics, and round-trip safety matter more than a superficially Word-like
-page.
-
-Third, the feedback is right that the product should be built in this order:
-
-1. strict structural document model
-2. revision and anchoring system
-3. legal semantics layer
-4. DOCX translation layer
-
-That ordering already matches the repo's design intent and should continue to
-govern expansion work.
-
-## Recommended Fidelity Targets
-
-The legal feedback's `Layer 0` through `Layer 5` model is useful, but it needs to
-be reset to fit the current architecture honestly.
-
-### Credible Now Or Near-Term
-
-#### Layer 5 or close to it
-
-- paragraphs and character runs for the supported text slice
-- supported comments and comment threads on text ranges
-- supported tracked insertions and deletions
-- headings through style references
-- nested lists and restart numbering for the supported numbering slice
-
-#### Layer 4 next, not yet full Layer 5
-
-- clause-aware heading and numbering semantics
-- bookmarks and stable anchors
-- versions and compare infrastructure
-- styles as policy and validation
-- defined terms
-- cross-reference infrastructure
-
-#### Layer 2 to 3 now
-
-- inline images as whole-unit review objects
-- hyperlinks
-- print-awareness and pagination cues
-- prototype-only table storytelling in the demo harness
-
-### Preserve-Only For Now
-
-These should remain explicit preserve-only surfaces until the repo owns their
-full import, canonical representation, edit semantics, export, and Word reopen
-behavior:
-
-- sections and page setup
-- headers and footers
-- footnotes and endnotes
-- fields and generated indexes
-- SDTs and content controls
-- embedded objects and OLE payloads
-- unknown OOXML and package parts
-- floating shapes, text boxes, and advanced DrawingML layout
-
-### Non-Goals For This Expansion
-
-- exact Word pagination parity
-- exact line-break parity
-- native installed-font parity across browsers and operating systems
-- full Word ribbon behavior
-- support claims based on static demo visuals alone
-
-## Recommended Table Architecture Expansion
-
-### Decision
-
-Tables should enter canonical content as first-class block nodes, not remain
-preserve-only blocks and not be faked only in the prototype.
-
-### Proposed Canonical Shape
-
-Add a typed table subtree under canonical content:
-
-- `TableNode`
-- `TableRowNode`
-- `TableCellNode`
-
-Each level needs stable identity:
-
-- `tableId`
-- `rowId`
-- `cellId`
-
-Each cell should own normal block content, starting with a conservative subset:
-
-- `ParagraphNode`
-- `OpaqueBlockNode`
-
-Cell metadata should capture structural facts the runtime needs to preserve and
-edit safely:
-
-- `rowSpan`
-- `colSpan`
-- merge topology
-- width hints or preserved width metadata
-- header-row or header-cell hints
-- preserved unsupported table properties
-
-### Editing Model
-
-Do not force tables into the current flat text-story abstraction.
-
-Instead, extend the runtime with a document-level selection model that can
-distinguish:
-
-- text range within a cell
-- cell selection
-- table selection
-
-The command system should split into:
-
-- cell-local text commands that reuse the current text engine
-- table structural commands for rows, columns, merges, and selection movement
-
-Recommended first serious table scope:
-
-- in-cell text editing
-- stable import and export of row and cell structure
-- merged-cell preservation
-- selection between cells
-- comments anchored to cells or cell ranges
-- supported insert/delete revisions inside cells
-
-Explicitly defer in the first architecture expansion:
-
-- tracked structural row and column revisions
-- tracked merge and split semantics
-- complete table style editing
-- full Word table layout parity
-
-### Import And Export Path
-
-The current `parse-main-document` path should stop treating every non-paragraph
-body child as `opaque_block` once the table slice is adopted.
-
-The importer should:
-
-- parse `w:tbl` into typed `TableNode` content
-- parse supported rows, cells, and merge structure into canonical state
-- preserve unsupported table descendants and properties as attached preserved
-  records rather than discarding them
-- fall back to preserve-only only when a table cannot be represented safely
-
-The exporter should:
-
-- serialize typed canonical tables back to `w:tbl`
-- preserve stable relationships and supported geometry
-- reattach preserved table properties and descendants when safe
-- block only when unsupported-fatal rewrites would be required
-
-### Runtime And UI Implications
-
-The runtime surface projection needs a real table view model rather than only
-paragraph and opaque-block projection.
-
-The UI should render:
-
-- real table blocks from runtime state
-- per-cell editing surfaces
-- comment and revision decorations inside cells
-- explicit preserve-only badges for unsupported table features
-- honest degraded or locked states where the runtime cannot safely expose deeper
-  editing
-
-This is architecture-compatible because it preserves the repo's core boundary:
-the runtime owns state, the UI renders projections, and unsupported OOXML is
-preserved rather than normalized away.
-
-## Recommended Approximate Font Architecture
-
-### Decision
-
-Do not pursue native Word font parity in the browser.
-
-Instead, add a curated web-font approximation layer that improves readability and
-visual consistency while preserving DOCX font intent on import and export where
-possible.
-
-### Product Posture
-
-The product should promise:
-
-- readable legal-document typography in the browser
-- consistent curated font rendering across supported environments
-- explicit approximation rather than false parity
-- preservation of DOCX font metadata where the editor is not rewriting it
-
-The product should not promise:
-
-- browser rendering identical to Word on the user's machine
-- line wrapping or pagination identical to Word
-- exposure of the full DOCX font system in the editing UI
-
-### Proposed Render Model
-
-Split font behavior into two layers.
-
-#### 1. Document font intent
-
-This is the DOCX-facing side:
-
-- imported font-family intent where modeled or preserved
-- exported `w:rFonts` behavior
-- source-package font tables and theme parts
-
-#### 2. Browser render profile
-
-This is the browser-facing side:
-
-- a small curated legal-reading font set
-- deterministic fallback behavior
-- explicit substitution signaling
-
-Recommended built-in curated roles:
-
-- `legalSerif`
-- `legalSans`
-- `legalMono`
-
-Recommended behavior:
-
-- map imported DOCX fonts to one of the curated roles for browser rendering
-- use those curated roles consistently inside the editor surface
-- preserve original DOCX font intent when round-tripping source-backed sessions
-- emit `font_substitution` warnings when imported font intent cannot be rendered
-  as requested in the browser
-
-### UI Scope
-
-If font choice is exposed at all in the editing UI, keep it constrained to the
-curated families rather than a Word-style full font picker.
-
-That means:
-
-- a limited family selector or typography preset control
-- no claim of native installed-font fidelity
-- no script-slot editing for `ascii`, `hAnsi`, `cs`, or East Asian font slots in
-  the first slice
-
-### Why This Fits The Current Architecture
-
-The repo is already stronger at structural and package truth than layout truth.
-Approximate curated font rendering builds on that reality instead of fighting it.
-
-It also keeps the legal-review surface calm and legible, which aligns with
-`DESIGN.md`.
-
-## Prototype Implications
-
-The internal `/demo` prototype is useful, but it must remain architecture-true.
-
-That means:
-
-- it may visualize future table behavior before the runtime lands
-- it may demonstrate curated font approximation choices
-- it must not imply editable support the runtime does not actually own
-- it must keep prototype-only additions clearly tagged
-
-Today the prototype uses `_prototypeOnly` table blocks and mock fixture types that
-structurally mirror the runtime snapshot. That is acceptable as a design surface,
-but only if it stays honest about what is real runtime behavior versus UX
-exploration.
-
-Prototype work should therefore converge toward:
-
-- runtime-shaped table block projections
-- preserved-region trust cues
-- compatibility and substitution messaging
-- curated typography tokens
-
-Prototype work should not introduce:
-
-- DOM-owned editing semantics
-- fake table support that bypasses canonical structure
-- fake font parity claims
-- review semantics that do not map back to runtime-owned anchors and commands
-
-## Proof And Test Requirements
-
-No support claim should widen without new proof on the same terms as the existing
-repo proof program.
-
-### Existing Proof Model To Reuse
-
-The repo already has the right proof posture:
-
-- frozen release-gate fixture corpus under `F01` through `F21`
-- separate scenario artifacts for representative real-world documents
-- synthetic XML tests for narrow semantic correctness
-- package-backed session tests for runtime truth
-- mounted `WordReviewEditor` interaction tests for user-visible behavior
-- compatibility taxonomy proof for `supported-roundtrip`, `preserve-only`, and
-  `unsupported-fatal`
-- durable `.tmp/wave-*` artifacts for closure
-
-Any expansion proposal should keep that model intact.
-
-### Table Proof Needed Before Wider Claims
-
-First-class tables need proof at all of these layers:
-
-#### Canonical and importer proof
-
-- typed `TableNode` import from real DOCX fixtures
-- merge topology preservation
-- unsupported table-descendant preservation
-
-#### Runtime and session proof
-
-- package-backed `loadDocxEditorSession(...)` imports real table fixtures into
-  typed canonical table state
-- in-cell text edits survive export without destructive fallback
-
-#### UI proof
-
-- mounted `WordReviewEditor` interaction test for entering a cell, editing text,
-  and exporting
-- comment anchoring and selection behavior inside cells
-
-#### Compatibility proof
-
-- supported tables classify as `supported-roundtrip`
-- unsupported table behaviors classify as `preserve-only`
-- unsupported-fatal cases fail closed
-
-#### Validator and closure proof
-
-- source and edited exports validate through the existing package validation path
-- wave review doc records fixture-by-fixture outcomes and durable artifacts
-
-### Font Proof Needed Before Wider Claims
-
-Approximate curated font rendering needs a different proof bar from Word layout
-parity.
-
-The required proof should show:
-
-- imported DOCX font intent is preserved or mapped non-destructively
-- source-backed sessions do not drop `fontTable.xml` or related font/theme data
-  during export
-- browser substitution triggers explicit `font_substitution` warnings
-- substitution does not silently block export unless another fatal condition is
-  present
-- representative Word reopen checks still pass
-
-The required proof should not demand:
-
-- pixel-identical browser rendering
-- exact page-layout equivalence with Word
-
-### Recommended New Test Surfaces
-
-Current repo conventions suggest the following kinds of additions when this work
-is eventually implemented:
-
-- new `test/io/*` import/export tests for typed tables and font-preservation paths
-- package-backed session proof alongside `test/io/docx-session.test.ts`
-- new mounted-shell interaction proof alongside
-  `test/ui/word-review-editor.interaction.test.tsx`
-- compatibility and warning proof under `test/validation/*`
-- later-wave review docs under `docs/plans/waves/reviews/`
-
-## What Should Remain Deferred
-
-Even after first-class tables and curated web-font rendering are added, these
-should remain deferred unless a later wave explicitly owns them:
-
-- exact Word print and pagination parity
-- structural tracked revisions for rows, columns, and merge operations
-- full Word style-definition editing
-- generated-field authoring and refresh semantics
-- general editable support for headers, footers, notes, or sections
-- OLE, macros, or advanced automation surfaces
-
-## Recommended Sequence
-
-The cleanest sequence is:
-
-1. keep Waves 8 through 11 focused on proof, pilot, QA, and fleet readiness for
-   the currently declared v1 surface
-2. preserve the legal-feedback expansion as a deferred packet
-3. promote it only as a later numbered wave after the current sequence closes
-4. widen public claims only after runtime, fixture, validator, and Word reopen
-   proof all exist
-
-## Bottom Line
-
-The legal feedback is right about where product credibility comes from, but the
-current architecture can only claim part of that vision honestly today.
-
-The most architecture-compatible next step is:
-
-- first-class canonical tables
-- table-aware runtime selection and commands
-- curated approximate web-font rendering
-- explicit substitution diagnostics
-- the same proof discipline already used elsewhere in the repo
-
-The repo should not chase Word visual parity first. It should extend the
-structured runtime in the areas where legal meaning and review trust depend on it,
-and keep the browser rendering layer honest about approximation.