@beyondwork/docx-react-component 1.0.0

package/docs/plans/waves/deferred/encrypted-intake-contracts.md

@@ -0,0 +1,282 @@
+# Deferred Wave - Encrypted Intake Contracts
+
+## Purpose
+
+This packet preserves the previously proposed component-owned encrypted-intake contract as a deferred option.
+
+It is not part of the active Wave 8 through Wave 10 plan because encrypted handling is currently upstream-owned.
+
+It does not replace the Wave 1 contract set. It extends it with a narrow later-wave packet because password-to-open `.docx` handling introduces:
+
+- pre-import container routing
+- sensitive password handling
+- runtime-owned challenge state
+- explicit export warnings for decrypted sessions
+
+## Governing Inputs
+
+- [README.md](/home/coder/docx-react-component/README.md)
+- [docs/reference/repository-guidance.md](/home/coder/docx-react-component/docs/reference/repository-guidance.md)
+- [docs/reference/public-api.md](/home/coder/docx-react-component/docs/reference/public-api.md)
+- [docs/reference/ooxml-compliance.md](/home/coder/docx-react-component/docs/reference/ooxml-compliance.md)
+- [docs/plans/master-plan.md](/home/coder/docx-react-component/docs/plans/master-plan.md)
+- [docs/reference/deep-research-report (15).md](/home/coder/docx-react-component/docs/reference/deep-research-report%20%2815%29.md)
+
+## Contract Scope
+
+This packet governs only password-to-open OOXML intake.
+
+It covers:
+
+- encrypted-container detection before OOXML parse
+- decrypt-to-OPC routing for supported ECMA-376 Office encryption
+- runtime-owned password challenge state and UI projection
+- export posture for documents opened through decrypt
+- dedicated encrypted-fixture proof requirements
+
+It does not change the core OOXML feature taxonomy. After a successful decrypt, the existing import, preservation, review, export, and validation contracts apply unchanged.
+
+## Terminology
+
+- `password-to-open` means an encrypted Office container that must be decrypted before any OOXML part can be read.
+- `document protection` or `restrict editing` remains in-package OOXML policy markup and is not part of this intake contract.
+- `IRM` and policy-bound encryption remain out of scope for v1.
+
+## Non-Negotiable Rules
+
+- Encrypted detection happens before any normal OPC or OOXML importer logic.
+- The normal OOXML importer must never receive encrypted bytes.
+- Decrypt must complete before canonical import begins.
+- Passwords, derived keys, and decrypted raw package bytes must never enter canonical state, persisted snapshots, datastore adapters, or host-visible diagnostics.
+- Unsupported encryption must fail explicitly; do not downgrade to empty or partial import.
+- Export after decrypt must not silently imply re-encryption.
+
+## Public Surface Contract
+
+The repo keeps one public component surface: `WordReviewEditor`.
+
+The encrypted-input contract is:
+
+- `initialDocx` and `externalDocSource.kind = "docx"` may contain either:
+- normal OPC `.docx` bytes
+- supported password-to-open OOXML Office containers
+- no standalone `importDocument()` API is added in v1
+- no host-supplied password callback is required in the baseline Wave 8 surface
+
+Wave 8 baseline uses component-managed password UX inside the editor shell.
+
+Future host-managed continuation is allowed only through an explicit public-API revision after pilot evidence proves the need.
+
+## Internal Ownership
+
+### `src/io`
+
+Owns:
+
+- source-byte normalization helpers used by the decrypt route
+- container sniffing
+- encrypted-container detection
+- decrypt-to-OPC routing
+- MS-OFFCRYPTO parsing and decrypt helpers
+
+Must not:
+
+- mutate canonical state directly
+- render UI
+
+### `src/runtime`
+
+Owns:
+
+- import state machine
+- source-replacement lifecycle
+- redacted status and warning projection
+- import cancellation and cleanup orchestration
+
+Must not:
+
+- persist password state
+- bypass the `src/io` decrypt route
+
+### `src/ui`
+
+Owns:
+
+- password prompt UI
+- import progress UI
+- export warning interstitial for decrypted sessions
+
+Must not:
+
+- parse encrypted containers
+- hold authoritative password state in React-owned snapshots
+
+### `src/validation`
+
+Owns:
+
+- compatibility and export-risk reporting after canonical import
+- sensitive-error redaction helpers for surfaced diagnostics
+
+Must not:
+
+- become the primary decrypt or package transformation engine
+
+## Container Routing Contract
+
+The intake order is frozen:
+
+1. normalize source bytes
+2. enforce source-size limits
+3. sniff container kind
+4. route:
+- `opc_zip` -> normal OOXML import
+- `encrypted_office` -> password challenge then decrypt
+- anything else -> fail safely
+5. if decrypt succeeds, validate decrypted bytes as OPC
+6. only then run the existing OOXML importer
+
+Required route outcomes:
+
+- `opc_zip`
+- `encrypted_office`
+- `unsupported_file_type`
+- `invalid_container`
+
+## Supported Encryption Scope
+
+Wave 8 v1 support is limited to:
+
+- ECMA-376 Standard encryption
+- ECMA-376 Agile encryption
+
+Wave 8 v1 explicitly excludes:
+
+- legacy RC4 Office encryption
+- extensible providers
+- IRM or policy-bound encryption
+- binary `.doc`
+- re-encrypt-on-export
+
+Unsupported schemes must fail with explicit user-facing and machine-readable error codes.
+
+## Runtime State Contract
+
+The import state machine is runtime-owned and redacted before React sees it.
+
+Minimum states:
+
+- `idle`
+- `reading_source`
+- `sniffing_container`
+- `password_required`
+- `decrypting`
+- `importing_ooxml`
+- `ready`
+- `failed`
+- `cancelled`
+
+Rules:
+
+- React may render a projection of this state, not own the authoritative password flow
+- starting a new source load aborts the in-flight import job and clears transient secrets
+- failure and cancel paths clear transient decrypted buffers and password references
+
+## Security And Cleanup Contract
+
+- Passwords must not be stored in canonical state, persisted snapshots, local storage, or logs.
+- Passwords must not be emitted through telemetry, `EditorError.details`, or exported diagnostics.
+- Decrypted buffers are transient and should be actively cleared when practical after import or failure.
+- Progress and failure reporting must stay secret-free.
+- Wave 8 must prove that encrypted bytes do not reach the normal OOXML importer.
+
+## Export Contract For Decrypted Sessions
+
+Wave 8 freezes this v1 behavior:
+
+- documents opened through decrypt export as normal unencrypted `.docx`
+- the first export per session must warn explicitly that the output will not be encrypted
+- cancelling the warning must cancel export
+- automatic re-encryption is not part of v1
+
+If a future host post-process hook is added, it must be explicit and documented as a host-side responsibility rather than editor-owned encryption.
+
+## Error Contract
+
+The encrypted-intake slice adds or clarifies these error codes:
+
+- `password_required`
+- `wrong_password`
+- `unsupported_encryption`
+- `malformed_encrypted_container`
+- `decrypt_engine_failure`
+- `invalid_decrypted_payload`
+- `unsupported_file_type`
+- `invalid_container`
+- `file_too_large`
+- `cancelled`
+
+Rules:
+
+- wrong password is retryable
+- unsupported encryption is fatal
+- malformed encrypted container is fatal
+- decrypted bytes that are not valid OPC fail before canonical import
+
+## Fixture Program
+
+Encrypted intake uses a separate durable corpus under `test/fixtures/encrypted-docx/`.
+
+Frozen fixture IDs:
+
+- `E01` Agile encrypted basic contract
+- `E02` Standard encrypted basic contract
+- `E03` Wrong-password retry contract
+- `E04` Unsupported legacy encryption
+- `E05` Malformed encrypted container
+- `E06` Encrypted comments-and-redlines contract
+- `E07` Encrypted preserve-only package contract
+- `E08` Source-size and decrypt-limit stress contract
+
+This corpus supplements `F01` through `F21`; it does not renumber them.
+
+## Proof Program By Wave
+
+### Wave 8
+
+- baseline-prove local encrypted intake
+- prove sniff -> decrypt -> import routing on `E01` through `E08`
+- prove the export warning for decrypted sessions
+- prove cleanup, redaction, and wrong-password retry handling
+
+### Wave 9
+
+- keep the harness baseline honest about encrypted uploads and secret handling
+- do not overclaim pilot-live encrypted editor behavior yet
+
+### Wave 10
+
+- pilot the encrypted editor loop on Railway with selected encrypted fixtures
+- capture live artifacts for at least one Agile and one Standard encrypted fixture
+
+### Wave 11
+
+- include encrypted fixtures in the final QA bundle
+- capture final Word reopen notes for exported decrypted sessions
+
+## Interface Impacts
+
+| Surface | Owner | Contract impact |
+| --- | --- | --- |
+| `docs/reference/public-api.md` | A9 | Keep encrypted intake on the existing component load surface; do not introduce a standalone import API in v1. |
+| `docs/reference/ooxml-compliance.md` | A9 | Clarify that encrypted files are an intake mode, not an OOXML feature-class row. |
+| `test/fixtures/encrypted-docx/README.md` | A5 | Freeze the encrypted-fixture registry and wave ownership. |
+| `docs/plans/component-cutover-matrix.*` | A9 | Track the new encrypted-intake component separately from normal OOXML feature breadth. |
+
+## Frozen Non-Goals
+
+- re-encrypt-on-export in v1
+- IRM or enterprise key-management integration
+- background decrypt via Web Workers
+- partial open without full decrypt
+- bypassing document-protection policy markup

