@civitai/blocks-react 0.26.0 → 0.28.0

package/README.md

@@ -307,6 +307,21 @@ const { keys } = await storage.list({ prefix: 'note-' });
 const quota = await storage.getQuota();       // { usedBytes, rowCount, limitBytes, limitRows }
 ```
 
+### `useSharedStorage()`
+
+App-scoped, append-only, community-votable SHARED datastore (every viewer sees
+the same list). Sibling of `useAppStorage`; anonymous viewers get the read path
+and a hard reject on mutations.
+
+```tsx
+const shared = useSharedStorage();
+const { key } = await shared.append({ title: 'Add dark mode', body: 'please' });
+const { items } = await shared.list({ limit: 20 });   // newest-first
+const count = await shared.vote(key);                 // idempotent up-vote
+await shared.unvote(key);
+await shared.withdraw(key);                            // remove my own entry
+```
+
 ### `useCheckpointPicker()`
 
 Drive the platform Checkpoint picker + persist a viewer override.
@@ -317,6 +332,55 @@ const { selected } = await open({ baseModelGroup: 'SDXL', currentVersionId });
 if (selected) await persist(selected.versionId);   // null clears the override
 ```
 
+### `useResourcePicker()`
+
+Drive the platform resource picker for page blocks — `'Checkpoint' | 'LORA'`.
+The viewer searches in host chrome; the block only ever sees the one resource it
+picked. DISCOVERY ONLY — the returned `versionId` is re-validated + re-priced
+server-side at estimate/submit.
+
+```tsx
+const { open } = useResourcePicker();
+const picked = await open({ resourceType: 'LORA', baseModelGroup: 'SDXL' });
+if (picked) {
+  const versionId = picked.versionId;   // feed into body.additionalResources
+  const weight = picked.strength;        // recommended default weight (may be undefined)
+}
+```
+
+### `useImageUpload()`
+
+Host-mediated image upload — the host opens its native upload modal and the
+iframe never handles the bytes. Resolves with a moderated image (or `null` on
+dismiss); pass `{ purpose: 'generationSource' }` for an unscanned img2img source
+or `{ asyncScan: true }` for the early-resolve + `scanStatus()` flow.
+
+```tsx
+const { open } = useImageUpload();
+const img = await open();               // BlockUploadedImageInfo | null
+if (img) {
+  await submit({
+    kind: 'textToImage',
+    modelId,
+    modelVersionId,
+    sourceImage: { url: img.url, width: 1024, height: 1024 },
+    params: { prompt },
+  });
+}
+```
+
+### `useGenerationResources()`
+
+Rehydrate a saved set of generation resources by version id — WITHOUT re-opening
+the picker. Returns the same widened projection `useResourcePicker` yields
+(recommended weights, trigger words, clipSkip). DISCOVERY ONLY.
+
+```tsx
+const { fetch } = useGenerationResources();
+const resources = await fetch([691639, 666002]);   // by saved versionIds
+const first = resources[0];             // .versionId / .strength / .trainedWords / .clipSkip
+```
+
 ### `useCivitaiNavigate()`
 
 Request a navigation within civitai.com (host-mediated; fire-and-forget).
