@beyondwork/docx-react-component 1.0.0 → 1.0.2

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

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

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