@civitai/blocks-react 0.63.2 → 0.65.0

package/README.md

@@ -111,6 +111,11 @@ writing: `useGatedImages()`, `usePublishGenerationOutputs()`, `useSaveImage()`,
 [`TipButton`](#the-ui-subexport) row documents the intended usage and the
 allowance-sharing rule. `useDirectLoad()` is covered under
 [Direct-load fallback](#direct-load-fallback-open-on-civitai) rather than here.
+**`dev:live` refuses `usePublishGenerationOutputs()`**: 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.
 
 ### `useBlockContext()`
 
@@ -724,11 +729,132 @@ async function share() {
 }
 ```
 
-In `dev:mock` the `createPostResult` / `createPostError` scenario knobs drive
-both arms (including `declined`). **`dev:live` refuses this bridge on purpose** —
+With the mock host — `createMockHost` or `Harness` from
+`@civitai/blocks-react/testing` — the `createPostResult` / `createPostError`
+options drive both arms (including `declined`). **`dev:live` refuses this bridge on purpose** —
 it has no civitai chrome to render the server-resolved confirm in, and driving
 the write without it would let dev prove out a flow production does not have.
 
+### `usePrepareTrainingDataset()` and `useRunTraining()` — LoRA training
+
+Train a LoRA with the ai-toolkit engine on the **viewer's own images**, from
+inside a page app — the App Blocks `kind: 'training'` flow. Four steps, three
+hooks:
+
+1. **Dataset** — `usePrepareTrainingDataset().prepareDataset([{ imageId, caption }])`
+   (`PREPARE_TRAINING_DATASET`). Only the viewer's own scanned, unflagged images
+   within the page's maturity ceiling are admitted; the rest come back in
+   `rejected` with a reason (`unavailable`, `unsupported-media`, `not-eligible`,
+   `pending-scan`, `import-failed`, `import-unavailable`; `pending-scan` and
+   `import-unavailable` are retryable). You get an opaque `datasetId` and the
+   admitted `count`, always at least 1 — if **nothing** is admitted the call
+   rejects with the server's message instead. 1–50 images, captions up to 1,000 characters; captions are
+   moderated. No dialog, no charge.
+2. **Quote** — `useBuzzWorkflow().estimate(body)` with a `WorkflowBodyTraining`
+   (`kind: 'training'`, no `quoteId`). The reply carries `trainingQuote:
+   { quoteId, total, imageCount, expiresAt }` — the orchestrator's own price for
+   exactly this run, stored server-side for 15 minutes.
+3. **Run** — `useRunTraining().runTraining({ ...body, quoteId })` (`RUN_TRAINING`).
+   **Civitai shows the viewer a consent dialog in its own chrome** — price, base
+   model, length and dataset size, all read back from the server, never from
+   your body — and submits only on their click. Change nothing in the body
+   between the estimate and the run; the server checks it against the quoted one.
+4. **Follow** — `useBuzzWorkflow().watch(workflowId)`. Once the run's moderation
+   status is approved, `trainedEpochs` lists the epochs whose checkpoint is
+   ready; send the viewer to the publish wizard with one of them (see
+   `trainedEpochs` on `BlockWorkflowSnapshot`).
+
+🔴 **Availability.** Behind the host flag **`app-blocks-training-kind`**, which
+ships **off** and is evaluated per viewer. **Page apps only** — the model slot
+answers both messages with an error. The manifest must declare
+**`ai:write:budgeted`** and the viewer must be signed in and have granted it.
+**Refused from `dev:live` and from review sessions** (the server refuses
+development and review tokens); build the flow against the mock host. Requires a
+civitai.com host carrying civitai/civitai#5434 (`kind: 'training'`,
+`RUN_TRAINING`) and civitai/civitai#5438 (`PREPARE_TRAINING_DATASET`).
+
+🔴 **Money.** There is no `maxBuzz` and no timeout knob — the price is the quote.
+A confirmed run may cost more than the token's per-call `buzzBudget` (the viewer
+confirms the exact price), up to `BLOCK_TRAINING_MAX_BUZZ_PER_RUN` (5,000 Buzz);
+an estimate above that is refused. `useBuzzWorkflow().submit()` **refuses** a
+training body before sending anything: only `RUN_TRAINING`'s dialog can confirm a
+quote, so a training run starts nowhere else.
+
+`runTraining` **rejects** with a `RunTrainingError`; read the flags before
+saying anything about money:
+
+| | meaning | what to do |
+|---|---|---|
+| `err.declined` | the viewer dismissed the dialog — **no run was submitted** | revert, say nothing |
+| `err.unconfirmed` | `submission-unconfirmed`, or no reply within the 10-min bound (`err.timedOut`) — the run **may be running and charged** | 🔴 **never retry automatically**: check the viewer's trainings first (`useAppWorkflows()` lists this app's runs). Re-running the same body after the server did start it is a **second, separately charged run** |
+| `err.refused` (`code: 'refused'`) | the server refused the submit after the viewer confirmed — a **spend cap** (their daily or private-run Buzz cap, the per-app consent budget, the app's daily spend or rate limit, a dev-session cap) or a **temporary-availability** deny. Refunded: **no run, nothing charged**; the quote is used up | show `err.message` (the server's reason, e.g. `daily Buzz cap reached: …`); estimate again before any retry — buying Buzz does not lift these caps |
+| `err.signInRequired` | no session | route into `useRequestSignIn()` |
+| `err.code` set otherwise | a host refusal (`review-mode` / `block is not ready` / `invalid training request` / `no block token`) | show or ignore per case |
+| `err.code === undefined`, no flag | a server refusal before any submit (expired or used quote, changed body, ineligible image) | estimate again, then retry |
+
+`prepareDataset` rejects with a `PrepareTrainingDatasetError` (`.code` for the
+host's refusals — `review-mode`, `block is not ready`, `sign in to train`,
+`invalid training dataset`, `no block token` — plus `.signInRequired` and
+`.timedOut`). Preparing charges nothing, so none of them cost Buzz. It prompts
+for `ai:write:budgeted` and retries once on a grant (see the table below);
+`runTraining` deliberately does not — it carries no idempotency key and has an
+outcome where a run may exist, so it never re-sends.
+
+```tsx
+const { prepareDataset } = usePrepareTrainingDataset();
+const { estimate, watch } = useBuzzWorkflow();
+const { runTraining } = useRunTraining();
+
+async function train(images: Array<{ id: number; caption: string }>) {
+  // Rejects (no `.code`) when NOTHING is admitted, e.g. "none of the requested
+  // images can be used for training"; a resolved dataset always has count >= 1.
+  const dataset = await prepareDataset(images.map((i) => ({ imageId: i.id, caption: i.caption })));
+  if (dataset.rejected.length > 0) showNotice(`${dataset.rejected.length} image(s) left out`);
+
+  const body: WorkflowBodyTraining = {
+    kind: 'training',
+    datasetId: dataset.datasetId,
+    engine: 'ai-toolkit',
+    model: baseModelKey, // a key from Civitai's training catalog
+    params: aiToolkitParams, // AiToolkitTrainingParams
+    triggerWord: 'mystyle',
+    samplePrompts: ['mystyle, a lighthouse at dusk'],
+  };
+  const quote = (await estimate(body)).trainingQuote;
+  if (!quote) return showError('No training price came back.');
+  // Show quote.total; the host's dialog will show the same number.
+
+  try {
+    const started = await runTraining({ ...body, quoteId: quote.quoteId });
+    const done = await watch(started.workflowId, { onUpdate: render });
+    setEpochs(done.trainedEpochs ?? []);
+  } catch (err) {
+    if (!(err instanceof RunTrainingError)) throw err;
+    if (err.declined) return; // no run
+    if (err.unconfirmed) return showCheckYourTrainings(); // may be running — never auto-retry
+    if (err.refused) return showError(err.message); // a cap / availability refusal; no run, nothing charged
+    if (err.signInRequired) return requestSignIn();
+    showError('Could not start training. Get a new price and try again.');
+  }
+}
+```
+
+With the mock host — `createMockHost` or `Harness` from
+`@civitai/blocks-react/testing` — the training path is **kind-faithful**: it
+holds the datasets it prepared and the quotes it stored, refuses an unknown
+dataset, a dataset with nothing admitted, a quote above 5,000 and a quote run
+twice, and needs
+`ai:write:budgeted` on the token and a signed-in viewer. Its knobs are
+`trainingDatasetRejected`, `trainingDatasetError`, `trainingQuoteTotal`,
+`runTrainingError` (`'declined'`, `'submission-unconfirmed'`, or any server
+message), `runTrainingCapRefusal` (the server's resolved cap / availability refusal, which consumes the quote →
+`err.refused`) and `generation.trainedEpochs` for the finished run. It has no
+consent dialog, so `runTraining` settles at once where the real host waits on a
+click, and it checks a run's body against its quote by `datasetId` only — the
+server compares the whole body.
+**`dev:live` refuses both bridges**, because the server refuses every training
+request from a dev token.
+
 ### `useAppWorkflows(params?)`
 
 The calling app's **own** generator subqueue — the tag-scoped list of generations
@@ -882,10 +1008,9 @@ ceiling that lands on `null` like everything else. Two earlier drafts of this
 section tried instead to enumerate the non-ceiling strings, and **both lists
 were short**; see the header of `blocks/appStorageErrors.ts` for what they
 missed and why no third list replaced them. `invalid block token` (an expired
-token mid-session), `block instance revoked` and `Apps are not enabled` are
-*illustrations* of what lands on `null`, never a bound on it. The practical
-consequence: `null` is a busy bucket, so see the `default` arm note below
-before writing copy for it.
+token mid-session) and `block instance revoked` are *illustrations* of what
+lands on `null`, never a bound on it. The practical consequence: `null` is a
+busy bucket, so see the `default` arm note below before writing copy for it.
 
 ⚠️ **The mock reaches four of the six.** It models no app-wide umbrella
 ([#368](https://github.com/civitai/civitai-app-starters/issues/368)), so
@@ -1222,6 +1347,7 @@ had just worked.
 |---|---|---|
 | `useBuzzWorkflow()` | `submit()` | `ai:write:budgeted` |
 | `useCreatePostFromApp()` | `createPost()` | `posts:write:self` |
+| `usePrepareTrainingDataset()` | `prepareDataset()` | `ai:write:budgeted` |
 | `useGoodPurchase()` | `purchase()` | `goods:purchase:self` |
 | `useTip()` | `tip()` | `social:tip:self` |
 
@@ -1506,6 +1632,62 @@ const directLoad = useDirectLoad();            // true iff top-level AND no BLOC
 const runUrl = hostToRunUrl('my-app.civit.ai'); // 'https://civitai.com/apps/run/my-app' | null (null = not a civit.ai host)
 ```
 
+## Embedding your own nested document
+
+🔴 **A nested `<iframe src="…">` pointing at your own bundled content cannot
+load, and no manifest change fixes it** — your block document's origin is opaque
+and the static host stamps `frame-ancestors` + `X-Frame-Options` on every path
+it serves. The full derivation, the dated external browser matrix (an
+observation of the platform — nothing in this repo verifies it) and the known
+limits
+live in one place: the header of `@civitai/app-sdk`'s
+`src/blocks/nestedDocument.ts`.
+
+**Prefer a single-document design.** An engine build (Defold, Unity WebGL,
+Phaser) is a `<canvas>` plus a JS loader that normally mounts straight into the
+document you hand it; point it at your block's own root element and the problem
+class disappears.
+
+When a separate document is genuinely required, fetch it and inline it as the
+iframe's `srcdoc` — a `srcdoc` frame inherits your opaque origin and carries no
+response headers, so neither policy applies:
+
+```tsx
+import { useNestedDocument } from '@civitai/blocks-react';
+
+function Game() {
+  const { srcDoc, status, error } = useNestedDocument({ src: '/game/index.html' });
+  if (status === 'error') return <p>Could not load: {error?.message}</p>;
+  if (status !== 'ready') return <p>Loading…</p>;
+  // Your own sandbox — the nested frame does not inherit the outer one's.
+  return <iframe title="game" sandbox="allow-scripts" srcDoc={srcDoc ?? undefined} />;
+}
+```
+
+`status` is `'idle'` (no `src`), `'loading'`, `'ready'` or `'error'`; `srcDoc` is
+non-null exactly when `ready`, `error` exactly when `error`. Changing `src`
+restarts the fetch and aborts the previous one — `status` returns to `'loading'`
+in the same render that changes `src`, so no frame ever shows the previous
+document as `'ready'` beside a new `src`. Unmounting aborts it and writes no
+state. The fetch has a **30-second deadline**: a response that never arrives
+becomes `status: 'error'` with a message naming the timeout, rather than
+`'loading'` forever.
+
+The helper injects an absolute `<base href="…/game/">` — the directory of the
+**response's final URL**, so a redirect is followed rather than resolved one
+directory too high — because a `srcdoc` document's base URL is `about:srcdoc`,
+inheriting yours, so relative asset loads would otherwise resolve to nothing. A
+document that already declares a `<base href>` has that one resolved against the
+final URL and replaced, so the base the parser uses is always absolute. It is
+**not** a de-duplication: markup declaring two `<base href>` tags comes back
+with two, the first (the only one a parser honours) rewritten and the second
+left inert. Only real markup counts — a `<base>` or a `<head>` inside a comment
+or an inline `<script>`/`<style>` body is ignored.
+
+**The string is not sanitized**, on purpose: it is your own markup and scripts,
+verbatim. Only pass a `src` you control. Outside React, `fetchNestedDocument`
+from `@civitai/app-sdk/blocks` is the same thing without the hook.
+
 ## The `/ui` subexport
 
 Opinionated components, imported separately so a transport-only block stays lean.

package/dist/hooks/useBuzzWorkflow.d.ts

@@ -1,5 +1,18 @@
 import type { BlockWorkflowSnapshot, WorkflowBody, WorkflowStatus } from '@civitai/app-sdk/blocks';
 import type { ConsentRetryOptions } from './consentRetryOptions.js';
+/**
+ * Why {@link UseBuzzWorkflow.submit} refuses a `kind: 'training'` body.
+ *
+ * 🔴 REFUSED BEFORE THE SEND, NOT LEFT TO THE SERVER. The server charges a
+ * training run only against a quote the viewer confirmed from a signed-in
+ * session, and only `RUN_TRAINING`'s host-chrome dialog can record that — so a
+ * `SUBMIT_WORKFLOW` carrying this body can never start a run. Refusing here
+ * turns a server round-trip ending in a confusing refusal into an immediate
+ * error that names the hook to use. Nothing is sent and nothing is spent, which
+ * is why it is a plain `Error` and not a {@link WorkflowSubmitError} (every code
+ * on that class is money-ambiguous by design).
+ */
+export declare const TRAINING_BODY_SUBMIT_REFUSAL = "useBuzzWorkflow.submit() does not run a kind:'training' body \u2014 estimate it here, then run it with useRunTraining().runTraining({ ...body, quoteId }). Nothing was sent.";
 /**
  * Default orchestrator-side hold per {@link UseBuzzWorkflow.watch} poll,
  * in SECONDS.
@@ -465,6 +478,10 @@ export interface UseBuzzWorkflow {
      * consent dialog with no user gesture behind it, once per edit. A missing
      * scope surfaces as an ordinary rejection; show no price and let `submit()`
      * do the asking.
+     *
+     * A `kind: 'training'` body's reply also carries
+     * {@link BlockWorkflowSnapshot.trainingQuote} — the `quoteId` to run it with
+     * through `useRunTraining()`.
      */
     estimate: (body: WorkflowBody) => Promise<BlockWorkflowSnapshot>;
     /**
@@ -512,6 +529,9 @@ export interface UseBuzzWorkflow {
      * `CONSENT_UNAVAILABLE` environment is never retried, and a second consent
      * failure reaches you unchanged. Opt out with
      * {@link ConsentRetryOptions.autoRequestConsent}`: false`.
+     *
+     * 🔴 A `kind: 'training'` BODY IS REFUSED before anything is sent — it runs
+     * only through `useRunTraining()`. See {@link TRAINING_BODY_SUBMIT_REFUSAL}.
      */
     submit: (body: WorkflowBody, options?: SubmitWorkflowOptions) => Promise<BlockWorkflowSnapshot>;
     /**

package/dist/hooks/useBuzzWorkflow.js

@@ -1,6 +1,7 @@
 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 { resolveIdempotencyKey, sendTypedRequest } from '../transport/transport.js';
 /**
@@ -16,6 +17,19 @@ import { resolveIdempotencyKey, sendTypedRequest } from '../transport/transport.
  * automatic prompt silently do nothing.
  */
 const WORKFLOW_SCOPES = [BLOCK_SCOPES.AI_WRITE_BUDGETED];
+/**
+ * Why {@link UseBuzzWorkflow.submit} refuses a `kind: 'training'` body.
+ *
+ * 🔴 REFUSED BEFORE THE SEND, NOT LEFT TO THE SERVER. The server charges a
+ * training run only against a quote the viewer confirmed from a signed-in
+ * session, and only `RUN_TRAINING`'s host-chrome dialog can record that — so a
+ * `SUBMIT_WORKFLOW` carrying this body can never start a run. Refusing here
+ * turns a server round-trip ending in a confusing refusal into an immediate
+ * error that names the hook to use. Nothing is sent and nothing is spent, which
+ * is why it is a plain `Error` and not a {@link WorkflowSubmitError} (every code
+ * on that class is money-ambiguous by design).
+ */
+export const TRAINING_BODY_SUBMIT_REFUSAL = "useBuzzWorkflow.submit() does not run a kind:'training' body — estimate it here, then run it with useRunTraining().runTraining({ ...body, quoteId }). Nothing was sent.";
 /**
  * Snapshot statuses that mean "no further polling is needed."
  * Used by both `submit` (a host can return an instant-fail / cached result)
@@ -27,18 +41,16 @@ const TERMINAL_STATUSES = new Set([
     'canceled',
     'expired',
 ]);
-/**
- * The workflow requests (estimate / submit / poll) are orchestrator-bound:
- * the host forwards them to the generation orchestrator and only replies
- * once it answers. `submit` is the slowest — server-side it does a whatif
- * cost-preflight AND the real submit (two orchestrator round-trips) plus a
- * prompt audit before responding, which legitimately exceeds the
- * transport's 30s `DEFAULT_REQUEST_TIMEOUT_MS` (tuned for fast bridge
- * messages) when the orchestrator queue is busy. Give these calls a
- * generous ceiling so a busy-but-healthy orchestrator doesn't surface as
- * a spurious `request "SUBMIT_WORKFLOW" timed out` rejection.
- */
-const WORKFLOW_REQUEST_TIMEOUT_MS = 120_000;
+// The workflow requests (estimate / submit / poll) are orchestrator-bound:
+// the host forwards them to the generation orchestrator and only replies
+// once it answers. `submit` is the slowest — server-side it does a whatif
+// cost-preflight AND the real submit (two orchestrator round-trips) plus a
+// prompt audit before responding, which legitimately exceeds the
+// transport's 30s `DEFAULT_REQUEST_TIMEOUT_MS` (tuned for fast bridge
+// messages) when the orchestrator queue is busy. `WORKFLOW_REQUEST_TIMEOUT_MS`
+// (imported above, from `transport/requestTimeouts.ts`) gives these calls a
+// generous ceiling so a busy-but-healthy orchestrator doesn't surface as a
+// spurious `request "SUBMIT_WORKFLOW" timed out` rejection.
 /**
  * Default orchestrator-side hold per {@link UseBuzzWorkflow.watch} poll,
  * in SECONDS.
@@ -720,6 +732,14 @@ export function useBuzzWorkflow() {
         return snapshot;
     }, []);
     const submit = useCallback(async (body, options) => {
+        // See `TRAINING_BODY_SUBMIT_REFUSAL`. Before the status flip, the key
+        // mint and the consent retry: nothing about this call may reach the wire.
+        if (body.kind === 'training') {
+            const refused = new Error(TRAINING_BODY_SUBMIT_REFUSAL);
+            setError(refused);
+            setStatus('error');
+            throw refused;
+        }
         setError(null);
         setStatus('submitting');
         // Idempotency: reuse a caller-supplied stable key across a retry (→ one Buzz

package/dist/hooks/useCreatePostFromApp.d.ts

@@ -58,8 +58,13 @@ export declare class CreatePostError extends Error {
      */
     readonly declined: boolean;
     /**
-     * There is no session. Route this into `useRequestSignIn()` rather than
-     * showing an error — the viewer's next step is signing in, not retrying.
+     * There is no session — the viewer is signed out (`sign in to post`), or
+     * their session ended, e.g. signed out in another tab (a bare
+     * `UNAUTHORIZED`). Route this into `useRequestSignIn()` rather than showing
+     * an error — the viewer's next step is signing in, not retrying.
+     *
+     * A session that now belongs to a different account is NOT this: `.message`
+     * asks the viewer to reload the page, and is safe to render.
      */
     readonly signInRequired: boolean;
     constructor(error: string, opts?: {

package/dist/hooks/useCreatePostFromApp.js

@@ -79,8 +79,13 @@ export class CreatePostError extends Error {
      */
     declined;
     /**
-     * There is no session. Route this into `useRequestSignIn()` rather than
-     * showing an error — the viewer's next step is signing in, not retrying.
+     * There is no session — the viewer is signed out (`sign in to post`), or
+     * their session ended, e.g. signed out in another tab (a bare
+     * `UNAUTHORIZED`). Route this into `useRequestSignIn()` rather than showing
+     * an error — the viewer's next step is signing in, not retrying.
+     *
+     * A session that now belongs to a different account is NOT this: `.message`
+     * asks the viewer to reload the page, and is safe to render.
      */
     signInRequired;
     constructor(error, opts) {
@@ -90,7 +95,7 @@ export class CreatePostError extends Error {
         if (isCreatePostErrorCode(error))
             this.code = error;
         this.declined = error === 'declined';
-        this.signInRequired = error === 'sign in to post';
+        this.signInRequired = error === 'sign in to post' || error === 'UNAUTHORIZED';
     }
 }
 /**

package/dist/hooks/useNestedDocument.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Where the fetch has got to. `idle` is the no-`src` state, not a
+ * pre-fetch tick: a mount WITH a `src` goes straight to `loading`.
+ */
+export type NestedDocumentStatus = 'idle' | 'loading' | 'ready' | 'error';
+/**
+ * What {@link useNestedDocument} returns. The three fields are driven from ONE
+ * state object, so they can never disagree: `srcDoc` is non-null exactly when
+ * `status === 'ready'`, and `error` is non-null exactly when
+ * `status === 'error'`.
+ */
+export interface UseNestedDocument {
+    /** The string to hand an iframe's `srcdoc`. Non-null iff `status === 'ready'`. */
+    srcDoc: string | null;
+    status: NestedDocumentStatus;
+    /** Non-null iff `status === 'error'`. A `NestedDocumentError` carries a `.code`. */
+    error: Error | null;
+}
+/** Options for {@link useNestedDocument}. */
+export interface UseNestedDocumentOptions {
+    /**
+     * The nested document to inline. Relative URLs resolve against `baseUrl`, or
+     * the current document. `undefined` or `''` keeps the hook `idle` and fetches
+     * nothing — the shape to use while you are still deciding what to embed.
+     */
+    src?: string | undefined;
+    /** Explicit base for resolving a relative `src`. */
+    baseUrl?: string | undefined;
+}
+/**
+ * Fetch one of your OWN bundled documents and get back a `srcdoc` string with
+ * an absolute `<base href>` injected — the only way a block can embed a nested
+ * document of its own.
+ *
+ * 🔴 PREFER NOT TO NEED THIS. A plain `<iframe src="/game/index.html">` of your
+ * own bundle **cannot load**, and no manifest change fixes it. An engine build
+ * (Defold, Unity, Phaser) is a `<canvas>` plus a JS loader and normally mounts
+ * directly into the block's own document, which avoids the whole problem class;
+ * reach for this hook only when a separate document is genuinely required.
+ *
+ * WHY, measured, in ONE place: the header of `@civitai/app-sdk`'s
+ * `src/blocks/nestedDocument.ts`. It carries the opaque-origin /
+ * `frame-ancestors` / `X-Frame-Options` derivation, the five-row DATED
+ * EXTERNAL platform matrix (verified by nothing in this repo — re-measure it if
+ * the platform's sandbox tiers or response headers change), and the known
+ * limits of the `<base>` rewrite. Do not restate any of it here: it was
+ * duplicated across 11 surfaces with nothing in the repo checking them for
+ * agreement, which is exactly how two measured claims in these files' own test
+ * headers went stale.
+ *
+ * 🔴 THE STRING IS NOT SANITIZED. It is your own markup and scripts, verbatim;
+ * pass a `src` you control, and put a `sandbox` attribute on the iframe.
+ *
+ * Changing `src` restarts the fetch and aborts the previous one — `status` goes
+ * back to `'loading'` in the SAME render that changes `src`, so no paint ever
+ * shows a stale `srcDoc` as `'ready'` beside a new `src`. Unmounting aborts the
+ * in-flight fetch, and no state is written after it.
+ *
+ * A fetch that never settles is bounded: after {@link NESTED_DOCUMENT_TIMEOUT_MS}
+ * it is aborted and `status` becomes `'error'` with a message naming the
+ * timeout. A timeout is distinguished from the hook's own aborts (unmount, a
+ * `src` change) — those stay silent, as they must.
+ *
+ * @example
+ * ```tsx
+ * const { srcDoc, status, error } = useNestedDocument({ src: '/game/index.html' });
+ * if (status === 'error') return <p>Could not load the game: {error?.message}</p>;
+ * if (status !== 'ready') return <p>Loading…</p>;
+ * return <iframe title="game" sandbox="allow-scripts" srcDoc={srcDoc ?? undefined} />;
+ * ```
+ */
+export declare function useNestedDocument(options?: UseNestedDocumentOptions): UseNestedDocument;
+//# sourceMappingURL=useNestedDocument.d.ts.map

package/dist/hooks/useNestedDocument.js

@@ -0,0 +1,160 @@
+import { useEffect, useState } from 'react';
+import { fetchNestedDocument } from '@civitai/app-sdk/blocks';
+const IDLE = { status: 'idle', srcDoc: null, error: null };
+const LOADING = { status: 'loading', srcDoc: null, error: null };
+/**
+ * How long the fetch is given before it is aborted and the hook reports an
+ * error. Without a deadline a stalled response leaves `status === 'loading'`
+ * FOREVER: the hook owns its `AbortController` and never exposes it, so a
+ * caller has nothing to cancel with and no timer of its own to hang one off.
+ *
+ * 30 seconds, equal to `transport/requestTimeouts.ts`'s
+ * `DEFAULT_REQUEST_TIMEOUT_MS` and to `useEntitlements`' `ENTITLEMENTS_TIMEOUT_MS`
+ * — this is a `'protocol'`-class wait in that file's vocabulary: a static-host
+ * round trip with NO PERSON IN THE LOOP, so `HUMAN_INTERACTION_TIMEOUT_MS` is
+ * the wrong bound. Declared locally rather than imported for the same reason
+ * `useEntitlements` declares its own: `DEFAULT_REQUEST_TIMEOUT_MS` documents the
+ * default of `IframeTransport.sendRequest`, and a `fetch` of a bundled document
+ * is not a bridge request. Equal by intent, not derived.
+ */
+const NESTED_DOCUMENT_TIMEOUT_MS = 30_000;
+/**
+ * Fetch one of your OWN bundled documents and get back a `srcdoc` string with
+ * an absolute `<base href>` injected — the only way a block can embed a nested
+ * document of its own.
+ *
+ * 🔴 PREFER NOT TO NEED THIS. A plain `<iframe src="/game/index.html">` of your
+ * own bundle **cannot load**, and no manifest change fixes it. An engine build
+ * (Defold, Unity, Phaser) is a `<canvas>` plus a JS loader and normally mounts
+ * directly into the block's own document, which avoids the whole problem class;
+ * reach for this hook only when a separate document is genuinely required.
+ *
+ * WHY, measured, in ONE place: the header of `@civitai/app-sdk`'s
+ * `src/blocks/nestedDocument.ts`. It carries the opaque-origin /
+ * `frame-ancestors` / `X-Frame-Options` derivation, the five-row DATED
+ * EXTERNAL platform matrix (verified by nothing in this repo — re-measure it if
+ * the platform's sandbox tiers or response headers change), and the known
+ * limits of the `<base>` rewrite. Do not restate any of it here: it was
+ * duplicated across 11 surfaces with nothing in the repo checking them for
+ * agreement, which is exactly how two measured claims in these files' own test
+ * headers went stale.
+ *
+ * 🔴 THE STRING IS NOT SANITIZED. It is your own markup and scripts, verbatim;
+ * pass a `src` you control, and put a `sandbox` attribute on the iframe.
+ *
+ * Changing `src` restarts the fetch and aborts the previous one — `status` goes
+ * back to `'loading'` in the SAME render that changes `src`, so no paint ever
+ * shows a stale `srcDoc` as `'ready'` beside a new `src`. Unmounting aborts the
+ * in-flight fetch, and no state is written after it.
+ *
+ * A fetch that never settles is bounded: after {@link NESTED_DOCUMENT_TIMEOUT_MS}
+ * it is aborted and `status` becomes `'error'` with a message naming the
+ * timeout. A timeout is distinguished from the hook's own aborts (unmount, a
+ * `src` change) — those stay silent, as they must.
+ *
+ * @example
+ * ```tsx
+ * const { srcDoc, status, error } = useNestedDocument({ src: '/game/index.html' });
+ * if (status === 'error') return <p>Could not load the game: {error?.message}</p>;
+ * if (status !== 'ready') return <p>Loading…</p>;
+ * return <iframe title="game" sandbox="allow-scripts" srcDoc={srcDoc ?? undefined} />;
+ * ```
+ */
+export function useNestedDocument(options) {
+    const src = options?.src;
+    const baseUrl = options?.baseUrl;
+    const [state, setState] = useState(src ? LOADING : IDLE);
+    // 🔴 RESET DURING RENDER, NOT IN THE EFFECT. The effect runs AFTER the commit,
+    // so between the render that changes `src` and the effect that sets `LOADING`
+    // the hook used to return the PREVIOUS document still labelled `'ready'` —
+    // one painted frame in which `(src, srcDoc)` disagree, and a consumer that
+    // keys an iframe off `src` would show the wrong document in it. This is
+    // React's documented "adjust state when a prop changes" pattern: the
+    // `setState` below re-renders this component immediately, before the browser
+    // paints, so the stale pair is never committed.
+    //
+    // The key carries BOTH inputs because both are effect dependencies. They are
+    // joined by a NUL rather than by a printable character: two distinct
+    // `(src, baseUrl)` pairs can only collide on one key if the separator itself
+    // occurs inside one of them, and a NUL is the byte least likely to appear in
+    // a URL anyone passes here. A collision would mean a missed reset, not a
+    // wrong document — the effect's own `[src, baseUrl]` deps still re-run it.
+    const key = `${src ?? ''}\u0000${baseUrl ?? ''}`;
+    const [stateKey, setStateKey] = useState(key);
+    let current = state;
+    if (stateKey !== key) {
+        setStateKey(key);
+        // 🔴 RETURNED FROM THIS PASS, not merely queued. React discards the JSX of
+        // a render that calls `setState` and retries, so queueing alone already
+        // keeps the stale pair off the screen — but it would still be the value
+        // this call RETURNS, which is the hook's contract and the thing a test can
+        // observe. Assigning locally makes every render consistent, committed or
+        // not.
+        current = src ? LOADING : IDLE;
+        // `IDLE`/`LOADING` are module constants, so when the effect sets the same
+        // one a moment later React bails out on reference equality.
+        setState(current);
+    }
+    useEffect(() => {
+        if (!src) {
+            setState(IDLE);
+            return;
+        }
+        // `cancelled` is belt AND braces alongside `abort()`: an abort only rejects
+        // a fetch that is still in flight, so a response that has already resolved
+        // can still land in a `.then` after unmount. Both are needed.
+        let cancelled = false;
+        // 🔴 A SEPARATE FLAG, NOT `controller.signal.aborted`. The timeout aborts
+        // THIS controller, and the `.catch` below drops anything whose signal is
+        // aborted — so a timeout wired to the same controller would be SWALLOWED
+        // and the hook would sit on `'loading'` exactly as it did with no timeout
+        // at all. The flag is what tells "the deadline passed" (report it) from
+        // "we unmounted / the src changed" (stay silent).
+        let timedOut = false;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, NESTED_DOCUMENT_TIMEOUT_MS);
+        setState(LOADING);
+        fetchNestedDocument({ src, baseUrl, signal: controller.signal })
+            .then((doc) => {
+            if (cancelled)
+                return;
+            setState({ status: 'ready', srcDoc: doc.srcDoc, error: null });
+        })
+            .catch((err) => {
+            if (cancelled)
+                return;
+            if (timedOut) {
+                setState({
+                    status: 'error',
+                    srcDoc: null,
+                    error: new Error(`useNestedDocument: fetching ${src} timed out after ` +
+                        `${NESTED_DOCUMENT_TIMEOUT_MS}ms.`),
+                });
+                return;
+            }
+            // Any OTHER abort is this hook's own cleanup, never something to
+            // surface: the component is gone, or a newer `src` already owns the
+            // state.
+            if (controller.signal.aborted)
+                return;
+            setState({
+                status: 'error',
+                srcDoc: null,
+                error: err instanceof Error ? err : new Error(String(err)),
+            });
+        })
+            .finally(() => {
+            clearTimeout(timeoutId);
+        });
+        return () => {
+            cancelled = true;
+            clearTimeout(timeoutId);
+            controller.abort();
+        };
+    }, [src, baseUrl]);
+    return current;
+}
+//# sourceMappingURL=useNestedDocument.js.map