@civitai/blocks-react 0.4.0

package/dist/internal/singleton.d.ts

@@ -0,0 +1,18 @@
+import { type DetectOptions } from './detector.js';
+import type { BlockTransport } from './transport.js';
+/**
+ * Returns the process-wide transport, instantiating it on first call.
+ *
+ * Hooks call this with no arguments — they get whatever the detector chose
+ * (iframe vs inline) based on the runtime environment. Tests and starter
+ * dev harnesses can pass explicit `DetectOptions` once before the first
+ * hook call to override origin allowlists or inject a mock window.
+ *
+ * After the first call with options, later calls without options return
+ * the same instance. A later call WITH different options is ignored — call
+ * `__resetTransport()` (from `@civitai/blocks-react/testing`) first.
+ */
+export declare function getTransport(opts?: DetectOptions): BlockTransport;
+/** Test-only. Production hooks never call this. */
+export declare function __resetTransport(): void;
+//# sourceMappingURL=singleton.d.ts.map

package/dist/internal/singleton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"singleton.d.ts","sourceRoot":"","sources":["../../src/internal/singleton.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAC3E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAIrD;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,IAAI,CAAC,EAAE,aAAa,GAAG,cAAc,CAIjE;AAED,mDAAmD;AACnD,wBAAgB,gBAAgB,IAAI,IAAI,CAKvC"}

package/dist/internal/singleton.js

@@ -0,0 +1,28 @@
+import { BlockTransportDetector } from './detector.js';
+let cached = null;
+/**
+ * Returns the process-wide transport, instantiating it on first call.
+ *
+ * Hooks call this with no arguments — they get whatever the detector chose
+ * (iframe vs inline) based on the runtime environment. Tests and starter
+ * dev harnesses can pass explicit `DetectOptions` once before the first
+ * hook call to override origin allowlists or inject a mock window.
+ *
+ * After the first call with options, later calls without options return
+ * the same instance. A later call WITH different options is ignored — call
+ * `__resetTransport()` (from `@civitai/blocks-react/testing`) first.
+ */
+export function getTransport(opts) {
+    if (cached)
+        return cached;
+    cached = BlockTransportDetector.detect(opts);
+    return cached;
+}
+/** Test-only. Production hooks never call this. */
+export function __resetTransport() {
+    // Some transports allocate listeners; dispose if possible.
+    const disposable = cached;
+    disposable?.dispose?.();
+    cached = null;
+}
+//# sourceMappingURL=singleton.js.map

package/dist/internal/singleton.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"singleton.js","sourceRoot":"","sources":["../../src/internal/singleton.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAsB,MAAM,eAAe,CAAC;AAG3E,IAAI,MAAM,GAA0B,IAAI,CAAC;AAEzC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,YAAY,CAAC,IAAoB;IAC/C,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAC1B,MAAM,GAAG,sBAAsB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC7C,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,gBAAgB;IAC9B,2DAA2D;IAC3D,MAAM,UAAU,GAAG,MAA4D,CAAC;IAChF,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC;IACxB,MAAM,GAAG,IAAI,CAAC;AAChB,CAAC"}

package/dist/internal/transport.d.ts

