feat(review): add controlled React review surface

README.md

@@ -70,7 +70,7 @@ runtime.
 | Envelope identity | `@contextualwisdomlab/cwl-editor/envelope-identity` | Framework-independent bounded schema identity for host-owned migration routing |
 | Revision evidence | `@contextualwisdomlab/cwl-editor/revision-evidence` | Framework-independent canonical envelope, strong revision, and transition evidence |
 | Text-position selector | `@contextualwisdomlab/cwl-editor/text-position-selector` | React-free deterministic W3C `TextPositionSelector` projection core |
-| Review target core | `@contextualwisdomlab/cwl-editor/review` | `implemented_on_active_pr` — React-free deterministic exact-revision review targets; durable review records and policy remain host-owned |
+| Review | `@contextualwisdomlab/cwl-editor/review` | `implemented_on_active_pr` — React-free exact-revision targets plus bounded insert/delete suggestions and operation results; durable review records and policy remain host-owned |
 | Autosave | `@contextualwisdomlab/cwl-editor/autosave` | Provider-neutral bounded single-flight persistence coordination |
 | Headless Markdown | `@contextualwisdomlab/cwl-editor/markdown` | React-free deterministic Markdown/HTML/email/plain-text conversion |
 | Styles | `@contextualwisdomlab/cwl-editor/styles.css` | Editor layout and theming |
@@ -728,4 +728,4 @@ capabilities they require.
 - **Fonts:** Noto Sans families are SIL Open Font License 1.1.
 
 See [`LICENSE`](LICENSE), [`src/fonts/OFL.txt`](src/fonts/OFL.txt), and
-[`src/fonts/NOTICE`](src/fonts/NOTICE).
+[`src/fonts/NOTICE`](src/fonts/NOTICE).

docs/CONTRACTS.md

@@ -16,7 +16,7 @@ The root package may expose React/TipTap integration plus framework-independent
 
 Package exports, declaration files, runtime support, and packed ESM/CommonJS/strict-TypeScript consumers are release evidence. A source file being present is not sufficient proof that a public contract is packaged correctly.
 
-Protected `main` includes the React-free `@contextualwisdomlab/cwl-editor/text-position-selector` subpath for deterministic W3C selector projection. The root editor surface remains the authority for capturing one immutable editor state and binding that projection to an exact document revision.
+Protected `main` includes the React-free `@contextualwisdomlab/cwl-editor/text-position-selector` subpath for deterministic W3C selector projection. The active review line adds the framework-independent `@contextualwisdomlab/cwl-editor/review` contract for bounded revision-scoped targets and deterministic insert/delete operation results; it is not protected-main implementation authority until merged and reverified. The root editor surface remains the authority for capturing one immutable editor state and binding that projection to an exact document revision.
 
 ## Document envelope and revision contract
 
@@ -71,6 +71,8 @@ The host owns annotation identifiers/bodies, source-resource IRI policy, authent
 
 ADR 0018 is the durable authority decision. `docs/selection-lifecycle.md` and `docs/doctoring/w3c-text-position-selector-evidence.md` record the operator-facing semantics and APA-7 standards basis. Packed ESM/CommonJS/strict-TypeScript consumers verify both the root public API and the protected React-free `@contextualwisdomlab/cwl-editor/text-position-selector` subpath; no database, network, provider credential, model, naruon, or contextual-orchestrator dependency is introduced by the projection subpath or evidence operation.
 
+The active review contract keeps comment bodies, durable thread/suggestion identity, authorization, persistence, audit, collaboration-provider state, and cross-revision re-anchoring with the host. Inkspan validates only bounded immutable revision/selector/projection metadata and deterministic insert/delete lifecycle/transition semantics. `docs/review-contract.md` and ADR 0032 define the proposed editor integration and its fail-closed stale-revision boundary; active-PR evidence must not be described as shipped behavior.
+
 ## Autosave contract
 
 Autosave is a local coordination surface. It provides bounded single-flight ordering, bounded pending work, explicit blocked/conflict/failure state, optional lifecycle observation, and host callback handoff. The host performs authenticated transport and durable persistence.

docs/DATA_MODEL.md

