@kumwe/studio-preview 0.1.0-alpha.4 → 0.1.0-alpha.6

package/README.md

@@ -14,7 +14,8 @@ still owns authentication, authorization, CSP, sandboxing, and rendering.
 `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.
+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:
 
@@ -22,21 +23,47 @@ The handshake and request flow is announce → ready → render → rendered:
    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()`. The host invokes its render
-   callback and replies with `studio.preview/rendered` carrying the same draft digest as the
-   request. A newer request supersedes an in-flight one on both sides, so a stale result is never
-   posted or resolved.
+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
-   draft digest as `correlationId`, `retryable: true`) and a generic message — renderer failure
+   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 bounded marker list and resolves with the
+`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.
+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
@@ -44,10 +71,12 @@ The host never reads the DOM. The embedding renderer passes a `measure` callback
 `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. A response whose digest no longer matches the client's latest completed render
-resolves as a typed `{ status: 'stale' }` outcome instead of geometry, and a reload voids in-flight
-measurements exactly like it voids renders. Newer measure requests supersede older ones on both
-sides.
+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

package/dist/index.d.ts

@@ -1,3 +1,4 @@
-export { PreviewClient, 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 { 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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,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"}
+{"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

@@ -1,3 +1,4 @@
-export { PreviewClient, } from './preview-client.js';
+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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,GAWd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,WAAW,GAMZ,MAAM,mBAAmB,CAAC"}
+{"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

@@ -1,4 +1,10 @@
-import { type PreviewMeasurePayload, type PreviewMeasurementsPayload, type PreviewMessage, type PreviewReadyPayload, type PreviewRenderedPayload, type PreviewRenderPayload, type PreviewSelectPayload, type PreviewTeardownPayload } from '@kumwe/studio-protocol';
+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;
@@ -42,6 +48,7 @@ export type PreviewMeasureOutcome = {
     status: 'stale';
 };
 export type PreviewProtocolListener = (message: PreviewMessage) => void;
+export type PreviewActivationListener = (payload: PreviewActivatedPayload) => void;
 export declare class PreviewClient {
     #private;
     constructor(options: PreviewClientOptions);
@@ -67,6 +74,20 @@ export declare class PreviewClient {
      * 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;

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

@@ -1 +1 @@
-{"version":3,"file":"preview-client.d.ts","sourceRoot":"","sources":["../src/preview-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,qBAAqB,EAC1B,KAAK,0BAA0B,EAC/B,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC5B,MAAM,wBAAwB,CAAC;AAEhC,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,MAAM,sBAAsB,GAAG,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,CAAC;AAE1E,MAAM,WAAW,oBAAoB;IACnC,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAC1E,mBAAmB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,sBAAsB,GAAG,IAAI,CAAC;CAC9E;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3D;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,MAAM,EAAE,oBAAoB,CAAC;IAC7B,MAAM,EAAE,oBAAoB,CAAC;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAC7B;IAAE,QAAQ,EAAE,0BAA0B,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,GAC5D;IAAE,cAAc,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC;AAEhD,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,CAAC;AAuBxE,qBAAa,aAAa;;gBAmBL,OAAO,EAAE,oBAAoB;IAazC,OAAO,IAAI,IAAI;IA2Bf,SAAS,CAAC,QAAQ,EAAE,uBAAuB,GAAG,MAAM,IAAI;IAO/D;;;;;;;;OAQG;IACI,KAAK,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAqCtE,MAAM,CACX,OAAO,EAAE,oBAAoB,EAC7B,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,sBAAsB,CAAC;IAiElC;;;;;;;OAOG;IACI,OAAO,CACZ,OAAO,EAAE,qBAAqB,EAC9B,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,qBAAqB,CAAC;IA6D1B,MAAM,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI;IAqJlD,sEAAsE;IAC/D,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC,QAAQ,CAAC,GAAG,IAAI;CAahE;AAGD,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAUrD"}
+{"version":3,"file":"preview-client.d.ts","sourceRoot":"","sources":["../src/preview-client.ts"],"names":[],"mappings":"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"}