@@ -0,0 +1,100 @@
+import type { BlockContext, BlockInitPayload, BlockSettings, BlockToken, Theme, ViewerInfo, WrappedToken, ParentToBlockMessage, ParentToBlockMessageType, BlockToParentMessage, BlockToParentMessageType } from '@civitai/app-sdk/blocks';
+/**
+ * Synchronous snapshot the hooks read via `useSyncExternalStore`.
+ *
+ * Before `BLOCK_INIT` lands, `ready === false`, `viewer === null`, and the
+ * per-field values are sentinel empties. Hooks that render UI must gate on
+ * `ready`; non-UI hooks (e.g. `useBuzzWorkflow`) rely on the outbound queue
+ * in `IframeTransport` instead of gating.
+ */
+export interface BlockSnapshot {
+    ready: boolean;
+    renderMode: 'iframe' | 'inline';
+    context: BlockContext;
+    token: BlockToken;
+    settings: BlockSettings;
+    /** `null` for anonymous viewers, matching `BlockInitPayload.viewer`. */
+    viewer: ViewerInfo | null;
+    theme: Theme;
+    blockInstanceId: string;
+    blockId: string;
+    appId: string;
+}
+/**
+ * Outbound message shape, without the auto-assigned `requestId` field.
+ * Callers of `sendRequest` describe the message they want sent; the transport
+ * appends the `requestId`.
+ */
+export type OutboundRequest = {
+    [K in BlockToParentMessageType]: Extract<BlockToParentMessage, {
+        type: K;
+    }> extends {
+        payload: {
+            requestId: string;
+        };
+    } ? {
+        type: K;
+        payload: Omit<Extract<BlockToParentMessage, {
+            type: K;
+        }>['payload'], 'requestId'>;
+    } : never;
+}[BlockToParentMessageType];
+/**
+ * Contract every transport (iframe v1, inline v2) implements. Hooks consume
+ * this through the singleton in `./singleton.ts` so block apps stay unaware
+ * of which path is active.
+ *
+ * Messages flow as full discriminated-union values rather than (type, payload)
+ * tuples — this avoids generic-variance pitfalls when the implementation
+ * has to widen back to the union.
+ *
+ * `sendRequest` here is intentionally untyped on the return; the typed view
+ * lives in the free function {@link sendTypedRequest}. Putting the generic
+ * on a free wrapper sidesteps the "interface method with generic return
+ * depending on a parameter" variance problem (TS can't prove `Promise<Extract<..., TRes>>`
+ * covariance across implementations).
+ */
+export interface BlockTransport {
+    /** Current snapshot; cheap to call (no allocation). */
+    getSnapshot(): BlockSnapshot;
+    /** Subscribe to snapshot changes. Returns an unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+    /** Fire-and-forget message to the peer. */
+    sendMessage(message: BlockToParentMessage): void;
+    /** Untyped — use {@link sendTypedRequest} for the type-narrowed view. */
+    sendRequest(request: OutboundRequest, responseType: ParentToBlockMessageType, opts?: {
+        timeoutMs?: number;
+    }): Promise<unknown>;
+}
+/**
+ * Type-safe wrapper around `transport.sendRequest`. Hooks always go through
+ * this so the response payload narrows based on `responseType`.
+ *
+ * Implemented as `async` + `await` instead of a single `as` cast: `Promise<T>`
+ * is invariant in `T`, so casting `Promise<unknown>` directly to
+ * `Promise<Extract<..., TRes>>` trips TS variance checking. Awaiting first
+ * yields a plain `unknown` we can cast synchronously, and the `async` keyword
+ * re-wraps it in the correctly-typed Promise.
+ */
+export declare function sendTypedRequest<TRes extends ParentToBlockMessageType>(transport: BlockTransport, request: OutboundRequest, responseType: TRes, opts?: {
+    timeoutMs?: number;
+}): Promise<Extract<ParentToBlockMessage, {
+    type: TRes;
+}>['payload']>;
+export declare const EMPTY_SNAPSHOT: BlockSnapshot;
+/** Convert a wire `BlockInitPayload` (ISO string expiresAt) into a `BlockSnapshot`. */
+export declare function snapshotFromInit(payload: BlockInitPayload): BlockSnapshot;
+/**
+ * Rehydrate a wire `WrappedToken` (ISO `expiresAt`) into the runtime
+ * `BlockToken` shape (`Date` `expiresAt`). Shared by `snapshotFromInit`
+ * and the `TOKEN_REFRESH` / `TOKEN_REFRESH_RESPONSE` handlers so the
+ * snapshot's token always reflects every wrapped field — `scopes` and
+ * `buzzBudget` included — not just `raw`/`expiresAt`.
+ */
+export declare function tokenFromWrapped(wrapped: WrappedToken): BlockToken;
+/**
+ * Monotonic request ID with a random prefix so concurrent block instances
+ * sharing the dev console don't collide in logs.
+ */
+export declare function nextRequestId(): string;
+//# sourceMappingURL=transport.d.ts.map

