@civitai/blocks-react 0.63.2 → 0.65.0

package/dist/hooks/usePrepareTrainingDataset.d.ts

@@ -0,0 +1,99 @@
+import type { BlockPrepareTrainingDatasetHostError, BlockTrainingDatasetItem, BlockTrainingDatasetResult, BlockTrainingRejectionReason } from '@civitai/app-sdk/blocks';
+import type { ConsentRetryOptions } from './consentRetryOptions.js';
+export type { BlockPrepareTrainingDatasetHostError, BlockTrainingDatasetItem, BlockTrainingDatasetResult, BlockTrainingRejectionReason, };
+/**
+ * The host's CLOSED refusal codes for `PREPARE_TRAINING_DATASET`, as a runtime
+ * list. Mirrors civitai/civitai's `PREPARE_TRAINING_DATASET_HOST_ERRORS`.
+ *
+ * 🔴 THE ERROR CHANNEL IS NOT AN ENUM: it also carries free-text server
+ * messages, so "is this a code?" is a membership question at runtime — see
+ * {@link isPrepareTrainingDatasetErrorCode}.
+ */
+export declare const PREPARE_TRAINING_DATASET_ERROR_CODES: readonly ["review-mode", "block is not ready", "sign in to train", "invalid training dataset", "no block token"];
+/** `true` when `error` is one of the host's closed refusal codes rather than a server message. */
+export declare function isPrepareTrainingDatasetErrorCode(error: string): error is BlockPrepareTrainingDatasetHostError;
+/**
+ * A dataset-preparation failure.
+ *
+ * `.code` is the host's refusal code when the HOST refused, `undefined` for a
+ * server message or a transport timeout. Check `.timedOut` before rendering
+ * `.message` — a timeout's message is an SDK-internal string.
+ *
+ * Preparing charges nothing, so no failure here costs the viewer Buzz.
+ */
+export declare class PrepareTrainingDatasetError extends Error {
+    /** The closed host refusal code, or `undefined` for a server/transport error. */
+    readonly code?: BlockPrepareTrainingDatasetHostError;
+    /**
+     * No reply arrived within the bound. The server may still have prepared a
+     * dataset; nothing was charged either way, and preparing again simply makes a
+     * new handle.
+     */
+    readonly timedOut: boolean;
+    /**
+     * There is no session — the viewer is signed out (`sign in to train`), or their
+     * session ended (a bare `UNAUTHORIZED`). Route into `useRequestSignIn()`.
+     */
+    readonly signInRequired: boolean;
+    constructor(error: string, opts?: {
+        timedOut?: boolean;
+    });
+}
+/** What {@link usePrepareTrainingDataset} returns. */
+export interface UsePrepareTrainingDataset {
+    /**
+     * Ask the host to prepare a training dataset from the viewer's OWN images.
+     * Resolves with the opaque `datasetId`, the admitted `count` and the
+     * `rejected` images. REJECTS with a {@link PrepareTrainingDatasetError}.
+     *
+     * A resolved result admitted AT LEAST ONE image (`count >= 1`) — when nothing
+     * is admitted the server refuses instead, and this rejects with its message
+     * (`none of the requested images can be used for training` / `… could be
+     * prepared for training`, no `.code`). Read `rejected` for what was left out:
+     * `pending-scan` and `import-unavailable` are retryable; the rest are not.
+     * The per-image reasons are not available when everything was rejected.
+     */
+    prepareDataset: (items: BlockTrainingDatasetItem[], options?: ConsentRetryOptions) => Promise<BlockTrainingDatasetResult>;
+    /** `true` while a request is in flight. */
+    pending: boolean;
+    /** The last request's failure, or `null`. Cleared at the start of the next call. */
+    error: PrepareTrainingDatasetError | null;
+}
+/**
+ * Step 1 of the App Blocks `kind: 'training'` flow: turn the viewer's own images
+ * and your captions into a dataset handle for `WorkflowBodyTraining.datasetId`,
+ * through the host-mediated `PREPARE_TRAINING_DATASET` → `TRAINING_DATASET_RESULT`
+ * bridge.
+ *
+ * 🔴 AVAILABILITY: page apps only, behind the host flag `app-blocks-training-kind`
+ * (ships off), with `ai:write:budgeted` declared in the manifest and granted by a
+ * signed-in viewer. Refused from `dev:live` and from review sessions — build the
+ * flow against the mock host. See `WorkflowBodyTraining` in `@civitai/app-sdk`.
+ *
+ * Only the viewer's OWN scanned, unflagged images within the page's maturity
+ * ceiling are admitted; captions are moderated. Bounds: 1–50 items, captions up
+ * to 1,000 characters (`BLOCK_TRAINING_DATASET_MAX_ITEMS`,
+ * `BLOCK_TRAINING_CAPTION_MAX_CHARS`); the host refuses anything else with
+ * `invalid training dataset` before calling the server.
+ *
+ * No dialog and no charge. When the token lacks `ai:write:budgeted`, the call
+ * opens the host's consent prompt and retries once on a grant (opt out with
+ * `{ autoRequestConsent: false }`).
+ *
+ * Sent under the 120s server-work bound, not the 30s protocol default: the server
+ * imports up to 50 images into the orchestrator within its own 60s budget.
+ *
+ * @example
+ * const { prepareDataset } = usePrepareTrainingDataset();
+ * try {
+ *   const dataset = await prepareDataset(
+ *     picked.map((img) => ({ imageId: img.id, caption: img.caption })),
+ *   );
+ *   if (dataset.rejected.length > 0) showNotice(`${dataset.rejected.length} image(s) left out`);
+ * } catch (e) {
+ *   // Includes "none of the requested images can be used for training".
+ *   if (e instanceof PrepareTrainingDatasetError) showError(e.message);
+ * }
+ */
+export declare function usePrepareTrainingDataset(): UsePrepareTrainingDataset;
+//# sourceMappingURL=usePrepareTrainingDataset.d.ts.map

