feat(reference-host): add buyer integration safety fixtures

[seonghobae]

Refs #377.

Status and ownership

Active PR / Proposed. Protected main remains the only shipped implementation authority. This is the existing reference-host writer; no competing runtime or Markdown repair is introduced.

Validated source: 9ecda1c. The parent remains #176, branch fix/public-markdown-resource-options-175, whose head 94b5ca8 is an ancestor of this head. The old source-reconciliation-unavailable paragraph is superseded: the parent was inherited through normal history, without rewriting history. Protected main was freshly read as 0b88c16.

Inkspan owns deterministic editing, conversion, evidence, local autosave coordination and provider-neutral adapters. Hosts retain transport, authentication, authorization, tenancy, durable persistence, credentials, retention, deployment, audit, collaboration-provider authority and model policy. This reference-host delta adds no service, database, credential, model call or dependency. The inherited TipTap 3.30.4, Python matrix and package declaration changes remain owned by #402.

The dependency stack is now #402 at 637b910d25dabb363e40d535c6d89f4a5beb8c6d → #176 at 94b5ca815749a7dd6bc071106eb685d2a193e4dd → this head. Both parent generations are verified ancestors through ordinary conflict-free merges. This generation also inherits #176's consolidation of the previously retained native encoder reuse from #379; the output-limit/options guards and independent output buffers are unchanged. Fresh 0.7.0 installed-consumer and browser evidence below supersedes the earlier 0.6.0 local artifact for this head; protected integration remains pending.

Executable save and recovery journey

The reference browser entry now connects the actual public editor and autosave session to the existing bounded, in-memory document repository. It demonstrates queued latest-edit saving, confirmed failure, lost confirmation before/after commit, reread-before-retry, conflict and independent-copy recovery. Edits after a fork target the copy while preserving the original. Same-turn retry/copy admission and out-of-order digest settlement are guarded.

The saved document is restored before editing or autosave is enabled. An unreadable stored draft stays untouched. A capture failure remains visibly unsaved even after an older save finishes, and shortening the draft permits saving again. Native controls, keyboard recovery, live status, forced colors, 320px layout and print behavior are exercised without changing the core editor presentation.

This remains an English-language, single-document, memory-only example with the existing 65,536-code-unit storage ceiling. Reloading or closing the tab loses every draft and copy; the screen states that limitation. It is not production persistence, a localization rollout, a latency benchmark or a 20ms performance claim.

The existing SSR/native-form, authorized collaboration lifecycle, delayed-proposal and bounded Office fixtures remain in the lane. The new recovery UI does not turn every fixture into a complete interactive application path.

The explicit Use saved version action now requires native confirmation. Cancel preserves the draft; confirmation rereads saved state, allows pending browser input to reach the editor, and rejects changed local or saved content before replacement. Malformed or schema-rejected saved content leaves the draft intact. Restore does not rewrite storage or advance its validator, and later edits use the freshly read version. In a fork it restores only the active copy. Keyboard focus returns to the editor. This is current-saved-version recovery, not a historical-version browser or durable rollback.

The complete recovery suite is 63/63 across three engines, including native cancellation/confirmation, reentrant admission, 320px forced colors, rich saved content, rejected envelopes, local/saved races, copy isolation and host/editor style isolation. The new race tests first reproduced pending browser input and a late save-state notification hiding restore rejection; both were repaired without weakening their oracles. The guide records the native-control design contract and the unavailable external visual-reference evidence.

Manual inspection of the 320px recovery capture exposed oversized toolbar text spilling beyond its controls. The example's broad native-control selectors were overriding the embedded editor. Those selectors now target only host action/control regions. Six browser regressions compare the embedded toolbar with its own package styling in normal and forced colors across all three engines, while retaining the host select's 44px minimum target. Both Chromium cases were RED before the selector fix; all six now pass. Core editor styles are unchanged; this is not proof of every narrow-toolbar layout. Before/after screenshots were retained and the corrected capture was manually inspected.

Interactive local suggestion

The new ?journey=proposal screen prepares a fixed in-memory suggestion, previews it as text, and requires native confirmation before replacement. It captures the original revision before delayed preparation, uses the public guarded restore during application, and preserves newer edits with a visible conflict. Discard returns focus to the draft. Read-only, single-flight preparation/application, competing discard, private failure redaction, keyboard, 320px forced colors, print and no-external-request boundaries are exercised. This fixture performs no model call or save; real hosts must preview their actual validated candidate and retain model/data-use policy.

All 18 proposal-specific checks pass across the three engines. The initial two missing-screen cases were RED before implementation; subsequent delayed preparation/application cases prove newer input is not replaced. The recovery suite now passes 63/63. The proposal fixture adds no production runtime or dependency change, and no coverage threshold, timeout or sample count was changed.

Interactive local collaboration

The new ?journey=collaboration screen connects two actual local document views using the existing authorized lifecycle and installed Yjs runtime. Start, reconnect and confirmed close are native controls. Reconnection preserves drafts and retires the prior connection before replacement; denied admission constructs no replacement. An indeterminate connection is reported as unconfirmed, never as a verified disconnection. Closing removes both editor bindings before destroying the documents, restores keyboard focus and requires confirmation before losing drafts.