@@ -48,6 +48,7 @@ erDiagram
 - `document_transition`: previous/resulting revision pair plus changed classification. It deliberately omits the document body from ordinary evidence.
 - `selection_evidence`: ProseMirror structural coordinates bound to one exact revision. It is a local evidence value, not a durable cross-revision anchor.
 - `text_position_selector_evidence`: `implemented_on_protected_main` as a frozen revision-scoped W3C `TextPositionSelector` plus explicit `inkspan-prosemirror-text` projection identity. It satisfies `0 <= start <= end <= projectedCodePointLength`; inclusive `start` and exclusive `end` count Unicode code points, boundaries are grapheme-validated, and ordinary evidence contains no selected quote text. It is not a durable cross-revision anchor, annotation identity, authorization record, timestamp, signature, or persistence receipt.
+- `review_target` / `review_suggestion`: `implemented_on_active_pr` under Proposed ADR 0032. These are bounded revision-scoped target and insert/delete lifecycle values; operation results contain only revisions and compact transition evidence. They do not contain comment bodies or transfer host identity, authorization, persistence, collaboration, audit, or cross-revision re-anchoring authority.
 - `autosave_revision`: detached immutable revision evidence accepted by the local single-flight autosave coordinator.
 - `autosave_snapshot`: frozen document-free queue/session lifecycle metadata such as idle/saving/blocked/closing/closed and bounded pending state. The explicit in-process snapshot may also carry the bounded active/pending/last-saved strong-validator fields defined by the autosave contract; those fields are confidential local concurrency metadata rather than generic telemetry.
 - `clipboard_policy`: bounded local policy describing the supported semantic rich-paste boundary. It grants no host network or tenant authority.
@@ -86,6 +87,7 @@ These values may remain ephemeral or release-artifact metadata. Their presence i
 | `document_transition` | none required; host may store | change evidence | no | content-lineage evidence only |
 | `selection_evidence` | none required | review/selection capture | no | exact-revision ProseMirror coordinates only |
 | `text_position_selector_evidence` | none required; `implemented_on_protected_main` | interoperable review/annotation capture | no | exact-revision W3C text positions satisfying `0 <= start <= end <= projectedCodePointLength` under one versioned projection only |
+| `review_target` / `review_suggestion` | none required; `implemented_on_active_pr` | inline review and deterministic suggestion operation | no | bounded revision-scoped metadata and local transition evidence only; host owns bodies, identity, authorization, persistence, audit, and re-anchoring |
 | `autosave_revision` | none required | queued local save evidence | envelope-bearing evidence may be retained boundedly by queue | local save ordering only |
 | `autosave_snapshot` | none required | lifecycle observation/coordination | no | local machine state only; validator fields remain confidential metadata |
 | `durable_validator` | host | durable version | no | host concurrency evidence, not authorization |

docs/DOCUMENTATION_FITNESS.md

