@beyondwork/docx-react-component 1.0.109 → 1.0.111

package/src/api/v3/README.md

@@ -1,91 +0,0 @@
-# `src/api/v3/` — End-state public API surface
-
-> **@endStateApi v3** — the canonical Beyond Work build-team contract.
-> Do NOT treat this as a rename of `WordReviewEditorRef`. It is a
-> separate, additive API that mirrors the target architecture in
-> [`docs/architecture/00-overview.md`](../../../docs/architecture/00-overview.md)
-> (Runtime API + AI API split per §9 + §10).
-
-## What this directory is
-
-- The shape every new Beyond Work consumer builds against, today.
-- Each function carries `ApiV3FnMetadata` declaring
-  `status: "mock" | "partial" | "live-with-adapter" | "live"`, its
-  target layer, UX intent, and agent metadata.
-- Every UX-visible function emits one `UxResponse` event on the
-  `api` telemetry channel per invocation so the future debug UX
-  (Phase Q) and agent-facing audit can observe it identically in
-  mock and live modes.
-
-### Four-status taxonomy (Phase P')
-
-| Status | Meaning |
-|---|---|
-| `mock` | No live path attempted; returns a `mockPayload(...)` / `mockArray(...)` carrying `__mock: true`. |
-| `partial` | Live path attempted; falls back to a mock-shaped payload when the runtime cannot satisfy it. `mockShape` is required. |
-| `live-with-adapter` | Delegates to a real runtime/facet method through a nontrivial adapter or composition layer. `mockShape` optional. |
-| `live` | Direct delegation to a single runtime/facet method. `mockShape` is forbidden. |
-
-The current distribution (as reported by the authoritative
-`test/runtime/debug/api-contract.test.ts` runner) is `9 live / 18
-live-with-adapter / 1 partial / 7 mock / 35 total`. See the Changelog
-in [`docs/reference/public-api.md`](../../../docs/reference/public-api.md)
-for the latest entry.
-
-## What this directory is NOT
-
-- NOT a re-export of the existing `WordReviewEditorRef`. The two CI
-  guards `scripts/ci-check-api-v3-no-ref-reexport.mjs` and
-  `scripts/ci-check-api-v3-metadata.mjs` enforce this. Adding a
-  convenience re-export of a ref method trips the guard.
-- NOT the place for internal runtime refactoring (`src/session/`,
-  `src/runtime/formatting/`, etc.). That work lands behind this
-  surface — v3 stays stable while internals move.
-- NOT a sandbox. `status: "live"` functions MUST parity-match the
-  underlying runtime behavior (asserted in per-family tests).
-
-## Consumers
-
-- **Beyond Work build team** (canonical). Import via
-  `import { createApiV3 } from "@beyondwork/docx-react-component/api/v3"`.
-- **Debug UX (Phase Q)**. Uses `UxResponse` events to render mock-or-live
-  visualizations.
-- **Phase D runners** (Layer-level validators). Use `createApiV3` as the
-  single entry point so runners don't depend on internal runtime shape.
-
-## Graduating a function's status
-
-The intended progression is `mock → partial → live-with-adapter → live`.
-Skipping a stage is allowed when justified, but each flip requires
-evidence:
-
-1. Implement the live path (delegate to the appropriate runtime
-   facet or layer extractor). For `live-with-adapter`, write the
-   adapter/composition in the family file; for `live`, the body
-   must be a single delegation call.
-2. Add a validator log entry under `services/debug/docs/` with the
-   new evidence.
-3. Update the function's `<fnName>Metadata.liveEvidence` field to
-   point at the log + the commit SHA; update `mockShape` per the
-   taxonomy rules above (required for `mock` and `partial`, optional
-   for `live-with-adapter`, forbidden for `live`).
-4. Update the per-family test's parity assertion and the matching
-   inline `// @endStateApi — <status>.` comment on the function
-   body so the status-drift canary stays green.
-
-Silent flips — changing `status` without updating `liveEvidence` or
-the inline annotation — are a review-time reject.
-
-## Canonical reference doc
-
-[`docs/reference/public-api.md`](../../../docs/reference/public-api.md).
-That's the URL the BW team bookmarks. This README is the in-repo
-maintainer-facing companion.
-
-## Phase Q (debug UX refactor) dependency
-
-Phase Q ships a runtime-embedded debug UX (`src/ui-tailwind/debug/**`)
-that subscribes to the `UxResponse` event stream emitted from this
-directory. Phase Q does NOT re-import the existing harness debug
-panel — it renders against `UxResponse` + `runtime.debug.getSnapshot`
-directly. See the Phase P plan for the full Phase Q spec.

package/src/component-inventory.md

