@civitai/sdk 0.2.0

package/dist/core/handshake.js

@@ -0,0 +1,60 @@
+/**
+ * The host's side of the handshake, as it arrives on the wire. The shapes are
+ * the host's and must track it.
+ */
+/** Discriminator only — the payload is still unvalidated wire data. */
+export function isHostMessage(data, type) {
+    return (typeof data === 'object' &&
+        data !== null &&
+        'type' in data &&
+        data.type === type);
+}
+const FRAGMENT_MARKER_KEY = 'civitai-block';
+const FRAGMENT_VERSION = 'v1';
+const FRAGMENT_KEYS = [FRAGMENT_MARKER_KEY, 'theme', 'renderMode', 'blockInstanceId'];
+/** `null` when the hash is not one the host wrote — it may be the app's own routing. */
+function ourFragment(hash) {
+    if (typeof hash !== 'string' || hash.length === 0)
+        return null;
+    const body = hash.startsWith('#') ? hash.slice(1) : hash;
+    if (body.length === 0)
+        return null;
+    let params;
+    try {
+        params = new URLSearchParams(body);
+    }
+    catch {
+        return null;
+    }
+    return params.get(FRAGMENT_MARKER_KEY) === FRAGMENT_VERSION ? params : null;
+}
+/**
+ * The theme and render mode the host put in the URL so a block can paint before
+ * `BLOCK_INIT` arrives. Frozen at mount — a later toggle arrives as
+ * `THEME_CHANGE`, never as a re-navigation of a third-party frame.
+ */
+export function parseBlockInitFragment(hash) {
+    const params = ourFragment(hash);
+    if (!params)
+        return {};
+    const out = {};
+    const theme = params.get('theme');
+    if (theme === 'light' || theme === 'dark')
+        out.theme = theme;
+    const renderMode = params.get('renderMode');
+    if (renderMode === 'iframe' || renderMode === 'inline')
+        out.renderMode = renderMode;
+    const blockInstanceId = params.get('blockInstanceId');
+    if (blockInstanceId)
+        out.blockInstanceId = blockInstanceId;
+    return out;
+}
+/** The hash with the host's own keys removed, or `null` when it wrote none. */
+export function stripBlockInitFragment(hash) {
+    const params = ourFragment(hash);
+    if (!params)
+        return null;
+    for (const key of FRAGMENT_KEYS)
+        params.delete(key);
+    return params.toString();
+}

package/dist/core/messaging.d.ts