package/dist/internal/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/internal/transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,UAAU,EACV,KAAK,EACL,UAAU,EACV,YAAY,EACZ,oBAAoB,EACpB,wBAAwB,EACxB,oBAAoB,EACpB,wBAAwB,EACzB,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAChC,OAAO,EAAE,YAAY,CAAC;IACtB,KAAK,EAAE,UAAU,CAAC;IAClB,QAAQ,EAAE,aAAa,CAAC;IACxB,wEAAwE;IACxE,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IAC1B,KAAK,EAAE,KAAK,CAAC;IACb,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG;KAC3B,CAAC,IAAI,wBAAwB,GAAG,OAAO,CAAC,oBAAoB,EAAE;QAAE,IAAI,EAAE,CAAC,CAAA;KAAE,CAAC,SAAS;QAClF,OAAO,EAAE;YAAE,SAAS,EAAE,MAAM,CAAA;SAAE,CAAC;KAChC,GACG;QACE,IAAI,EAAE,CAAC,CAAC;QACR,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,oBAAoB,EAAE;YAAE,IAAI,EAAE,CAAC,CAAA;SAAE,CAAC,CAAC,SAAS,CAAC,EAAE,WAAW,CAAC,CAAC;KACnF,GACD,KAAK;CACV,CAAC,wBAAwB,CAAC,CAAC;AAE5B;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,cAAc;IAC7B,uDAAuD;IACvD,WAAW,IAAI,aAAa,CAAC;IAC7B,sEAAsE;IACtE,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IAC5C,2CAA2C;IAC3C,WAAW,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACjD,yEAAyE;IACzE,WAAW,CACT,OAAO,EAAE,eAAe,EACxB,YAAY,EAAE,wBAAwB,EACtC,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAC5B,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,SAAS,wBAAwB,EAC1E,SAAS,EAAE,cAAc,EACzB,OAAO,EAAE,eAAe,EACxB,YAAY,EAAE,IAAI,EAClB,IAAI,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5B,OAAO,CAAC,OAAO,CAAC,oBAAoB,EAAE;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAInE;AAED,eAAO,MAAM,cAAc,EAAE,aAW5B,CAAC;AAEF,uFAAuF;AACvF,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,gBAAgB,GAAG,aAAa,CAazE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,YAAY,GAAG,UAAU,CAOlE;AAGD;;;GAGG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAGtC"}

package/dist/internal/transport.js

@@ -0,0 +1,67 @@
+/**
+ * Type-safe wrapper around `transport.sendRequest`. Hooks always go through
+ * this so the response payload narrows based on `responseType`.
+ *
+ * Implemented as `async` + `await` instead of a single `as` cast: `Promise<T>`
+ * is invariant in `T`, so casting `Promise<unknown>` directly to
+ * `Promise<Extract<..., TRes>>` trips TS variance checking. Awaiting first
+ * yields a plain `unknown` we can cast synchronously, and the `async` keyword
+ * re-wraps it in the correctly-typed Promise.
+ */
+export async function sendTypedRequest(transport, request, responseType, opts) {
+    const payload = await transport.sendRequest(request, responseType, opts);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- variance escape; see fn jsdoc
+    return payload;
+}
+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: '',
+    blockId: '',
+    appId: '',
+};
+/** Convert a wire `BlockInitPayload` (ISO string expiresAt) into a `BlockSnapshot`. */
+export function snapshotFromInit(payload) {
+    return {
+        ready: true,
+        renderMode: payload.renderMode,
+        context: payload.context,
+        token: tokenFromWrapped(payload.token),
+        settings: payload.settings,
+        viewer: payload.viewer,
+        theme: payload.theme,
+        blockInstanceId: payload.blockInstanceId,
+        blockId: payload.blockId,
+        appId: payload.appId,
+    };
+}
+/**
+ * Rehydrate a wire `WrappedToken` (ISO `expiresAt`) into the runtime
+ * `BlockToken` shape (`Date` `expiresAt`). Shared by `snapshotFromInit`
+ * and the `TOKEN_REFRESH` / `TOKEN_REFRESH_RESPONSE` handlers so the
+ * snapshot's token always reflects every wrapped field — `scopes` and
+ * `buzzBudget` included — not just `raw`/`expiresAt`.
+ */
+export function tokenFromWrapped(wrapped) {
+    return {
+        raw: wrapped.raw,
+        scopes: wrapped.scopes,
+        expiresAt: new Date(wrapped.expiresAt),
+        buzzBudget: wrapped.buzzBudget,
+    };
+}
+let requestIdCounter = 0;
+/**
+ * Monotonic request ID with a random prefix so concurrent block instances
+ * sharing the dev console don't collide in logs.
+ */
+export function nextRequestId() {
+    requestIdCounter += 1;
+    return `${Math.random().toString(36).slice(2, 8)}-${requestIdCounter}`;
+}
+//# sourceMappingURL=transport.js.map

