@civitai/blocks-react 0.67.1 → 0.69.0

package/dist/hooks/useBatchEstimate.d.ts

@@ -0,0 +1,191 @@
+import type { BlockEstimateBatchAggregate, BlockWorkflowSnapshot, WorkflowBody } from '@civitai/app-sdk/blocks';
+import { WorkflowEstimateError } from './useBuzzWorkflow.js';
+export type { BlockEstimateBatchAggregate };
+/**
+ * The most bodies one {@link UseBatchEstimate.estimateBatch} call may carry.
+ *
+ * The host's own cap (`BLOCK_ESTIMATE_BATCH_MAX_CELLS` in civitai/civitai). The
+ * hook refuses a longer list before sending it, with the code the host would
+ * have answered with a round trip later. A larger grid is priced in several
+ * calls; each call is still one request against the estimate allowance.
+ */
+export declare const BATCH_ESTIMATE_MAX_CELLS = 16;
+/**
+ * The host's `snapshot.error` for a batch cell its time budget ran out on before
+ * the cell priced. The copy is the host's (`BLOCK_ESTIMATE_BATCH_TIMEOUT_ERROR`
+ * in civitai/civitai `src/server/routers/blocks.router.ts`). This is the ONE
+ * place the SDK spells it: the hook maps it to {@link BatchEstimateCell}'s
+ * `timedOut`, and the mock host answers with it. Not exported from the package:
+ * apps branch on `timedOut`, never on this string.
+ */
+export declare const BATCH_ESTIMATE_CELL_TIMEOUT_ERROR = "estimate timed out";
+/**
+ * Why a WHOLE batch estimate was refused. The stable branch target on
+ * {@link BatchEstimateError}.
+ *
+ * - `'unsupported'` — the host answered `unsupported on this host`: it knows the
+ *   message and has no handler for it on this surface. Nothing was priced. **Fall
+ *   back to one `useBuzzWorkflow().estimate()` per cell.**
+ * - `'timeout'` — no reply arrived in time. A host that supports the message
+ *   bounds its own work and replies well inside the default wait, marking any
+ *   cell it could not price in time as an `ok: false` cell with `timedOut:
+ *   true`, so this code usually means the host or its upstream is SLOW, not
+ *   that it is old. 🔴 Do NOT fall back to per-cell estimates here:
+ *   that sends up to 16 more estimates at an upstream that is already struggling.
+ *   Show the estimate as unavailable and let the viewer retry later. A host that
+ *   predates the message also ends here (it never replies); an app that must
+ *   tell the two apart can probe once with a one-body batch and a short explicit
+ *   `timeoutMs`, and treat only THAT probe's `'timeout'` as "no batch support".
+ * - `'invalid-request'` — the list is empty, is not an array, or holds more than
+ *   {@link BATCH_ESTIMATE_MAX_CELLS} bodies. Refused by the hook before sending,
+ *   or by the host. A per-cell fallback is pointless for an empty list and is the
+ *   wrong fix for an over-long one: split it.
+ * - `'failed'` — the host or the server refused the call for another reason (the
+ *   scope, the rate limit, review preview, no credential) or returned something
+ *   that is not a batch result. The reason is on
+ *   {@link BatchEstimateError.hostError}.
+ */
+export type BatchEstimateErrorCode = 'unsupported' | 'timeout' | 'invalid-request' | 'failed';
+/**
+ * Thrown by {@link UseBatchEstimate.estimateBatch} when the WHOLE call failed.
+ *
+ * One cell failing is NOT this: a cell that could not be priced comes back as an
+ * `ok: false` entry in {@link BatchEstimateResult.cells} and the call resolves.
+ *
+ * Same three-audience split as `WorkflowEstimateError`:
+ * - {@link BatchEstimateError.code} is what you branch on.
+ * - {@link BatchEstimateError.hostError} is the host's or server's own text. It
+ *   is server-authored and unsanitised: log it, never render it.
+ * - `message` is a generic developer-facing summary whose wording is not a
+ *   contract.
+ */
+export declare class BatchEstimateError extends Error {
+    readonly code: BatchEstimateErrorCode;
+    /** The host's or server's reason, verbatim, when it gave one. */
+    readonly hostError?: string;
+    constructor(code: BatchEstimateErrorCode, hostError?: string);
+}
+/**
+ * One cell of a batch estimate — the answer to the body at the same index.
+ *
+ * - `ok: true` — the cell priced. `cost` is the cost object a single
+ *   `estimate()` returns for that body, passed through untouched (`cost.total`
+ *   is the price shown before `submit()`).
+ * - `ok: false` — the cell did not price. `error` is the SAME
+ *   `WorkflowEstimateError` a single `estimate()` of that body would have
+ *   rejected with (`code: 'failed' | 'no-cost'`, the reason on
+ *   `error.snapshot.error`), so one function can turn either into viewer copy.
+ *   It is a value here, not a throw: the other cells are still usable.
+ * - `timedOut` (on `ok: false` only) — `true` when the host's time budget for
+ *   the call ran out before this cell priced (its `error.code` is `'failed'`).
+ *   Show it as unavailable and retry later rather than re-estimating it at once.
+ *   Branch on `timedOut`, never on `snapshot.error`: the host's wording is not a
+ *   contract, and the hook maps it here so no app has to match it.
+ *
+ * `snapshot` is the host's snapshot for the cell, verbatim, on both arms.
+ */
+export type BatchEstimateCell = {
+    ok: true;
+    cost: NonNullable<BlockWorkflowSnapshot['cost']>;
+    snapshot: BlockWorkflowSnapshot;
+} | {
+    ok: false;
+    error: WorkflowEstimateError;
+    /** `true` when the host's time budget for the call ran out before this cell priced. */
+    timedOut: boolean;
+    snapshot: BlockWorkflowSnapshot;
+};
+/** What {@link UseBatchEstimate.estimateBatch} resolves with. */
+export interface BatchEstimateResult {
+    /** One entry per body, in the order the bodies were given. */
+    cells: BatchEstimateCell[];
+    /**
+     * The host's run total over the cells that priced. It covers the whole list
+     * only when `aggregate.pricedCells === aggregate.cellCount`.
+     */
+    aggregate: BlockEstimateBatchAggregate;
+}
+/** Options for one {@link UseBatchEstimate.estimateBatch} call. */
+export interface EstimateBatchOptions {
+    /**
+     * How long to wait for the host's reply, in milliseconds. Default
+     * `WORKFLOW_REQUEST_TIMEOUT_MS` (120,000), the single estimate's bound.
+     *
+     * A host that supports the batch replies within its own time budget, well
+     * inside this default, so leave it unset for ordinary pricing. Pass a short
+     * value only for a deliberate old-host probe (a one-body batch, sent once):
+     * a host that predates the message never replies, and a short wait finds that
+     * out sooner. A short wait on a full grid gives up on slow but healthy batches.
+     */
+    timeoutMs?: number;
+}
+/** What {@link useBatchEstimate} returns. */
+export interface UseBatchEstimate {
+    /**
+     * Price several workflow bodies in one request. Resolves with one cell per
+     * body, in order, plus a run total; rejects with {@link BatchEstimateError}
+     * only when the whole call failed.
+     *
+     * 🔴 ESTIMATE ONLY. Nothing is submitted and no Buzz is held or spent. Submit
+     * each cell with `useBuzzWorkflow().submit()`, which asks the viewer and
+     * checks the budget per cell.
+     */
+    estimateBatch: (bodies: WorkflowBody[], options?: EstimateBatchOptions) => Promise<BatchEstimateResult>;
+    /** `true` while the most recent call is in flight. */
+    pending: boolean;
+    /**
+     * The most recent call's result, or `null` before the first one and after a
+     * call that failed — a failed call never leaves an earlier total on display.
+     */
+    result: BatchEstimateResult | null;
+    /** The most recent call's error, or `null`. */
+    error: BatchEstimateError | null;
+}
+/**
+ * Price a grid of generations in ONE request: a list of workflow bodies in, one
+ * result per body (a cost, or that cell's error) plus a run total out. Backed by
+ * the `ESTIMATE_WORKFLOW_BATCH` → `ESTIMATE_BATCH_RESULT` bridge.
+ *
+ * Use it where an app would otherwise call `useBuzzWorkflow().estimate()` once
+ * per cell. Every rule a single estimate enforces still applies to each cell;
+ * what changes is the accounting and the round trips:
+ *
+ * - **One request against the estimate allowance**, whatever the number of
+ *   cells. On a page app that allowance is shared by every viewer of the app and
+ *   by the host's other reads for it, so a 16-cell grid used to take 16 of it per
+ *   pricing pass.
+ * - **Cells are metered separately.** The host also counts the cells of every
+ *   batch against an allowance of their own, shared like the estimate allowance
+ *   (on a page app, by every viewer of the app), so a batch is not a way around
+ *   it. A call over either is refused whole (`code: 'failed'`, the host's
+ *   rate-limit text on `hostError`); retry in a few seconds.
+ * - **At most {@link BATCH_ESTIMATE_MAX_CELLS} bodies per call.**
+ * - **`kind: 'training'` bodies are refused per cell.** Estimate a training run
+ *   with `useBuzzWorkflow().estimate()`.
+ *
+ * 🔴 ESTIMATE ONLY. There is no batch submit and no server-side id for the
+ * list. To watch and cancel the submitted cells together, use
+ * `useWorkflowBatch()`. The total is a quote: nothing reserves it and each cell
+ * is priced again at `submit()`.
+ *
+ * Like `estimate()`, this does NOT prompt for consent. It needs the
+ * `ai:write:budgeted` scope; without it the call rejects with `code: 'failed'`.
+ *
+ * @example
+ * const { estimateBatch } = useBatchEstimate();
+ * try {
+ *   const { cells, aggregate } = await estimateBatch(bodies);
+ *   // cells[i] answers bodies[i]; a cell with `!c.ok && c.timedOut` was not
+ *   // priced in time — show it as unavailable and retry later
+ * } catch (err) {
+ *   if (!(err instanceof BatchEstimateError)) throw err;
+ *   if (err.code === 'unsupported') {
+ *     // this host has no batch estimate — price each cell with estimate()
+ *   } else {
+ *     // 'timeout' (a slow host, not an old one) or 'failed': show the estimate
+ *     // as unavailable and retry later — never one estimate() per cell
+ *   }
+ * }
+ */
+export declare function useBatchEstimate(): UseBatchEstimate;
+//# sourceMappingURL=useBatchEstimate.d.ts.map

