@kumwe/studio-preview 0.1.0-alpha.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kumwe Studio contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# `@kumwe/studio-preview`
+
+Status: pre-Gate-A foundation alpha. The channel is an executable contract spike, not a qualified adapter.
+
+An exact-origin, typed request channel between Studio and a host-rendered preview surface. A host can
+render Twig, Liquid, JSX, or another server template without teaching the canvas to reproduce its
+markup. Wildcard target origins are rejected.
+
+The channel handles correlation, timeouts, abort signals, protocol filtering, and disposal. The host
+still owns authentication, authorization, CSP, sandboxing, and rendering.
+
+## Host responder and handshake
+
+`PreviewClient` is the Studio half of the channel; `PreviewHost` is the preview-surface half. Both
+pin an exact target origin and drop any inbound message whose source window, origin, schema, channel
+ID, session generation, or sequence does not match; each direction stamps its own monotonic sequence
+counter. Outbound client messages cross the same canonical guard before posting, and the draft.2
+message vocabulary is closed.
+
+The handshake and request flow is announce → ready → render → rendered:
+
+1. The host constructs a `PreviewHost` with its renderer id, viewport inventory, and a render
+   callback, then calls `announce()` to post `studio.preview/ready`.
+2. Studio awaits `client.ready()`, which resolves with the announced payload — immediately when the
+   announcement already arrived — and rejects on timeout, abort, or disposal.
+3. Studio requests `studio.preview/render` via `client.render()` with a session-unique `requestId`.
+   The host invokes its render callback with an `AbortSignal` and replies with
+   `studio.preview/rendered` carrying the same request ID and draft digest. A newer request aborts and
+   generation-invalidates in-flight work on both sides, so a stale result is never posted or resolved
+   even when a retry uses the same digest at another viewport.
+4. A failed render is answered with `studio.preview/error` (code `studio.preview/render-failed`, the
+   request ID as `correlationId`, `retryable: true`) and a generic message — renderer failure
+   details never cross the channel.
+5. `client.select()` forwards `studio.preview/select` to the host's `onSelect` listeners.
+
+## Portable draft identity and markers
+
+`canonicalPreviewDraftBytes(draft)` returns exactly the canonical UTF-8 bytes of a complete Studio
+artifact. `computePreviewDraftDigest(draft)` hashes those bytes as lowercase hexadecimal SHA-256; it
+does not add an envelope, prefix, viewport, BOM, or newline. The host still validates and authorizes
+the staged draft, recomputes its digest, and compares it before rendering — the digest is never a
+credential.
+
+`createPreviewMarker(digest, ordinal)` implements the canonical
+`studio.preview/node/<digest>/<ordinal>` grammar. `createPreviewMarkerInventory(blueprint, digest)`
+enumerates roots, each node before descendants, sorted slot names, then child arrays. Every rendered
+response requires an exact one-to-one `markerMap`; the generic responder refuses a mismatched digest,
+grammar, contiguous order, duplicate, or incomplete map. Because the channel does not hold the draft,
+the authoritative renderer additionally compares node mapping with `createPreviewMarkerInventory`;
+the standalone reference renderer does so. `announceActivation()` accepts only a marker from the
+currently accepted inventory, and the client independently drops invented or revoked activation
+traffic.
+
+These semantics require wire protocol `0.1.0-draft.2`. A `.1` peer is incompatible rather than
+silently accepted. Portable implementations replay `@kumwe/studio-testkit/vectors/preview/` against
+their own canonicalizer and traversal.
+
+## Marker geometry
+
+`client.measure()` posts `studio.preview/measure` with a non-empty bounded marker list and resolves with the
+`studio.preview/measurements` answer: per marker, one or more CSS-pixel rectangles relative to the
+preview viewport origin (inline content fragments across lines), plus viewport metrics. Markers the
+renderer cannot place are returned in a distinct `unknown` list, never thrown. A marker outside the
+latest digest-bound inventory is rejected locally with `PreviewChannelError` code
+`studio.preview/measure-stale-marker`; the host independently rejects raw stale traffic without
+invoking the measurer.
+
+The host never reads the DOM. The embedding renderer passes a `measure` callback in
+`PreviewHostOptions`; without one, measure requests are answered with the qualified
+`studio.preview/measure-unavailable` error, and a throwing measurer is answered with
+`studio.preview/measure-failed` — measurer failure details never cross the channel.
+
+Geometry is volatile, not document state: each response is stamped with the digest of the render it
+was measured against. The host captures that digest and a private generation before invoking the
+callback. A same-digest rerender, newer measurement, disposal, reload or teardown aborts and
+invalidates the prior measurement. A viewport instruction also rejects the client's pending
+measurement with `PreviewChannelError` code `studio.preview/measure-viewport-changed` and aborts the
+host callback before viewport listeners run, so pre-resize geometry cannot settle late. Measured and
+unknown entries must exactly partition the requested markers.
+
+Version negotiation currently requires the exact draft wire version on both sides: schema filtering
+accepts only `STUDIO_WIRE_PROTOCOL_VERSION`, so a ready announcement from a host speaking any other
+version is discarded and `ready()` times out instead of resolving against an incompatible host.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,9 @@
+# Third-party notices
+
+<!-- Generated by scripts/generate-third-party-notices.mjs. Do not edit by hand. -->
+
+Package: `@kumwe/studio-preview`
+
+Production closure SHA-256: `4f53cda18c2baa0c0354bb5f9a3ecbe5ed12ab4d8e11ba873c2f11161202b945`
+
+This package has no third-party runtime dependencies.

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { PreviewClient, PreviewChannelError, type PreviewClientOptions, type PreviewMeasureOptions, type PreviewMeasureOutcome, type PreviewMessageEvent, type PreviewMessageListener, type PreviewMessageSource, type PreviewMessageTarget, type PreviewProtocolListener, type PreviewReadyOptions, type PreviewRenderOptions, } from './preview-client.js';
+export { PreviewHost, type PreviewHostOptions, type PreviewMeasureCallback, type PreviewMeasurement, type PreviewRenderCallback, type PreviewSelectListener, } from './preview-host.js';
+export { canonicalPreviewDraftBytes, computePreviewDraftDigest, createPreviewMarker, createPreviewMarkerInventory, type PreviewDigestOptions, type PreviewMarkerInventory, } from './preview-identity.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,GAC1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,WAAW,EACX,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,GAC3B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,0BAA0B,EAC1B,yBAAyB,EACzB,mBAAmB,EACnB,4BAA4B,EAC5B,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,GAC5B,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { PreviewClient, PreviewChannelError, } from './preview-client.js';
+export { PreviewHost, } from './preview-host.js';
+export { canonicalPreviewDraftBytes, computePreviewDraftDigest, createPreviewMarker, createPreviewMarkerInventory, } from './preview-identity.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,mBAAmB,GAWpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,WAAW,GAMZ,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,0BAA0B,EAC1B,yBAAyB,EACzB,mBAAmB,EACnB,4BAA4B,GAG7B,MAAM,uBAAuB,CAAC"}

