@civitai/blocks-react 0.37.0 → 0.39.0

package/dist/hooks/useBuzzWorkflow.d.ts

@@ -1,8 +1,121 @@
 import type { BlockWorkflowSnapshot, WorkflowBody, WorkflowStatus } from '@civitai/app-sdk/blocks';
+/**
+ * Default orchestrator-side hold per {@link UseBuzzWorkflowReturn.watch} poll,
+ * in SECONDS.
+ *
+ * 🔴 THE UNIT IS SECONDS, matching the orchestrator's `?wait=` parameter — not
+ * the milliseconds every other timing option in this file uses. Named
+ * `waitSeconds` everywhere for exactly that reason.
+ *
+ * 15 rather than something larger for two reasons, both of them ceilings this
+ * value must stay UNDER, not preferences:
+ *   - civitai's shared `getWorkflow` helper aborts a single orchestrator read at
+ *     20s. A hold at or above that is cancelled by our own backstop before the
+ *     orchestrator can answer.
+ *   - the host's poll additionally runs an inline output-moderation scan with
+ *     its own ~12s ceiling, and the two are SEQUENTIAL — so the round trip's
+ *     worst case is 15 + 12 = 27s, which must stay inside the host's own
+ *     end-to-end response budget.
+ */
+export declare const DEFAULT_WATCH_WAIT_SECONDS = 15;
+/** Optional controls for {@link UseBuzzWorkflowReturn.watch}. */
+export interface WatchWorkflowOptions {
+    /**
+     * Called with EVERY snapshot the host returns, intermediate ones included, in
+     * order. This is the push side of the API: render from here instead of
+     * re-reading `result` on a timer.
+     *
+     * A throw from this callback is not caught — it rejects the `watch` promise.
+     */
+    onUpdate?: (snapshot: BlockWorkflowSnapshot) => void;
+    /**
+     * Stop watching. The promise RESOLVES with the last snapshot seen rather than
+     * rejecting: an abort is the caller's own decision, not a failure, and the
+     * common case (a component unmounting) has nobody left to catch a rejection.
+     *
+     * 🔴 This does NOT cancel the workflow — it stops watching it. Buzz is already
+     * spent and the orchestrator keeps running. To actually stop the work, call
+     * {@link UseBuzzWorkflowReturn.cancel}.
+     */
+    signal?: AbortSignal;
+    /**
+     * Orchestrator-side hold per poll, in **seconds**. Default
+     * {@link DEFAULT_WATCH_WAIT_SECONDS}. `0` disables long polling and falls back
+     * to a plain read per `intervalMs`.
+     *
+     * 🔴 CURRENTLY ADVISORY. It travels on the `POLL_WORKFLOW` message and a host
+     * that does not yet read the field simply answers immediately, exactly as
+     * today — so `watch` is correct either way, it just polls more often. See the
+     * field's note on `BlockToParentMessage`.
+     */
+    waitSeconds?: number;
+    /**
+     * Delay between polls, in ms. Default 1500.
+     *
+     * 🔴 NOT REDUNDANT WITH `waitSeconds`. When the host long-polls, the hold
+     * dominates and this is a few percent of overhead. When it does NOT — an
+     * older host, or `waitSeconds: 0` — this is the only thing standing between
+     * this loop and a request storm.
+     */
+    intervalMs?: number;
+    /** Give up and resolve with the last snapshot after this long. Default 10min. */
+    timeoutMs?: number;
+    /**
+     * Consecutive transport failures to absorb before rejecting. Default 3.
+     *
+     * A poll can fail for reasons that have nothing to do with the workflow (a
+     * pod rolling, a network blip). Because `watch` OWNS the loop, a single blip
+     * would otherwise end a generation the caller's own retry loop used to
+     * survive. The counter RESETS on any successful poll, so this bounds a burst,
+     * not a lifetime.
+     */
+    maxRetries?: number;
+}
+/** Optional per-submit controls. */
+export interface SubmitWorkflowOptions {
+    /**
+     * A STABLE idempotency key for this logical submit. Reuse the SAME value when
+     * RETRYING a submit whose response was lost (timeout / network drop) so the
+     * host+orchestrator collapse it to ONE Buzz charge instead of double-charging.
+     * Omit → the hook generates a fresh key per `submit()` call (each call is a new
+     * logical submit); pass a stable id (e.g. a grid-cell id) to make a retry safe.
+     */
+    idempotencyKey?: string;
+}
 interface UseBuzzWorkflowReturn {
     estimate: (body: WorkflowBody) => Promise<BlockWorkflowSnapshot>;
-    submit: (body: WorkflowBody) => Promise<BlockWorkflowSnapshot>;
+    submit: (body: WorkflowBody, options?: SubmitWorkflowOptions) => Promise<BlockWorkflowSnapshot>;
+    /**
+     * ONE host round-trip. The low-level pull primitive — you almost certainly
+     * want {@link UseBuzzWorkflowReturn.watch} instead, which owns the loop.
+     */
     poll: (workflowId: string) => Promise<BlockWorkflowSnapshot>;
+    /**
+     * Watch a workflow to completion. Resolves with the TERMINAL snapshot; calls
+     * `onUpdate` with every intermediate snapshot along the way.
+     *
+     * This is the replacement for the `useEffect` + `setTimeout` backoff every
+     * block used to hand-write around {@link UseBuzzWorkflowReturn.poll}. The app
+     * consumes a promise and/or a callback; the loop lives here.
+     *
+     * 🔴 THE LOOP IS SEQUENTIAL AND NON-OVERLAPPING BY CONSTRUCTION — each poll is
+     * awaited before the next is scheduled, so exactly one request per watched
+     * workflow is ever in flight. That is not tidiness: it is the property that
+     * makes a long hold SAFE. A caller-written `setInterval(poll, 2000)` against
+     * a host holding 15s would stack ~7 concurrent requests per workflow, and
+     * that is precisely why long polling is opt-in on the wire rather than
+     * switched on for every deployed block.
+     *
+     * @example
+     * const { submit, watch, cancel } = useBuzzWorkflow();
+     * const submitted = await submit(body);
+     * const done = await watch(submitted.workflowId, {
+     *   onUpdate: (snap) => setProgress(snap.status),
+     *   signal: abortRef.current.signal,
+     * });
+     * if (done.status === 'succeeded') setImages(done.imageUrls ?? []);
+     */
+    watch: (workflowId: string, options?: WatchWorkflowOptions) => Promise<BlockWorkflowSnapshot>;
     /**
      * Cancel a running workflow on the orchestrator (a real server-side stop,
      * not just client-side untracking). The host re-derives ownership from the
@@ -24,22 +137,29 @@ interface UseBuzzWorkflowReturn {
  * refuses. Block apps should call `useBuzzPurchase().openPurchaseModal()`
  * when that happens.
  *
- * The hook does NOT auto-poll: after `submit` flips `status` to `'polling'`,
- * the caller runs a `useEffect` that calls `poll(workflowId)` on a backoff
- * until the snapshot is terminal. `status === 'confirming'` is IDLE (estimate
- * landed, user reviewing cost) — keep the Generate button enabled.
+ * AFTER `submit` FLIPS `status` TO `'polling'`, USE `watch(workflowId)`. It owns
+ * the loop, resolves on the terminal snapshot, and pushes every intermediate
+ * one to an `onUpdate` callback — so a block consumes a promise/callback rather
+ * than running its own timer. `poll(workflowId)` remains the single-round-trip
+ * primitive for callers that genuinely want to drive their own cadence; the
+ * hand-written `useEffect` + backoff around it that this docstring used to
+ * prescribe is no longer the recommended shape. `status === 'confirming'` is
+ * IDLE (estimate landed, user reviewing cost) — keep the Generate button
+ * enabled.
  *
  * `estimate`/`submit` take a full {@link WorkflowBody} — the discriminated
- * union keyed by `kind`, so either a `textToImage` body (`{ kind, modelId,
- * modelVersionId, params }`) or a `customComfy` recipe body (`{ kind, recipe,
- * params }`), not a bare `{ prompt }`. The hook forwards the body to the host
- * verbatim and never reads variant-specific fields, so both members flow
- * through unchanged.
+ * union keyed by `kind`, with THREE members as of `@civitai/app-sdk@0.30.0`:
+ * a `textToImage` body (`{ kind, modelId, modelVersionId, params }`), a
+ * `customComfy` recipe body (`{ kind, recipe, params }`), or a `step` body
+ * (`{ kind: 'step', step, params }` — a server-registered orchestrator step
+ * such as `'chat-completion'`), never a bare `{ prompt }`. The hook forwards
+ * the body to the host verbatim and never reads variant-specific fields, so
+ * every member flows through unchanged, including any member added later.
  *
- * @returns `{ estimate, submit, poll, cancel, status, result, error }`.
+ * @returns `{ estimate, submit, poll, watch, cancel, status, result, error }`.
  *
  * @example
- * const { estimate, submit, poll, status, result } = useBuzzWorkflow();
+ * const { estimate, submit, watch, status, result } = useBuzzWorkflow();
  * const body = {
  *   kind: 'textToImage' as const,
  *   modelId,
@@ -48,7 +168,7 @@ interface UseBuzzWorkflowReturn {
  * };
  * await estimate(body);            // status 'estimating' → 'confirming' (cost in result.cost.total)
  * const snap = await submit(body); // status 'submitting' → 'polling'; returns a workflowId
- * await poll(snap.workflowId);     // caller loops this on a backoff until terminal
+ * const done = await watch(snap.workflowId, { onUpdate: render }); // → terminal
  */
 export declare function useBuzzWorkflow(): UseBuzzWorkflowReturn;
 export {};

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

@@ -1 +1 @@
-{"version":3,"file":"useBuzzWorkflow.d.ts","sourceRoot":"","sources":["../../src/hooks/useBuzzWorkflow.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AA8BnG,UAAU,qBAAqB;IAC7B,QAAQ,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACjE,MAAM,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC/D,IAAI,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC7D;;;;;;OAMG;IACH,MAAM,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC/D,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,qBAAqB,GAAG,IAAI,CAAC;IACrC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,eAAe,IAAI,qBAAqB,CAuFvD"}
+{"version":3,"file":"useBuzzWorkflow.d.ts","sourceRoot":"","sources":["../../src/hooks/useBuzzWorkflow.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AA8BnG;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAW7C,iEAAiE;AACjE,MAAM,WAAW,oBAAoB;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,qBAAqB,KAAK,IAAI,CAAC;IACrD;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAyBD,oCAAoC;AACpC,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,UAAU,qBAAqB;IAC7B,QAAQ,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACjE,MAAM,EAAE,CACN,IAAI,EAAE,YAAY,EAClB,OAAO,CAAC,EAAE,qBAAqB,KAC5B,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACpC;;;OAGG;IACH,IAAI,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC7D;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,KAAK,EAAE,CACL,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,oBAAoB,KAC3B,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACpC;;;;;;OAMG;IACH,MAAM,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC/D,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,qBAAqB,GAAG,IAAI,CAAC;IACrC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,eAAe,IAAI,qBAAqB,CA+MvD"}

package/dist/hooks/useBuzzWorkflow.js

@@ -1,6 +1,6 @@
 import { useCallback, useState } from 'react';
 import { getTransport } from '../internal/singleton.js';
-import { sendTypedRequest } from '../internal/transport.js';
+import { generateIdempotencyKey, sendTypedRequest } from '../internal/transport.js';
 /**
  * Snapshot statuses that mean "no further polling is needed."
  * Used by both `submit` (a host can return an instant-fail / cached result)
@@ -24,6 +24,54 @@ const TERMINAL_STATUSES = new Set([
  * a spurious `request "SUBMIT_WORKFLOW" timed out` rejection.
  */
 const WORKFLOW_REQUEST_TIMEOUT_MS = 120_000;
+/**
+ * Default orchestrator-side hold per {@link UseBuzzWorkflowReturn.watch} poll,
+ * in SECONDS.
+ *
+ * 🔴 THE UNIT IS SECONDS, matching the orchestrator's `?wait=` parameter — not
+ * the milliseconds every other timing option in this file uses. Named
+ * `waitSeconds` everywhere for exactly that reason.
+ *
+ * 15 rather than something larger for two reasons, both of them ceilings this
+ * value must stay UNDER, not preferences:
+ *   - civitai's shared `getWorkflow` helper aborts a single orchestrator read at
+ *     20s. A hold at or above that is cancelled by our own backstop before the
+ *     orchestrator can answer.
+ *   - the host's poll additionally runs an inline output-moderation scan with
+ *     its own ~12s ceiling, and the two are SEQUENTIAL — so the round trip's
+ *     worst case is 15 + 12 = 27s, which must stay inside the host's own
+ *     end-to-end response budget.
+ */
+export const DEFAULT_WATCH_WAIT_SECONDS = 15;
+/** Gap between `watch` polls, in ms. See {@link WatchWorkflowOptions.intervalMs}. */
+const DEFAULT_WATCH_INTERVAL_MS = 1_500;
+/** Total `watch` budget, in ms. Generation can legitimately take minutes. */
+const DEFAULT_WATCH_TIMEOUT_MS = 10 * 60_000;
+/** How many CONSECUTIVE transport failures `watch` absorbs before rejecting. */
+const DEFAULT_WATCH_MAX_RETRIES = 3;
+/**
+ * Sleep, waking EARLY if `signal` aborts.
+ *
+ * 🔴 A PLAIN `setTimeout` WOULD MAKE ABORT LATENCY EQUAL THE POLL INTERVAL. A
+ * component unmounting mid-gap would keep a pending timer alive for up to
+ * `intervalMs` and only then notice, which is exactly the "unmounted component
+ * kept working" shape an abort signal exists to prevent. The listener is always
+ * removed, so an abort long after the sleep resolved cannot fire into a
+ * finished loop.
+ */
+function sleep(ms, signal) {
+    if (signal?.aborted)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const done = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', done);
+            resolve();
+        };
+        const timer = setTimeout(done, ms);
+        signal?.addEventListener('abort', done);
+    });
+}
 /**
  * Orchestrates the estimate → confirm → submit → poll dance through the
  * host-mediated `postMessage` path.
@@ -33,22 +81,29 @@ const WORKFLOW_REQUEST_TIMEOUT_MS = 120_000;
  * refuses. Block apps should call `useBuzzPurchase().openPurchaseModal()`
  * when that happens.
  *
- * The hook does NOT auto-poll: after `submit` flips `status` to `'polling'`,
- * the caller runs a `useEffect` that calls `poll(workflowId)` on a backoff
- * until the snapshot is terminal. `status === 'confirming'` is IDLE (estimate
- * landed, user reviewing cost) — keep the Generate button enabled.
+ * AFTER `submit` FLIPS `status` TO `'polling'`, USE `watch(workflowId)`. It owns
+ * the loop, resolves on the terminal snapshot, and pushes every intermediate
+ * one to an `onUpdate` callback — so a block consumes a promise/callback rather
+ * than running its own timer. `poll(workflowId)` remains the single-round-trip
+ * primitive for callers that genuinely want to drive their own cadence; the
+ * hand-written `useEffect` + backoff around it that this docstring used to
+ * prescribe is no longer the recommended shape. `status === 'confirming'` is
+ * IDLE (estimate landed, user reviewing cost) — keep the Generate button
+ * enabled.
  *
  * `estimate`/`submit` take a full {@link WorkflowBody} — the discriminated
- * union keyed by `kind`, so either a `textToImage` body (`{ kind, modelId,
- * modelVersionId, params }`) or a `customComfy` recipe body (`{ kind, recipe,
- * params }`), not a bare `{ prompt }`. The hook forwards the body to the host
- * verbatim and never reads variant-specific fields, so both members flow
- * through unchanged.
+ * union keyed by `kind`, with THREE members as of `@civitai/app-sdk@0.30.0`:
+ * a `textToImage` body (`{ kind, modelId, modelVersionId, params }`), a
+ * `customComfy` recipe body (`{ kind, recipe, params }`), or a `step` body
+ * (`{ kind: 'step', step, params }` — a server-registered orchestrator step
+ * such as `'chat-completion'`), never a bare `{ prompt }`. The hook forwards
+ * the body to the host verbatim and never reads variant-specific fields, so
+ * every member flows through unchanged, including any member added later.
  *
- * @returns `{ estimate, submit, poll, cancel, status, result, error }`.
+ * @returns `{ estimate, submit, poll, watch, cancel, status, result, error }`.
  *
  * @example
- * const { estimate, submit, poll, status, result } = useBuzzWorkflow();
+ * const { estimate, submit, watch, status, result } = useBuzzWorkflow();
  * const body = {
  *   kind: 'textToImage' as const,
  *   modelId,
@@ -57,7 +112,7 @@ const WORKFLOW_REQUEST_TIMEOUT_MS = 120_000;
  * };
  * await estimate(body);            // status 'estimating' → 'confirming' (cost in result.cost.total)
  * const snap = await submit(body); // status 'submitting' → 'polling'; returns a workflowId
- * await poll(snap.workflowId);     // caller loops this on a backoff until terminal
+ * const done = await watch(snap.workflowId, { onUpdate: render }); // → terminal
  */
 export function useBuzzWorkflow() {
     const [status, setStatus] = useState('idle');
@@ -78,11 +133,14 @@ export function useBuzzWorkflow() {
             throw err;
         }
     }, []);