package/dist/hooks/usePrepareTrainingDataset.js

@@ -0,0 +1,157 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { BLOCK_SCOPES } from '@civitai/app-sdk/blocks';
+import { withConsentRetry } from '../internal/withConsentRetry.js';
+import { WORKFLOW_REQUEST_TIMEOUT_MS } from '../transport/requestTimeouts.js';
+import { getTransport } from '../transport/singleton.js';
+import { RequestTimeoutError, sendTypedRequest } from '../transport/transport.js';
+/**
+ * The consent-gated scope the training flow requires — `ai:write:budgeted`. The
+ * server refuses a dataset request from a token without it (it is the spend
+ * scope, and preparing is gated exactly like the run it prepares for). From
+ * {@link BLOCK_SCOPES}, never a literal: a typo would make the automatic consent
+ * prompt silently do nothing.
+ */
+const TRAINING_SCOPES = [BLOCK_SCOPES.AI_WRITE_BUDGETED];
+/**
+ * The host's CLOSED refusal codes for `PREPARE_TRAINING_DATASET`, as a runtime
+ * list. Mirrors civitai/civitai's `PREPARE_TRAINING_DATASET_HOST_ERRORS`.
+ *
+ * 🔴 THE ERROR CHANNEL IS NOT AN ENUM: it also carries free-text server
+ * messages, so "is this a code?" is a membership question at runtime — see
+ * {@link isPrepareTrainingDatasetErrorCode}.
+ */
+export const PREPARE_TRAINING_DATASET_ERROR_CODES = [
+    'review-mode',
+    'block is not ready',
+    'sign in to train',
+    'invalid training dataset',
+    'no block token',
+];
+const CODE_SET = new Set(PREPARE_TRAINING_DATASET_ERROR_CODES);
+/** `true` when `error` is one of the host's closed refusal codes rather than a server message. */
+export function isPrepareTrainingDatasetErrorCode(error) {
+    return CODE_SET.has(error);
+}
+/**
+ * A dataset-preparation failure.
+ *
+ * `.code` is the host's refusal code when the HOST refused, `undefined` for a
+ * server message or a transport timeout. Check `.timedOut` before rendering
+ * `.message` — a timeout's message is an SDK-internal string.
+ *
+ * Preparing charges nothing, so no failure here costs the viewer Buzz.
+ */
+export class PrepareTrainingDatasetError extends Error {
+    /** The closed host refusal code, or `undefined` for a server/transport error. */
+    code;
+    /**
+     * No reply arrived within the bound. The server may still have prepared a
+     * dataset; nothing was charged either way, and preparing again simply makes a
+     * new handle.
+     */
+    timedOut;
+    /**
+     * There is no session — the viewer is signed out (`sign in to train`), or their
+     * session ended (a bare `UNAUTHORIZED`). Route into `useRequestSignIn()`.
+     */
+    signInRequired;
+    constructor(error, opts) {
+        super(error);
+        this.name = 'PrepareTrainingDatasetError';
+        this.timedOut = opts?.timedOut === true;
+        if (isPrepareTrainingDatasetErrorCode(error))
+            this.code = error;
+        this.signInRequired = error === 'sign in to train' || error === 'UNAUTHORIZED';
+    }
+}
+/**
+ * Step 1 of the App Blocks `kind: 'training'` flow: turn the viewer's own images
+ * and your captions into a dataset handle for `WorkflowBodyTraining.datasetId`,
+ * through the host-mediated `PREPARE_TRAINING_DATASET` → `TRAINING_DATASET_RESULT`
+ * bridge.
+ *
+ * 🔴 AVAILABILITY: page apps only, behind the host flag `app-blocks-training-kind`
+ * (ships off), with `ai:write:budgeted` declared in the manifest and granted by a
+ * signed-in viewer. Refused from `dev:live` and from review sessions — build the
+ * flow against the mock host. See `WorkflowBodyTraining` in `@civitai/app-sdk`.
+ *
+ * Only the viewer's OWN scanned, unflagged images within the page's maturity
+ * ceiling are admitted; captions are moderated. Bounds: 1–50 items, captions up
+ * to 1,000 characters (`BLOCK_TRAINING_DATASET_MAX_ITEMS`,
+ * `BLOCK_TRAINING_CAPTION_MAX_CHARS`); the host refuses anything else with
+ * `invalid training dataset` before calling the server.
+ *
+ * No dialog and no charge. When the token lacks `ai:write:budgeted`, the call
+ * opens the host's consent prompt and retries once on a grant (opt out with
+ * `{ autoRequestConsent: false }`).
+ *
+ * Sent under the 120s server-work bound, not the 30s protocol default: the server
+ * imports up to 50 images into the orchestrator within its own 60s budget.
+ *
+ * @example
+ * const { prepareDataset } = usePrepareTrainingDataset();
+ * try {
+ *   const dataset = await prepareDataset(
+ *     picked.map((img) => ({ imageId: img.id, caption: img.caption })),
+ *   );
+ *   if (dataset.rejected.length > 0) showNotice(`${dataset.rejected.length} image(s) left out`);
+ * } catch (e) {
+ *   // Includes "none of the requested images can be used for training".
+ *   if (e instanceof PrepareTrainingDatasetError) showError(e.message);
+ * }
+ */
+export function usePrepareTrainingDataset() {
+    const [pending, setPending] = useState(false);
+    const [error, setError] = useState(null);
+    // The consent wait can outlive the component; see `useCreatePostFromApp`.
+    const mountedRef = useRef(true);
+    useEffect(() => {
+        mountedRef.current = true;
+        return () => {
+            mountedRef.current = false;
+        };
+    }, []);
+    /** ONE round-trip + its result contract. Re-invoked verbatim on a consent retry. */
+    const prepareOnce = useCallback(async (items) => {
+        const reply = await sendTypedRequest(getTransport(), { type: 'PREPARE_TRAINING_DATASET', payload: { items } }, 'TRAINING_DATASET_RESULT', { timeoutMs: WORKFLOW_REQUEST_TIMEOUT_MS }).catch((err) => {
+            // Stamped INSIDE the closure `withConsentRetry` re-invokes, so its rule 4
+            // sees it: a 120s wait is not repeated behind a consent prompt.
+            if (err instanceof RequestTimeoutError) {
+                throw new PrepareTrainingDatasetError(err.message, { timedOut: true });
+            }
+            throw err instanceof Error ? err : new Error(String(err));
+        });
+        if (reply.error || !reply.result) {
+            // `||`, not `??`: the validator shape-checks `error`, so `''` is a valid
+            // reply that must not become an Error with an empty message. The
+            // fallback is deliberately NOT a host code — `invalid training dataset`
+            // would claim "nothing reached the server", which an empty error does
+            // not tell us.
+            throw new PrepareTrainingDatasetError(reply.error || 'training dataset could not be prepared');
+        }
+        return reply.result;
+    }, []);
+    const prepareDataset = useCallback(async (items, options) => {
+        if (mountedRef.current) {
+            setPending(true);
+            setError(null);
+        }
+        try {
+            return await withConsentRetry(getTransport(), TRAINING_SCOPES, () => prepareOnce(items), options, () => mountedRef.current);
+        }
+        catch (err) {
+            const wrapped = err instanceof PrepareTrainingDatasetError
+                ? err
+                : new PrepareTrainingDatasetError(err instanceof Error ? err.message : String(err));
+            if (mountedRef.current)
+                setError(wrapped);
+            throw wrapped;
+        }
+        finally {
+            if (mountedRef.current)
+                setPending(false);
+        }
+    }, [prepareOnce]);
+    return { prepareDataset, pending, error };
+}
+//# sourceMappingURL=usePrepareTrainingDataset.js.map