package/docs/plans/waves/deferred/legal-feedback-wave-expansion.md

@@ -0,0 +1,308 @@
+# Deferred Wave - Legal Fidelity Expansion
+
+Historical note: this packet was later promoted into [docs/plans/waves/wave-12.md](/home/coder/docx-react-component/docs/plans/waves/wave-12.md). Keep this file as the precursor rationale and gap inventory; the authored Wave 12 doc is now the active plan.
+
+**Commit message**: `Build: add post-v1 legal fidelity expansion packet`
+
+## Component promotions
+
+- canonical-document-model: baseline-proved
+- command-and-transaction-runtime: baseline-proved
+- comments-and-anchor-mapping: baseline-proved
+- tracked-changes-and-review-actions: baseline-proved
+- docx-import-and-normalization: baseline-proved
+- docx-export-and-serialization: baseline-proved
+- unsupported-ooxml-preservation: baseline-proved
+- compatibility-and-word-validation: baseline-proved
+- react-editor-ui: baseline-proved
+
+## Scope note
+
+This packet is not part of the active numbered wave sequence. It is the historical pre-promotion packet that fed the authored Wave 12 plan.
+
+It preserves a post-v1 architecture expansion driven by legal-review feedback and
+should only be promoted after Wave 11 closes and the current v1 surface is stable.
+
+This packet owns:
+
+- first-class canonical table nodes
+- table-aware selection and command routing
+- table-aware comment and revision mapping for the supported slice
+- curated approximate web-font rendering for browser readability
+- explicit font-substitution diagnostics
+- proof expansion for table semantics and browser-font approximation
+
+This packet does not own:
+
+- exact Word pagination parity
+- exact native-font parity with Word on user machines
+- full structural tracked revisions for rows, columns, merges, or splits
+- full Word style-definition editing
+- editable headers, footers, notes, fields, or section layout as part of the same wave
+- OLE, macros, or advanced Word automation
+
+## Why This Must Not Fold Into Waves 8 Through 11
+
+Waves 8 through 11 are already proof-first closure waves for the declared v1
+surface:
+
+- Wave 8: harness and validator baseline
+- Wave 9: pilot-live editor loop
+- Wave 10: QA certification
+- Wave 11: fleet-ready package and demo story
+
+Folding this packet into those waves would:
+
+- widen the certified support boundary mid-closure
+- mix new architecture work into proof and release waves
+- weaken the honesty of current `baseline-proved`, `qa-proved`, and `fleet-ready`
+  claims
+- force docs and proof bundles to overclaim support that the current runtime does
+  not yet own
+
+This expansion was later promoted as `wave-12` after the v1 closure line was separated from the post-v1 legal-fidelity scope.
+
+## Governing Inputs
+
+- `README.md`
+- `docs/legal-feedback-architecture.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/api/public-types.ts`
+
+## Entry criteria
+
+- Wave 11 closure is complete or explicitly frozen enough that the active v1
+  support boundary will not change during this packet.
+- README, public API docs, compliance docs, and current-state notes all align on
+  the existing v1 claims.
+- The repo still treats exact pagination and native Word rendering parity as
+  non-goals.
+- There is explicit agreement that table architecture and browser-font
+  approximation are post-v1 expansion work rather than quiet v1 widening.
+
+## Promotion target
+
+If promoted into the numbered sequence, this packet should target:
+
+- `repo-landed` for new canonical and runtime surfaces
+- `baseline-proved` for table import or export or UI or validator proof on the
+  supported slice
+
+It should not target `pilot-live`, `qa-proved`, or `fleet-ready` in the same
+wave. Those belong to later proof and release waves after the new support slice
+is landed and bounded.
+
+## Promotion conditions
+
+- canonical content has first-class typed table nodes rather than treating all
+  body-level `w:tbl` content as opaque blocks
+- runtime selection and command flows support in-cell editing on the supported
+  slice
+- table import and export remain package-safe and preserve unsupported table
+  descendants honestly
+- browser typography uses curated approximation rather than false Word parity
+- font substitution is surfaced through explicit runtime warnings
+- mounted-shell proof exists for the new supported table slice
+- validator and Word reopen evidence remain explicit and bounded
+
+## Context7 defaults
+
+- bundle: word-editor-runtime
+- query: "first-class table schema, table-aware selection and mapping, curated browser-font approximation, and legal-review-safe proof expansion"
+
+## Deliverables By Subsystem
+
+### `src/model`
+
+Own:
+
+- typed canonical table nodes
+- stable table, row, and cell identity
+- supported cell content ownership
+- preserved unsupported table property attachments
+
+Expected deliverables:
+
+- canonical table subtree definitions
+- updated document validation rules
+- snapshot compatibility for table-bearing documents
+
+### `src/core`
+
+Own:
+
+- table-aware selection primitives
+- cell-local text routing
+- table structural commands
+- anchor remapping rules for comments and revisions within supported table edits
+
+Expected deliverables:
+
+- selection model extensions
+- table command handlers
+- transaction safety around structural edits
+
+### `src/io`
+
+Own:
+
+- `w:tbl` import into typed canonical content
+- supported table export back to `w:tbl`
+- preserved unsupported descendants and properties
+- source-backed font intent retention where possible
+
+Expected deliverables:
+
+- main-document importer integration for typed tables
+- table serializer integration on the main export path
+- explicit browser-font approximation notes that do not change OOXML export
+  guarantees silently
+
+### `src/runtime`
+
+Own:
+
+- runtime snapshots for typed table blocks
+- table-aware selection state
+- comment and revision projection for cell-local supported edits
+- warning emission for font substitution or degraded browser typography states
+
+Expected deliverables:
+
+- runtime projection additions for tables
+- warning plumbing for `font_substitution`
+- export posture rules that keep browser approximation non-destructive
+
+### `src/ui`
+
+Own:
+
+- runtime-backed table surface rendering
+- cell focus and selection affordances
+- comment and revision cues inside cells
+- curated browser typography application and substitution messaging
+
+Expected deliverables:
+
+- mounted table surface in the shipped `WordReviewEditor` path
+- explicit preserve-only or degraded badges for unsupported table behaviors
+- calm substitution and compatibility cues for approximate font rendering
+
+### `services/react-word-editor`
+
+Own:
+
+- prototype and harness convergence toward the real table and font posture
+- sample sessions that demonstrate supported tables and font approximation honestly
+
+Expected deliverables:
+
+- updated internal demo sessions
+- non-production messaging that remains explicit
+- no prototype-only behavior that overclaims runtime support
+
+## Required Fixture Additions
+
+The existing `F01` through `F21` corpus remains frozen as the v1 minimum.
+
+If this packet is promoted, add a later-wave extension corpus or clearly named
+new fixtures rather than rewriting the meaning of the existing minimum corpus.
+
+Recommended additions:
+
+- table fixture for typed import and in-cell edit proof
+- merged-cell fixture that survives supported edits without opaque fallback
+- table-comments fixture with cell-anchored comment proof
+- table-redline fixture for supported in-cell insert and delete behavior
+- mixed-font fixture with representative legal-document font variation
+- missing-font substitution fixture for browser approximation warning proof
+
+Scenario additions:
+
+- table-heavy scenario artifact with realistic legal schedules
+- typography-variant scenario artifact where browser approximation is visible but
+  Word reopen remains intact
+
+## Required Proof Artifacts
+
+If this packet is promoted, closure should require durable artifacts under a new
+wave-specific directory such as `.tmp/wave-12-legal-fidelity/`.
+
+Minimum proof artifacts:
+
+- `table-runtime-roundtrip-report.json`
+- `table-session-edit-report.json`
+- `table-ui-interaction-report.json`
+- `table-compatibility-report.json`
+- `font-substitution-report.json`
+- `font-package-preservation-report.json`
+- `word-reopen-notes.md`
+
+## Required Test Expansion
+
+The proof program should extend existing repo conventions rather than inventing a
+new style.
+
+Required layers:
+
+- synthetic XML tests for narrow table and font semantics
+- package-backed session tests for real fixture truth
+- mounted `WordReviewEditor` interaction tests
+- compatibility taxonomy tests
+- wave review docs with fixture-by-fixture evidence
+
+Concrete gaps this packet must close:
+
+- no first-class table nodes in canonical content today
+- main-document import currently downgrades non-paragraph body children to
+  `opaque_block`
+- table prototype support is `_prototypeOnly` today
+- `font_substitution` exists as a warning type but is not yet an active proved
+  runtime behavior
+
+## Shared-Doc Sync Required If Promoted
+
+If this packet is accepted into a numbered wave, the promoting change must also
+sync the shared planning and reference set:
+
+- `docs/plans/master-plan.md`
+- `docs/plans/current-state.md`
+- `docs/roadmap.md`
+- `docs/plans/component-cutover-matrix.md`
+- `docs/plans/component-cutover-matrix.json`
+- `docs/reference/public-api.md` if runtime or host contracts change
+- `docs/reference/ooxml-compliance.md`
+- fixture registry docs under `test/fixtures/`
+
+The promotion must keep bounded claims bounded. No doc may imply native Word
+visual parity or support for broader OOXML surfaces unless proof exists.
+
+## Frozen Non-Goals
+
+- exact Word pagination and page-break parity
+- exact native-font rendering parity in browser environments
+- unrestricted Word-style font pickers
+- tracked structural revisions for rows, columns, merge, and split in the first
+  expansion slice
+- broadening preserve-only package parts into editable surfaces by convenience
+- OLE, macros, advanced automation, or enterprise Word edge cases
+
+## Bottom Line
+
+This packet is a good post-v1 expansion because it deepens legal-review
+credibility in places the product actually needs:
+
+- tables as meaningful legal objects
+- browser typography that is more legible and predictable
+- trust cues around approximation rather than false parity
+
+It should remain deferred until the active Wave 8 through Wave 11 closure path is
+finished, then promoted as a new bounded architecture wave rather than smuggled
+into the current certification sequence.