@@ -1,99 +0,0 @@
-# Component Inventory
-
-This file is the source-owned inventory for the major subsystems in the active docx implementation.
-
-Wave 0 established the scaffold and ownership boundaries. Wave 1 froze the contract surface for the editor-side components listed below. That promotion does not claim implementation completeness; it means the subsystem boundaries, contract artifacts, and proof expectations are now explicit enough for later docx waves to build against without reopening the architecture.
-
-This inventory does not yet track:
-
-- shared OOXML platform extraction as a separate source area
-- a future xlsx runtime inventory
-- future pdf work
-
-## Inventory Table
-
-| Component | Current target | Primary paths | Scope in this repo phase | Contract and proof surfaces |
-| --- | --- | --- | --- | --- |
-| `canonical-document-model` | `contract-frozen` | `src/model/`, `src/api/` | Versioned canonical envelope, persisted snapshot shape, migration boundary, document metadata ownership | `docs/plans/waves/specs/wave-1-component-boundaries.md`, `docs/plans/waves/specs/wave-1-runtime-contracts.md`, schema docs, canonical JSON examples, model tests |
-| `command-and-transaction-runtime` | `contract-frozen` | `src/core/`, `src/runtime/` | Deterministic commands, transactions, mapping, selection semantics, runtime mutation boundary | `docs/plans/waves/specs/wave-1-component-boundaries.md`, `docs/plans/waves/specs/wave-1-runtime-contracts.md`, command tests, mapping tests, state-transition proofs |
-| `comments-and-anchor-mapping` | `contract-frozen` | `src/review/`, `src/core/selection/` | Comment threads, anchor remapping, review selectors, edit-safe anchor mapping policy | `docs/plans/waves/specs/wave-1-review-and-ui-contracts.md`, `docs/plans/waves/specs/wave-1-runtime-contracts.md`, anchor remap tests, threaded comment fixtures, review model docs |
-| `tracked-changes-and-review-actions` | `contract-frozen` | `src/review/`, `src/ui/review/` | Revision records, display modes, accept/reject boundaries, review-oriented commands | `docs/plans/waves/specs/wave-1-review-and-ui-contracts.md`, revision fixtures, accept/reject tests, review-state mapping tests |
-| `docx-import-and-normalization` | `contract-frozen` | `src/io/opc/`, `src/io/ooxml/`, `src/io/normalize/` | OPC opening, WordprocessingML parsing, normalization into canonical state, support classification inputs | `docs/plans/waves/specs/wave-1-ooxml-contracts.md`, `.docx` import fixtures, normalization tests, supported-feature mapping docs |
-| `docx-export-and-serialization` | `contract-frozen` | `src/io/export/`, `src/io/opc/` | Regenerated OOXML parts, package writing, relationship integrity, supported-feature serialization | `docs/plans/waves/specs/wave-1-ooxml-contracts.md`, round-trip fixtures, export validation tests, serializer docs |
-| `unsupported-ooxml-preservation` | `contract-frozen` | `src/preservation/`, `src/io/` | Opaque fragment capture, untouched package-part retention, reattachment policy, locked editing regions | `docs/plans/waves/specs/wave-1-ooxml-contracts.md`, preservation fixtures, fragment retention tests, export reattachment tests |
-| `compatibility-and-word-validation` | `contract-frozen` | `src/validation/`, `src/ui/compatibility/`, `services/openxml-validator/` | Editor-side compatibility reporting, support classification, export-risk reporting, validator-service integration boundary | `docs/plans/waves/specs/wave-1-ooxml-contracts.md`, `docs/plans/waves/specs/wave-1-review-and-ui-contracts.md`, feature matrix, compatibility tests, Word reopen evidence |
-| `react-editor-ui` | `contract-frozen` | `src/ui-tailwind/`, `src/ui/headless/`, `src/runtime/`, `src/api/` | Tailwind-based React shell with Radix UI primitives. Headless logic in `src/ui/headless/`. Legacy inline-CSSProperties components removed. | `docs/plans/waves/specs/wave-1-review-and-ui-contracts.md`, component tests, selection behavior checks, review-surface checks, token and theme checks |
-
-## Boundary Notes
-
-### Canonical data stays outside React
-
-- `src/model/`, `src/core/`, `src/review/`, `src/io/`, `src/preservation/`, and `src/validation/` should remain framework-light and serializable.
-- The DOM is a rendering target, not canonical state.
-
-### Runtime is the mutation choke point
-
-- UI surfaces call into `src/runtime/`.
-- Commands and transactions are owned by `src/core/`.
-- Review actions remain explicit state transitions rather than implicit UI side effects.
-
-### DOCX handling is package-first
-
-- `src/io/opc/` owns ZIP/package and relationship handling.
-- `src/io/ooxml/` owns WordprocessingML parsing.
-- `src/preservation/` owns unsupported-content retention and untouched package parts.
-
-### Broader repo work is planned, not landed
-
-- The repo now documents a target source layout under `src/platform/` and `src/formats/*`, but this file still inventories the landed docx-first tree.
-- Shared platform and xlsx architecture are currently defined in docs, not in source ownership tables here.
-
-### Review semantics are first-class
-
-- Comments and tracked changes are not annotations layered loosely on top of text rendering.
-- Anchors and revisions must stay mappable through edits and export.
-
-## Service-Backed Wave 0 Components
-
-The following components have a higher Wave 0 target because they already have repo-landed scaffolds:
-
-| Component | Wave 0 target | Primary paths | Landed scaffold evidence |
-| --- | --- | --- | --- |
-| `railway-test-harness` | `repo-landed` | `services/react-word-editor/` | Next.js service package, layout shell, harness dashboard stub, Dockerfile, Railway-oriented README |
-| `openxml-sdk-validator-service` | `repo-landed` | `services/openxml-validator/` | .NET 8 minimal API, `GET /health`, `POST /validate`, Dockerfile, SDK-backed validation README |
-
-## Out Of Scope For Wave 0
-
-- No canonical schema implementation yet
-- No command engine implementation yet
-- No comment or revision persistence yet
-- No OOXML transformer or serializer yet
-- No production `WordReviewEditor` React runtime yet
-- No live Railway persistence or private networking integration yet
-
-Those surfaces move in later waves. This inventory only establishes where they belong and what proof each promotion will require.
-
-## Contract Freeze References
-
-Wave 1 froze the owned architecture in the following durable spec set:
-
-- `docs/plans/waves/design/wave-1-a1.md`
-- `docs/plans/waves/specs/wave-1-component-boundaries.md`
-- `docs/plans/waves/specs/wave-1-runtime-contracts.md`
-- `docs/plans/waves/specs/wave-1-ooxml-contracts.md`
-- `docs/plans/waves/specs/wave-1-review-and-ui-contracts.md`
-
-## Future Source Direction
-
-Target broader layout:
-
-```text
-src/
-  platform/
-  formats/
-    docx/
-    xlsx/
-    pdf/
-```
-
-That future layout is a planning direction only. Do not treat it as a landed source move until the actual implementation is reorganized.