package/dist/internal/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../../src/internal/transport.ts"],"names":[],"mappings":"AAkFA;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,SAAyB,EACzB,OAAwB,EACxB,YAAkB,EAClB,IAA6B;IAE7B,MAAM,OAAO,GAAG,MAAM,SAAS,CAAC,WAAW,CAAC,OAAO,EAAE,YAAY,EAAE,IAAI,CAAC,CAAC;IACzE,+FAA+F;IAC/F,OAAO,OAAc,CAAC;AACxB,CAAC;AAED,MAAM,CAAC,MAAM,cAAc,GAAkB;IAC3C,KAAK,EAAE,KAAK;IACZ,UAAU,EAAE,QAAQ;IACpB,OAAO,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE;IACvB,KAAK,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE;IACtD,QAAQ,EAAE,EAAE,iBAAiB,EAAE,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE;IACrD,MAAM,EAAE,IAAI;IACZ,KAAK,EAAE,OAAO;IACd,eAAe,EAAE,EAAE;IACnB,OAAO,EAAE,EAAE;IACX,KAAK,EAAE,EAAE;CACV,CAAC;AAEF,uFAAuF;AACvF,MAAM,UAAU,gBAAgB,CAAC,OAAyB;IACxD,OAAO;QACL,KAAK,EAAE,IAAI;QACX,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,KAAK,EAAE,gBAAgB,CAAC,OAAO,CAAC,KAAK,CAAC;QACtC,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,eAAe,EAAE,OAAO,CAAC,eAAe;QACxC,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,KAAK,EAAE,OAAO,CAAC,KAAK;KACrB,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAqB;IACpD,OAAO;QACL,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,SAAS,EAAE,IAAI,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC;QACtC,UAAU,EAAE,OAAO,CAAC,UAAU;KAC/B,CAAC;AACJ,CAAC;AAED,IAAI,gBAAgB,GAAG,CAAC,CAAC;AACzB;;;GAGG;AACH,MAAM,UAAU,aAAa;IAC3B,gBAAgB,IAAI,CAAC,CAAC;IACtB,OAAO,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,gBAAgB,EAAE,CAAC;AACzE,CAAC"}

package/dist/internal/validate.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Trust-boundary shape validation for inbound `postMessage` payloads.
+ *
+ * Origin allowlisting in `IframeTransport.handleMessage` gates *who* can
+ * send — these guards gate *what* the message contains. They're shape
+ * checks, not schema validation: each guard asserts the fields downstream
+ * code will dereference, nothing more. Anything that fails drops with a
+ * `console.warn` instead of crashing, so a malformed message degrades the
+ * affected feature without breaking the rest of the block.
+ *
+ * Keep these in lockstep with `BlockInitPayload` / `ParentToBlockMessage`
+ * in `@civitai/app-sdk/blocks` AND with the host implementation in
+ * civitai/civitai's `src/components/AppBlocks/IframeHost.tsx`. A new field
+ * downstream code reads → a new check here.
+ */
+import type { BlockInitPayload, BlockWorkflowSnapshot, WrappedToken } from '@civitai/app-sdk/blocks';
+/**
+ * Shape check for the wrapped-token shape carried by `BLOCK_INIT.token`,
+ * `TOKEN_REFRESH.payload.token`, and `TOKEN_REFRESH_RESPONSE.payload.token`.
+ */
+export declare function isValidWrappedToken(t: unknown): t is WrappedToken;
+export declare function isValidBlockInitPayload(p: unknown): p is BlockInitPayload;
+export declare function isValidWorkflowSnapshot(s: unknown): s is BlockWorkflowSnapshot;
+/**
+ * Host-pushed token rotation. No `requestId` field; the host is the initiator.
+ * Carries the same wrapped-token shape as the reply path.
+ */
+export declare function isValidTokenRefresh(p: unknown): p is {
+    token: WrappedToken;
+};
+/**
+ * Reply to a block-initiated `REQUEST_TOKEN`. `requestId` is optional — the
+ * platform's IframeHost.tsx echoes it back when supplied, omits it otherwise.
+ */
+export declare function isValidTokenRefreshResponse(p: unknown): p is {
+    token: WrappedToken;
+    requestId?: string;
+};
+export declare function isValidWorkflowReply(p: unknown): p is {
+    snapshot: BlockWorkflowSnapshot;
+    requestId?: string;
+};
+export declare function isValidBuzzPurchaseResult(p: unknown): p is {
+    purchased: boolean;
+    newBalance?: number;
+    requestId?: string;
+};
+/**
+ * Returns the validator for an inbound message type, or `null` for types
+ * that don't carry a payload requiring shape checks (SUSPEND/RESUME).
+ *
+ * Falsy result from the validator means "drop the message"; `iframeTransport`
+ * pairs that with a `console.warn` carrying the type name.
+ */
+export declare function payloadValidatorFor(type: string): ((payload: unknown) => boolean) | null;
+//# sourceMappingURL=validate.d.ts.map