-    const submit = useCallback(async (body) => {
+    const submit = useCallback(async (body, options) => {
         setError(null);
         setStatus('submitting');
+        // Idempotency: reuse a caller-supplied stable key across a retry (→ one Buzz
+        // charge), or mint a fresh one per call (each call is a new logical submit).
+        const idempotencyKey = options?.idempotencyKey ?? generateIdempotencyKey();
         try {
-            const { snapshot } = await sendTypedRequest(getTransport(), { type: 'SUBMIT_WORKFLOW', payload: { body } }, 'WORKFLOW_SUBMITTED', { timeoutMs: WORKFLOW_REQUEST_TIMEOUT_MS });
+            const { snapshot } = await sendTypedRequest(getTransport(), { type: 'SUBMIT_WORKFLOW', payload: { body, idempotencyKey } }, 'WORKFLOW_SUBMITTED', { timeoutMs: WORKFLOW_REQUEST_TIMEOUT_MS });
             setResult(snapshot);
             setStatus(TERMINAL_STATUSES.has(snapshot.status) ? 'done' : 'polling');
             return snapshot;
@@ -93,10 +151,45 @@ export function useBuzzWorkflow() {
             throw err;
         }
     }, []);
+    /**
+     * ONE poll round-trip, with an optional long-poll hint. The single place that
+     * builds a `POLL_WORKFLOW` message, so `poll` and `watch` cannot drift on the
+     * message shape or the request timeout.
+     */
+    const pollOnce = useCallback(async (workflowId, waitSeconds) => {
+        const { snapshot } = await sendTypedRequest(getTransport(), {
+            type: 'POLL_WORKFLOW',
+            payload: {
+                workflowId,
+                // Omitted rather than sent as 0 when long polling is off, so the
+                // message stays byte-identical to what pre-`watch` blocks send.
+                ...(waitSeconds !== undefined && waitSeconds > 0 ? { waitSeconds } : {}),
+            },
+        }, 'WORKFLOW_STATUS', { timeoutMs: WORKFLOW_REQUEST_TIMEOUT_MS });
+        // A reply without a usable snapshot is a failure, not a result: returning
+        // `undefined` would make `poll` resolve with a non-snapshot, and would
+        // make `watch` — whose stop condition is
+        // `TERMINAL_STATUSES.has(snapshot.status)` — loop to its timeout against a
+        // host that is answering with nothing. Throwing routes it into `watch`'s
+        // bounded retry instead.
+        //
+        // 🔴 NOT CLAIMED TO BE REACHABLE THROUGH `IframeTransport`, WHICH ALREADY
+        // FAIL-CLOSES THIS. Its `payloadValidatorFor('WORKFLOW_STATUS')`
+        // (internal/validate.ts) drops a reply whose `snapshot.status` is absent
+        // or outside the known set, so the request never resolves at all and
+        // times out instead. This guard covers the OTHER transports
+        // `sendTypedRequest` accepts (mock/test hosts, `dev:live`), and is kept as
+        // cheap defence — do not cite it as validated input handling on the
+        // iframe path.
+        if (!snapshot || typeof snapshot.status !== 'string') {
+            throw new Error(`POLL_WORKFLOW: malformed response (no snapshot) for ${workflowId}`);
+        }
+        return snapshot;
+    }, []);
     const poll = useCallback(async (workflowId) => {
         setStatus('polling');
         try {
-            const { snapshot } = await sendTypedRequest(getTransport(), { type: 'POLL_WORKFLOW', payload: { workflowId } }, 'WORKFLOW_STATUS', { timeoutMs: WORKFLOW_REQUEST_TIMEOUT_MS });
+            const snapshot = await pollOnce(workflowId);
             setResult(snapshot);
             if (TERMINAL_STATUSES.has(snapshot.status)) {
                 setStatus('done');
@@ -108,7 +201,75 @@ export function useBuzzWorkflow() {
             setStatus('error');
             throw err;
         }
-    }, []);
+    }, [pollOnce]);
+    const watch = useCallback(async (workflowId, options) => {
+        const interval = options?.intervalMs ?? DEFAULT_WATCH_INTERVAL_MS;
+        const waitSeconds = options?.waitSeconds ?? DEFAULT_WATCH_WAIT_SECONDS;
+        const maxRetries = options?.maxRetries ?? DEFAULT_WATCH_MAX_RETRIES;
+        const deadline = Date.now() + (options?.timeoutMs ?? DEFAULT_WATCH_TIMEOUT_MS);
+        setError(null);
+        setStatus('polling');
+        let last = null;
+        let consecutiveFailures = 0;
+        // 🔴 SEQUENTIAL BY CONSTRUCTION. Every iteration AWAITS its poll before
+        // scheduling the next, so at most one request per watched workflow is
+        // ever in flight no matter how long the host holds it. A timer-driven
+        // caller cannot make that guarantee, which is why long polling is
+        // requested here and not enabled globally.
+        for (;;) {
+            if (options?.signal?.aborted)
+                break;
+            let snapshot;
+            try {
+                snapshot = await pollOnce(workflowId, waitSeconds);
+                consecutiveFailures = 0;
+            }
+            catch (err) {
+                // A blip is not the end of a generation. `watch` owns the loop, so a
+                // single transport failure would otherwise kill a run that a
+                // caller-written retry loop used to survive.
+                consecutiveFailures += 1;
+                if (consecutiveFailures > maxRetries || Date.now() >= deadline) {
+                    setError(err);
+                    setStatus('error');
+                    throw err;
+                }
+                await sleep(interval, options?.signal);
+                continue;
+            }
+            last = snapshot;
+            setResult(snapshot);
+            // 🔴 `onUpdate` RECEIVES THE SNAPSHOT AS AN ARGUMENT AND MUST USE IT.
+            // `setResult` above is a React state update, so it is NOT visible to a
+            // callback reading the hook's `result` in this same tick — that reads
+            // the PREVIOUS render's value. The argument is the current one; the
+            // hook state catches up on the next render.
+            //
+            // A throw here propagates deliberately — swallowing a consumer's error
+            // would leave the loop spinning against a broken consumer.
+            options?.onUpdate?.(snapshot);
+            if (TERMINAL_STATUSES.has(snapshot.status)) {
+                setStatus('done');
+                return snapshot;
+            }
+            // Budget exhausted: resolve with what we have rather than throwing. A
+            // non-terminal result is a legitimate answer ("still running"), and the
+            // caller can tell the difference by reading `.status`.
+            if (Date.now() + interval >= deadline)
+                break;
+            await sleep(interval, options?.signal);
+        }
+        // Aborted or timed out with a snapshot in hand — resolve with it.
+        if (last)
+            return last;
+        // 🔴 NO SNAPSHOT AT ALL. Only reachable when the signal was ALREADY
+        // aborted on entry. Rejecting is the only honest option: there is nothing
+        // to resolve with, and issuing a poll here would make a request the
+        // caller explicitly asked us not to make.
+        const aborted = new Error(`watch(${workflowId}) aborted before any snapshot`);
+        aborted.name = 'AbortError';
+        throw aborted;
+    }, [pollOnce]);
     const cancel = useCallback(async (workflowId) => {
         try {
             const { snapshot } = await sendTypedRequest(getTransport(), { type: 'CANCEL_WORKFLOW', payload: { workflowId } }, 'WORKFLOW_CANCELED', { timeoutMs: WORKFLOW_REQUEST_TIMEOUT_MS });
@@ -124,6 +285,6 @@ export function useBuzzWorkflow() {
             throw err;
         }
     }, []);
-    return { estimate, submit, poll, cancel, status, result, error };
+    return { estimate, submit, poll, watch, cancel, status, result, error };
 }
 //# sourceMappingURL=useBuzzWorkflow.js.map

package/dist/hooks/useBuzzWorkflow.js.map

@@ -1 +1 @@
-{"version":3,"file":"useBuzzWorkflow.js","sourceRoot":"","sources":["../../src/hooks/useBuzzWorkflow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAI9C,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;;;GAIG;AACH,MAAM,iBAAiB,GAAiD,IAAI,GAAG,CAAC;IAC9E,WAAW;IACX,QAAQ;IACR,UAAU;IACV,SAAS;CACV,CAAC,CAAC;AAEH;;;;;;;;;;GAUG;AACH,MAAM,2BAA2B,GAAG,OAAO,CAAC;AAmB5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,UAAU,eAAe;IAC7B,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,QAAQ,CAAiB,MAAM,CAAC,CAAC;IAC7D,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,QAAQ,CAA+B,IAAI,CAAC,CAAC;IACzE,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAe,IAAI,CAAC,CAAC;IAEvD,MAAM,QAAQ,GAAG,WAAW,CAAC,KAAK,EAAE,IAAkB,EAAE,EAAE;QACxD,QAAQ,CAAC,IAAI,CAAC,CAAC;QACf,SAAS,CAAC,YAAY,CAAC,CAAC;QACxB,IAAI,CAAC;YACH,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,gBAAgB,CACzC,YAAY,EAAE,EACd,EAAE,IAAI,EAAE,mBAAmB,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,EAAE,EAChD,iBAAiB,EACjB,EAAE,SAAS,EAAE,2BAA2B,EAAE,CAC3C,CAAC;YACF,SAAS,CAAC,QAAQ,CAAC,CAAC;YACpB,SAAS,CAAC,YAAY,CAAC,CAAC;YACxB,OAAO,QAAQ,CAAC;QAClB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,QAAQ,CAAC,GAAY,CAAC,CAAC;YACvB,SAAS,CAAC,OAAO,CAAC,CAAC;YACnB,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,MAAM,MAAM,GAAG,WAAW,CAAC,KAAK,EAAE,IAAkB,EAAE,EAAE;QACtD,QAAQ,CAAC,IAAI,CAAC,CAAC;QACf,SAAS,CAAC,YAAY,CAAC,CAAC;QACxB,IAAI,CAAC;YACH,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,gBAAgB,CACzC,YAAY,EAAE,EACd,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,EAAE,EAC9C,oBAAoB,EACpB,EAAE,SAAS,EAAE,2BAA2B,EAAE,CAC3C,CAAC;YACF,SAAS,CAAC,QAAQ,CAAC,CAAC;YACpB,SAAS,CAAC,iBAAiB,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;YACvE,OAAO,QAAQ,CAAC;QAClB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,QAAQ,CAAC,GAAY,CAAC,CAAC;YACvB,SAAS,CAAC,OAAO,CAAC,CAAC;YACnB,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,EAAE,UAAkB,EAAE,EAAE;QACpD,SAAS,CAAC,SAAS,CAAC,CAAC;QACrB,IAAI,CAAC;YACH,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,gBAAgB,CACzC,YAAY,EAAE,EACd,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,EAAE,UAAU,EAAE,EAAE,EAClD,iBAAiB,EACjB,EAAE,SAAS,EAAE,2BAA2B,EAAE,CAC3C,CAAC;YACF,SAAS,CAAC,QAAQ,CAAC,CAAC;YACpB,IAAI,iBAAiB,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC3C,SAAS,CAAC,MAAM,CAAC,CAAC;YACpB,CAAC;YACD,OAAO,QAAQ,CAAC;QAClB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,QAAQ,CAAC,GAAY,CAAC,CAAC;YACvB,SAAS,CAAC,OAAO,CAAC,CAAC;YACnB,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,MAAM,MAAM,GAAG,WAAW,CAAC,KAAK,EAAE,UAAkB,EAAE,EAAE;QACtD,IAAI,CAAC;YACH,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,gBAAgB,CACzC,YAAY,EAAE,EACd,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,EAAE,UAAU,EAAE,EAAE,EACpD,mBAAmB,EACnB,EAAE,SAAS,EAAE,2BAA2B,EAAE,CAC3C,CAAC;YACF,SAAS,CAAC,QAAQ,CAAC,CAAC;YACpB,SAAS,CAAC,MAAM,CAAC,CAAC;YAClB,OAAO,QAAQ,CAAC;QAClB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,0EAA0E;YAC1E,sEAAsE;YACtE,sDAAsD;YACtD,QAAQ,CAAC,GAAY,CAAC,CAAC;YACvB,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AACnE,CAAC"}
+{"version":3,"file":"useBuzzWorkflow.js","sourceRoot":"","sources":["../../src/hooks/useBuzzWorkflow.ts"],"names":[],"mappings":"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"}

package/dist/hooks/useSaveImage.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Input to {@link UseSaveImage.saveImage}. Exactly ONE of `url` / `imageId` is
+ * required — the two variants map to the host's two download paths:
+ *
+ *  - `{ url }` — the block's OWN fresh output (e.g. an orchestration blob it has
+ *    no `imageId` for yet). The host ALLOWLISTS the URL's origin to the civitai
+ *    image/blob CDN and refuses an arbitrary host — a sandboxed block can't
+ *    coerce a host-side fetch of an attacker origin.
+ *  - `{ imageId }` — a cross-user grid image (e.g. a benchmark cell). The host
+ *    resolves it through the SAME per-viewer gated read that backs
+ *    `useGatedImages()`, so a withheld/above-ceiling image can never be saved.
+ */
+export type SaveImageInput = {
+    url: string;
+    imageId?: never;
+    filename?: string;
+} | {
+    imageId: number;
+    url?: never;
+    filename?: string;
+};
+export interface UseSaveImage {
+    /**
+     * Ask the host to DOWNLOAD an image the block already displays — the host
+     * fetches the blob in its unsandboxed top frame and triggers the browser
+     * "Save As". A sandboxed opaque-origin block lacks `allow-downloads`, so it
+     * otherwise can only copy a URL; this bridge is the only way to save a paid
+     * output. Resolves once the host has started the download; rejects with the
+     * host's error string on failure (a disallowed URL origin, a withheld image,
+     * an over-size blob, or a fetch failure), or the transport timeout — the hook
+     * never hangs.
+     */
+    saveImage: (input: SaveImageInput) => Promise<void>;
+}
+/**
+ * Download an image via the host-mediated `SAVE_IMAGE` → `SAVE_IMAGE_RESULT`
+ * bridge. See {@link SaveImageInput} for the url-vs-id security posture.
+ *
+ * @example
+ * const { saveImage } = useSaveImage();
+ * // block's own generation output (origin-allowlisted host-side):
+ * await saveImage({ url: output.url, filename: 'my-render.png' });
+ * // a cross-user grid cell (routed through the gated per-viewer read):
+ * await saveImage({ imageId: cell.imageId });
+ */
+export declare function useSaveImage(): UseSaveImage;
+//# sourceMappingURL=useSaveImage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useSaveImage.d.ts","sourceRoot":"","sources":["../../src/hooks/useSaveImage.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAExD,MAAM,WAAW,YAAY;IAC3B;;;;;;;;;OASG;IACH,SAAS,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACrD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,IAAI,YAAY,CAiB3C"}

package/dist/hooks/useSaveImage.js

@@ -0,0 +1,27 @@
+import { useCallback } from 'react';
+import { getTransport } from '../internal/singleton.js';
+import { sendTypedRequest } from '../internal/transport.js';
+/**
+ * Download an image via the host-mediated `SAVE_IMAGE` → `SAVE_IMAGE_RESULT`
+ * bridge. See {@link SaveImageInput} for the url-vs-id security posture.
+ *
+ * @example
+ * const { saveImage } = useSaveImage();
+ * // block's own generation output (origin-allowlisted host-side):
+ * await saveImage({ url: output.url, filename: 'my-render.png' });
+ * // a cross-user grid cell (routed through the gated per-viewer read):
+ * await saveImage({ imageId: cell.imageId });
+ */
+export function useSaveImage() {
+    const saveImage = useCallback(async (input) => {
+        const payload = 'url' in input && input.url !== undefined
+            ? { url: input.url, filename: input.filename }
+            : { imageId: input.imageId, filename: input.filename };
+        const reply = await sendTypedRequest(getTransport(), { type: 'SAVE_IMAGE', payload }, 'SAVE_IMAGE_RESULT');
+        if (!reply.ok || reply.error) {
+            throw new Error(reply.error ?? 'failed to save image');
+        }
+    }, []);
+    return { saveImage };
+}
+//# sourceMappingURL=useSaveImage.js.map

package/dist/hooks/useSaveImage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSaveImage.js","sourceRoot":"","sources":["../../src/hooks/useSaveImage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAEpC,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAgC5D;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,SAAS,GAAG,WAAW,CAAC,KAAK,EAAE,KAAqB,EAAiB,EAAE;QAC3E,MAAM,OAAO,GACX,KAAK,IAAI,KAAK,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS;YACvC,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE;YAC9C,CAAC,CAAC,EAAE,OAAO,EAAG,KAA6B,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC;QACpF,MAAM,KAAK,GAAG,MAAM,gBAAgB,CAClC,YAAY,EAAE,EACd,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,EAC/B,mBAAmB,CACpB,CAAC;QACF,IAAI,CAAC,KAAK,CAAC,EAAE,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,KAAK,CAAC,KAAK,IAAI,sBAAsB,CAAC,CAAC;QACzD,CAAC;IACH,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,OAAO,EAAE,SAAS,EAAE,CAAC;AACvB,CAAC"}

package/dist/hooks/useSharedStorage.d.ts

@@ -20,6 +20,14 @@ export interface SharedListItem {
     count: number;
     createdAt: Date;
     updatedAt: Date;
+    /**
+     * Whether the current viewer has an active up-vote on this entry — hydrate the
+     * vote-button state from this on load instead of guessing (fixes the
+     * "double-click to unvote" bug). Anonymous viewers are always `false`. Defaults
+     * to `false` when talking to an older host that doesn't send it, so a new block
+     * on an old host degrades to today's behavior.
+     */
+    viewerVoted: boolean;
 }
 export interface SharedListResult {
     items: SharedListItem[];
@@ -36,6 +44,24 @@ export interface UseSharedStorage {
         limit?: number;
         cursor?: string;
     }): Promise<SharedListResult>;
+    /**
+     * Fetch ONE entry by its key — the single-row companion to {@link list} for
+     * resolving a `?g=<key>` deep-link to an item past the first page. Resolves
+     * with the full {@link SharedListItem} (incl. `count`/`viewerVoted`) or `null`
+     * when the key is missing / hidden (a withdrawn or moderated row is never
+     * leaked). Respects the same per-viewer visibility as `list`. Rejects with the
+     * host's `error` string on host-side failure.
+     */
+    get(key: string): Promise<SharedListItem | null>;
+    /**
+     * Report a posted entry for moderator review — the post-write abuse seam for a
+     * shared board. `reason` is optional free text. Resolves once the report is
+     * filed; rejects with the host's `error` string on failure (`NOT_FOUND` for a
+     * missing key, a trust/scope rejection, or when the viewer is anonymous).
+     * Filing a report does not hide the row — a moderator decides. Gated by the
+     * same `apps:storage:shared:write` trust boundary as {@link append}.
+     */
+    report(key: string, reason?: string): Promise<void>;
     /** Current vote total for a single entry (`0` when the key isn't present). */
     getCount(key: string): Promise<number>;
     /**
@@ -83,30 +109,5 @@ export interface UseSharedStorage {
         deleted: boolean;
     }>;
 }
-/**
- * App-scoped, append-only, community-votable SHARED datastore. Sibling of
- * {@link useAppStorage} (the per-viewer KV store) — same postMessage bridge,
- * same request/await/correlate-by-requestId mechanism — but the scope is the
- * APP (every viewer sees the same list) and entries are structured
- * `{ title, body? }` records that any viewer can vote on.
- *
- * Calls flow through the host's postMessage bridge; the block never sees the
- * datastore credentials and never sends its block token (the host injects both
- * the token and the viewer identity). Anonymous viewers get a read path (`list`
- * / `getCount(s)`) and a hard reject on mutations (`append`/`vote`/`unvote`/
- * `withdraw`).
- *
- * The hook is stable across renders — it returns the same object identity once
- * the transport singleton is created, so it's safe in `useEffect`/`useMemo`
- * dependency arrays.
- *
- * @example
- * const shared = useSharedStorage();
- * const { key } = await shared.append({ title: 'Add dark mode', body: '…' });
- * 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
- */
 export declare function useSharedStorage(): UseSharedStorage;
 //# sourceMappingURL=useSharedStorage.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"useSharedStorage.d.ts","sourceRoot":"","sources":["../../src/hooks/useSharedStorage.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAKlE;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,kBAAkB,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,iBAAiB,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,IAAI,CAAC,IAAI,CAAC,EAAE;QACV,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC9B,8EAA8E;IAC9E,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACvC;;;OAGG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC3D;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC3D;;;;;;;;;OASG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D;;;OAGG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACnC;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACrC;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACnE;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,gBAAgB,IAAI,gBAAgB,CAkGnD"}
+{"version":3,"file":"useSharedStorage.d.ts","sourceRoot":"","sources":["../../src/hooks/useSharedStorage.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAyB,MAAM,yBAAyB,CAAC;AAKzF;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,kBAAkB,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,iBAAiB,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;IAChB;;;;;;OAMG;IACH,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,IAAI,CAAC,IAAI,CAAC,EAAE;QACV,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC9B;;;;;;;OAOG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IACjD;;;;;;;OAOG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,8EAA8E;IAC9E,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACvC;;;OAGG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC3D;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC3D;;;;;;;;;OASG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D;;;OAGG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACnC;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACrC;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACnE;AA8CD,wBAAgB,gBAAgB,IAAI,gBAAgB,CA8GnD"}