package/src/core/README.md

@@ -1,10 +0,0 @@
-# Core
-
-Commands, transactions, selection, mapping, schema, and deterministic state transitions belong here.
-
-Key subdirectories:
-
-- `schema/`
-- `state/`
-- `commands/`
-- `selection/`

package/src/core/commands/README.md

@@ -1,3 +0,0 @@
-# Core Commands
-
-Command handlers, transaction builders, and editor mutation policies belong here.

package/src/core/schema/README.md

@@ -1,3 +0,0 @@
-# Core Schema
-
-Canonical node, mark, and attribute definitions belong here.

package/src/core/selection/README.md

@@ -1,3 +0,0 @@
-# Core Selection
-
-Selections, ranges, position mapping, and anchor remapping helpers belong here.

package/src/core/state/README.md

@@ -1,3 +0,0 @@
-# Core State
-
-Canonical state containers, selectors, and structural invariants belong here.

package/src/io/README.md

@@ -1,10 +0,0 @@
-# IO
-
-OPC package handling, OOXML parsing, normalization, and serialization belong here.
-
-Key subdirectories:
-
-- `opc/`
-- `ooxml/`
-- `normalize/`
-- `export/`

package/src/io/export/README.md

@@ -1,3 +0,0 @@
-# IO Export
-
-OOXML serialization, part regeneration, and package writing helpers belong here.

package/src/io/normalize/README.md

@@ -1,3 +0,0 @@
-# IO Normalize
-
-Normalization from OOXML structures into canonical state belongs here.

package/src/io/ooxml/README.md

@@ -1,3 +0,0 @@
-# IO OOXML
-
-WordprocessingML parsing and intermediate OOXML structures belong here.

package/src/io/opc/README.md

@@ -1,3 +0,0 @@
-# IO OPC
-
-Open Packaging Conventions package reading, part enumeration, and relationship handling belong here.

package/src/model/README.md

@@ -1,3 +0,0 @@
-# Model
-
-Canonical document envelope types, schema versions, persisted snapshots, and migration contracts belong here.

package/src/preservation/README.md

@@ -1,3 +0,0 @@
-# Preservation
-
-Unsupported OOXML capture, retention, untouched package-part preservation, and export reattachment logic belong here.

package/src/review/README.md

@@ -1,16 +0,0 @@
-# Review
-
-Comments, anchors, revisions, remap helpers, and accept/reject behavior belong here.
-
-Frozen Wave 1 contract:
-
-- comments and revisions live in the canonical `review` store, not in the content tree
-- review anchors use canonical position ranges or detached-anchor payloads, never DOM paths
-- all review mutations flow through runtime commands and transactions
-- detached comments or revisions remain addressable with reason metadata; they are not silently dropped
-- v1 authoring is limited to single-paragraph comments, thread replies, tracked insertions, tracked deletions, and accept/reject flows
-- preserve-only review structures such as multi-paragraph editable comment ranges, unlinked move revisions, and unsupported structural list/table revisions stay locked and warning-backed
-
-Key subdirectories:
-
-- `store/`