package/dist/preview-client.d.ts

@@ -0,0 +1,96 @@
+import { type PreviewMeasurePayload, type PreviewMeasurementsPayload, type PreviewMessage, type PreviewReadyPayload, type PreviewRenderedPayload, type PreviewRenderPayload, type PreviewActivatedPayload, type PreviewDisposePayload, type PreviewSelectPayload, type PreviewViewportPayload, type PreviewTeardownPayload, type QualifiedName } from '@kumwe/studio-protocol';
+/** Stable client-side and wire failure surfaced by the preview channel. */
+export declare class PreviewChannelError extends Error {
+    readonly code: QualifiedName;
+    readonly retryable: boolean;
+    constructor(code: QualifiedName, message: string, retryable?: boolean);
+}
+export interface PreviewMessageEvent {
+    data: unknown;
+    origin: string;
+    source: unknown;
+}
+export type PreviewMessageListener = (event: PreviewMessageEvent) => void;
+export interface PreviewMessageSource {
+    addEventListener(type: 'message', listener: PreviewMessageListener): void;
+    removeEventListener(type: 'message', listener: PreviewMessageListener): void;
+}
+export interface PreviewMessageTarget {
+    postMessage(message: unknown, targetOrigin: string): void;
+}
+export interface PreviewClientOptions {
+    channelId: string;
+    sessionGeneration: string;
+    source: PreviewMessageSource;
+    target: PreviewMessageTarget;
+    targetOrigin: string;
+    timeoutMilliseconds?: number;
+}
+export interface PreviewReadyOptions {
+    signal?: AbortSignal;
+}
+export interface PreviewRenderOptions {
+    signal?: AbortSignal;
+}
+export interface PreviewMeasureOptions {
+    signal?: AbortSignal;
+}
+/**
+ * Result of a `measure()` call. Geometry whose render digest no longer matches the
+ * client's latest rendered digest is discarded and surfaced as a `stale` outcome —
+ * a typed signal to re-measure, not an error.
+ */
+export type PreviewMeasureOutcome = {
+    geometry: PreviewMeasurementsPayload;
+    status: 'measured';
+} | {
+    measuredDigest: string;
+    status: 'stale';
+};
+export type PreviewProtocolListener = (message: PreviewMessage) => void;
+export type PreviewActivationListener = (payload: PreviewActivatedPayload) => void;
+export declare class PreviewClient {
+    #private;
+    constructor(options: PreviewClientOptions);
+    dispose(): void;
+    onMessage(listener: PreviewProtocolListener): () => void;
+    /**
+     * Resolves once the host announces `studio.preview/ready` on this channel. If the
+     * announcement was already received, the cached payload resolves immediately.
+     *
+     * `isPreviewMessage` accepts only ready payloads carrying the exact draft wire protocol
+     * version, so an announcement from an incompatible host is filtered out and never resolves
+     * this promise — the wait times out instead. The promise also rejects on abort or when the
+     * client is disposed.
+     */
+    ready(options?: PreviewReadyOptions): Promise<PreviewReadyPayload>;
+    render(payload: PreviewRenderPayload, options?: PreviewRenderOptions): Promise<PreviewRenderedPayload>;
+    /**
+     * Requests the on-screen geometry of render markers from the responder. Resolves with a
+     * `measured` outcome carrying viewport-relative CSS-pixel rectangles, or a `stale`
+     * outcome when the response was measured against a render this client no longer
+     * considers latest. Rejects on teardown, reload, supersession, abort, timeout, and
+     * disposal exactly like `render()` does. Requires a completed render: geometry is a
+     * volatile measurement of a specific render digest, never document state.
+     */
+    measure(payload: PreviewMeasurePayload, options?: PreviewMeasureOptions): Promise<PreviewMeasureOutcome>;
+    /**
+     * Drive the preview surface to a semantic viewport role or to bounded
+     * explicit dimensions. The two are alternatives, so a payload carrying both
+     * is refused before it reaches the channel.
+     */
+    setViewport(payload: PreviewViewportPayload): void;
+    /**
+     * Instruct the renderer to revoke the resources it holds for a superseded
+     * draft while the channel stays open. This is not teardown: teardown ends
+     * the session, dispose frees a render's resources within it.
+     */
+    disposeDraft(payload: PreviewDisposePayload): void;
+    /** Observe trusted marker interactions the renderer reports. */
+    onActivated(listener: PreviewActivationListener): () => void;
+    select(payload: PreviewSelectPayload): void;
+    /** Announce channel closure to the host, then dispose this client. */
+    teardown(reason: PreviewTeardownPayload['reason']): void;
+}
+export declare function normalizeOrigin(input: string): string;
+//# sourceMappingURL=preview-client.d.ts.map

package/dist/preview-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-client.d.ts","sourceRoot":"","sources":["../src/preview-client.ts"],"names":[],"mappings":"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"}