package/dist/hooks/usePublishGenerationOutputs.d.ts

@@ -49,6 +49,12 @@ export interface UsePublishGenerationOutputs {
  * a human the request carries {@link HUMAN_INTERACTION_TIMEOUT_MS}, not the
  * default protocol timeout.
  *
+ * `dev:live` refuses this bridge: publishing requires the viewer's signed-in
+ * civitai.com session, which the local harness does not have, so `publish()`
+ * rejects with a message saying so. Test publishing against the mock host —
+ * `createMockHost` or `Harness` from `@civitai/blocks-react/testing`, with the
+ * `publishImageIds` / `publishError` options.
+ *
  * @example
  * const { publish } = usePublishGenerationOutputs();
  * const imageIds = await publish({ workflowId: w.workflowId, imageIndexes: [0, 2] });

package/dist/hooks/usePublishGenerationOutputs.js

@@ -16,6 +16,12 @@ import { sendTypedRequest } from '../transport/transport.js';
  * a human the request carries {@link HUMAN_INTERACTION_TIMEOUT_MS}, not the
  * default protocol timeout.
  *
+ * `dev:live` refuses this bridge: publishing requires the viewer's signed-in
+ * civitai.com session, which the local harness does not have, so `publish()`
+ * rejects with a message saying so. Test publishing against the mock host —
+ * `createMockHost` or `Harness` from `@civitai/blocks-react/testing`, with the
+ * `publishImageIds` / `publishError` options.
+ *
  * @example
  * const { publish } = usePublishGenerationOutputs();
  * const imageIds = await publish({ workflowId: w.workflowId, imageIndexes: [0, 2] });

package/dist/hooks/useRunTraining.d.ts

@@ -0,0 +1,151 @@
+import type { BlockRunTrainingHostError, BlockTrainingQuote, BlockWorkflowSnapshot, WorkflowBodyTraining } from '@civitai/app-sdk/blocks';
+export type { BlockRunTrainingHostError, BlockTrainingQuote, WorkflowBodyTraining };
+/**
+ * A training body ready to RUN: {@link WorkflowBodyTraining} with the `quoteId`
+ * its estimate returned. Required here so a body without one is a compile error
+ * rather than a host refusal.
+ */
+export type QuotedTrainingBody = WorkflowBodyTraining & {
+    quoteId: string;
+};
+/**
+ * The host's CLOSED refusal codes for `RUN_TRAINING`, as a runtime list. Mirrors
+ * civitai/civitai's `RUN_TRAINING_HOST_ERRORS`.
+ *
+ * 🔴 THE ERROR CHANNEL IS NOT AN ENUM: server messages (an expired or used quote,
+ * a body that differs from the quoted one) arrive in the same field — see
+ * {@link isRunTrainingErrorCode}.
+ */
+export declare const RUN_TRAINING_ERROR_CODES: readonly ["review-mode", "block is not ready", "sign in to train", "invalid training request", "no block token", "declined", "submission-unconfirmed"];
+/**
+ * The `code` a {@link RunTrainingError} can carry: one of the host's closed
+ * refusal codes, or `'refused'` — assigned by THIS SDK, never sent by the host,
+ * for a submit the server refused at a spend cap or as temporarily unavailable
+ * (see {@link RunTrainingError.refused}).
+ */
+export type RunTrainingErrorCode = BlockRunTrainingHostError | 'refused';
+/** `true` when `error` is one of the host's closed refusal codes rather than a server message. */
+export declare function isRunTrainingErrorCode(error: string): error is BlockRunTrainingHostError;
+/**
+ * A training run that did not come back with a snapshot.
+ *
+ * 🔴 READ THE FLAGS BEFORE SAYING ANYTHING ABOUT MONEY — they are the only part of
+ * this error with a money meaning, and they point in opposite directions:
+ *
+ *  - `.declined` — the viewer dismissed the consent dialog. NO RUN WAS
+ *    SUBMITTED, guaranteed by the host's consent latch. Render nothing.
+ *  - `.unconfirmed` — the run MAY BE RUNNING AND CHARGED: the host sent the
+ *    submit and could not learn its outcome (`submission-unconfirmed`), or no
+ *    reply arrived at all (`.timedOut` — the viewer may have clicked Train on a
+ *    dialog this block had stopped waiting for). Do NOT retry automatically and
+ *    do NOT tell the viewer it failed: check their trainings first
+ *    (`useAppWorkflows()` lists this app's runs), because re-running the same
+ *    body after the server did start it is a SECOND, separately charged run.
+ *  - `.refused` (`code: 'refused'`) — the server REFUSED the submit at a spend
+ *    cap after the viewer confirmed (the viewer's daily or private-run Buzz cap,
+ *    the per-app consent budget, the app's daily spend or rate limit, a dev
+ *    session cap). Its reservation was refunded: NO RUN, nothing charged.
+ *    `.message` is the server's reason (e.g. `daily Buzz cap reached: …`) and
+ *    `.snapshot` the refusal it arrived in. Retrying needs a new estimate and
+ *    usually a later time; buying Buzz does not lift these caps.
+ *  - `.signInRequired` — no session. Route into `useRequestSignIn()`.
+ *  - anything else — a refusal before any submit (an expired or used quote, a
+ *    body that no longer matches its quote, an ineligible image). Estimate again
+ *    before retrying; `.message` is the host's or server's text.
+ */
+export declare class RunTrainingError extends Error {
+    /**
+     * The closed host refusal code, `'refused'` for a cap refusal, or `undefined`
+     * for a server/transport error.
+     */
+    readonly code?: RunTrainingErrorCode;
+    /**
+     * The server refused the submit (a spend cap, or a temporary-availability deny)
+     * and refunded it — no run exists. The quote is used up: estimate again.
+     * See the class docs; `.message` is the server's reason.
+     */
+    readonly refused: boolean;
+    /** The refusal snapshot the host replied with, when {@link refused}. */
+    readonly snapshot?: BlockWorkflowSnapshot;
+    /** The viewer dismissed the consent dialog — no run was submitted. */
+    readonly declined: boolean;
+    /**
+     * The run may exist and may have been charged — `submission-unconfirmed`, or a
+     * transport timeout. Check the viewer's trainings before retrying.
+     */
+    readonly unconfirmed: boolean;
+    /** No reply arrived within the 10-minute consent bound. Implies {@link unconfirmed}. */
+    readonly timedOut: boolean;
+    /** There is no session (`sign in to train`, or a bare `UNAUTHORIZED`). */
+    readonly signInRequired: boolean;
+    constructor(error: string, opts?: {
+        timedOut?: boolean;
+        refusedSnapshot?: BlockWorkflowSnapshot;
+    });
+}
+/** What {@link useRunTraining} returns. */
+export interface UseRunTraining {
+    /**
+     * Ask the host to run a quoted training body. Civitai shows the viewer a
+     * consent dialog with the server's price and details; on their click it
+     * submits, and this resolves with the submitted workflow's snapshot — poll it
+     * with `useBuzzWorkflow().watch(snapshot.workflowId)`.
+     *
+     * REJECTS with a {@link RunTrainingError} — including `declined` (no run),
+     * `refused` (a spend-cap or temporary-availability refusal; no run) and
+     * `unconfirmed` (a run may
+     * exist). Read the flags before rendering anything. A resolved snapshot is
+     * always a submitted run with a pollable `workflowId`.
+     */
+    runTraining: (body: QuotedTrainingBody) => Promise<BlockWorkflowSnapshot>;
+    /** `true` while a request is in flight (including the viewer's dialog). */
+    pending: boolean;
+    /** The last request's failure, or `null`. Cleared at the start of the next call. */
+    error: RunTrainingError | null;
+}
+/**
+ * Run an App Blocks `kind: 'training'` LoRA training — the only way one starts —
+ * through the host-mediated `RUN_TRAINING` → `TRAINING_RESULT` bridge.
+ *
+ * 🔴 AVAILABILITY: page apps only, behind the host flag `app-blocks-training-kind`
+ * (ships off), with `ai:write:budgeted` declared and granted by a signed-in
+ * viewer. Refused from `dev:live` and from review sessions — build the flow
+ * against the mock host. See `WorkflowBodyTraining` in `@civitai/app-sdk`.
+ *
+ * The flow: `usePrepareTrainingDataset()` → `useBuzzWorkflow().estimate(body)`
+ * (its `trainingQuote.quoteId`) → `runTraining({ ...body, quoteId })` →
+ * `useBuzzWorkflow().watch(workflowId)`. Change nothing in the body between the
+ * estimate and the run: the server checks it against the quoted one.
+ *
+ * 🔴 THE CONSENT DIALOG IS CIVITAI'S, AND IT IS THE CHARGE. Every number on it is
+ * read back from the server's stored quote — never from your body. A run may cost
+ * more than the token's per-call budget (the viewer confirms the exact price), up
+ * to `BLOCK_TRAINING_MAX_BUZZ_PER_RUN` (5,000 Buzz). Images are the viewer's own.
+ *
+ * 🔴 NO AUTOMATIC CONSENT RETRY, unlike the other consent-gated hooks — on
+ * purpose. `RUN_TRAINING` carries no idempotency key and has an outcome
+ * (`submission-unconfirmed`) where a run may exist, so this hook never re-sends.
+ * It is also unreachable in practice: a block holding a `quoteId` got it from an
+ * estimate that already required `ai:write:budgeted`.
+ *
+ * Sent under the 10-minute human-interaction bound: the host replies only when
+ * the viewer clicks or dismisses its dialog.
+ *
+ * @example
+ * const { estimate, watch } = useBuzzWorkflow();
+ * const { runTraining } = useRunTraining();
+ * const quote = (await estimate(body)).trainingQuote!;
+ * try {
+ *   const started = await runTraining({ ...body, quoteId: quote.quoteId });
+ *   await watch(started.workflowId, { onUpdate: render });
+ * } catch (e) {
+ *   if (!(e instanceof RunTrainingError)) throw e;
+ *   if (e.declined) return;                          // no run — say nothing
+ *   if (e.signInRequired) return requestSignIn();
+ *   if (e.unconfirmed) return showCheckYourTrainings(); // may be running — never auto-retry
+ *   if (e.refused) return showError(e.message); // a cap / availability refusal; no run, nothing charged
+ *   showError('Could not start training. Get a new price and try again.');
+ * }
+ */
+export declare function useRunTraining(): UseRunTraining;
+//# sourceMappingURL=useRunTraining.d.ts.map

package/dist/hooks/useRunTraining.js

@@ -0,0 +1,212 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { HUMAN_INTERACTION_TIMEOUT_MS } from '../transport/requestTimeouts.js';
+import { getTransport } from '../transport/singleton.js';
+import { RequestTimeoutError, sendTypedRequest } from '../transport/transport.js';
+/**
+ * The host's CLOSED refusal codes for `RUN_TRAINING`, as a runtime list. Mirrors
+ * civitai/civitai's `RUN_TRAINING_HOST_ERRORS`.
+ *
+ * 🔴 THE ERROR CHANNEL IS NOT AN ENUM: server messages (an expired or used quote,
+ * a body that differs from the quoted one) arrive in the same field — see
+ * {@link isRunTrainingErrorCode}.
+ */
+export const RUN_TRAINING_ERROR_CODES = [
+    'review-mode',
+    'block is not ready',
+    'sign in to train',
+    'invalid training request',
+    'no block token',
+    'declined',
+    'submission-unconfirmed',
+];
+const CODE_SET = new Set(RUN_TRAINING_ERROR_CODES);
+/**
+ * The `workflowId` the host's training submit stamps on a snapshot that is NOT a
+ * run — its cap refusals resolve `{ workflowId: 'failed', status: 'failed', cost,
+ * error }` (`submitTrainingWorkflow` in civitai/civitai `blocks.router.ts`).
+ * Compared with `===`: a real orchestrator id is a workflow that may exist.
+ */
+const HOST_REFUSAL_WORKFLOW_ID = 'failed';
+/** `true` when `error` is one of the host's closed refusal codes rather than a server message. */
+export function isRunTrainingErrorCode(error) {
+    return CODE_SET.has(error);
+}
+/**
+ * A training run that did not come back with a snapshot.
+ *
+ * 🔴 READ THE FLAGS BEFORE SAYING ANYTHING ABOUT MONEY — they are the only part of
+ * this error with a money meaning, and they point in opposite directions:
+ *
+ *  - `.declined` — the viewer dismissed the consent dialog. NO RUN WAS
+ *    SUBMITTED, guaranteed by the host's consent latch. Render nothing.
+ *  - `.unconfirmed` — the run MAY BE RUNNING AND CHARGED: the host sent the
+ *    submit and could not learn its outcome (`submission-unconfirmed`), or no
+ *    reply arrived at all (`.timedOut` — the viewer may have clicked Train on a
+ *    dialog this block had stopped waiting for). Do NOT retry automatically and
+ *    do NOT tell the viewer it failed: check their trainings first
+ *    (`useAppWorkflows()` lists this app's runs), because re-running the same
+ *    body after the server did start it is a SECOND, separately charged run.
+ *  - `.refused` (`code: 'refused'`) — the server REFUSED the submit at a spend
+ *    cap after the viewer confirmed (the viewer's daily or private-run Buzz cap,
+ *    the per-app consent budget, the app's daily spend or rate limit, a dev
+ *    session cap). Its reservation was refunded: NO RUN, nothing charged.
+ *    `.message` is the server's reason (e.g. `daily Buzz cap reached: …`) and
+ *    `.snapshot` the refusal it arrived in. Retrying needs a new estimate and
+ *    usually a later time; buying Buzz does not lift these caps.
+ *  - `.signInRequired` — no session. Route into `useRequestSignIn()`.
+ *  - anything else — a refusal before any submit (an expired or used quote, a
+ *    body that no longer matches its quote, an ineligible image). Estimate again
+ *    before retrying; `.message` is the host's or server's text.
+ */
+export class RunTrainingError extends Error {
+    /**
+     * The closed host refusal code, `'refused'` for a cap refusal, or `undefined`
+     * for a server/transport error.
+     */
+    code;
+    /**
+     * The server refused the submit (a spend cap, or a temporary-availability deny)
+     * and refunded it — no run exists. The quote is used up: estimate again.
+     * See the class docs; `.message` is the server's reason.
+     */
+    refused;
+    /** The refusal snapshot the host replied with, when {@link refused}. */
+    snapshot;
+    /** The viewer dismissed the consent dialog — no run was submitted. */
+    declined;
+    /**
+     * The run may exist and may have been charged — `submission-unconfirmed`, or a
+     * transport timeout. Check the viewer's trainings before retrying.
+     */
+    unconfirmed;
+    /** No reply arrived within the 10-minute consent bound. Implies {@link unconfirmed}. */
+    timedOut;
+    /** There is no session (`sign in to train`, or a bare `UNAUTHORIZED`). */
+    signInRequired;
+    constructor(error, opts) {
+        super(error);
+        this.name = 'RunTrainingError';
+        this.timedOut = opts?.timedOut === true;
+        this.refused = opts?.refusedSnapshot !== undefined;
+        if (opts?.refusedSnapshot !== undefined) {
+            this.code = 'refused';
+            this.snapshot = opts.refusedSnapshot;
+        }
+        else if (isRunTrainingErrorCode(error)) {
+            this.code = error;
+        }
+        this.declined = error === 'declined';
+        this.unconfirmed = this.timedOut || error === 'submission-unconfirmed';
+        this.signInRequired = error === 'sign in to train' || error === 'UNAUTHORIZED';
+    }
+}
+/**
+ * Run an App Blocks `kind: 'training'` LoRA training — the only way one starts —
+ * through the host-mediated `RUN_TRAINING` → `TRAINING_RESULT` bridge.
+ *
+ * 🔴 AVAILABILITY: page apps only, behind the host flag `app-blocks-training-kind`
+ * (ships off), with `ai:write:budgeted` declared and granted by a signed-in
+ * viewer. Refused from `dev:live` and from review sessions — build the flow
+ * against the mock host. See `WorkflowBodyTraining` in `@civitai/app-sdk`.
+ *
+ * The flow: `usePrepareTrainingDataset()` → `useBuzzWorkflow().estimate(body)`
+ * (its `trainingQuote.quoteId`) → `runTraining({ ...body, quoteId })` →
+ * `useBuzzWorkflow().watch(workflowId)`. Change nothing in the body between the
+ * estimate and the run: the server checks it against the quoted one.
+ *
+ * 🔴 THE CONSENT DIALOG IS CIVITAI'S, AND IT IS THE CHARGE. Every number on it is
+ * read back from the server's stored quote — never from your body. A run may cost
+ * more than the token's per-call budget (the viewer confirms the exact price), up
+ * to `BLOCK_TRAINING_MAX_BUZZ_PER_RUN` (5,000 Buzz). Images are the viewer's own.
+ *
+ * 🔴 NO AUTOMATIC CONSENT RETRY, unlike the other consent-gated hooks — on
+ * purpose. `RUN_TRAINING` carries no idempotency key and has an outcome
+ * (`submission-unconfirmed`) where a run may exist, so this hook never re-sends.
+ * It is also unreachable in practice: a block holding a `quoteId` got it from an
+ * estimate that already required `ai:write:budgeted`.
+ *
+ * Sent under the 10-minute human-interaction bound: the host replies only when
+ * the viewer clicks or dismisses its dialog.
+ *
+ * @example
+ * const { estimate, watch } = useBuzzWorkflow();
+ * const { runTraining } = useRunTraining();
+ * const quote = (await estimate(body)).trainingQuote!;
+ * try {
+ *   const started = await runTraining({ ...body, quoteId: quote.quoteId });
+ *   await watch(started.workflowId, { onUpdate: render });
+ * } catch (e) {
+ *   if (!(e instanceof RunTrainingError)) throw e;
+ *   if (e.declined) return;                          // no run — say nothing
+ *   if (e.signInRequired) return requestSignIn();
+ *   if (e.unconfirmed) return showCheckYourTrainings(); // may be running — never auto-retry
+ *   if (e.refused) return showError(e.message); // a cap / availability refusal; no run, nothing charged
+ *   showError('Could not start training. Get a new price and try again.');
+ * }
+ */
+export function useRunTraining() {
+    const [pending, setPending] = useState(false);
+    const [error, setError] = useState(null);
+    // This request can outlive the component by up to ten minutes (the dialog may
+    // stay open), so a `pending` toggled on an unmounted control is state nobody
+    // can clear.
+    const mountedRef = useRef(true);
+    useEffect(() => {
+        mountedRef.current = true;
+        return () => {
+            mountedRef.current = false;
+        };
+    }, []);
+    const runTraining = useCallback(async (body) => {
+        if (mountedRef.current) {
+            setPending(true);
+            setError(null);
+        }
+        try {
+            const reply = await sendTypedRequest(getTransport(), { type: 'RUN_TRAINING', payload: { body } }, 'TRAINING_RESULT', { timeoutMs: HUMAN_INTERACTION_TIMEOUT_MS }).catch((err) => {
+                if (err instanceof RequestTimeoutError) {
+                    throw new RunTrainingError(err.message, { timedOut: true });
+                }
+                throw err instanceof Error ? err : new Error(String(err));
+            });
+            if (reply.error || !reply.snapshot) {
+                // `||`, not `??`: `error: ''` is a shape-valid reply. Its fallback is the
+                // CAUTIOUS code — with neither a snapshot nor a reason, nothing says a
+                // run was not started, so the block must not be told it was safe to
+                // retry.
+                throw new RunTrainingError(reply.error || 'submission-unconfirmed');
+            }
+            // 🔴 A RESOLVED SNAPSHOT IS NOT ALWAYS A RUN. The host's training submit
+            // answers its spend-cap and temporary-availability refusals (refunded,
+            // nothing started) with a
+            // resolved `{ workflowId: 'failed', status: 'failed', cost, error }`.
+            // Resolving that would hand the caller a workflow id to `watch()` that
+            // names nothing, and drop the reason. Exact match on the host's
+            // sentinel: a failed snapshot with a REAL id is a workflow that may
+            // exist, and keeps resolving so it can be watched.
+            if (reply.snapshot.workflowId === HOST_REFUSAL_WORKFLOW_ID &&
+                reply.snapshot.status === 'failed') {
+                throw new RunTrainingError(reply.snapshot.error || 'training run refused', {
+                    refusedSnapshot: reply.snapshot,
+                });
+            }
+            return reply.snapshot;
+        }
+        catch (err) {
+            const wrapped = err instanceof RunTrainingError
+                ? err
+                : new RunTrainingError(err instanceof Error ? err.message : String(err));
+            if (mountedRef.current)
+                setError(wrapped);
+            // Thrown even when unmounted: the caller's `await` must still learn the
+            // outcome of a possibly-charged run.
+            throw wrapped;
+        }
+        finally {
+            if (mountedRef.current)
+                setPending(false);
+        }
+    }, []);
+    return { runTraining, pending, error };
+}
+//# sourceMappingURL=useRunTraining.js.map

package/dist/index.d.ts

@@ -67,6 +67,10 @@ export { useCollectionFollow, CollectionFollowError, COLLECTION_FOLLOW_ERROR_COD
 export type { UseCollectionFollow } from './hooks/useCollectionFollow.js';
 export { useCreatePostFromApp, CreatePostError, CREATE_POST_ERROR_CODES, isCreatePostErrorCode, } from './hooks/useCreatePostFromApp.js';
 export type { UseCreatePostFromApp, BlockPostSource, BlockCreatePostRequest, BlockCreatePostResult, BlockCreatePostHostError, } from './hooks/useCreatePostFromApp.js';
+export { usePrepareTrainingDataset, PrepareTrainingDatasetError, PREPARE_TRAINING_DATASET_ERROR_CODES, isPrepareTrainingDatasetErrorCode, } from './hooks/usePrepareTrainingDataset.js';
+export type { UsePrepareTrainingDataset, BlockPrepareTrainingDatasetHostError, BlockTrainingDatasetItem, BlockTrainingDatasetResult, BlockTrainingRejectionReason, } from './hooks/usePrepareTrainingDataset.js';
+export { useRunTraining, RunTrainingError, RUN_TRAINING_ERROR_CODES, isRunTrainingErrorCode, } from './hooks/useRunTraining.js';
+export type { UseRunTraining, QuotedTrainingBody, RunTrainingErrorCode, BlockRunTrainingHostError, BlockTrainingQuote, WorkflowBodyTraining, } from './hooks/useRunTraining.js';
 export type { BlockBuzzTransaction, BlockBuzzAccount, BlockDailyCompensationResource, BlockWildcardPack, BlockWildcardPackErrorCode, AppWorkflow, AppWorkflowImage, AppWorkflowsParams, BlockGatedImage, BlockCollectionFollowErrorCode, BlockCollectionFollowResult, } from '@civitai/app-sdk/blocks';
 export { useCheckpointPicker } from './hooks/useCheckpointPicker.js';
 export type { UseCheckpointPicker } from './hooks/useCheckpointPicker.js';
@@ -98,6 +102,8 @@ export type { SfwGateProps } from './hooks/SfwGate.js';
 export { useDirectLoad } from './hooks/useDirectLoad.js';
 export type { UseDirectLoad, UseDirectLoadOptions } from './hooks/useDirectLoad.js';
 export { hostToRunUrl, DIRECT_LOAD_TIMEOUT_MS } from './transport/directLoad.js';
+export { useNestedDocument } from './hooks/useNestedDocument.js';
+export type { NestedDocumentStatus, UseNestedDocument, UseNestedDocumentOptions, } from './hooks/useNestedDocument.js';
 export { useAppStorage } from './hooks/useAppStorage.js';
 export type { AppStorageKeyEntry, AppStorageListResult, AppStorageQuota, UseAppStorage, } from './hooks/useAppStorage.js';
 export { useSharedStorage } from './hooks/useSharedStorage.js';