package/src/review/store/README.md

@@ -1,3 +0,0 @@
-# Review Store
-
-Comment threads, revision records, review selectors, and accept/reject state belong here.

package/src/runtime/README.md

@@ -1,3 +0,0 @@
-# Runtime
-
-The document controller and coordination between canonical state, review state, UI state, preservation, validation, and IO belong here.

package/src/ui/README.md

@@ -1,30 +0,0 @@
-# UI
-
-This directory contains the public entry point and shared headless logic for the editor UI.
-
-## Entry Point
-
-`WordReviewEditor.tsx` is the public component. It bridges the `DocumentRuntime` to the Tailwind rendering layer in `src/ui-tailwind/`.
-
-## Headless Logic
-
-`headless/` contains pure, framework-free utilities shared across implementations:
-
-- `use-editor-keyboard.ts` — Keyboard event handler factory
-- `comment-decoration-model.ts` — Comment anchor → highlight class computation
-- `revision-decoration-model.ts` — Revision anchor → highlight class computation
-- `selection-helpers.ts` — Selection snapshot utilities
-
-## Session Capabilities
-
-`src/runtime/session-capabilities.ts` derives all UI control states from `RuntimeRenderSnapshot`. The `deriveCapabilities(snapshot, reviewMode)` function is called on every render in `WordReviewEditor.tsx` and the result is passed to the workspace components.
-
-## Shared Utilities
-
-`shared/revision-filters.ts` — Shared revision filtering and empty state helpers.
-
-## Rendering
-
-All visual rendering is in `src/ui-tailwind/`. See `docs/reference/word-review-editor-frontend-architecture.md` for the canonical architecture.
-
-Legacy inline-CSSProperties components have been removed.

package/src/ui/comments/README.md

@@ -1,3 +0,0 @@
-# Comments UI
-
-Comment markers, thread navigation, and sidebar thread views belong here.

package/src/ui/compatibility/README.md

@@ -1,3 +0,0 @@
-# Compatibility UI
-
-Compatibility reports, preserve-only warnings, and unsupported-content summaries belong here.

package/src/ui/editor-surface/README.md

@@ -1,3 +0,0 @@
-# Editor Surface
-
-The editable document canvas, overlays, and selection-aware rendering belong here.

package/src/ui/review/README.md

@@ -1,3 +0,0 @@
-# Review UI
-
-Tracked-change display modes, review navigation, and accept/reject surfaces belong here.

package/src/ui/status/README.md

@@ -1,3 +0,0 @@
-# Status UI
-
-Dirty state, autosave state, import/export progress, and validation status surfaces belong here.

package/src/ui/theme/README.md

@@ -1,3 +0,0 @@
-# Theme
-
-Design tokens, CSS variable mapping, and host-theme integration belong here.

package/src/ui/toolbar/README.md

@@ -1,3 +0,0 @@
-# Toolbar
-
-The compact command toolbar and contextual editor controls belong here.

package/src/ui-tailwind/debug/README.md

@@ -1,22 +0,0 @@
-# Debug UX (internal only)
-
-Runtime debug chrome is not a production API surface. `WordReviewEditor` does
-not expose a `debugMode` prop, `api.ui.debug.attach()` is a hard-disabled
-runtime API call, and `ChromePosture.debugMode` is production-forced to
-`"off"`.
-
-The supported local diagnostic surface is the mounted runtime REPL keyboard
-shortcut. Open it with `Cmd/Ctrl+Alt+P`; its `Agent layer view` shares the
-L01-L11 layer map with the harness debug pane, including `Alt+1`...`Alt+9`,
-`Alt+0`, and `Alt+-` navigation plus snippets that evaluate against
-`runtime`/`ref`. These components remain in the tree for internal harness/story
-experiments only; do not wire them into `WordReviewEditor` or public API paths.
-
-## Files
-
-| File | Purpose |
-|---|---|
-| `tw-debug-top-bar.tsx` | Internal minimal top bar for harness/story experiments |
-| `tw-debug-overlay.tsx` | Internal overlay rendering `DebugInspectorSnapshot` sections |
-| `tw-debug-repl.tsx` | Legacy placeholder; production diagnostics use `tw-runtime-repl-dialog.tsx` |
-| `tw-debug-event-tail.tsx` | Tail of the last N events on active telemetry channels |

package/src/validation/README.md

@@ -1,3 +0,0 @@
-# Validation
-
-Compatibility checks, round-trip validation, support classification, and Word reopen evidence helpers belong here.