package/dist/hooks/useBatchEstimate.js

@@ -0,0 +1,196 @@
+import { useCallback, useState } from 'react';
+import { WORKFLOW_REQUEST_TIMEOUT_MS } from '../transport/requestTimeouts.js';
+import { getTransport } from '../transport/singleton.js';
+import { RequestTimeoutError, sendTypedRequest } from '../transport/transport.js';
+import { WorkflowEstimateError } from './useBuzzWorkflow.js';
+import { useRequestSequencer } from './useRequestSequencer.js';
+/**
+ * The most bodies one {@link UseBatchEstimate.estimateBatch} call may carry.
+ *
+ * The host's own cap (`BLOCK_ESTIMATE_BATCH_MAX_CELLS` in civitai/civitai). The
+ * hook refuses a longer list before sending it, with the code the host would
+ * have answered with a round trip later. A larger grid is priced in several
+ * calls; each call is still one request against the estimate allowance.
+ */
+export const BATCH_ESTIMATE_MAX_CELLS = 16;
+/**
+ * The host's generic reply to a request it registers no handler for. The copy is
+ * the host's (`BRIDGE_NACK_NO_HANDLER` in civitai/civitai), matched here ONCE so
+ * no app has to match it: branch on {@link BatchEstimateError.code} instead.
+ */
+const HOST_UNSUPPORTED_REPLY = 'unsupported on this host';
+/**
+ * The host's `snapshot.error` for a batch cell its time budget ran out on before
+ * the cell priced. The copy is the host's (`BLOCK_ESTIMATE_BATCH_TIMEOUT_ERROR`
+ * in civitai/civitai `src/server/routers/blocks.router.ts`). This is the ONE
+ * place the SDK spells it: the hook maps it to {@link BatchEstimateCell}'s
+ * `timedOut`, and the mock host answers with it. Not exported from the package:
+ * apps branch on `timedOut`, never on this string.
+ */
+export const BATCH_ESTIMATE_CELL_TIMEOUT_ERROR = 'estimate timed out';
+/**
+ * Thrown by {@link UseBatchEstimate.estimateBatch} when the WHOLE call failed.
+ *
+ * One cell failing is NOT this: a cell that could not be priced comes back as an
+ * `ok: false` entry in {@link BatchEstimateResult.cells} and the call resolves.
+ *
+ * Same three-audience split as `WorkflowEstimateError`:
+ * - {@link BatchEstimateError.code} is what you branch on.
+ * - {@link BatchEstimateError.hostError} is the host's or server's own text. It
+ *   is server-authored and unsanitised: log it, never render it.
+ * - `message` is a generic developer-facing summary whose wording is not a
+ *   contract.
+ */
+export class BatchEstimateError extends Error {
+    code;
+    /** The host's or server's reason, verbatim, when it gave one. */
+    hostError;
+    constructor(code, hostError) {
+        super(`batch estimate failed (${code})${hostError === undefined ? '' : ' — reason on .hostError'}`);
+        this.name = 'BatchEstimateError';
+        this.code = code;
+        if (hostError !== undefined)
+            this.hostError = hostError;
+    }
+}
+function toCell(snapshot) {
+    // The rule `useBuzzWorkflow().estimate()` applies to one reply, per cell.
+    if (snapshot.status === 'failed') {
+        return {
+            ok: false,
+            error: new WorkflowEstimateError(snapshot, 'failed'),
+            // The one place the host's per-cell timeout string is matched.
+            timedOut: snapshot.error === BATCH_ESTIMATE_CELL_TIMEOUT_ERROR,
+            snapshot,
+        };
+    }
+    const cost = snapshot.cost;
+    if (!cost || typeof cost.total !== 'number') {
+        return {
+            ok: false,
+            error: new WorkflowEstimateError(snapshot, 'no-cost'),
+            timedOut: false,
+            snapshot,
+        };
+    }
+    return { ok: true, cost, snapshot };
+}
+function toBatchEstimateError(err) {
+    if (err instanceof BatchEstimateError)
+        return err;
+    // Structural, not a message match — see `RequestTimeoutError`.
+    if (err instanceof RequestTimeoutError)
+        return new BatchEstimateError('timeout', err.message);
+    return new BatchEstimateError('failed', err instanceof Error ? err.message : String(err));
+}
+/**
+ * Price a grid of generations in ONE request: a list of workflow bodies in, one
+ * result per body (a cost, or that cell's error) plus a run total out. Backed by
+ * the `ESTIMATE_WORKFLOW_BATCH` → `ESTIMATE_BATCH_RESULT` bridge.
+ *
+ * Use it where an app would otherwise call `useBuzzWorkflow().estimate()` once
+ * per cell. Every rule a single estimate enforces still applies to each cell;
+ * what changes is the accounting and the round trips:
+ *
+ * - **One request against the estimate allowance**, whatever the number of
+ *   cells. On a page app that allowance is shared by every viewer of the app and
+ *   by the host's other reads for it, so a 16-cell grid used to take 16 of it per
+ *   pricing pass.
+ * - **Cells are metered separately.** The host also counts the cells of every
+ *   batch against an allowance of their own, shared like the estimate allowance
+ *   (on a page app, by every viewer of the app), so a batch is not a way around
+ *   it. A call over either is refused whole (`code: 'failed'`, the host's
+ *   rate-limit text on `hostError`); retry in a few seconds.
+ * - **At most {@link BATCH_ESTIMATE_MAX_CELLS} bodies per call.**
+ * - **`kind: 'training'` bodies are refused per cell.** Estimate a training run
+ *   with `useBuzzWorkflow().estimate()`.
+ *
+ * 🔴 ESTIMATE ONLY. There is no batch submit and no server-side id for the
+ * list. To watch and cancel the submitted cells together, use
+ * `useWorkflowBatch()`. The total is a quote: nothing reserves it and each cell
+ * is priced again at `submit()`.
+ *
+ * Like `estimate()`, this does NOT prompt for consent. It needs the
+ * `ai:write:budgeted` scope; without it the call rejects with `code: 'failed'`.
+ *
+ * @example
+ * const { estimateBatch } = useBatchEstimate();
+ * try {
+ *   const { cells, aggregate } = await estimateBatch(bodies);
+ *   // cells[i] answers bodies[i]; a cell with `!c.ok && c.timedOut` was not
+ *   // priced in time — show it as unavailable and retry later
+ * } catch (err) {
+ *   if (!(err instanceof BatchEstimateError)) throw err;
+ *   if (err.code === 'unsupported') {
+ *     // this host has no batch estimate — price each cell with estimate()
+ *   } else {
+ *     // 'timeout' (a slow host, not an old one) or 'failed': show the estimate
+ *     // as unavailable and retry later — never one estimate() per cell
+ *   }
+ * }
+ */
+export function useBatchEstimate() {
+    const [pending, setPending] = useState(false);
+    const [result, setResult] = useState(null);
+    const [error, setError] = useState(null);
+    // Latest call wins: an app re-prices on a form edit, so an older reply landing
+    // after a newer one must not put the older total back on display.
+    const sequencer = useRequestSequencer();
+    const estimateBatch = useCallback(async (bodies, options) => {
+        const call = sequencer.begin();
+        if (sequencer.isCurrent(call)) {
+            setPending(true);
+            setError(null);
+        }
+        try {
+            if (!Array.isArray(bodies) || bodies.length === 0) {
+                throw new BatchEstimateError('invalid-request', 'invalid estimate batch');
+            }
+            if (bodies.length > BATCH_ESTIMATE_MAX_CELLS) {
+                throw new BatchEstimateError('invalid-request', 'estimate batch too large');
+            }
+            const reply = await sendTypedRequest(getTransport(), { type: 'ESTIMATE_WORKFLOW_BATCH', payload: { bodies } }, 'ESTIMATE_BATCH_RESULT', 
+            // Server-bound like the single estimate, and slower: up to 16 cost
+            // quotes behind one reply.
+            { timeoutMs: options?.timeoutMs ?? WORKFLOW_REQUEST_TIMEOUT_MS });
+            if (reply.error !== undefined) {
+                if (reply.error === HOST_UNSUPPORTED_REPLY) {
+                    throw new BatchEstimateError('unsupported', reply.error);
+                }
+                if (reply.error === 'invalid estimate batch' ||
+                    reply.error === 'estimate batch too large') {
+                    throw new BatchEstimateError('invalid-request', reply.error);
+                }
+                throw new BatchEstimateError('failed', reply.error);
+            }
+            const { snapshots, aggregate } = reply;
+            if (!snapshots || !aggregate || snapshots.length !== bodies.length) {
+                // A reply that does not answer every body cannot be lined up with the
+                // grid, so it is refused rather than shown shifted by a cell.
+                throw new BatchEstimateError('failed', 'the host returned a malformed batch estimate');
+            }
+            const next = { cells: snapshots.map(toCell), aggregate };
+            if (sequencer.isCurrent(call))
+                setResult(next);
+            return next;
+        }
+        catch (err) {
+            const wrapped = toBatchEstimateError(err);
+            if (sequencer.isCurrent(call)) {
+                setError(wrapped);
+                // Fail closed: a confirm gate reading `result` must not keep quoting the
+                // previous list's total after this one failed.
+                setResult(null);
+            }
+            // Thrown even when superseded or unmounted — the caller's `await` is not
+            // the component.
+            throw wrapped;
+        }
+        finally {
+            if (sequencer.isCurrent(call))
+                setPending(false);
+        }
+    }, [sequencer]);
+    return { estimateBatch, pending, result, error };
+}
+//# sourceMappingURL=useBatchEstimate.js.map

