@beyondwork/docx-react-component 1.0.110 → 1.0.111

package/src/ui-tailwind/debug/layer11-consumer-readiness.ts

@@ -215,6 +215,38 @@ export interface Layer11RenderCalibrationSummary {
   route: "presentation-check" | "lower-layer-fact-required" | "insufficient-evidence";
 }
 
+export type Layer11AdjacentGeometryAxis = "numbering-marker" | "field-region";
+
+export interface Layer11AdjacentGeometryIntakeLike {
+  readonly schemaVersion?: unknown;
+  readonly totals?: {
+    readonly numberingCompositorReadyRows?: unknown;
+    readonly fieldRegionCompositorReadyRows?: unknown;
+  };
+  readonly pageLocalNormalization?: {
+    readonly framePixelCoordinateSpace?: unknown;
+    readonly framePixelPrecision?: unknown;
+    readonly compositorReady?: unknown;
+  };
+}
+
+export interface Layer11AdjacentGeometryAxisReadiness {
+  axis: Layer11AdjacentGeometryAxis;
+  compositorReadyRows: number;
+  assertionReady: boolean;
+  route: "presentation-consumer-ready" | "lower-layer-fact-required";
+  reason: string;
+}
+
+export interface Layer11AdjacentGeometryConsumerSummary {
+  schemaVersion: string | null;
+  framePixelCoordinateSpace: string | null;
+  framePixelPrecision: string | null;
+  assertionReadyCount: number;
+  lowerLayerFactRequiredCount: number;
+  entries: readonly Layer11AdjacentGeometryAxisReadiness[];
+}
+
 const PRIMARY_RENDER_EVIDENCE = new Set<Layer11RenderEvidenceKind>([
   "word-oracle",
   "render-word",
@@ -270,3 +302,75 @@ export function summarizeWordFirstRenderCalibration(
     route: "presentation-check",
   };
 }
+
+export function summarizeLayer11AdjacentGeometryConsumer(
+  intake: Layer11AdjacentGeometryIntakeLike,
+): Layer11AdjacentGeometryConsumerSummary {
+  const schemaVersion =
+    typeof intake.schemaVersion === "string" ? intake.schemaVersion : null;
+  const normalization = intake.pageLocalNormalization;
+  const framePixelCoordinateSpace =
+    typeof normalization?.framePixelCoordinateSpace === "string"
+      ? normalization.framePixelCoordinateSpace
+      : null;
+  const framePixelPrecision =
+    typeof normalization?.framePixelPrecision === "string"
+      ? normalization.framePixelPrecision
+      : null;
+  const normalizationReady =
+    schemaVersion === "layer-05-adjacent-geometry-intake/v2" &&
+    framePixelCoordinateSpace === "frame-px" &&
+    normalization?.compositorReady === true;
+  const entries: Layer11AdjacentGeometryAxisReadiness[] = [
+    summarizeAdjacentGeometryAxis(
+      "numbering-marker",
+      numberValue(intake.totals?.numberingCompositorReadyRows),
+      normalizationReady,
+    ),
+    summarizeAdjacentGeometryAxis(
+      "field-region",
+      numberValue(intake.totals?.fieldRegionCompositorReadyRows),
+      normalizationReady,
+    ),
+  ];
+
+  return {
+    schemaVersion,
+    framePixelCoordinateSpace,
+    framePixelPrecision,
+    assertionReadyCount: entries.filter((entry) => entry.assertionReady).length,
+    lowerLayerFactRequiredCount: entries.filter((entry) => !entry.assertionReady)
+      .length,
+    entries,
+  };
+}
+
+function summarizeAdjacentGeometryAxis(
+  axis: Layer11AdjacentGeometryAxis,
+  compositorReadyRows: number,
+  normalizationReady: boolean,
+): Layer11AdjacentGeometryAxisReadiness {
+  const assertionReady = normalizationReady && compositorReadyRows > 0;
+  if (assertionReady) {
+    return {
+      axis,
+      compositorReadyRows,
+      assertionReady,
+      route: "presentation-consumer-ready",
+      reason:
+        "L05 published frame-pixel rows with compositorReady provenance; L11 may consume this bounded subset without reconstructing geometry.",
+    };
+  }
+  return {
+    axis,
+    compositorReadyRows,
+    assertionReady,
+    route: "lower-layer-fact-required",
+    reason:
+      "L11 must wait for L05 frame-pixel rows marked compositorReady before treating this axis as a presentation assertion.",
+  };
+}
+
+function numberValue(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}

package/src/ui-tailwind/editor-surface/pm-page-break-decorations.ts

@@ -89,6 +89,15 @@ export interface PageBreakDecorationInput {
    * heuristic.
    */
   blockIndexRangeByPageIndex?: ReadonlyMap<number, { first: number; last: number }>;
+  /**
+   * Page indexes whose boundary/content widgets would be inserted at a document
+   * position inside a table. PM widgets inherit that table-cell containing
+   * block, so visible chrome there paints page numbers inside the cell and
+   * block-level invisible anchors can perturb table layout. Keep the diagnostic
+   * markers but suppress the visible spacer/seam and shrink anchors to inline
+   * zero-size markers.
+   */
+  suppressChromeForPageIndex?: ReadonlySet<number>;
 }
 
 export function buildPageBreakDecorations(
@@ -111,7 +120,13 @@ export function buildPageBreakDecorations(
   // (coord-11 §19) are emitted in a second pass at the end of this
   // function.
   if (graph.pages.length < 2) {
-    return buildPageAnchorDecorationsInto(decorations, graph, posture, runtimeToPmOffset);
+    return buildPageAnchorDecorationsInto(
+      decorations,
+      graph,
+      posture,
+      runtimeToPmOffset,
+      input.suppressChromeForPageIndex,
+    );
   }
 
   for (let i = 1; i < graph.pages.length; i += 1) {
@@ -133,6 +148,8 @@ export function buildPageBreakDecorations(
       input.headerPreviewByPageId?.get(next.pageId) ?? "";
 
     const nextBlockRange = input.blockIndexRangeByPageIndex?.get(next.pageIndex);
+    const suppressVisibleChrome =
+      input.suppressChromeForPageIndex?.has(next.pageIndex) === true;
 
     decorations.push(
       Decoration.widget(
@@ -155,6 +172,7 @@ export function buildPageBreakDecorations(
             nextHeaderPreview,
             nextPageFirstBlockIndex: nextBlockRange?.first ?? -1,
             nextPageLastBlockIndex: nextBlockRange?.last ?? -1,
+            suppressVisibleChrome,
           }),
         {
           side: -1,
@@ -171,7 +189,13 @@ export function buildPageBreakDecorations(
       ),
     );
   }
-  return buildPageAnchorDecorationsInto(decorations, graph, posture, runtimeToPmOffset);
+  return buildPageAnchorDecorationsInto(
+    decorations,
+    graph,
+    posture,
+    runtimeToPmOffset,
+    input.suppressChromeForPageIndex,
+  );
 }
 
 /**
@@ -197,6 +221,7 @@ function buildPageAnchorDecorationsInto(
   graph: RuntimePageGraph,
   posture: "page" | "canvas",
   runtimeToPmOffset: ((runtimeOffset: number) => number | null) | undefined,
+  tableInteriorPageIndex?: ReadonlySet<number>,
 ): Decoration[] {
   let contentPageOrdinal = 0;
   for (const page of graph.pages) {
@@ -214,6 +239,7 @@ function buildPageAnchorDecorationsInto(
         () => buildPageAnchorWidgetDom({
           pageNumber: anchorPageNumber,
           pageId: anchorPageId,
+          tableInterior: tableInteriorPageIndex?.has(page.pageIndex) === true,
         }),
         {
           side: 1,
@@ -268,6 +294,7 @@ interface ChromeWidgetInput {
    * -1 when block-index info was not supplied to the decoration builder.
    */
   nextPageLastBlockIndex: number;
+  suppressVisibleChrome?: boolean;
 }
 
 // P14.c — cache the widget DOM by input identity.  PM rebuilds the
@@ -299,6 +326,7 @@ function widgetCacheKey(input: ChromeWidgetInput): string {
     input.nextHeaderPreview,
     input.nextPageFirstBlockIndex,
     input.nextPageLastBlockIndex,
+    input.suppressVisibleChrome ? "1" : "0",
   ].join("\x1f");
 }
 
@@ -337,22 +365,29 @@ export function __resetPageBreakWidgetCache(): void {
  *
  * Emitted as a PM widget via `buildPageBreakDecorations` so it lives
  * on the content layer (present under chrome=none) rather than on an
- * absolute-positioned chrome overlay.
+ * absolute-positioned chrome overlay. When the page starts inside a table,
+ * the marker stays inline and zero-width so it does not create a block box
+ * inside the table cell.
  */
 function buildPageAnchorWidgetDom(input: {
   pageNumber: number;
   pageId: string;
+  tableInterior?: boolean;
 }): HTMLElement {
   const root = document.createElement("span");
   root.setAttribute("data-kind", "page-content-anchor");
   root.setAttribute("data-page-content-wrapper", "");
   root.setAttribute("data-page-number", String(input.pageNumber));
   root.setAttribute("data-page-id", input.pageId);
+  if (input.tableInterior) {
+    root.setAttribute("data-page-anchor-suppressed", "table-interior");
+  }
   root.setAttribute("aria-hidden", "true");
   root.contentEditable = "false";
-  root.style.display = "block";
+  root.style.display = input.tableInterior ? "inline-block" : "block";
   root.style.height = "0";
-  root.style.width = "100%";
+  root.style.width = input.tableInterior ? "0" : "100%";
+  root.style.overflow = "hidden";
   root.style.userSelect = "none";
   return root;
 }
@@ -391,6 +426,16 @@ function buildChromeWidgetDomUncached(input: ChromeWidgetInput): HTMLElement {
   root.style.width = "100%";
   root.style.userSelect = "none";
 
+  if (input.suppressVisibleChrome) {
+    root.setAttribute("data-page-chrome-suppressed", "table-interior");
+    root.setAttribute("aria-hidden", "true");
+    root.style.height = "0";
+    root.style.width = "0";
+    root.style.overflow = "hidden";
+    root.style.pointerEvents = "none";
+    return root;
+  }
+
   if (input.posture === "canvas") {
     // Single dotted horizontal line with an unframed page-number label.
     root.style.height = `${input.interGapPx + 1}px`;

package/src/ui-tailwind/editor-surface/tw-prosemirror-surface.tsx

@@ -185,6 +185,7 @@ function buildPageBreakDecorationsFromProps(
   // carry `data-page-first-block-index` / `data-page-last-block-index`
   // attributes needed by `useVisibleBlockRange`.
   let blockIndexRangeByPageIndex: Map<number, { first: number; last: number }> | undefined;
+  let suppressChromeForPageIndex: Set<number> | undefined;
   if (surfaceBlocks && surfaceBlocks.length > 0 && frame.pages.length > 0) {
     blockIndexRangeByPageIndex = new Map();
     for (let pi = 0; pi < frame.pages.length; pi++) {
@@ -194,6 +195,13 @@ function buildPageBreakDecorationsFromProps(
       if (range) {
         blockIndexRangeByPageIndex.set(page.page.pageIndex, range);
       }
+      if (
+        pi > 0 &&
+        isRuntimeOffsetInsideTableBlock(surfaceBlocks, page.page.startOffset)
+      ) {
+        if (!suppressChromeForPageIndex) suppressChromeForPageIndex = new Set();
+        suppressChromeForPageIndex.add(page.page.pageIndex);
+      }
     }
   }
 
@@ -207,9 +215,27 @@ function buildPageBreakDecorationsFromProps(
     headerPreviewByPageId: previews?.headerPreviewByPageId,
     footerPreviewByPageId: previews?.footerPreviewByPageId,
     blockIndexRangeByPageIndex,
+    suppressChromeForPageIndex,
   });
 }
 
+function isRuntimeOffsetInsideTableBlock(
+  blocks: readonly import("../../api/public-types.ts").SurfaceBlockSnapshot[],
+  offset: number,
+): boolean {
+  for (const block of blocks) {
+    if (offset <= block.from || offset >= block.to) continue;
+    if (block.kind === "table") return true;
+    if (
+      block.kind === "sdt_block" &&
+      isRuntimeOffsetInsideTableBlock(block.children, offset)
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
 function extractDecorations(
   set: DecorationSet,
   _doc: unknown,

package/src/README.md

@@ -1,85 +0,0 @@
-# Source Layout
-
-The landed source tree is still organized around the active docx implementation, not around the future target office-wide layout.
-
-## Current Landed Layout
-
-```text
-src/
-  api/
-  model/
-  core/
-    schema/
-    state/
-    commands/
-    selection/
-  review/
-    store/
-  io/
-    opc/
-    ooxml/
-    normalize/
-    export/
-  preservation/
-  validation/
-  runtime/
-  ui/
-    headless/            # Shared pure logic (framework-free)
-    shared/              # Shared utilities (revision-filters)
-    WordReviewEditor.tsx  # Entry point
-  ui-tailwind/           # Default rendering (Tailwind + Radix + Lucide)
-    editor-surface/
-    toolbar/
-    review/
-    status/
-    chrome/
-    theme/
-```
-
-This is the truthful current layout for implementation work today.
-
-## Target Broader Layout
-
-The broader repo story now targets a future layout like this:
-
-```text
-src/
-  platform/
-  formats/
-    docx/
-    xlsx/
-    pdf/
-```
-
-That layout is not landed yet. Use it as a planning direction, not as evidence that the current code has already been reorganized.
-
-## UI Layer Strategy
-
-- `ui/headless/` — Pure logic: keyboard handling, decoration models, selection utilities. No React dependencies.
-- `ui-tailwind/` — Default rendering: Tailwind CSS, Radix UI primitives, Lucide icons. All styling via CSS custom properties.
-- `ui/WordReviewEditor.tsx` — Public entry point that bridges the runtime to the Tailwind layer.
-
-Legacy inline-CSSProperties components have been removed. See `docs/reference/word-review-editor-frontend-architecture.md` for the canonical frontend architecture.
-
-Keep business rules close to the subsystem that owns them. Do not centralize unrelated logic into generic utility layers.
-
-Ownership rules:
-
-- `api` exposes public contracts only.
-- `model`, `core`, `review`, `io`, `preservation`, and `validation` should remain React-free when possible.
-- `runtime` is the only mutation boundary the UI calls into.
-- `ui` consumes runtime contracts and design tokens; it does not own canonical document truth.
-
-## Broader Repo Direction
-
-As the repo broadens:
-
-- shared package and preservation concerns should move toward `src/platform/`
-- current docx runtime code remains the active implementation track until a deliberate source move lands
-- future xlsx work should gain its own source area rather than widening docx-specific modules by implication
-- future pdf work should remain separate from the first OOXML platform layer unless architecture decisions intentionally broaden it
-
-Wave 0 inventory references:
-
-- `component-inventory.md`
-  Wave-owned inventory for the major editor subsystems, their boundaries, and the promotion target for this scaffold phase.

package/src/api/README.md

@@ -1,26 +0,0 @@
-# API
-
-Public TypeScript contracts for `WordReviewEditor` belong here.
-
-This layer should expose:
-
-- component props and ref types
-- session-state and snapshot compatibility types
-- host adapter and datastore adapter interfaces
-- runtime-derived position and selection projection types used by the public API
-- discriminated event unions
-- warning and error payloads
-- persisted snapshot contracts
-- export and compatibility report types
-
-Do not place runtime logic here.
-
-Frozen naming and boundary rules:
-
-- the shipped component name is `WordReviewEditor`
-- `DocumentRuntime` is an internal runtime contract, not a public React component name
-- `EditorSessionState` is the canonical host-facing live-session contract
-- `PersistedEditorSnapshot` is the legacy/store compatibility envelope
-- `EditorHostAdapter` is the preferred persistence boundary; `EditorDatastoreAdapter` remains the snapshot-compatible bridge
-- public range references are canonical-position projections, not DOM-path handles
-- render snapshots stay in `src/runtime`; `src/api` only exposes persisted host-facing snapshot types

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.