@@ -335,6 +399,56 @@ const { track } = useBlockAnalytics();
 track('generate_clicked', { modelId });
 ```
 
+### `useRequestSignIn()`
+
+Ask the host to open its sign-in flow for an ANONYMOUS viewer (fire-and-forget).
+On sign-in the host re-inits the block with the now-authenticated viewer.
+
+```tsx
+const { requestSignIn } = useRequestSignIn();
+// e.g. onClick of a "Sign in to generate" button:
+requestSignIn();
+```
+
+### `useRequestConsent()`
+
+Lazy consent: ask the host to open its consent UI when a LOGGED-IN viewer takes
+an action whose consent-gated scope the block token is missing (e.g. Generate
+needs `ai:write:budgeted` but the viewer hasn't granted it). Fire-and-forget —
+on grant the host pushes a new token; observe `useBlockToken().scopes` and retry.
+
+```tsx
+const { requestConsent } = useRequestConsent();
+requestConsent({ scopes: ['ai:write:budgeted', 'buzz:read:self'] });
+```
+
+### `useDomainMaturity()`
+
+Read the surrounding color-domain's maturity ceiling (civitai #2670) so a block
+can hide/blur mature affordances on a SFW domain. **Fail-closed SFW** until
+`BLOCK_INIT` lands or against a host that predates the field.
+
+```tsx
+const { isSfw, isLevelAllowed } = useDomainMaturity();
+const showRSlider = isLevelAllowed(BrowsingLevel.R);   // false on a SFW domain
+```
+
+### `SfwGate`
+
+Convenience component that renders `children` only when the domain permits the
+maturity — no `level` prop gates on the SFW ceiling, a `level` prop gates on that
+browsing-level bit. Fail-closed SFW.
+
+```tsx
+function MatureSection() {
+  return (
+    <SfwGate level={BrowsingLevel.R} fallback={<SafePlaceholder />}>
+      <RRatedControl />
+    </SfwGate>
+  );
+}
+```
+
 ## The `/ui` subexport
 
 Opinionated components, imported separately so a transport-only block stays lean.
@@ -469,6 +583,9 @@ Runnable, minimal blocks — one per feature, each with its own README:
 
 | `@civitai/blocks-react` | pairs with `@civitai/app-sdk` | adds |
 |---|---|---|
+| `0.27.x` | `^0.23.0` | async-scan image upload; transport validators for all `SHARED_*` / `APP_STORAGE_*` / picker replies |
+| `0.26.x` | `^0.22.0` | `useViewer()` (`GET_VIEWER`) |
+| `0.25.x` | `^0.21.0` | `useBuzzTransactions`, `useBuzzAccounts`, `useDailyCompensation`, `useWildcardPack` |
 | `0.5.0` | `^0.7.0` | `useBuzzWorkflow().cancel()` (real server-side cancel, gotcha #51) |
 | `0.4.x` | `^0.6.0` | `useAppStorage`, `SettingsForm` (`/ui`) |
 | `0.3.x` | `^0.5.0` | earlier hook set |

package/dist/hooks/useBlockToken.d.ts

@@ -20,4 +20,10 @@ import type { BlockToken } from '@civitai/app-sdk/blocks';
 export declare function useBlockToken(): BlockToken & {
     refresh: () => Promise<void>;
 };
+/**
+ * Mint/await a token refresh for one block instance, coalescing concurrent calls
+ * for the SAME `blockInstanceId`. Exported for the inline-mode multi-instance
+ * dedup test — hooks call it via `useBlockToken().refresh`.
+ */
+export declare function requestRefresh(blockInstanceId: string): Promise<void>;
 //# sourceMappingURL=useBlockToken.d.ts.map

package/dist/hooks/useBlockToken.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useBlockToken.d.ts","sourceRoot":"","sources":["../../src/hooks/useBlockToken.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAS1D;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,IAAI,UAAU,GAAG;IAAE,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAwB7E"}
+{"version":3,"file":"useBlockToken.d.ts","sourceRoot":"","sources":["../../src/hooks/useBlockToken.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAS1D;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,IAAI,UAAU,GAAG;IAAE,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAwB7E;AAiBD;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAe3E"}

package/dist/hooks/useBlockToken.js

@@ -47,22 +47,35 @@ export function useBlockToken() {
     return { ...token, refresh: () => requestRefresh(instanceId) };
 }
 /**
- * In-flight dedup. Both the scheduled-timeout path and the "already past"
- * synchronous path can fire while a previous refresh is still pending —
- * coalescing into a single round-trip avoids fanning out duplicate
- * REQUEST_TOKEN messages, which would otherwise hit the host once per
+ * In-flight dedup, keyed by `blockInstanceId`. Both the scheduled-timeout path
+ * and the "already past" synchronous path can fire while a previous refresh is
+ * still pending — coalescing into a single round-trip avoids fanning out
+ * duplicate REQUEST_TOKEN messages, which would otherwise hit the host once per
  * snapshot update.
+ *
+ * The key MUST include `blockInstanceId`: in iframe mode there is one module per
+ * iframe so any key works, but on the INLINE transport (v2) several block
+ * instances share one module context. A module-global singleton would coalesce
+ * across instances, so instance B's 401-retry `refresh()` would resolve on
+ * instance A's in-flight `REQUEST_TOKEN` and B would never mint its OWN token.
+ */
+const inFlightRefreshByInstance = new Map();
+/**
+ * Mint/await a token refresh for one block instance, coalescing concurrent calls
+ * for the SAME `blockInstanceId`. Exported for the inline-mode multi-instance
+ * dedup test — hooks call it via `useBlockToken().refresh`.
  */
-let inFlightRefresh = null;
-async function requestRefresh(blockInstanceId) {
-    if (inFlightRefresh)
-        return inFlightRefresh;
+export async function requestRefresh(blockInstanceId) {
+    const existing = inFlightRefreshByInstance.get(blockInstanceId);
+    if (existing)
+        return existing;
     const transport = getTransport();
-    inFlightRefresh = sendTypedRequest(transport, { type: 'REQUEST_TOKEN', payload: { blockInstanceId } }, 'TOKEN_REFRESH_RESPONSE')
+    const refresh = sendTypedRequest(transport, { type: 'REQUEST_TOKEN', payload: { blockInstanceId } }, 'TOKEN_REFRESH_RESPONSE')
         .then(() => undefined)
         .finally(() => {
-        inFlightRefresh = null;
+        inFlightRefreshByInstance.delete(blockInstanceId);
     });
-    return inFlightRefresh;
+    inFlightRefreshByInstance.set(blockInstanceId, refresh);
+    return refresh;
 }
 //# sourceMappingURL=useBlockToken.js.map

package/dist/hooks/useBlockToken.js.map

@@ -1 +1 @@
-{"version":3,"file":"useBlockToken.js","sourceRoot":"","sources":["../../src/hooks/useBlockToken.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAIlC,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAE5D,sEAAsE;AACtE,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AAEtC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,IAAI,GAAG,oBAAoB,EAAE,CAAC;IACpC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IACzB,MAAM,UAAU,GAAG,IAAI,CAAC,eAAe,CAAC;IAExC,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,IAAI,CAAC,KAAK;YAAE,OAAO;QACxB,MAAM,cAAc,GAAG,KAAK,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,eAAe,CAAC;QAChF,IAAI,cAAc,IAAI,CAAC,EAAE,CAAC;YACxB,iDAAiD;YACjD,oEAAoE;YACpE,6CAA6C;YAC7C,cAAc,CAAC,UAAU,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YAC3C,OAAO;QACT,CAAC;QACD,MAAM,EAAE,GAAG,UAAU,CAAC,GAAG,EAAE;YACzB,oEAAoE;YACpE,6CAA6C;YAC7C,cAAc,CAAC,UAAU,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAC7C,CAAC,EAAE,cAAc,CAAC,CAAC;QACnB,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;IAChC,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC;IAE9C,OAAO,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,cAAc,CAAC,UAAU,CAAC,EAAE,CAAC;AACjE,CAAC;AAED;;;;;;GAMG;AACH,IAAI,eAAe,GAAyB,IAAI,CAAC;AAEjD,KAAK,UAAU,cAAc,CAAC,eAAuB;IACnD,IAAI,eAAe;QAAE,OAAO,eAAe,CAAC;IAC5C,MAAM,SAAS,GAAG,YAAY,EAAE,CAAC;IACjC,eAAe,GAAG,gBAAgB,CAChC,SAAS,EACT,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,EAAE,eAAe,EAAE,EAAE,EACvD,wBAAwB,CACzB;SACE,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC;SACrB,OAAO,CAAC,GAAG,EAAE;QACZ,eAAe,GAAG,IAAI,CAAC;IACzB,CAAC,CAAC,CAAC;IACL,OAAO,eAAe,CAAC;AACzB,CAAC"}
+{"version":3,"file":"useBlockToken.js","sourceRoot":"","sources":["../../src/hooks/useBlockToken.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAIlC,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAE5D,sEAAsE;AACtE,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AAEtC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,IAAI,GAAG,oBAAoB,EAAE,CAAC;IACpC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IACzB,MAAM,UAAU,GAAG,IAAI,CAAC,eAAe,CAAC;IAExC,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,IAAI,CAAC,KAAK;YAAE,OAAO;QACxB,MAAM,cAAc,GAAG,KAAK,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,eAAe,CAAC;QAChF,IAAI,cAAc,IAAI,CAAC,EAAE,CAAC;YACxB,iDAAiD;YACjD,oEAAoE;YACpE,6CAA6C;YAC7C,cAAc,CAAC,UAAU,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YAC3C,OAAO;QACT,CAAC;QACD,MAAM,EAAE,GAAG,UAAU,CAAC,GAAG,EAAE;YACzB,oEAAoE;YACpE,6CAA6C;YAC7C,cAAc,CAAC,UAAU,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAC7C,CAAC,EAAE,cAAc,CAAC,CAAC;QACnB,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;IAChC,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC;IAE9C,OAAO,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,cAAc,CAAC,UAAU,CAAC,EAAE,CAAC;AACjE,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,yBAAyB,GAAG,IAAI,GAAG,EAAyB,CAAC;AAEnE;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,eAAuB;IAC1D,MAAM,QAAQ,GAAG,yBAAyB,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IAChE,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC9B,MAAM,SAAS,GAAG,YAAY,EAAE,CAAC;IACjC,MAAM,OAAO,GAAG,gBAAgB,CAC9B,SAAS,EACT,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,EAAE,eAAe,EAAE,EAAE,EACvD,wBAAwB,CACzB;SACE,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC;SACrB,OAAO,CAAC,GAAG,EAAE;QACZ,yBAAyB,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;IACpD,CAAC,CAAC,CAAC;IACL,yBAAyB,CAAC,GAAG,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;IACxD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/hooks/useGenerationResources.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useGenerationResources.d.ts","sourceRoot":"","sources":["../../src/hooks/useGenerationResources.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AASjE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,sBAAsB,IAAI;IACxC,KAAK,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;CAC/D,CAyBA"}
+{"version":3,"file":"useGenerationResources.d.ts","sourceRoot":"","sources":["../../src/hooks/useGenerationResources.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAiBjE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,sBAAsB,IAAI;IACxC,KAAK,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;CAC/D,CA0DA"}

package/dist/hooks/useGenerationResources.js

@@ -1,7 +1,14 @@
-import { useCallback } from 'react';
+import { useCallback, useEffect, useRef } from 'react';
 import { buildGenerationResourcesUrl, responseToResources, } from '../api/generationResources.js';
 import { useHostOrigin } from './useHostOrigin.js';
 import { useBlockToken } from './useBlockToken.js';
+/**
+ * Backstop timeout for the direct REST fetch. Unlike the postMessage hooks
+ * (which inherit the transport's 30s request timeout), this hook talks to the
+ * HTTP API directly, so it needs its OWN bound — otherwise a hung request never
+ * rejects. Matches the transport's default request timeout.
+ */
+const GENERATION_RESOURCES_TIMEOUT_MS = 30_000;
 /**
  * Rehydrate a saved set of generation resources by version id, WITHOUT
  * re-opening the resource picker. `fetch(versionIds)` GETs the block-token-gated
@@ -27,19 +34,49 @@ import { useBlockToken } from './useBlockToken.js';
 export function useGenerationResources() {
     const host = useHostOrigin();
     const { raw } = useBlockToken();
+    // In-flight AbortControllers, aborted on unmount so a pending fetch never
+    // resolves into an unmounted component (and its timer is cleared).
+    const inFlight = useRef(new Set());
+    useEffect(() => {
+        const controllers = inFlight.current;
+        return () => {
+            for (const c of controllers)
+                c.abort();
+            controllers.clear();
+        };
+    }, []);
     const doFetch = useCallback(async (versionIds) => {
         if (!host) {
             throw new Error('useGenerationResources: host origin not established yet (wait for BLOCK_INIT).');
         }
         const url = host + buildGenerationResourcesUrl(versionIds);
-        const res = await fetch(url, {
-            headers: { Authorization: `Bearer ${raw}` },
-        });
-        if (!res.ok) {
-            throw new Error(`generation-resources request failed (${res.status})`);
+        const controller = new AbortController();
+        inFlight.current.add(controller);
+        const timeoutId = setTimeout(() => controller.abort(), GENERATION_RESOURCES_TIMEOUT_MS);
+        try {
+            const res = await fetch(url, {
+                headers: { Authorization: `Bearer ${raw}` },
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                throw new Error(`generation-resources request failed (${res.status})`);
+            }
+            const body = (await res.json());
+            return responseToResources(body);
+        }
+        catch (err) {
+            // Distinguish an abort (timeout OR unmount) from a real network/HTTP
+            // failure so the caller gets an actionable message instead of a bare
+            // DOMException.
+            if (controller.signal.aborted) {
+                throw new Error(`useGenerationResources: request aborted (timed out after ${GENERATION_RESOURCES_TIMEOUT_MS}ms or the hook unmounted).`);
+            }
+            throw err;
+        }
+        finally {
+            clearTimeout(timeoutId);
+            inFlight.current.delete(controller);
         }
-        const body = (await res.json());
-        return responseToResources(body);
     }, [host, raw]);
     return { fetch: doFetch };
 }

package/dist/hooks/useGenerationResources.js.map

@@ -1 +1 @@
-{"version":3,"file":"useGenerationResources.js","sourceRoot":"","sources":["../../src/hooks/useGenerationResources.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAIpC,OAAO,EACL,2BAA2B,EAC3B,mBAAmB,GACpB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,sBAAsB;IAGpC,MAAM,IAAI,GAAG,aAAa,EAAE,CAAC;IAC7B,MAAM,EAAE,GAAG,EAAE,GAAG,aAAa,EAAE,CAAC;IAEhC,MAAM,OAAO,GAAG,WAAW,CACzB,KAAK,EAAE,UAAoB,EAAgC,EAAE;QAC3D,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,KAAK,CACb,gFAAgF,CACjF,CAAC;QACJ,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,GAAG,2BAA2B,CAAC,UAAU,CAAC,CAAC;QAC3D,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAC3B,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,GAAG,EAAE,EAAE;SAC5C,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,wCAAwC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;QACzE,CAAC;QACD,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAY,CAAC;QAC3C,OAAO,mBAAmB,CAAC,IAAiD,CAAC,CAAC;IAChF,CAAC,EACD,CAAC,IAAI,EAAE,GAAG,CAAC,CACZ,CAAC;IAEF,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AAC5B,CAAC"}
+{"version":3,"file":"useGenerationResources.js","sourceRoot":"","sources":["../../src/hooks/useGenerationResources.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAIvD,OAAO,EACL,2BAA2B,EAC3B,mBAAmB,GACpB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,+BAA+B,GAAG,MAAM,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,sBAAsB;IAGpC,MAAM,IAAI,GAAG,aAAa,EAAE,CAAC;IAC7B,MAAM,EAAE,GAAG,EAAE,GAAG,aAAa,EAAE,CAAC;IAEhC,0EAA0E;IAC1E,mEAAmE;IACnE,MAAM,QAAQ,GAAG,MAAM,CAAuB,IAAI,GAAG,EAAE,CAAC,CAAC;IACzD,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,WAAW,GAAG,QAAQ,CAAC,OAAO,CAAC;QACrC,OAAO,GAAG,EAAE;YACV,KAAK,MAAM,CAAC,IAAI,WAAW;gBAAE,CAAC,CAAC,KAAK,EAAE,CAAC;YACvC,WAAW,CAAC,KAAK,EAAE,CAAC;QACtB,CAAC,CAAC;IACJ,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,MAAM,OAAO,GAAG,WAAW,CACzB,KAAK,EAAE,UAAoB,EAAgC,EAAE;QAC3D,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,KAAK,CACb,gFAAgF,CACjF,CAAC;QACJ,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,GAAG,2BAA2B,CAAC,UAAU,CAAC,CAAC;QAC3D,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACjC,MAAM,SAAS,GAAG,UAAU,CAC1B,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EACxB,+BAA+B,CAChC,CAAC;QACF,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;gBAC3B,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,GAAG,EAAE,EAAE;gBAC3C,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAC;YACH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACZ,MAAM,IAAI,KAAK,CAAC,wCAAwC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;YACzE,CAAC;YACD,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAY,CAAC;YAC3C,OAAO,mBAAmB,CAAC,IAAiD,CAAC,CAAC;QAChF,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,qEAAqE;YACrE,qEAAqE;YACrE,gBAAgB;YAChB,IAAI,UAAU,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBAC9B,MAAM,IAAI,KAAK,CACb,4DAA4D,+BAA+B,4BAA4B,CACxH,CAAC;YACJ,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,SAAS,CAAC,CAAC;YACxB,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QACtC,CAAC;IACH,CAAC,EACD,CAAC,IAAI,EAAE,GAAG,CAAC,CACZ,CAAC;IAEF,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AAC5B,CAAC"}

package/dist/hooks/useImageUpload.d.ts

@@ -1,4 +1,4 @@
-import type { BlockGenerationSourceImageInfo, BlockUploadedImageInfo, BlockUploadPurpose } from '@civitai/app-sdk/blocks';
+import type { BlockGenerationSourceImageInfo, BlockImageScanResult, BlockPendingImageInfo, BlockUploadedImageInfo, BlockUploadPurpose } from '@civitai/app-sdk/blocks';
 /** Options for {@link useImageUpload}. */
 export interface UseImageUploadOptions {
     /**
@@ -10,6 +10,14 @@ export interface UseImageUploadOptions {
      *    (`{ url, width, height }`).
      */
     purpose?: BlockUploadPurpose;
+    /**
+     * Opt in to the NON-BLOCKING `'display'` flow. When `true`, `open()` resolves
+     * EARLY (on persist) with a {@link BlockPendingImageInfo} and the scan verdict
+     * is delivered separately via `scanStatus()` (see the async overload). Only
+     * meaningful for `'display'`; ignored for `'generationSource'` (that path has
+     * no host-side scan). Absent/`false` keeps the legacy blocking behavior.
+     */
+    asyncScan?: boolean;
 }
 /**
  * Drives the platform-side image-upload flow for App Blocks (Design 1 —
@@ -18,12 +26,17 @@ export interface UseImageUploadOptions {
  * routes through civitai's session-authed pipeline; the host is what decides
  * how the image is scanned/returned based on the requested `purpose`.
  *
- * The RETURN of `open()` is typed by `purpose`:
- *  - default / `'display'` → resolves with a MODERATED
+ * The RETURN of `open()` is typed by `purpose` / `asyncScan`:
+ *  - default / `'display'` (BLOCKING) → resolves with a MODERATED
  *    {@link BlockUploadedImageInfo} (imageId/nsfwLevel/contentRating/url), or
  *    `null` when the user dismissed the modal without a successful upload. The
  *    returned `url` is a Civitai-hosted image URL usable directly as a
  *    `WorkflowBody.sourceImage.url`.
+ *  - `'display'` + `asyncScan: true` (NON-BLOCKING) → resolves EARLY (on persist)
+ *    with a {@link BlockPendingImageInfo} (`status:'pending'`, imageId, url), or
+ *    `null` on dismiss. The image is AUTHOR-PREVIEW-ONLY until the scan verdict —
+ *    obtain it with `scanStatus(handle)`. Do NOT persist the image to a
+ *    cross-user surface until `scanStatus` resolves `'scanned'`.
  *  - `'generationSource'` → resolves with the source
  *    {@link BlockGenerationSourceImageInfo} (`{ url, width, height }`, UNSCANNED —
  *    the orchestrator scans it at gen time), or `null` on dismiss. Feed it
@@ -38,7 +51,7 @@ export interface UseImageUploadOptions {
  * purpose to `'display'`) behaves exactly as before.
  *
  * @example
- * // display (moderated public image) — default
+ * // display (moderated public image) — default, BLOCKING
  * const { open } = useImageUpload();
  * const img = await open();
  * if (!img) return;                       // user dismissed
@@ -46,6 +59,17 @@ export interface UseImageUploadOptions {
  *   sourceImage: { url: img.url, width: 1024, height: 1024 }, params: { prompt } });
  *
  * @example
+ * // display (NON-BLOCKING) — early handle now, scan verdict streamed
+ * const { open, scanStatus } = useImageUpload({ asyncScan: true });
+ * const handle = await open();            // BlockPendingImageInfo | null
+ * if (!handle) return;
+ * // …show the author their own preview immediately…
+ * const verdict = await scanStatus(handle);
+ * if (verdict.status === 'scanned') persistBackground(verdict.image);   // clean
+ * else if (verdict.status === 'blocked') showRejected(verdict.reason);  // terminal
+ * else retryLater(verdict.message);       // transient — re-call scanStatus(handle)
+ *
+ * @example
  * // generationSource (private img2img source, unscanned)
  * const { open } = useImageUpload({ purpose: 'generationSource' });
  * const src = await open();               // { url, width, height } | null
@@ -58,6 +82,20 @@ export declare function useImageUpload(options: {
 }): {
     open: () => Promise<BlockGenerationSourceImageInfo | null>;
 };
+export declare function useImageUpload(options: {
+    purpose?: 'display';
+    asyncScan: true;
+}): {
+    /** Early-resolve handle (image persisted, NOT yet scanned) or `null` (dismissed). */
+    open: () => Promise<BlockPendingImageInfo | null>;
+    /**
+     * Resolve the async scan verdict for a handle returned by `open()`. Re-callable
+     * for retry: the host emits the verdict once and the hook buffers it, so a
+     * re-call after an `'error'`/timeout re-awaits (or immediately returns) the same
+     * verdict. An unknown/expired handle resolves to a retryable `'error'`.
+     */
+    scanStatus: (handle: BlockPendingImageInfo) => Promise<BlockImageScanResult>;
+};
 export declare function useImageUpload(options?: {
     purpose?: 'display';
 }): {

package/dist/hooks/useImageUpload.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useImageUpload.d.ts","sourceRoot":"","sources":["../../src/hooks/useImageUpload.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,8BAA8B,EAC9B,sBAAsB,EACtB,kBAAkB,EACnB,MAAM,yBAAyB,CAAC;AAMjC,0CAA0C;AAC1C,MAAM,WAAW,qBAAqB;IACpC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,kBAAkB,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE;IAAE,OAAO,EAAE,kBAAkB,CAAA;CAAE,GAAG;IACxE,IAAI,EAAE,MAAM,OAAO,CAAC,8BAA8B,GAAG,IAAI,CAAC,CAAC;CAC5D,CAAC;AACF,wBAAgB,cAAc,CAAC,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,SAAS,CAAA;CAAE,GAAG;IACjE,IAAI,EAAE,MAAM,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAAC;CACpD,CAAC"}
+{"version":3,"file":"useImageUpload.d.ts","sourceRoot":"","sources":["../../src/hooks/useImageUpload.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,8BAA8B,EAC9B,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,EACtB,kBAAkB,EACnB,MAAM,yBAAyB,CAAC;AAejC,0CAA0C;AAC1C,MAAM,WAAW,qBAAqB;IACpC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AA+BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE;IAAE,OAAO,EAAE,kBAAkB,CAAA;CAAE,GAAG;IACxE,IAAI,EAAE,MAAM,OAAO,CAAC,8BAA8B,GAAG,IAAI,CAAC,CAAC;CAC5D,CAAC;AACF,wBAAgB,cAAc,CAAC,OAAO,EAAE;IAAE,OAAO,CAAC,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,IAAI,CAAA;CAAE,GAAG;IACjF,qFAAqF;IACrF,IAAI,EAAE,MAAM,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAAC;IAClD;;;;;OAKG;IACH,UAAU,EAAE,CAAC,MAAM,EAAE,qBAAqB,KAAK,OAAO,CAAC,oBAAoB,CAAC,CAAC;CAC9E,CAAC;AACF,wBAAgB,cAAc,CAAC,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,SAAS,CAAA;CAAE,GAAG;IACjE,IAAI,EAAE,MAAM,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAAC;CACpD,CAAC"}

package/dist/hooks/useImageUpload.js

@@ -1,10 +1,106 @@
-import { useCallback } from 'react';
+import { useCallback, useEffect, useRef } from 'react';
 import { getTransport } from '../internal/singleton.js';
-import { sendTypedRequest } from '../internal/transport.js';
+import { sendTypedRequest, subscribeTyped } from '../internal/transport.js';
 import { PICKER_REQUEST_TIMEOUT_MS } from './useCheckpointPicker.js';
+/**
+ * Generous hook-side backstop for {@link BlockImageScanResult} delivery. The
+ * host-side scan POLL budget is authoritative and the consuming app applies its
+ * own (shorter) timeout; this only guards against a verdict that never arrives,
+ * resolving RETRYABLE so a later re-call can still pick up a late verdict from
+ * the buffer.
+ */
+const SCAN_STATUS_TIMEOUT_MS = PICKER_REQUEST_TIMEOUT_MS;
+/**
+ * A verdict is TERMINAL when the host has reached a final answer (`scanned` /
+ * `blocked`) — the block will never poll it again. An `error` verdict is
+ * transient/retryable, so its entry is KEPT so `scanStatus()` can be re-called.
+ * Terminal entries are EVICTED from the tracking map once delivered (see below)
+ * so a long-lived block doing many uploads can't grow the map unbounded.
+ */
+function isTerminalVerdict(v) {
+    return v.status === 'scanned' || v.status === 'blocked';
+}
 export function useImageUpload(options) {
     const purpose = options?.purpose;
+    const asyncScan = options?.asyncScan === true && purpose !== 'generationSource';
+    // Per-instance scan tracking, keyed by imageId. Persists across renders; a
+    // verdict is correlated back to its upload by imageId + the generated requestId.
+    const scansRef = useRef(new Map());
+    // Mount ONE listener for the host→block IMAGE_SCAN_RESOLVED push. The transport
+    // invokes this ONLY AFTER the message has cleared BOTH the origin allowlist and
+    // the payload validator (see IframeTransport.handleMessage), and we ADDITIONALLY
+    // honor a verdict only if it matches a request this hook instance originated
+    // (matching requestId + imageId), so concurrent instances coexist and a
+    // forged/replayed verdict is ignored.
+    useEffect(() => {
+        const scans = scansRef.current;
+        const unsubscribe = subscribeTyped(getTransport(), 'IMAGE_SCAN_RESOLVED', ({ requestId, imageId, result }) => {
+            const entry = scans.get(imageId);
+            if (!entry || entry.requestId !== requestId)
+                return; // not ours / forged
+            if (entry.verdict)
+                return; // host emits once — honor only the first
+            entry.verdict = result;
+            const hadWaiters = entry.waiters.length > 0;
+            for (const w of entry.waiters) {
+                clearTimeout(w.timeoutId);
+                w.resolve(result);
+            }
+            entry.waiters = [];
+            // Evict a TERMINAL verdict once it has been delivered to a live caller
+            // (bounded-memory: L1). If nobody was waiting yet (verdict arrived before
+            // scanStatus() was called), keep it BUFFERED so the eventual scanStatus()
+            // can still read it — that read then evicts it (see scanStatus below).
+            // `error` verdicts are always kept (retryable).
+            if (hadWaiters && isTerminalVerdict(result))
+                scans.delete(imageId);
+        });
+        return () => {
+            unsubscribe();
+            for (const entry of scans.values()) {
+                for (const w of entry.waiters)
+                    clearTimeout(w.timeoutId);
+            }
+        };
+    }, []);
     const open = useCallback(async () => {
+        if (asyncScan) {
+            // Omit `purpose` (display byte-compat) but opt into the early-resolve flow.
+            const { requestId, selected } = await sendTypedRequest(getTransport(), { type: 'OPEN_IMAGE_UPLOAD', payload: { asyncScan: true } }, 'IMAGE_UPLOAD_RESULT', { timeoutMs: PICKER_REQUEST_TIMEOUT_MS });
+            if (!selected)
+                return null; // dismissed
+            // NEW host: an early-resolve pending handle. Track it and wait for the push.
+            if ('status' in selected && selected.status === 'pending') {
+                scansRef.current.set(selected.imageId, { requestId, waiters: [] });
+                const handle = {
+                    status: 'pending',
+                    imageId: selected.imageId,
+                    url: selected.url,
+                };
+                return handle;
+            }
+            // OLD host (ignored asyncScan): it blocking-resolved a MODERATED image. Wrap
+            // it in a pending-shaped handle AND pre-buffer a `scanned` verdict so
+            // scanStatus() resolves immediately — no hang. (Compat matrix case 2.)
+            if ('imageId' in selected && typeof selected.imageId === 'number') {
+                const moderated = selected;
+                scansRef.current.set(moderated.imageId, {
+                    requestId,
+                    verdict: { status: 'scanned', image: moderated },
+                    waiters: [],
+                });
+                const handle = {
+                    status: 'pending',
+                    imageId: moderated.imageId,
+                    url: moderated.url,
+                };
+                return handle;
+            }
+            // Any other shape on a display request (e.g. an unexpected source-only
+            // payload) → treat as dismissed rather than fabricate a handle.
+            return null;
+        }
+        // ---- Existing BLOCKING behavior (unchanged) ----
         // Omit `purpose` for the default/display mode so the wire stays
         // byte-compatible with an older host that predates the field.
         const payload = purpose === 'generationSource' ? { purpose } : {};
@@ -12,7 +108,31 @@ export function useImageUpload(options) {
         // Normalize the "dismissed" case to an explicit null so callers can
         // `if (!img) return;` without an `undefined` ambiguity.
         return selected ?? null;
-    }, [purpose]);
-    return { open };
+    }, [asyncScan, purpose]);
+    const scanStatus = useCallback((handle) => {
+        const entry = scansRef.current.get(handle.imageId);
+        if (!entry) {
+            // No tracked upload for this handle (a foreign/expired handle, or the
+            // hook remounted). Retryable rather than a hang.
+            return Promise.resolve({ status: 'error', message: 'unknown or expired upload handle' });
+        }
+        if (entry.verdict) {
+            const buffered = entry.verdict;
+            // A BUFFERED terminal verdict (the push arrived before this call) is
+            // consumed here — evict it so the map doesn't grow (L1). `error` stays
+            // (retryable). See isTerminalVerdict + the push handler above.
+            if (isTerminalVerdict(buffered))
+                scansRef.current.delete(handle.imageId);
+            return Promise.resolve(buffered);
+        }
+        return new Promise((resolve) => {
+            const timeoutId = setTimeout(() => {
+                entry.waiters = entry.waiters.filter((w) => w.timeoutId !== timeoutId);
+                resolve({ status: 'error', message: 'scan status timed out' });
+            }, SCAN_STATUS_TIMEOUT_MS);
+            entry.waiters.push({ resolve, timeoutId });
+        });
+    }, []);
+    return { open, scanStatus };
 }
 //# sourceMappingURL=useImageUpload.js.map

package/dist/hooks/useImageUpload.js.map

@@ -1 +1 @@
-{"version":3,"file":"useImageUpload.js","sourceRoot":"","sources":["../../src/hooks/useImageUpload.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAQpC,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AA+DrE,MAAM,UAAU,cAAc,CAAC,OAA+B;IAG5D,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,CAAC;IACjC,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,IAAI,EAAE;QAClC,gEAAgE;QAChE,8DAA8D;QAC9D,MAAM,OAAO,GAAG,OAAO,KAAK,kBAAkB,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClE,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,gBAAgB,CACzC,YAAY,EAAE,EACd,EAAE,IAAI,EAAE,mBAAmB,EAAE,OAAO,EAAE,EACtC,qBAAqB,EACrB,EAAE,SAAS,EAAE,yBAAyB,EAAE,CACzC,CAAC;QACF,oEAAoE;QACpE,wDAAwD;QACxD,OAAO,QAAQ,IAAI,IAAI,CAAC;IAC1B,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IAEd,OAAO,EAAE,IAAI,EAAE,CAAC;AAClB,CAAC"}
+{"version":3,"file":"useImageUpload.js","sourceRoot":"","sources":["../../src/hooks/useImageUpload.ts"],"names":[],"mappings":"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"}

package/dist/internal/iframeTransport.d.ts

@@ -29,6 +29,12 @@ export declare class IframeTransport implements BlockTransport {
     /** Messages queued before `BLOCK_INIT` lands. Flushed in arrival order. */
     private readonly outbound;
     private readonly pending;
+    /**
+     * Handlers for UNSOLICITED parent→block pushes (e.g. `IMAGE_SCAN_RESOLVED`) —
+     * messages the host initiates on its own schedule, NOT replies to a pending
+     * `sendRequest`. Keyed by message type; each entry a set of subscribers.
+     */
+    private readonly pushListeners;
     private readonly initPromise;
     private resolveInit;
     private rejectInit;
@@ -61,6 +67,7 @@ export declare class IframeTransport implements BlockTransport {
     sendRequest(request: OutboundRequest, responseType: ParentToBlockMessageType, opts?: {
         timeoutMs?: number;
     }): Promise<unknown>;
+    onMessage(type: ParentToBlockMessageType, handler: (payload: unknown) => void): () => void;
     /** Test-only: tear down listeners + reject pending. */
     dispose(): void;
     private dispatch;

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

@@ -1 +1 @@
-{"version":3,"file":"iframeTransport.d.ts","sourceRoot":"","sources":["../../src/internal/iframeTransport.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EAEzB,KAAK,wBAAwB,EAC9B,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAKL,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AASxB,MAAM,WAAW,sBAAsB;IACrC;;;;;;;OAOG;IACH,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AASD;;;;;GAKG;AACH,qBAAa,eAAgB,YAAW,cAAc;IACpD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC,OAAO,CAAC,QAAQ,CAAiC;IACjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;IAEnD,yEAAyE;IACzE,OAAO,CAAC,YAAY,CAAuB;IAE3C,2EAA2E;IAC3E,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiD;IAC1E,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;IAE7D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA4B;IACxD,OAAO,CAAC,WAAW,CAAuC;IAC1D,OAAO,CAAC,UAAU,CAAwB;IAC1C,OAAO,CAAC,aAAa,CAAgC;IACrD,OAAO,CAAC,YAAY,CAAS;IAE7B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAgC;gBAEpD,IAAI,EAAE,sBAAsB;IAoCxC,WAAW,IAAI,aAAa;IAI5B;;;;;;;;;;;;;;;;OAgBG;IACH,aAAa,IAAI,MAAM,GAAG,IAAI;IAI9B,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAO3C,WAAW,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAIxC,WAAW,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI;IAIhD,WAAW,CACT,OAAO,EAAE,eAAe,EACxB,YAAY,EAAE,wBAAwB,EACtC,IAAI,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GAChC,OAAO,CAAC,OAAO,CAAC;IAmBnB,uDAAuD;IACvD,OAAO,IAAI,IAAI;IAWf,OAAO,CAAC,QAAQ;IAQhB,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,YAAY;IAKpB,OAAO,CAAC,aAAa;IA2FrB,OAAO,CAAC,iBAAiB;IASzB,OAAO,CAAC,IAAI;CAGb"}
+{"version":3,"file":"iframeTransport.d.ts","sourceRoot":"","sources":["../../src/internal/iframeTransport.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EAEzB,KAAK,wBAAwB,EAC9B,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAKL,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AASxB,MAAM,WAAW,sBAAsB;IACrC;;;;;;;OAOG;IACH,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AASD;;;;;GAKG;AACH,qBAAa,eAAgB,YAAW,cAAc;IACpD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC,OAAO,CAAC,QAAQ,CAAiC;IACjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;IAEnD,yEAAyE;IACzE,OAAO,CAAC,YAAY,CAAuB;IAE3C,2EAA2E;IAC3E,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiD;IAC1E,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;IAE7D;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAsD;IAEpF,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA4B;IACxD,OAAO,CAAC,WAAW,CAAuC;IAC1D,OAAO,CAAC,UAAU,CAAwB;IAC1C,OAAO,CAAC,aAAa,CAAgC;IACrD,OAAO,CAAC,YAAY,CAAS;IAE7B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAgC;gBAEpD,IAAI,EAAE,sBAAsB;IAoCxC,WAAW,IAAI,aAAa;IAI5B;;;;;;;;;;;;;;;;OAgBG;IACH,aAAa,IAAI,MAAM,GAAG,IAAI;IAI9B,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAO3C,WAAW,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAIxC,WAAW,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI;IAIhD,WAAW,CACT,OAAO,EAAE,eAAe,EACxB,YAAY,EAAE,wBAAwB,EACtC,IAAI,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GAChC,OAAO,CAAC,OAAO,CAAC;IAmBnB,SAAS,CACP,IAAI,EAAE,wBAAwB,EAC9B,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAClC,MAAM,IAAI;IAeb,uDAAuD;IACvD,OAAO,IAAI,IAAI;IAYf,OAAO,CAAC,QAAQ;IAQhB,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,YAAY;IAKpB,OAAO,CAAC,aAAa;IA2GrB,OAAO,CAAC,iBAAiB;IASzB,OAAO,CAAC,IAAI;CAGb"}