@@ -0,0 +1,30 @@
+import type { BlockTransport } from './transport.js';
+export interface NotifyOptions {
+    transport?: BlockTransport;
+}
+export interface CallOptions extends NotifyOptions {
+    /**
+     * Cancels the call. Request timeouts belong to the host, which owes a reply
+     * to every request; this is the caller's own deadline, not a bound we impose.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * A domain's requests: name → what it takes and what it answers with. The same
+ * shape the DOM uses for `WindowEventMap`, so a generic function can be typed
+ * by the name it is given.
+ */
+export type RequestMap = Record<string, {
+    params: unknown;
+    result: unknown;
+}>;
+/** A domain's unsolicited messages: name → payload. Both directions use it. */
+export type PushMap = Record<string, unknown>;
+/**
+ * The typed entry points for one domain. A domain declares its own maps and
+ * calls these; nothing in `core` needs to know the domains exist.
+ */
+export declare function createCaller<R extends RequestMap>(): <K extends keyof R & string>(type: K, params: R[K]['params'], opts?: CallOptions) => Promise<R[K]['result']>;
+/** A message the host does not answer, so there is nothing to await. */
+export declare function createNotifier<N extends PushMap>(): <K extends keyof N & string>(type: K, payload: N[K], opts?: NotifyOptions) => void;
+export declare function createListener<P extends PushMap>(): <K extends keyof P & string>(transport: BlockTransport, type: K, handler: (payload: P[K]) => void) => () => void;

package/dist/core/messaging.js

@@ -0,0 +1,23 @@
+import { getTransport } from './get-transport.js';
+/**
+ * The typed entry points for one domain. A domain declares its own maps and
+ * calls these; nothing in `core` needs to know the domains exist.
+ */
+export function createCaller() {
+    return async function call(type, params, opts = {}) {
+        const transport = opts.transport ?? getTransport();
+        return (await transport.request(type, params, { signal: opts.signal }));
+    };
+}
+/** A message the host does not answer, so there is nothing to await. */
+export function createNotifier() {
+    return function notify(type, payload, opts = {}) {
+        const transport = opts.transport ?? getTransport();
+        transport.notify({ type, payload });
+    };
+}
+export function createListener() {
+    return function on(transport, type, handler) {
+        return transport.on(type, (payload) => handler(payload));
+    };
+}

package/dist/core/origin-matcher.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Matches exact origins and `https://*.example.com` wildcards. Scheme-pinned and
+ * anchored on a dot boundary, so `*.civitaic.com` rejects both
+ * `civitaic.com.attacker.tld` and `evilcivitaic.com`.
+ */
+export declare class OriginMatcher {
+    private readonly exact;
+    private readonly wildcards;
+    constructor(allowedParentOrigins: readonly string[]);
+    /** True when `origin` is allowed by an exact or wildcard allowlist entry. */
+    matches(origin: string): boolean;
+}

package/dist/core/origin-matcher.js

@@ -0,0 +1,71 @@
+/**
+ * Matches exact origins and `https://*.example.com` wildcards. Scheme-pinned and
+ * anchored on a dot boundary, so `*.civitaic.com` rejects both
+ * `civitaic.com.attacker.tld` and `evilcivitaic.com`.
+ */
+export class OriginMatcher {
+    exact;
+    wildcards;
+    constructor(allowedParentOrigins) {
+        const exact = new Set();
+        const wildcards = [];
+        for (const raw of allowedParentOrigins) {
+            const entry = raw.trim();
+            if (!entry)
+                continue;
+            const wildcard = parseWildcard(entry);
+            if (wildcard) {
+                wildcards.push(wildcard);
+            }
+            else {
+                exact.add(entry);
+            }
+        }
+        this.exact = exact;
+        this.wildcards = wildcards;
+    }
+    /** True when `origin` is allowed by an exact or wildcard allowlist entry. */
+    matches(origin) {
+        if (this.exact.has(origin))
+            return true;
+        for (const wc of this.wildcards) {
+            if (!origin.startsWith(wc.scheme))
+                continue;
+            const host = origin.slice(wc.scheme.length);
+            if (host.includes('/'))
+                continue;
+            // Dot-anchored against the END of the host, so a port never matches a
+            // wildcard — list a ported parent as an exact entry. The length test
+            // requires a leading label, excluding the apex itself.
+            if (host.length > wc.suffix.length && host.endsWith(wc.suffix)) {
+                return true;
+            }
+        }
+        return false;
+    }
+}
+/**
+ * Parses a `https://*.example.com`-style entry into `{scheme, suffix}`.
+ * Returns `null` for non-wildcard (exact) entries.
+ * Throws for malformed wildcards (`*` only, `https://*`, `https://*.`).
+ */
+function parseWildcard(entry) {
+    const star = entry.indexOf('*');
+    if (star === -1)
+        return null;
+    // Wildcard must be of the exact form `<scheme>://*.<suffix>`.
+    const marker = '://*.';
+    const markerAt = entry.indexOf(marker);
+    if (markerAt === -1) {
+        throw new Error(`IframeTransport: invalid wildcard origin "${entry}". ` +
+            'Wildcard entries must look like "https://*.example.com".');
+    }
+    const scheme = entry.slice(0, markerAt + 3); // include "://"
+    const bareSuffix = entry.slice(markerAt + marker.length); // after "://*."
+    if (!scheme || scheme === '://' || !bareSuffix) {
+        throw new Error(`IframeTransport: invalid wildcard origin "${entry}". ` +
+            'A wildcard needs a scheme and a non-empty domain suffix, e.g. "https://*.example.com".');
+    }
+    // Dot-anchor the suffix so `*.civitaic.com` only matches on a label boundary.
+    return { scheme, suffix: `.${bareSuffix}` };
+}

package/dist/core/transport.d.ts

@@ -0,0 +1,60 @@
+import type { BlockContext, BlockInitPayload, BlockSettings, BlockToken, ColorDomain, Theme, ViewerInfo, WrappedToken } from './handshake.js';
+/**
+ * Synchronous snapshot. Before `BLOCK_INIT` every field is a sentinel empty, so
+ * anything rendering UI must gate on `ready`; senders can rely on the outbound queue.
+ */
+export interface BlockSnapshot {
+    ready: boolean;
+    renderMode: 'iframe' | 'inline';
+    context: BlockContext;
+    token: BlockToken;
+    settings: BlockSettings;
+    /** `null` for anonymous viewers. For identity, read `/me` from the API rather than this. */
+    viewer: ViewerInfo | null;
+    theme: Theme;
+    blockInstanceId: string;
+    /**
+     * The validated parent origin; `null` until init. A money-scoped bearer token
+     * is sent here, so it is only ever an origin that passed the allowlist —
+     * never `document.referrer`, a cross-origin `location` or anything supplied
+     * by a caller.
+     */
+    hostOrigin: string | null;
+    /** Informational only — derive SFW from `maxBrowsingLevel`, not this. */
+    domain?: ColorDomain | null;
+    /** Domain ceiling bitmask. `undefined` means consumers must fail closed to SFW. */
+    maxBrowsingLevel?: number;
+    /** The domain ceiling narrowed to this viewer. Always a subset of `maxBrowsingLevel`. */
+    effectiveBrowsingLevel?: number;
+}
+export interface RequestOptions {
+    signal?: AbortSignal;
+}
+export interface BlockTransport {
+    /** Read synchronously at render time; `subscribe` fires on every change. */
+    readonly snapshot: {
+        get(): BlockSnapshot;
+        subscribe(listener: () => void): () => void;
+    };
+    /** A message the host does not answer. */
+    notify(message: {
+        type: string;
+        payload?: unknown;
+    }): void;
+    /**
+     * Resolves with the value the host answered, or rejects: a `BridgeError` for a
+     * failure it reported, the signal's `reason` if the caller aborts. Framing —
+     * correlation ids, envelopes — is this layer's business, not a caller's.
+     */
+    request(type: string, params: unknown, opts?: RequestOptions): Promise<unknown>;
+    /**
+     * Unsolicited host pushes, already origin-checked — a caller never needs its
+     * own window listener.
+     */
+    on(type: string, handler: (payload: unknown) => void): () => void;
+}
+export declare const EMPTY_SNAPSHOT: BlockSnapshot;
+/** Convert a wire `BlockInitPayload` (ISO string expiresAt) into a `BlockSnapshot`. */
+export declare function snapshotFromInit(payload: BlockInitPayload, hostOrigin: string): BlockSnapshot;
+/** Wire `WrappedToken` (ISO expiry) → runtime `BlockToken` (Date expiry). */
+export declare function tokenFromWrapped(wrapped: WrappedToken): BlockToken;

package/dist/core/transport.js

@@ -0,0 +1,37 @@
+export const EMPTY_SNAPSHOT = {
+    ready: false,
+    renderMode: 'iframe',
+    context: { slotId: '' },
+    token: { raw: '', scopes: [], expiresAt: new Date(0) },
+    settings: { publisherSettings: {}, userSettings: {} },
+    viewer: null,
+    theme: 'light',
+    blockInstanceId: '',
+    hostOrigin: null,
+};
+/** Convert a wire `BlockInitPayload` (ISO string expiresAt) into a `BlockSnapshot`. */
+export function snapshotFromInit(payload, hostOrigin) {
+    return {
+        ready: true,
+        hostOrigin,
+        renderMode: payload.renderMode,
+        context: payload.context,
+        token: tokenFromWrapped(payload.token),
+        settings: payload.settings,
+        viewer: payload.viewer,
+        theme: payload.theme,
+        blockInstanceId: payload.blockInstanceId,
+        domain: payload.domain,
+        maxBrowsingLevel: payload.maxBrowsingLevel,
+        effectiveBrowsingLevel: payload.effectiveBrowsingLevel,
+    };
+}
+/** Wire `WrappedToken` (ISO expiry) → runtime `BlockToken` (Date expiry). */
+export function tokenFromWrapped(wrapped) {
+    return {
+        raw: wrapped.raw,
+        scopes: wrapped.scopes,
+        expiresAt: new Date(wrapped.expiresAt),
+        buzzBudget: wrapped.buzzBudget,
+    };
+}

package/dist/core/transports/iframe-transport.d.ts

@@ -0,0 +1,27 @@
+import { type BlockSnapshot, type BlockTransport, type RequestOptions } from '../transport.js';
+export interface IframeTransportOptions {
+    /** At least one entry. Other origins — including the local one — drop silently. */
+    allowedParentOrigins: string[];
+    /** Override for tests / SSR. Defaults to `globalThis.window`. */
+    window?: Window;
+}
+/**
+ * Validates `event.origin` on every inbound message, queues outbound until
+ * `BLOCK_INIT`, and correlates replies by `requestId`.
+ */
+export declare class IframeTransport implements BlockTransport {
+    #private;
+    readonly snapshot: {
+        get: () => BlockSnapshot;
+        subscribe: (listener: () => void) => () => boolean;
+    };
+    constructor(opts: IframeTransportOptions);
+    notify(message: {
+        type: string;
+        payload?: unknown;
+    }): void;
+    request(type: string, params: unknown, opts?: RequestOptions): Promise<unknown>;
+    on(type: string, handler: (payload: unknown) => void): () => void;
+    /** Test-only: tear down listeners + reject pending. */
+    dispose(): void;
+}

package/dist/core/transports/iframe-transport.js

@@ -0,0 +1,342 @@
+import { isHostMessage, parseBlockInitFragment, stripBlockInitFragment, } from '../handshake.js';
+import { EMPTY_SNAPSHOT, snapshotFromInit, tokenFromWrapped, } from '../transport.js';
+import { BridgeError, classifyHostError } from '../errors.js';
+import { OriginMatcher } from '../origin-matcher.js';
+/**
+ * The framing the host had before this package owned the protocol: fields
+ * straight in the payload, and failure as the server's own sentence. Converting
+ * it here is what keeps the rest of this file — and every domain — speaking one
+ * shape; when the host modernises a message, its domain drops the declaration
+ * and this stops being reached.
+ */
+function fromLegacyReply(reply) {
+    const { requestId, error, ...fields } = reply;
+    // An empty string is how the host spells "no failure" on these replies.
+    if (typeof error === 'string' && error !== '') {
+        return { requestId, error: { code: classifyHostError(error), message: error } };
+    }
+    // Some of these replies nest their value under `result` and others put its
+    // fields straight in the payload; the host was never consistent about it.
+    return { requestId, result: 'result' in fields ? fields.result : fields };
+}
+/**
+ * The host's pre-protocol messages, each with the reply it answers with —
+ * `<REQUEST>_RESULT` holds across most of them but not all. It is the migration
+ * ledger for this protocol: an entry leaves the day the host modernises that
+ * reply, and when it empties `fromLegacyReply` goes with it.
+ */
+const LEGACY_REPLIES = {
+    OPEN_BUZZ_PURCHASE: 'BUZZ_PURCHASE_RESULT',
+    OPEN_RESOURCE_PICKER: 'RESOURCE_PICKER_RESULT',
+    REQUEST_TOKEN: 'TOKEN_REFRESH_RESPONSE',
+    SAVE_IMAGE: 'SAVE_IMAGE_RESULT',
+};
+function replyTypeFor(type) {
+    return LEGACY_REPLIES[type] ?? `${type}_RESULT`;
+}
+/** Turns a reply into the value it carries, or the failure it reports. */
+function unwrap(type, reply, framing) {
+    if (reply == null || typeof reply !== 'object') {
+        throw new BridgeError('malformed', type, `${type} replied with no payload`);
+    }
+    const envelope = framing === 'legacy'
+        ? fromLegacyReply(reply)
+        : reply;
+    if (envelope.error !== undefined) {
+        throw new BridgeError(envelope.error.code, type, envelope.error.message || `${type} failed`);
+    }
+    if (envelope.result === undefined) {
+        throw new BridgeError('malformed', type, `${type} reply carried no result`);
+    }
+    return envelope.result;
+}
+let requestIdCounter = 0;
+/**
+ * Monotonic request ID with a random prefix so concurrent block instances
+ * sharing the dev console don't collide in logs.
+ */
+function nextRequestId() {
+    requestIdCounter += 1;
+    return `${Math.random().toString(36).slice(2, 8)}-${requestIdCounter}`;
+}
+/**
+ * Validates `event.origin` on every inbound message, queues outbound until
+ * `BLOCK_INIT`, and correlates replies by `requestId`.
+ */
+export class IframeTransport {
+    #originMatcher;
+    /** A wildcard entry is not a concrete origin, so it cannot be a `targetOrigin`. */
+    #exactAllowedOrigins;
+    #window;
+    #snapshot = EMPTY_SNAPSHOT;
+    #listeners = new Set();
+    snapshot = {
+        get: () => this.#snapshot,
+        subscribe: (listener) => {
+            this.#listeners.add(listener);
+            return () => this.#listeners.delete(listener);
+        },
+    };
+    /** Origin of the parent — captured from the first valid `BLOCK_INIT`. */
+    #parentOrigin = null;
+    /** Messages queued before `BLOCK_INIT` lands. Flushed in arrival order. */
+    #outbound = [];
+    #pending = new Map();
+    /**
+     * Handlers for UNSOLICITED parent→block pushes (e.g. `IMAGE_SCAN_RESOLVED`) —
+     * messages the host initiates on its own schedule, NOT replies to a pending
+     * `request`. Keyed by message type; each entry a set of subscribers.
+     */
+    #pushListeners = new Map();
+    /** Latches on the first `BLOCK_INIT`; the host re-posts it until it sees `BLOCK_READY`. */
+    #initResolved = false;
+    #messageListener;
+    constructor(opts) {
+        if (!opts.allowedParentOrigins.length) {
+            throw new Error('IframeTransport: allowedParentOrigins must contain at least one entry. ' +
+                'Configure NEXT_PUBLIC_BLOCK_ALLOWED_PARENT_ORIGINS (or the framework equivalent).');
+        }
+        this.#originMatcher = new OriginMatcher(opts.allowedParentOrigins);
+        this.#exactAllowedOrigins = opts.allowedParentOrigins
+            .map((entry) => entry.trim())
+            .filter((entry) => entry.length > 0 && !entry.includes('*'));
+        this.#window = opts.window ?? globalThis.window;
+        if (!this.#window) {
+            throw new Error('IframeTransport: no window available; cannot mount on the server.');
+        }
+        // Seeds theme/renderMode/blockInstanceId before the listener attaches, so a
+        // racing BLOCK_INIT finds them. `ready` stays false and nothing secret is
+        // ever sourced from the URL.
+        this.#seedFromFragment();
+        this.#messageListener = (event) => this.#handleMessage(event);
+        this.#window.addEventListener('message', this.#messageListener);
+        // Must follow addEventListener: a host that answers synchronously would
+        // otherwise post into a frame with no listener. Best-effort — the host still
+        // retries on its own.
+        this.#announceReady();
+    }
+    /** No-op when absent, foreign or an unknown version — we then just await BLOCK_INIT. */
+    #seedFromFragment() {
+        let hash;
+        try {
+            hash = this.#window.location?.hash;
+        }
+        catch {
+            // A location read can throw in exotic embeddings; the fast path is
+            // optional, so degrade to "no fragment".
+            return;
+        }
+        const fragment = parseBlockInitFragment(hash);
+        if (fragment.theme === undefined &&
+            fragment.renderMode === undefined &&
+            fragment.blockInstanceId === undefined) {
+            return;
+        }
+        this.#snapshot = {
+            ...this.#snapshot,
+            ...(fragment.theme !== undefined ? { theme: fragment.theme } : {}),
+            ...(fragment.renderMode !== undefined ? { renderMode: fragment.renderMode } : {}),
+            ...(fragment.blockInstanceId !== undefined
+                ? { blockInstanceId: fragment.blockInstanceId }
+                : {}),
+        };
+        // Cosmetic only, so a sandbox rejecting replaceState is swallowed.
+        try {
+            const remainder = stripBlockInitFragment(hash);
+            if (remainder !== null) {
+                const loc = this.#window.location;
+                const base = `${loc.pathname}${loc.search}`;
+                this.#window.history.replaceState(this.#window.history.state, '', remainder.length > 0 ? `${base}#${remainder}` : base);
+            }
+        }
+        catch {
+            // Sandboxed opaque origin, or no History API. Nothing depends on this.
+        }
+    }
+    /**
+     * Aimed at each exact allowlist entry, since `parentOrigin` is not yet known.
+     * Falls back to `'*'` only for a wildcard-only allowlist, which is safe here
+     * solely because the message carries no payload.
+     */
+    #announceReady() {
+        let parent;
+        try {
+            parent = this.#window.parent;
+            // Not framed (or self-framed) — nobody to announce to.
+            if (!parent || parent === this.#window)
+                return;
+        }
+        catch {
+            return;
+        }
+        const targets = this.#exactAllowedOrigins.length > 0 ? this.#exactAllowedOrigins : ['*'];
+        for (const target of targets) {
+            try {
+                parent.postMessage({ type: 'BLOCK_HELLO' }, target);
+            }
+            catch {
+                // An unreachable/mismatched target throws nothing in practice; guard
+                // anyway so one bad allowlist entry can't abort the remaining posts.
+            }
+        }
+    }
+    notify(message) {
+        this.#dispatch(message.type, message.payload);
+    }
+    async request(type, params, opts = {}) {
+        const framing = type in LEGACY_REPLIES ? 'legacy' : 'envelope';
+        return unwrap(type, await this.#exchange(type, params, opts), framing);
+    }
+    #exchange(type, params, opts) {
+        const responseType = replyTypeFor(type);
+        const { signal } = opts;
+        if (signal?.aborted)
+            return Promise.reject(signal.reason);
+        const requestId = nextRequestId();
+        return new Promise((resolve, reject) => {
+            const onAbort = () => {
+                if (this.#pending.delete(requestId))
+                    reject(signal.reason);
+            };
+            signal?.addEventListener('abort', onAbort, { once: true });
+            this.#pending.set(requestId, {
+                resolve: resolve,
+                reject,
+                detach: () => signal?.removeEventListener('abort', onAbort),
+                responseType,
+            });
+            this.#dispatch(type, { ...params, requestId });
+        });
+    }
+    on(type, handler) {
+        let set = this.#pushListeners.get(type);
+        if (!set) {
+            set = new Set();
+            this.#pushListeners.set(type, set);
+        }
+        set.add(handler);
+        return () => {
+            const s = this.#pushListeners.get(type);
+            if (!s)
+                return;
+            s.delete(handler);
+            if (s.size === 0)
+                this.#pushListeners.delete(type);
+        };
+    }
+    /** Test-only: tear down listeners + reject pending. */
+    dispose() {
+        this.#window.removeEventListener('message', this.#messageListener);
+        for (const pending of this.#pending.values()) {
+            pending.detach();
+            pending.reject(new Error('IframeTransport disposed'));
+        }
+        this.#pending.clear();
+        this.#listeners.clear();
+        this.#pushListeners.clear();
+    }
+    #dispatch(type, payload) {
+        if (!this.#parentOrigin) {
+            this.#outbound.push({ type, payload });
+            return;
+        }
+        this.#postToParent({ type, payload });
+    }
+    #flushOutbound() {
+        while (this.#outbound.length) {
+            const msg = this.#outbound.shift();
+            this.#postToParent(msg);
+        }
+    }
+    #postToParent(msg) {
+        // `parentOrigin` is captured from a validated BLOCK_INIT; safe to use as targetOrigin.
+        this.#window.parent.postMessage(msg, this.#parentOrigin);
+    }
+    #handleMessage(event) {
+        if (!this.#originMatcher.matches(event.origin))
+            return;
+        const data = event.data;
+        if (data == null || typeof data !== 'object' || typeof data.type !== 'string')
+            return;
+        if (isHostMessage(data, 'BLOCK_INIT')) {
+            if (!this.#initResolved) {
+                // Build before latching: a throw here must leave the transport exactly as
+                // it was, so the host's re-post can still heal it.
+                const snapshot = snapshotFromInit(data.payload, event.origin);
+                this.#initResolved = true;
+                this.#parentOrigin = event.origin;
+                this.#snapshot = snapshot;
+                this.#emit();
+                this.#flushOutbound();
+                // height 0 is a placeholder; the real measurement follows once the app mounts.
+                this.#dispatch('BLOCK_READY', { height: 0 });
+            }
+            return;
+        }
+        // Host-pushed token rotation (no requestId). Always apply to the
+        // snapshot; never matches a pending request.
+        if (isHostMessage(data, 'TOKEN_REFRESH')) {
+            this.#applyTokenRefresh(data.payload.token);
+            return;
+        }
+        // Not gated on init: a pre-init push is still the freshest value, and it
+        // cannot half-init anything because BLOCK_INIT replaces the snapshot wholesale.
+        if (isHostMessage(data, 'THEME_CHANGE')) {
+            this.#applyThemeChange(data.payload.theme);
+            return;
+        }
+        // Matching the TYPE too, not just the id: `IMAGE_SCAN_RESOLVED` is a push
+        // that deliberately reuses its `OPEN_IMAGE_UPLOAD`'s requestId, so an
+        // id-only match could resolve the upload with the scan verdict's payload.
+        const payload = data.payload;
+        let pending;
+        let matchedRequestId = null;
+        if (payload && typeof payload.requestId === 'string') {
+            const candidate = this.#pending.get(payload.requestId);
+            if (candidate && candidate.responseType === data.type) {
+                pending = candidate;
+                matchedRequestId = payload.requestId;
+            }
+        }
+        // Applies whether or not a requestId matched — the host may answer unsolicited.
+        // Before resolving, so awaiting code sees the new token.
+        if (isHostMessage(data, 'TOKEN_REFRESH_RESPONSE')) {
+            this.#applyTokenRefresh(data.payload.token);
+        }
+        if (pending && matchedRequestId !== null) {
+            pending.detach();
+            this.#pending.delete(matchedRequestId);
+            pending.resolve(payload);
+            return;
+        }
+        const handlers = this.#pushListeners.get(data.type);
+        if (handlers && handlers.size > 0) {
+            for (const handler of [...handlers])
+                handler(data.payload);
+            return;
+        }
+    }
+    #applyTokenRefresh(wrapped) {
+        // Whole token: scopes and buzzBudget can move at refresh, not just expiry.
+        this.#snapshot = { ...this.#snapshot, token: tokenFromWrapped(wrapped) };
+        this.#emit();
+    }
+    /**
+     * Emits only on a real change, and updates both `snapshot.theme` and
+     * `context.theme` — the host sends both and callers read them
+     * interchangeably. Never introduces `context.theme` where the host omitted it.
+     */
+    #applyThemeChange(theme) {
+        if (this.#snapshot.theme === theme)
+            return;
+        const next = { ...this.#snapshot, theme };
+        if ('theme' in next.context)
+            next.context = { ...next.context, theme };
+        this.#snapshot = next;
+        this.#emit();
+    }
+    #emit() {
+        for (const listener of this.#listeners)
+            listener();
+    }
+}