package/dist/hooks/useBlockAnalytics.d.ts

@@ -1,15 +1,57 @@
 /** What {@link useBlockAnalytics} returns. */
 export interface UseBlockAnalytics {
+    /**
+     * Send one custom event. Fire-and-forget: returns nothing, and nothing tells
+     * you whether it was recorded. See {@link useBlockAnalytics}
+     * for what is kept.
+     */
     track: (eventName: string, properties?: Record<string, unknown>) => void;
 }
 /**
- * Fire-and-forget analytics tracking. The host forwards events to its
- * analytics pipeline (ClickHouse in production); the block doesn't see
- * acknowledgements and shouldn't block on them.
+ * Custom events for your app's analytics panel. Fire-and-forget: the host
+ * forwards the event and the block gets no acknowledgement, so never wait on
+ * one or branch on it.
+ *
+ * 🔴 **Only what your manifest DECLARES is recorded.** Declare every event, and
+ * every property it carries, under `analytics.events` in `block.manifest.json`.
+ * The declaration is reviewed with the rest of the manifest, and events are
+ * accepted against the APPROVED version:
+ *
+ * - **An undeclared event** is counted as dropped. Its name and properties are
+ *   not stored; the owner sees only a count of drops.
+ * - **A declared event keeps only its declared properties**, each only when the
+ *   value has the declared type. An undeclared property, or a value of the
+ *   wrong type, is dropped and the rest of the event is kept.
+ * - **Property types are `enum`, `number` and `boolean`.** There is no free-text
+ *   string: a string is kept only when it is one of the enum's declared values.
+ *   So a prompt, an email or a username cannot be recorded. A `number` is not
+ *   range-limited, so do not use one to carry an identifier.
+ * - Names are lowercase snake_case: a letter, then up to 63 of `a-z`, `0-9`, `_`.
+ *   At most 50 events per app and 10 properties per event.
+ *
+ * **Limits.** Each mount of your app may send at most 10 events per second and
+ * 500 in total; the host batches events into bodies of at most 32 KiB. An event
+ * over a limit is dropped in the browser and is not counted anywhere, so the
+ * panel's numbers are floors. Events are recorded only from the production
+ * site.
+ *
+ * **What owners see.** Aggregates in the app's analytics panel: per declared
+ * event, the count, unique signed-in viewers, and the declared properties'
+ * breakdowns. Signed-out viewers are counted as events but never identified,
+ * and the team's own activity is excluded by default. Individual events are
+ * never shown.
+ *
+ * **Check locally.** In `dev:live`, pass your manifest to `createLiveHost`
+ * (`createLiveHost({ blockToken, manifest })`) and the console warns once per
+ * undeclared event, undeclared property, or value of the wrong type.
  *
  * @example
+ * // block.manifest.json
+ * // "analytics": { "events": { "generate_clicked": { "properties": {
+ * //   "mode": { "type": "enum", "values": ["txt2img", "img2img"] },
+ * //   "batch": { "type": "number" } } } } }
  * const { track } = useBlockAnalytics();
- * track('generate_clicked', { modelId });
+ * track('generate_clicked', { mode: 'txt2img', batch: 4 });
  */
 export declare function useBlockAnalytics(): UseBlockAnalytics;
 //# sourceMappingURL=useBlockAnalytics.d.ts.map