All 18 collaboration-specific checks pass across three engines, including actual bidirectional update wiring, same-turn admission, failure recovery, denied replacement, read-only controls, 320px forced colors, print and real application unmount. The missing-screen, close-focus, missing unmount hook and false-disconnection cases were first RED; the final suite retains those checks. The exact installed browser consumer shares Yjs as well as React to avoid split document runtimes.

This is one tab with two in-memory views, no server, presence/cursors, remote transport, durable save or production authorization service. The demo admission checkbox authorizes the next connection only; real hosts retain revocation and provider policy. The collaboration fixture adds no dependency or published runtime contract change.

Causal verification repairs

• Extracting the tarball alone left external editor dependencies unresolved. The browser verifier now installs the exact tarball and dependency closure in an isolated consumer and shares its React peers with the host.
• Installed fonts were rejected by the browser harness. Its strict filesystem allowlist now includes only the repository and installed package directories; the guard is not disabled.
• Replacement input sometimes appended the preceding draft. The recovery tests now use focused keyboard selection/replacement and assert the entered text without weakening the delayed-digest or oversized-draft oracles.
• A full run with 1,094 passing assertions still failed on two worker RPC timeouts. The two implicated synchronous child builds lasted 63,237ms and 67,305ms. Build-capable reference tests now await the standard asynchronous child-process API, preserving the existing child/test deadlines and all consumer assertions. The final run has no RPC errors.
• The one-command Office handoff selected an unrelated ambient Python environment lacking Office dependencies. Its default is now the project-local Office virtual environment; the explicit controlled-host interpreter override remains supported. The regression was RED before the fix.

Earlier failures are not counted as successes or erased by later runs. No test timeout, retry policy, corpus size or coverage threshold was relaxed.

Exact-head local evidence — 2026-09-05

All following commands completed on 9ecda1c:

Verification	Result
pnpm coverage --maxWorkers 2	198 files, 1,097 tests; 100% statements, branches, functions and lines; no unhandled errors
pnpm verify:package	Public package contents, ESM/CJS, SSR, framework-free subpaths and strict TypeScript consumers passed
Project-local Office Python 3.14 docstring check and coverage run	173 tests; 100% statements, branches and docstring coverage
node examples/reference-host/verify-current-reference-journey.mjs	All 9 currently implemented partial-journey stages passed, including installed package, application SSR, bounded Office and browsers
node examples/reference-host/verify-browser-journey.mjs --self-test	135 installed-package browser tests across Chromium, Firefox and WebKit; 0 unexpected, skipped or flaky tests
Full repository Playwright suite	205 tests passed, including cross-engine clipboard consensus; 0 unexpected, skipped or flaky tests; this is source-harness evidence, distinct from the installed-package run above

The browser verifier also strictly typechecks the executable host. The configured production coverage boundary excludes reference example files; their UI behavior is covered by the actual browser journeys, not mislabeled as production unit coverage.

The tested and separately retained npm tarball is version 0.7.0, SHA-256:

7887c94822fc27ebd590627700c0c20c9b5c7f79d3b6c13b491fdb96d37b0321

Runtime: Node 24.19.0, pnpm 11.5.3, Playwright 1.62.0. Browser-test lock SHA-256: 3f6b822f0b271b57cd255bc7efba677177b96079a304a43959260cb48e81d94b. Fresh source-harness 320px forced-colors restore, suggestion and collaboration captures were retained, along with the toolbar style-boundary capture. These source captures are distinct from the installed-package browser receipt. The retained artifact was produced with the same pnpm pack command as the verifier, after all builds completed, and its digest matches the tested archive. Its unchanged digest is expected: this head changes example styling, example documentation and browser tests, not packaged library content. During the earlier 03-generation verification, an npm pack archive differed in package-manager metadata and was excluded; that historical mismatch remains recorded rather than mislabeled as a current-head tested artifact. This is a candidate artifact, not a published protected release.

See the exact-head reference guide for executable commands, replacement boundaries and omissions. PRD/TRD/CONTRACTS ownership remains canonical; inherited foundation documentation remains owned by #402, and these reference journeys do not expand the published host boundary.

Remaining acceptance and gates

Keep Draft. The shared dependency prerequisite is now inherited locally. Remaining #377 acceptance includes parent-before-child protected integration and the clean-checkout journey against the immutable protected artifact selected by #118. Next.js, production credentials, a live collaboration service and a durable database are not requirements of #377; its reference adapters may be synthetic.

#176 retains Markdown ownership; #379 retains performance work; #153 retains React act containment; #151 retains forced-colors accessibility work against the already-merged #362 baseline; #380 retains the dedicated input lane; #402 retains shared dependency/foundation repairs; #118 retains release authority. No lane is closed or declared inherited solely from these local results.

Fresh exact-head repository and central checks, independent formal review, thread resolution and parent/protected integration are still required. GitHub API access recovered; hosted checks and reviews are being refreshed for this newly pushed head. Draft-admission skipped jobs are non-passing, not green evidence. Local browser and Git verification do not replace required hosted evidence. No Ready, approval, merge, tag, publication, gate weakening or bypass is claimed.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}