package/dist/internal/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/internal/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,qBAAqB,EACrB,YAAY,EACb,MAAM,yBAAyB,CAAC;AAejC;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,YAAY,CAQjE;AAED,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,gBAAgB,CA6BzE;AAcD,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,qBAAqB,CA4B9E;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,CAAC,EAAE,OAAO,GACT,CAAC,IAAI;IAAE,KAAK,EAAE,YAAY,CAAA;CAAE,CAI9B;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,CAAC,EAAE,OAAO,GACT,CAAC,IAAI;IAAE,KAAK,EAAE,YAAY,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAKlD;AAED,wBAAgB,oBAAoB,CAClC,CAAC,EAAE,OAAO,GACT,CAAC,IAAI;IAAE,QAAQ,EAAE,qBAAqB,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAK9D;AAED,wBAAgB,yBAAyB,CACvC,CAAC,EAAE,OAAO,GACT,CAAC,IAAI;IAAE,SAAS,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAMtE;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,GACX,CAAC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,GAAG,IAAI,CAsBxC"}

package/dist/internal/validate.js

@@ -0,0 +1,202 @@
+/**
+ * Trust-boundary shape validation for inbound `postMessage` payloads.
+ *
+ * Origin allowlisting in `IframeTransport.handleMessage` gates *who* can
+ * send — these guards gate *what* the message contains. They're shape
+ * checks, not schema validation: each guard asserts the fields downstream
+ * code will dereference, nothing more. Anything that fails drops with a
+ * `console.warn` instead of crashing, so a malformed message degrades the
+ * affected feature without breaking the rest of the block.
+ *
+ * Keep these in lockstep with `BlockInitPayload` / `ParentToBlockMessage`
+ * in `@civitai/app-sdk/blocks` AND with the host implementation in
+ * civitai/civitai's `src/components/AppBlocks/IframeHost.tsx`. A new field
+ * downstream code reads → a new check here.
+ */
+const isObject = (v) => v !== null && typeof v === 'object';
+const isNonEmptyString = (v) => typeof v === 'string' && v.length > 0;
+/** Accepts an ISO 8601 string that `new Date()` can parse to a finite timestamp. */
+function isParseableDateString(v) {
+    if (typeof v !== 'string' || v.length === 0)
+        return false;
+    const ts = Date.parse(v);
+    return Number.isFinite(ts);
+}
+/**
+ * Shape check for the wrapped-token shape carried by `BLOCK_INIT.token`,
+ * `TOKEN_REFRESH.payload.token`, and `TOKEN_REFRESH_RESPONSE.payload.token`.
+ */
+export function isValidWrappedToken(t) {
+    if (!isObject(t))
+        return false;
+    if (!isNonEmptyString(t.raw))
+        return false;
+    if (!Array.isArray(t.scopes))
+        return false;
+    if (!t.scopes.every((s) => typeof s === 'string'))
+        return false;
+    if (!isParseableDateString(t.expiresAt))
+        return false;
+    if (t.buzzBudget !== undefined && typeof t.buzzBudget !== 'number')
+        return false;
+    return true;
+}
+export function isValidBlockInitPayload(p) {
+    if (!isObject(p))
+        return false;
+    if (!isNonEmptyString(p.blockId))
+        return false;
+    if (!isNonEmptyString(p.blockInstanceId))
+        return false;
+    if (!isNonEmptyString(p.appId))
+        return false;
+    if (p.renderMode !== 'iframe' && p.renderMode !== 'inline')
+        return false;
+    if (!isValidWrappedToken(p.token))
+        return false;
+    if (!isObject(p.context))
+        return false;
+    if (!isNonEmptyString(p.context.slotId))
+        return false;
+    if (!isObject(p.settings))
+        return false;
+    if (!isObject(p.settings.publisherSettings))
+        return false;
+    if (!isObject(p.settings.userSettings))
+        return false;
+    // `null` for anonymous viewers; otherwise { id, username, status }.
+    if (p.viewer !== null) {
+        if (!isObject(p.viewer))
+            return false;
+        if (typeof p.viewer.id !== 'number')
+            return false;
+        if (p.viewer.username !== null && typeof p.viewer.username !== 'string')
+            return false;
+        if (p.viewer.status !== 'active' && p.viewer.status !== 'banned' && p.viewer.status !== 'muted') {
+            return false;
+        }
+    }
+    if (p.theme !== 'light' && p.theme !== 'dark')
+        return false;
+    return true;
+}
+const WORKFLOW_STATUSES = new Set([
+    'pending',
+    'processing',
+    'succeeded',
+    'failed',
+    'expired',
+    'canceled',
+]);
+const AUTO_CLAIM_TYPES = new Set(['dailyBoost']);
+const AUTO_CLAIM_ACCOUNT_TYPES = new Set(['yellow', 'blue', 'red', 'green']);
+export function isValidWorkflowSnapshot(s) {
+    if (!isObject(s))
+        return false;
+    if (!isNonEmptyString(s.workflowId))
+        return false;
+    if (typeof s.status !== 'string' || !WORKFLOW_STATUSES.has(s.status))
+        return false;
+    if (s.cost !== undefined) {
+        if (!isObject(s.cost) || typeof s.cost.total !== 'number')
+            return false;
+    }
+    if (s.imageUrls !== undefined) {
+        if (!Array.isArray(s.imageUrls))
+            return false;
+        if (!s.imageUrls.every((u) => typeof u === 'string'))
+            return false;
+    }
+    if (s.error !== undefined && typeof s.error !== 'string')
+        return false;
+    if (s.autoClaim !== undefined) {
+        if (!isObject(s.autoClaim))
+            return false;
+        if (typeof s.autoClaim.type !== 'string' || !AUTO_CLAIM_TYPES.has(s.autoClaim.type)) {
+            return false;
+        }
+        if (typeof s.autoClaim.amount !== 'number' || !Number.isFinite(s.autoClaim.amount)) {
+            return false;
+        }
+        if (typeof s.autoClaim.accountType !== 'string' ||
+            !AUTO_CLAIM_ACCOUNT_TYPES.has(s.autoClaim.accountType)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Host-pushed token rotation. No `requestId` field; the host is the initiator.
+ * Carries the same wrapped-token shape as the reply path.
+ */
+export function isValidTokenRefresh(p) {
+    if (!isObject(p))
+        return false;
+    if (!isValidWrappedToken(p.token))
+        return false;
+    return true;
+}
+/**
+ * Reply to a block-initiated `REQUEST_TOKEN`. `requestId` is optional — the
+ * platform's IframeHost.tsx echoes it back when supplied, omits it otherwise.
+ */
+export function isValidTokenRefreshResponse(p) {
+    if (!isObject(p))
+        return false;
+    if (!isValidWrappedToken(p.token))
+        return false;
+    if (p.requestId !== undefined && typeof p.requestId !== 'string')
+        return false;
+    return true;
+}
+export function isValidWorkflowReply(p) {
+    if (!isObject(p))
+        return false;
+    if (!isValidWorkflowSnapshot(p.snapshot))
+        return false;
+    if (p.requestId !== undefined && typeof p.requestId !== 'string')
+        return false;
+    return true;
+}
+export function isValidBuzzPurchaseResult(p) {
+    if (!isObject(p))
+        return false;
+    if (typeof p.purchased !== 'boolean')
+        return false;
+    if (p.newBalance !== undefined && typeof p.newBalance !== 'number')
+        return false;
+    if (p.requestId !== undefined && typeof p.requestId !== 'string')
+        return false;
+    return true;
+}
+/**
+ * Returns the validator for an inbound message type, or `null` for types
+ * that don't carry a payload requiring shape checks (SUSPEND/RESUME).
+ *
+ * Falsy result from the validator means "drop the message"; `iframeTransport`
+ * pairs that with a `console.warn` carrying the type name.
+ */
+export function payloadValidatorFor(type) {
+    switch (type) {
+        case 'BLOCK_INIT':
+            return isValidBlockInitPayload;
+        case 'TOKEN_REFRESH':
+            return isValidTokenRefresh;
+        case 'TOKEN_REFRESH_RESPONSE':
+            return isValidTokenRefreshResponse;
+        case 'ESTIMATE_RESULT':
+        case 'WORKFLOW_SUBMITTED':
+        case 'WORKFLOW_STATUS':
+            return isValidWorkflowReply;
+        case 'BUZZ_PURCHASE_RESULT':
+            return isValidBuzzPurchaseResult;
+        case 'SUSPEND':
+        case 'RESUME':
+            return null;
+        default:
+            // Unknown type names get a structural pass; handleMessage's earlier
+            // `isMessage` branches won't match them anyway.
+            return null;
+    }
+}
+//# sourceMappingURL=validate.js.map

package/dist/internal/validate.js.map

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

package/dist/testing.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Test-only helpers for `@civitai/blocks-react`. Not part of the runtime
+ * surface — block apps should never import from here.
+ *
+ * Subpath-exported so accidental production imports show up in code review.
+ */
+import { __resetTransport } from './internal/singleton.js';
+export { __resetTransport as resetTransport };
+/**
+ * Builds a `MessageEvent` that mimics a parent-frame postMessage so tests can
+ * exercise `IframeTransport.handleMessage` without a real cross-frame setup.
+ */
+export declare function mockParentMessage(data: unknown, origin: string): MessageEvent;
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D,OAAO,EAAE,gBAAgB,IAAI,cAAc,EAAE,CAAC;AAE9C;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,MAAM,GACb,YAAY,CAEd"}

package/dist/testing.js

@@ -0,0 +1,16 @@
+/**
+ * Test-only helpers for `@civitai/blocks-react`. Not part of the runtime
+ * surface — block apps should never import from here.
+ *
+ * Subpath-exported so accidental production imports show up in code review.
+ */
+import { __resetTransport } from './internal/singleton.js';
+export { __resetTransport as resetTransport };
+/**
+ * Builds a `MessageEvent` that mimics a parent-frame postMessage so tests can
+ * exercise `IframeTransport.handleMessage` without a real cross-frame setup.
+ */
+export function mockParentMessage(data, origin) {
+    return new MessageEvent('message', { data, origin, source: null });
+}
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D,OAAO,EAAE,gBAAgB,IAAI,cAAc,EAAE,CAAC;AAE9C;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAa,EACb,MAAc;IAEd,OAAO,IAAI,YAAY,CAAC,SAAS,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;AACrE,CAAC"}

package/dist/ui/SettingsForm.d.ts

@@ -0,0 +1,79 @@
+import type { ManifestSettings, ManifestSettingField, SettingScope } from '@civitai/app-sdk/blocks';
+/**
+ * W3 v0 — generic, manifest-driven settings form.
+ *
+ * Renders one of seven primitive inputs per field based on the manifest's
+ * widget hint, filters by `forScope` + `requires_scope`, and posts the
+ * collected values back via `onSubmit`. Designed to be used from:
+ *   1. Platform-side `/apps/installed` settings modal (publisher slice).
+ *   2. Same page (viewer slice).
+ *   3. Per-app settings page (`/apps/[appBlockId]/settings`).
+ *   4. Model edit page banner (publisher slice).
+ *
+ * Intentionally headless-styled. No design tokens, no Mantine, no CSS
+ * imports — the host page applies CSS via wrapper / className. The W6
+ * component pack (when it lands) will own theming for `<Button>` etc.;
+ * until then this form ships unstyled native controls so the platform
+ * pages can theme them inline.
+ *
+ * Validation note: the form does client-side type / range checks only
+ * (NaN, out-of-bounds). Server-side `validateBlockSettings` is the
+ * authoritative gate; this layer just prevents obvious typos before the
+ * round trip. Server errors surface inline via `onSubmit` rejecting with
+ * `{ fieldErrors }`.
+ */
+export interface SettingsFormProps {
+    /** App's manifest.settings declaration (already validated server-side). */
+    manifestSettings: ManifestSettings;
+    /** App's declared scopes — drives `requires_scope` field gating. */
+    declaredScopes: string[];
+    /** Which slice of fields to render. */
+    forScope: SettingScope;
+    /**
+     * Initial values keyed by field name. Missing keys fall back to the
+     * manifest field's `default`. Unknown keys are ignored.
+     */
+    initialValues: Record<string, unknown>;
+    /**
+     * Persist the form's collected values. May throw a SettingsFormError
+     * with per-field messages — the form surfaces them inline.
+     */
+    onSubmit: (values: Record<string, unknown>) => Promise<void>;
+    /**
+     * Resource picker integration. Required when the manifest declares any
+     * `widget: 'resource_picker'` field. Pass the host-mediated picker —
+     * typically a thin wrapper around `useCheckpointPicker()` for the
+     * Checkpoint case, or a future `useResourcePicker()` hook.
+     *
+     * The callback receives the field's `widget_options` (e.g.
+     * `{ resource_type: 'Checkpoint', filter_by_ecosystem: true }`) plus
+     * the current value, and returns the picked resource's id (or null if
+     * the user dismissed without picking).
+     */
+    resourcePicker?: (opts: {
+        fieldKey: string;
+        widgetOptions: Record<string, unknown>;
+        currentValue: number | null;
+    }) => Promise<number | null>;
+    /** Button label. Defaults to 'Save'. */
+    submitLabel?: string;
+    /** Optional className applied to the form root for the host to style. */
+    className?: string;
+}
+/**
+ * Thrown by `onSubmit` callers to surface per-field server errors back to
+ * the form. The form renders the message under the named field.
+ */
+export declare class SettingsFormError extends Error {
+    readonly fieldErrors: Record<string, string>;
+    readonly name = "SettingsFormError";
+    constructor(fieldErrors: Record<string, string>);
+}
+/**
+ * Test if a field should render for the current scope + declared-scopes
+ * combination. Exposed for callers that want to count visible fields
+ * before rendering (e.g. "no settings to configure" empty state).
+ */
+export declare function isFieldVisible(field: ManifestSettingField, forScope: SettingScope, declaredScopes: string[]): boolean;
+export declare function SettingsForm(props: SettingsFormProps): React.JSX.Element;
+//# sourceMappingURL=SettingsForm.d.ts.map

package/dist/ui/SettingsForm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SettingsForm.d.ts","sourceRoot":"","sources":["../../src/ui/SettingsForm.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,gBAAgB,EAChB,oBAAoB,EAIpB,YAAY,EACb,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,WAAW,iBAAiB;IAChC,2EAA2E;IAC3E,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,oEAAoE;IACpE,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,uCAAuC;IACvC,QAAQ,EAAE,YAAY,CAAC;IACvB;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC;;;OAGG;IACH,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D;;;;;;;;;;OAUG;IACH,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE;QACtB,QAAQ,EAAE,MAAM,CAAC;QACjB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACvC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;KAC7B,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC7B,wCAAwC;IACxC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;aAEd,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAD/D,SAAkB,IAAI,uBAAuB;gBACjB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;CAGhE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,oBAAoB,EAC3B,QAAQ,EAAE,YAAY,EACtB,cAAc,EAAE,MAAM,EAAE,GACvB,OAAO,CAIT;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAqHxE"}