feat(example): ship an executable reference host for SSR, autosave, collaboration, and conflicts

[seonghobae]

Buyer-visible product gap

Inkspan’s protected branch documents a strict host/editor authority boundary and exposes composable package surfaces, but acquisition readiness requires that boundary to be executable from the packed public artifact rather than inferred from source imports or prose. This issue owns the stable buyer-facing acceptance contract. Draft #381 is the existing Inkspan writer for the reference-host implementation; its mutable head/base/check/review state must be refetched live and is not duplicated here.

Product objective

Ship a small executable reference host that demonstrates the correct integration contract without turning Inkspan into the host application. It must be useful for buyers, package consumers, regression tests, support reproduction, and acquisition review.

The reference is not a production identity provider, tenant service, document database, collaboration server, model gateway, deployment plane, durable audit service, or PDF authority. Every non-Inkspan responsibility must remain explicit and replaceable. Standalone Inkspan must continue to require no service, database, network, credential, or model; model output is untrusted proposal data.

Required reference application

Maintain examples/reference-host as the canonical executable example and consume the exact packed Inkspan artifact rather than source-relative imports.

The application must demonstrate:

1. SSR/hydration
   • deterministic server shell;
   • narrow client-only hydration boundary;
   • no browser editor view during server rendering;
   • no hydration warning/error on the supported React/browser matrix.
2. Package consumption
   • root editor export and documented subpaths;
   • styles.css and both supported font-bundle options;
   • React-free imports usable in server/worker-safe files;
   • CJS and ESM wherever the package contract promises both;
   • no src/ import, unpublished workspace alias, runtime environment-variable dependency, or hidden network requirement.
3. Host-owned persistence contract
   • bounded reference DocumentRepositoryPort or equivalent;
   • strong-validator / RFC 9110 If-Match semantics;
   • deterministic success, conflict, ambiguous failure, retry, restore/fork demonstrations;
   • reference adapters clearly marked synthetic/non-production unless separately reviewed.
4. Autosave and lifecycle UX
   • saving, queued, blocked, conflict, failed, retrying, recovered, and clean states derived from programmatic state;
   • no untranslated host copy embedded in the core package;
   • no silent validator advancement after conflict or ambiguous failure.
5. Collaboration composition
   • host-created Yjs document/provider lifecycle;
   • room/identity/authorization values supplied by the host boundary;
   • provider-generation replacement, reconnect, unmount, and teardown cleanup;
   • no embedded provider credential, room authorization, or durable-success claim.
6. Native forms and accessibility
   • SSR-compatible named form field;
   • reset, submit, controlled/uncontrolled, read-only, keyboard, screen-reader, forced-colors, print, and narrow-viewport journeys;
   • submit/reset admission bound to the same synchronous single-flight state guarding the host-owned durable callback, including a same-turn regression before asynchronous presentation state commits.
7. Model-assisted proposal boundary
   • deterministic local proposal fixture or mock;
   • capture expected revision before delay;
   • insert/restore only under the documented revision contract;
   • show conflict rather than overwriting newer content;
   • no provider SDK, key, prompt logging, or network model call.
8. Office/converter handoff
   • bounded content passed through the React-free Markdown/converter and Office interfaces;
   • deterministic supported fidelity demonstrated without claiming unsupported round-trip fidelity or durable PDF authority.

Test and acquisition evidence

• Build the npm tarball first and install that exact tarball into the reference host in CI.
• Run typecheck, production/server build where applicable, server render, hydration, package-consumer, deterministic host fixtures, Office/converter checks, and Playwright acceptance.
• Cover Chromium, Firefox, and WebKit for browser journeys applicable to the public package.
• Verify packed ESM/CJS public subpaths under hostile ambient browser-authority fixtures where relevant.
• Include deterministic synthetic conflict/retry/ambiguous-failure/provider-disconnect fixtures.
• Verify there are no unexpected runtime network requests from Inkspan or bundled fonts.
• Verify source-relative imports cannot satisfy the lane.
• Keep host-specific example code outside published runtime entry points unless an accepted package contract explicitly makes it public.
• Add acquisition-readable ownership documentation/diagram showing editor state, persistence, identity/authorization, collaboration provider, model policy, Office/export handoff, and release authority.

“Copy this, replace that” documentation contract

Reference element	Buyer action
synthetic actor/tenant	replace with the host’s authenticated authorization context
reference document repository	replace with an atomic durable store enforcing strong-validator semantics
local Yjs/provider fixture	replace with an authorized provider under host lifecycle control
deterministic AI fixture	replace with a host-approved model gateway and data-use policy
sample messages	localize in the host application

Document every deliberate omission. Do not call sample persistence, authentication, provider, model, deployment, audit, or export infrastructure production-ready.

Acceptance criteria

• A clean checkout can build the Inkspan tarball, install it into the reference host, and pass the complete supported reference journey with one documented command.
• SSR/hydration, native form, autosave success/conflict/ambiguous failure, provider teardown/reconnect/replacement, read-only, and stale proposal paths are executable and tested.
• Native-form submit/reset admission uses the synchronous single-flight state that guards durable host mutation.
• The application never imports from src/, never relies on an unpublished alias, and never reads an Inkspan runtime credential/environment variable.
• Host/editor ownership is visible in code, tests, diagrams, and recovery behavior.
• Accessibility and cross-engine tests exercise the packed CSS/fonts and real controls.
• No credential, production PII, external model call, hidden network dependency, durable database, tenant authority, or durable audit authority is introduced into the package.
• Production code/public APIs introduced by reference infrastructure satisfy repository coverage/documentation gates, or remain clearly excluded example/test code under an accepted policy.
• Current dependency-owner repairs are inherited rather than duplicated: in particular, public Markdown/serialization behavior remains owned by its existing canonical lane and must be revalidated in feat(reference-host): add buyer integration safety fixtures #381 after safe reconciliation.

Lifecycle and dependency contract

Priority: P1 adoption and procurement evidence.

Development may proceed against a packed candidate, but final acceptance must use the exact integrated protected artifact selected by the stable-release lane in #118. Active-PR, predecessor, branch-only, skipped-required, synthetic-merge-only, or model-only evidence cannot substitute for protected release acceptance.

Before changing #381 lifecycle state or closing this issue, refetch protected main, exact head/live base, ancestry/mergeability, changed paths/active writers, live rulesets, formal reviews/threads, all applicable repository/central workflow jobs and their actual checkout/source identities, package/SBOM/provenance evidence, and release/tag/registry state. Do not force-push, destructively rebase, self-approve, copy another active writer’s source repair, transfer predecessor evidence, weaken gates, or bypass governance.