@@ -50,6 +50,7 @@ Document fitness and implementation maturity are independent. A `present_current
 | Accessible editor placeholder semantics | accessibility guidance/doctoring and protected editor source from #131 | `present_current` | `implemented_on_protected_main` | Visual placeholder guidance and `aria-placeholder` remain synchronized without making placeholder text an accessible name or persistent document value. |
 | Revision-scoped selection evidence | selection lifecycle guide, doctoring and protected public handle/type contract | `present_current` | `implemented_on_protected_main` | Atomic selection+revision evidence, privacy minimization and host-owned re-anchoring are reconstructable. |
 | W3C text-position selector evidence / React-free text-position selector subpath | ADR 0018, protected handle/type contract, package subpath, selector implementation/verifier and doctoring | `present_current` | `implemented_on_protected_main` | ADR 0018 makes Unicode-code-point offsets, grapheme-boundary fail-closed semantics, projection identity, same-state revision binding, React-free text-position selector subpath reuse and text-free evidence reconstructable without confusing W3C offsets with ProseMirror positions. |
+| Provider-neutral review contract / React-free review subpath | Proposed ADR 0032, `docs/review-contract.md`, package subpath, core tests and packed verifier | `present_current` | `implemented_on_active_pr` | Bounded revision-scoped targets and deterministic insert/delete transition semantics are reconstructable; editor UI, browser accessibility, durable comments, collaboration, and re-anchoring remain unshipped acceptance work. |
 | Document-transition evidence | transition doctoring, public framework-independent contract and protected revision-evidence package | `present_current` | `implemented_on_protected_main` | Previous/resulting revision lineage is reconstructable without implying actor/time/durable-write provenance. |
 | Envelope schema identity / migration routing | ADR 0015, PRD, TRD, DATA_MODEL, envelope guide/doctoring and protected identity-routing source | `present_current` | `implemented_on_protected_main` | Bounded schema identification remains separate from host-owned migration execution and persistence. |
 | Cross-engine browser-semantic release assurance | ADR 0016, doctoring, TEST_STRATEGY, OPERABILITY, TRACEABILITY and protected browser-evidence workflows | `present_current` | `implemented_on_protected_main` | SafeClipboard is also `implemented_on_protected_main`; Chromium/Firefox/WebKit evidence, exact source/lock/browser identity, packed-artifact digest binding and fail-closed divergence are protected release authority. |

docs/OPERABILITY.md

@@ -10,6 +10,14 @@ This distinction controls incident ownership: an Inkspan incident is a determini
 
 Protected `main` is the shipped implementation authority. Open PRs are not operational authority until protected integration.
 
+The active review contract is an operationally bounded proposal. When its
+editor adapter is enabled, hosts must treat `stale` results as a refetch/review
+decision, not as permission to re-anchor or overwrite. Host callbacks must
+record durable thread/suggestion outcomes in the host system; Inkspan's local
+transition evidence is not a durable audit event. Review UI failure must leave
+the document editable or explicitly read-only according to host policy without
+inventing acceptance or rejection.
+
 ## Health and evidence
 
 Inkspan itself does not expose a network health endpoint. Operational health is proven through exact-head CI and package-consumer evidence, deterministic runtime outcomes, bounded public errors, security scans, package/release verification, and host-observable local state.

docs/PRD.md

@@ -58,6 +58,7 @@ The product promise is: **author, convert, collaborate, and prove document chang
 - The producer derives the range from one valid ordered ProseMirror `Selection`; it does not accept arbitrary caller-supplied selector numbers. Any impossible emitted range violation is an internal defect and must not be normalized or published.
 - ProseMirror structural positions and W3C text positions are distinct coordinate systems even when numeric values happen to match for a simple document.
 - Text-position evidence remains revision-scoped and text-free. Hosts own annotation identifiers/bodies, source-resource identifiers, publication, durable persistence, authorization, tenant policy, and cross-revision re-anchoring.
+- **Active PR / Proposed review mode** adds bounded revision-scoped comment targets and deterministic insert/delete suggestions. Accept must change the document, reject must preserve the revision, and stale targets fail closed without implicit re-anchoring. The editor panel, callbacks, browser evidence, and full acceptance slice remain active work and are not protected-main product claims.
 - Autosave remains single-flight with bounded active/pending work and explicit conflict/failure recovery.
 - Durable saves use a host/server-selected strong validator; conflict or ambiguous failure never silently advances it.
 - Lifecycle observation emits only distinct externally visible document-free state transitions; construction and no-op operations do not manufacture notifications.
@@ -105,7 +106,7 @@ The product promise is: **author, convert, collaborate, and prove document chang
 
 ## Non-goals
 
-Inkspan is not an identity provider, tenant database, durable document store, collaboration authorization server, deployment platform, credential manager, retention engine, model router, durable audit service, application migration owner, annotation database, cross-revision annotation re-anchoring service, or merge/release authority for host products.
+Inkspan is not an identity provider, tenant database, durable document store, collaboration authorization server, deployment platform, credential manager, retention engine, model router, durable audit service, application migration owner, annotation database, cross-revision annotation re-anchoring service, or merge/release authority for host products. The active review contract does not change those non-goals.
 
 Inkspan does not promise universal HTML/Office round-trip fidelity, arbitrary executable document content, implicit network fetching, model-generated content as trusted source, silent migration of unknown document schemas, a security bounty, legal safe harbor, fixed vulnerability-response SLA, or certification from repository documentation alone.
 
@@ -146,3 +147,8 @@ Shareable acquisition evidence excludes production tenant content and credential
 Protected `main` is the sole implemented baseline. Open PRs may describe Proposed or Active work but are not shipped contracts until protected integration. Canonical documentation must state when a requirement is target architecture rather than current implementation.
 
 SafeClipboard, real Chromium/Firefox/WebKit release assurance, lifecycle observation, the root security disclosure lifecycle, toolbar shortcut accessibility metadata, SSR/native-form serialization, revision-scoped selection evidence, W3C text-position selector evidence, document-transition evidence, and envelope identity migration routing are implemented on protected `main`.
+
+The revision-scoped review contract and `@contextualwisdomlab/cwl-editor/review`
+subpath are `implemented_on_active_pr` under Proposed ADR 0032. The interactive
+review panel, editor transaction integration, Storybook/equivalent states, and
+cross-engine interaction evidence are not shipped until protected integration.

docs/README.md

@@ -16,6 +16,7 @@ This directory is the discoverable index for Inkspan's product, technical, secur
 | [`TRD.md`](TRD.md) | Technical invariants, runtime boundaries, failure semantics and release evidence |
 | [`CONTRACTS.md`](CONTRACTS.md) | Public package/API/event/schema/plugin/collaboration and host-integration contracts |
 | [`package-distribution.md`](package-distribution.md) | Buyer-facing public npm package entrypoints, packaged contents, runtime dependency boundaries, and consumer verification |
+| [`review-contract.md`](review-contract.md) | Active-PR provider-neutral review contract, ownership boundary, and research basis |
 | [`email-output.md`](email-output.md) | Deterministic email fragment/full-document authority, language/direction metadata, accessibility and host-owned transport boundary |
 | [`print-output.md`](print-output.md) | Browser print/paged-media presentation, accessibility/fidelity limits, host-owned governed-export boundary, and rollback |
 | [`UML.md`](UML.md) | Component, sequence, state and authority-flow diagrams |

docs/TEST_STRATEGY.md

@@ -55,6 +55,11 @@ At minimum, maintain regressions for:
 - SSR client-controlled form values, escaping, hydration continuity, reset behavior, and absence of server editor construction;
 - autosave stale validators, conflict/failure recovery, ambiguous transport outcomes, duplicate/no-op lifecycle transitions, callback exceptions, queue bounds, flush/close behavior, and durable-validator coherence;
 - selection/revision races and document movement during asynchronous hashing;
+- review target/suggestion accessors and exotic prototypes, unsupported
+  projections, bounded text/counts, exact-once accept/reject semantics,
+  stale-revision fail-closed behavior, undo/redo, keyboard/screen-reader
+  review-panel states, print output, and packed `./review` ESM/CommonJS/strict
+  TypeScript consumers;
 - Office formula prefixes, invalid XML characters, malicious strings, path/publication races, invalid worksheet names, invalid freeze panes, cyclic input, pathological nesting, excessive container size, and partial write failure;
 - package/release stale draft assets, unexpected or non-regular local entries, exact three-file inventory violations, incomplete remote uploads, GitHub-vs-local digest mismatch, stale exact-head evidence, mutable provenance inputs, and isolated packed-consumer behavior.
 

docs/THREAT_MODEL.md

@@ -53,6 +53,17 @@ Local SHA-256 revisions identify deterministic content equality only. Selection
 
 Concurrent editors, delayed digests, stale selections, ambiguous transport failure, or stale durable validators can cause lost updates or false success. Inkspan must bind asynchronous evidence to one immutable local state, keep autosave single-flight with bounded pending work, fail closed on ambiguous durable outcomes, and require explicit recovery from blocked conflict/failure states. Hosts own atomic persistence transactions and durable conflict resolution.
 
+### Review targets, suggestions, and comment metadata
+
+Host-supplied thread/suggestion values can contain accessors, exotic
+prototypes, oversized identifiers/text, unsupported projections, stale
+revisions, or attempts to smuggle comment bodies into evidence. The active
+review contract validates plain bounded records, binds operations to the exact
+revision, requires accept to change and reject to preserve the revision, and
+returns stale rather than re-anchoring. It carries no body, credential,
+authorization, durable-write, or cross-revision anchor claim; hosts must still
+authorize and persist their own records.
+
 ### Collaboration and Yjs
 
 Inkspan may bind to Yjs-compatible document/awareness surfaces but does not own provider creation, room authorization, tenant identity, persistence, retention, or durable audit. Yjs updates and awareness metadata can contain sensitive tenant information. Host providers must authenticate rooms, authorize membership, bound awareness disclosure, and apply retention/encryption policy. Inkspan must not silently create a network provider or elevate an awareness update into authorization.