package/dist/hooks/useBlockAnalytics.js

@@ -1,13 +1,50 @@
 import { useCallback } from 'react';
 import { getTransport } from '../transport/singleton.js';
 /**
- * Fire-and-forget analytics tracking. The host forwards events to its
- * analytics pipeline (ClickHouse in production); the block doesn't see
- * acknowledgements and shouldn't block on them.
+ * Custom events for your app's analytics panel. Fire-and-forget: the host
+ * forwards the event and the block gets no acknowledgement, so never wait on
+ * one or branch on it.
+ *
+ * 🔴 **Only what your manifest DECLARES is recorded.** Declare every event, and
+ * every property it carries, under `analytics.events` in `block.manifest.json`.
+ * The declaration is reviewed with the rest of the manifest, and events are
+ * accepted against the APPROVED version:
+ *
+ * - **An undeclared event** is counted as dropped. Its name and properties are
+ *   not stored; the owner sees only a count of drops.
+ * - **A declared event keeps only its declared properties**, each only when the
+ *   value has the declared type. An undeclared property, or a value of the
+ *   wrong type, is dropped and the rest of the event is kept.
+ * - **Property types are `enum`, `number` and `boolean`.** There is no free-text
+ *   string: a string is kept only when it is one of the enum's declared values.
+ *   So a prompt, an email or a username cannot be recorded. A `number` is not
+ *   range-limited, so do not use one to carry an identifier.
+ * - Names are lowercase snake_case: a letter, then up to 63 of `a-z`, `0-9`, `_`.
+ *   At most 50 events per app and 10 properties per event.
+ *
+ * **Limits.** Each mount of your app may send at most 10 events per second and
+ * 500 in total; the host batches events into bodies of at most 32 KiB. An event
+ * over a limit is dropped in the browser and is not counted anywhere, so the
+ * panel's numbers are floors. Events are recorded only from the production
+ * site.
+ *
+ * **What owners see.** Aggregates in the app's analytics panel: per declared
+ * event, the count, unique signed-in viewers, and the declared properties'
+ * breakdowns. Signed-out viewers are counted as events but never identified,
+ * and the team's own activity is excluded by default. Individual events are
+ * never shown.
+ *
+ * **Check locally.** In `dev:live`, pass your manifest to `createLiveHost`
+ * (`createLiveHost({ blockToken, manifest })`) and the console warns once per
+ * undeclared event, undeclared property, or value of the wrong type.
  *
  * @example
+ * // block.manifest.json
+ * // "analytics": { "events": { "generate_clicked": { "properties": {
+ * //   "mode": { "type": "enum", "values": ["txt2img", "img2img"] },
+ * //   "batch": { "type": "number" } } } } }
  * const { track } = useBlockAnalytics();
- * track('generate_clicked', { modelId });
+ * track('generate_clicked', { mode: 'txt2img', batch: 4 });
  */
 export function useBlockAnalytics() {
     const track = useCallback((eventName, properties) => {

package/dist/hooks/useBuzzWorkflow.d.ts

@@ -207,7 +207,10 @@ export declare class WorkflowEstimateError extends Error {
      * rather than on prose. It is the ONLY stable branch target here:
      * `snapshot.error` is server-authored and can change without notice, and
      * {@link WorkflowEstimateError.message} is a generic developer-facing summary
-     * whose exact wording is not a contract either.
+     * whose exact wording is not a contract either. The one carve-out is a batch
+     * cell the host's time budget ran out on: it keeps `code: 'failed'`, and its
+     * stable signal is `timedOut: true` on the `useBatchEstimate()` cell, never a
+     * match on `snapshot.error`.
      *
      * 🔴 THIS IS WHAT A VIEWER-FACING MESSAGE MUST BE DERIVED FROM. Branch on
      * `code` and return a string your app owns and localises; never render

package/dist/hooks/useBuzzWorkflow.js

@@ -191,7 +191,10 @@ export class WorkflowEstimateError extends Error {
      * rather than on prose. It is the ONLY stable branch target here:
      * `snapshot.error` is server-authored and can change without notice, and
      * {@link WorkflowEstimateError.message} is a generic developer-facing summary
-     * whose exact wording is not a contract either.
+     * whose exact wording is not a contract either. The one carve-out is a batch
+     * cell the host's time budget ran out on: it keeps `code: 'failed'`, and its
+     * stable signal is `timedOut: true` on the `useBatchEstimate()` cell, never a
+     * match on `snapshot.error`.
      *
      * 🔴 THIS IS WHAT A VIEWER-FACING MESSAGE MUST BE DERIVED FROM. Branch on
      * `code` and return a string your app owns and localises; never render