@civitai/blocks-react 0.63.1 → 0.64.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,8 +729,9 @@ 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.
 
@@ -882,10 +888,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
@@ -1506,6 +1511,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.
@@ -1517,8 +1578,7 @@ Two surfaces live here:
 
 ### W6 component pack
 
-A drop-in set of primitives that match Civitai's look (8px radius, the blue
-primary, the dark/light surfaces) — **with zero setup**:
+A drop-in set of primitives that match Civitai's look — **with zero setup**:
 
 - **No Mantine dependency, no CSS import, no setup step.** The pack ships its
   CSS as a string and injects it into your block document's `<head>` the first
@@ -1532,8 +1592,8 @@ primary, the dark/light surfaces) — **with zero setup**:
 - **Auto-themed via your block's `data-theme`.** Set `data-theme={theme}` on
   your block's own root (from `useBlockContext().theme` — gotcha #60; the host
   can't reach across the iframe to set it for you). The components read an
-  ancestor `[data-theme='dark']` / `[data-theme='light']`; **no attribute =
-  light**, matching the starter palette.
+  ancestor `[data-theme='dark']` / `[data-theme='light']`; default (no
+  attribute) is the **dark** palette, and nothing consults the OS preference.
 
 ```tsx
 import { useRef } from 'react';

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

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/index.d.ts

@@ -98,6 +98,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';

package/dist/index.js

@@ -76,6 +76,10 @@ export { useDomainMaturity } from './hooks/useDomainMaturity.js';
 export { SfwGate } from './hooks/SfwGate.js';
 export { useDirectLoad } from './hooks/useDirectLoad.js';
 export { hostToRunUrl, DIRECT_LOAD_TIMEOUT_MS } from './transport/directLoad.js';
+// A block CANNOT frame its own bundled content by URL. This is the `srcdoc`
+// fallback; prefer a single-document design. Why, measured, in one place:
+// `@civitai/app-sdk`'s `src/blocks/nestedDocument.ts` header.
+export { useNestedDocument } from './hooks/useNestedDocument.js';
 export { useAppStorage } from './hooks/useAppStorage.js';
 export { useSharedStorage } from './hooks/useSharedStorage.js';
 //# sourceMappingURL=index.js.map

package/dist/internal/liveHost.d.ts

@@ -46,8 +46,8 @@
  * --- BEGIN DERIVED ---
  * fetch chokepoints ..... 2
  * REST endpoints ........ GET /api/v1/blocks/me
- * tRPC procedures ....... 29 = blocks.* (14) + apps.shared.* (10) + apps.storage.* (5)
- * switch case labels .... 45, of which 7 REFUSE (enumerated under SCOPE below)
+ * tRPC procedures ....... 28 = blocks.* (13) + apps.shared.* (10) + apps.storage.* (5)
+ * switch case labels .... 45, of which 8 REFUSE (enumerated under SCOPE below)
  * --- END DERIVED ---
  *
  * PICKERS (Phase 1 of "make dev:live a faithful local host"): the live host
@@ -101,6 +101,11 @@
  *     host-chrome consent. Replies `collection-unavailable`.
  *   • CREATE_POST_FROM_APP — needs the server-resolved preview plus host-chrome
  *     confirm before a PUBLIC post is written. Replies with a refusal.
+ *   • PUBLISH_GENERATION_OUTPUTS — publishing requires the viewer's signed-in
+ *     civitai.com session, which the local harness does not have; test
+ *     publishing against the mock host — `createMockHost` or `Harness` from
+ *     `@civitai/blocks-react/testing`, with the `publishImageIds` /
+ *     `publishError` options. Replies with a refusal.
  *   • GET_WILDCARD_PACK — needs the session-authed resolve plus the in-tab
  *     zip/yaml parse that lives in civitai, not this SDK. Replies `parse-failed`.
  *   • OPEN_IMAGE_UPLOAD — needs the host's native modal + session-authed byte

package/dist/internal/liveHost.js

@@ -46,8 +46,8 @@
  * --- BEGIN DERIVED ---
  * fetch chokepoints ..... 2
  * REST endpoints ........ GET /api/v1/blocks/me
- * tRPC procedures ....... 29 = blocks.* (14) + apps.shared.* (10) + apps.storage.* (5)
- * switch case labels .... 45, of which 7 REFUSE (enumerated under SCOPE below)
+ * tRPC procedures ....... 28 = blocks.* (13) + apps.shared.* (10) + apps.storage.* (5)
+ * switch case labels .... 45, of which 8 REFUSE (enumerated under SCOPE below)
  * --- END DERIVED ---
  *
  * PICKERS (Phase 1 of "make dev:live a faithful local host"): the live host
@@ -101,6 +101,11 @@
  *     host-chrome consent. Replies `collection-unavailable`.
  *   • CREATE_POST_FROM_APP — needs the server-resolved preview plus host-chrome
  *     confirm before a PUBLIC post is written. Replies with a refusal.
+ *   • PUBLISH_GENERATION_OUTPUTS — publishing requires the viewer's signed-in
+ *     civitai.com session, which the local harness does not have; test
+ *     publishing against the mock host — `createMockHost` or `Harness` from
+ *     `@civitai/blocks-react/testing`, with the `publishImageIds` /
+ *     `publishError` options. Replies with a refusal.
  *   • GET_WILDCARD_PACK — needs the session-authed resolve plus the in-tab
  *     zip/yaml parse that lives in civitai, not this SDK. Replies `parse-failed`.
  *   • OPEN_IMAGE_UPLOAD — needs the host's native modal + session-authed byte
@@ -1025,29 +1030,37 @@ export function createLiveHost(options) {
                         return;
                     }
                     case 'PUBLISH_GENERATION_OUTPUTS': {
-                        // Publish selected outputs of one of the app's OWN workflows as bare,
-                        // real-scanned public Image rows via the token-bound
-                        // `blocks.publishGenerationOutputs` MUTATION (POST). The block sends
-                        // `workflowId` + optional `imageIndexes` (NEVER urls); the host
-                        // re-derives ownership, re-uploads + FULL-scans server-side. Returns a
-                        // plain `{ imageIds }`, unwrapped with `callTrpcData`. FREE-TEXT error
-                        // on failure. Unroutable without requestId.
+                        // UNSUPPORTED in live, for the same reason as CREATE_POST_FROM_APP
+                        // above: publishing requires the viewer's signed-in civitai.com
+                        // session, which the local harness does not have — it holds a dev
+                        // block token and has no civitai chrome to render the publish
+                        // confirm in. On civitai.com the real host resolves the workflow's
+                        // outputs, shows that confirm, and only then publishes bare,
+                        // real-scanned public Image rows.
+                        //
+                        // FREE TEXT, like the post refusal: none of the host's codes is
+                        // honest about "this harness cannot do it". `usePublishGenerationOutputs`
+                        // rejects with it as the message. Test publishing against the mock
+                        // host — `createMockHost` or `Harness` from
+                        // `@civitai/blocks-react/testing`, with the `publishImageIds` /
+                        // `publishError` options.
                         if (!isRoutableRequestId(requestId))
                             return;
-                        void callTrpcData('blocks.publishGenerationOutputs', {
-                            blockToken: rawToken,
-                            workflowId: typed.payload?.workflowId,
-                            ...(typed.payload?.imageIndexes !== undefined
-                                ? { imageIndexes: typed.payload.imageIndexes }
-                                : {}),
-                            ...(typed.payload?.title !== undefined ? { title: typed.payload.title } : {}),
-                        }, 'POST').then((r) => {
-                            dispatchToBlock({
-                                type: 'PUBLISH_RESULT',
-                                payload: r.data
-                                    ? { requestId, result: r.data }
-                                    : { requestId, error: r.error ?? 'publish unavailable' },
-                            });
+                        logOnce('publish-outputs', 'PUBLISH_GENERATION_OUTPUTS is not supported in dev:live (publishing requires the ' +
+                            "viewer's signed-in civitai.com session, which the local harness does not have). " +
+                            'Replying with a refusal. Test publishing against the mock host — createMockHost ' +
+                            'or Harness from @civitai/blocks-react/testing, with the publishImageIds / ' +
+                            'publishError options.');
+                        dispatchToBlock({
+                            type: 'PUBLISH_RESULT',
+                            payload: {
+                                requestId,
+                                error: 'publishing generation outputs is not supported in dev:live — publishing ' +
+                                    "requires the viewer's signed-in civitai.com session, which the local harness " +
+                                    'does not have; test publishing against the mock host — createMockHost or ' +
+                                    'Harness from @civitai/blocks-react/testing, with the publishImageIds / ' +
+                                    'publishError options',
+                            },
                         });
                         return;
                     }

package/dist/internal/mockHost.d.ts

@@ -37,7 +37,7 @@
  * called). Only the postMessage bridge round-trips are exercised. Never import
  * this from production code.
  */
-import { type BlockContext, type BlockResourceInfo, type BlockResourcePickerType, type BlockUploadedImageInfo, type BlockGenerationSourceImageInfo, type BuzzAccountType, type BlockBuzzTransaction, type BlockBuzzAccount, type BlockDailyCompensationResource, type BlockViewer, type BlockWildcardPack, type BlockWildcardPackErrorCode, type AppWorkflow, type BlockGatedImage, type BlockCollectionFollowErrorCode, type BlockCreatePostHostError, type BlockCreatePostResult, type ColorDomain, type SharedStorageValue, type Theme, type ViewerInfo, type WorkflowBody } from '@civitai/app-sdk/blocks';
+import { type BlockContext, type BlockResourceInfo, type BlockResourcePickerType, type BlockUploadedImageInfo, type BlockGenerationSourceImageInfo, type BuzzAccountType, type BlockBuzzTransaction, type BlockBuzzAccount, type BlockDailyCompensationResource, type BlockViewer, type BlockWildcardPack, type BlockWildcardPackErrorCode, type AppWorkflow, type BlockPublishedModel, type BlockGatedImage, type BlockCollectionFollowErrorCode, type BlockCreatePostHostError, type BlockCreatePostResult, type ColorDomain, type SharedStorageValue, type Theme, type ViewerInfo, type WorkflowBody } from '@civitai/app-sdk/blocks';
 /**
  * How submits behave. `'none'` = everything succeeds; `'all'` / `'insufficient'`
  * = every submit RESOLVES an insufficient-Buzz `failed` snapshot, priced
@@ -178,6 +178,38 @@ export interface MockGenerationScenario {
      * {@link image} when both are set.
      */
     images?: string[] | ((req: WorkflowBody) => string[]);
+    /**
+     * How many trained epochs a succeeded PASS-THROUGH training step reports on
+     * {@link BlockWorkflowSnapshot.trainedEpochs} — epochs `1…n`, each tagged with
+     * the submitted `$type`. Applies only to a `{ kind: 'step', $type: 'training' }`
+     * or `'imageResourceTraining'` body; every other body is unaffected.
+     *
+     * Default `0`: the field is omitted, as the host omits it for a run that
+     * produced no checkpoint. Opt in with `n > 0` to simulate a finished run —
+     * it is off by default because a real run on this arm is bounded by the
+     * spend rules below, so a default success would promise what the host may
+     * not deliver.
+     *
+     * The mock never fabricates a checkpoint url: the block contract does not
+     * include one, so nothing here does either. A training snapshot's `imageUrls` stand for
+     * the run's SAMPLE images only (the same {@link image}/{@link images} knobs
+     * apply).
+     *
+     * 🔴 The real host's spend and timeout rules for this arm (see
+     * `WorkflowBodyPassThroughStep.maxBuzz` in `@civitai/app-sdk/blocks`) are
+     * NOT simulated: the mock neither quotes nor times out, so a success here
+     * says nothing about whether your run is quoted, what it costs, or whether
+     * it finishes.
+     */
+    trainedEpochs?: number;
+    /**
+     * When set, a succeeded pass-through training snapshot also carries this as
+     * {@link BlockWorkflowSnapshot.publishedModel} — simulating a run the viewer
+     * has started (`published: false`) or finished (`published: true`) publishing
+     * through the model wizard. Default: unset (field omitted). For the app-queue
+     * read, put `publishedModel` on the rows you pass as `appWorkflows`.
+     */
+    trainingPublishedModel?: BlockPublishedModel;
 }
 /**
  * BUZZ scenario controls — simulate a balance so the insufficient-Buzz / top-up

package/dist/internal/mockHost.js

@@ -112,6 +112,15 @@ const BUDGETED_SCOPE = 'ai:write:budgeted';
 const DEFAULT_STORAGE_QUOTA_BYTES = APP_STORAGE_MAX_BYTES;
 const DEFAULT_STORAGE_VALUE_CAP_BYTES = APP_STORAGE_MAX_VALUE_BYTES;
 const DEFAULT_STORAGE_LIMIT_ROWS = APP_STORAGE_MAX_ROWS;
+/**
+ * The pass-through training `$type` a body names, if any. Exact match — the
+ * orchestrator's `$type` discriminator is case-sensitive. Only the pass-through
+ * arm carries a `$type`, so no separate `kind` narrow is needed.
+ */
+const passThroughTrainingType = (body) => {
+    const t = body.$type;
+    return t === 'training' || t === 'imageResourceTraining' ? t : undefined;
+};
 // The canned picks carry the WIDENED BlockResourceInfo projection (PR-C) — the
 // public recommended settings a real host now returns — so dev:mock mirrors prod
 // (a picked resource seeds a weight slider + trigger words). Defaults match the
@@ -894,11 +903,36 @@ export function createMockHost(options = {}) {
                 ...(consentGranted ? { buzzBudget } : {}),
             };
         };
+        /**
+         * The training-only fields of a succeeded snapshot — see
+         * {@link MockGenerationScenario.trainedEpochs}. KIND-FAITHFUL, unlike the
+         * rest of the money path: only a pass-through `training` /
+         * `imageResourceTraining` body gets them, because only such a step produces
+         * a checkpoint. Empty for every other body, so their snapshots are unchanged.
+         */
+        const trainingFields = (body) => {
+            const $type = passThroughTrainingType(body);
+            if (!$type)
+                return {};
+            const count = Math.max(0, Math.floor(gen.trainedEpochs ?? 0));
+            return {
+                ...(count > 0
+                    ? {
+                        trainedEpochs: Array.from({ length: count }, (_, i) => ({
+                            $type,
+                            epochNumber: i + 1,
+                        })),
+                    }
+                    : {}),
+                ...(gen.trainingPublishedModel ? { publishedModel: { ...gen.trainingPublishedModel } } : {}),
+            };
+        };
         const succeededSnapshot = (workflowId) => {
             const wf = workflows.get(workflowId);
             const cost = wf?.cost ?? legacyCost;
             const body = wf?.body ?? {};
             return {
+                ...trainingFields(body),
                 workflowId,
                 status: 'succeeded',
                 cost: { total: cost },

package/dist/transport/validate.js

@@ -255,8 +255,91 @@ export function isValidWorkflowSnapshot(s) {
             return false;
         }
     }
+    // ---- The host fields mirrored in #524, plus the training-publish pair. ----
+    //
+    // Same policy as `autoClaim` above: each is OPTIONAL (an older host omits it
+    // and the snapshot stays valid), and a PRESENT but malformed value rejects
+    // the snapshot, because the block dereferences these fields.
+    //
+    // 🔴 ONE DELIBERATE DIFFERENCE: the open-ended string unions
+    // (`modelSubstitutions[].reason`, `trainedEpochs[].$type`, `toolCalls[].type`)
+    // are checked as STRINGS, not against their current members. A rejected snapshot is a dropped
+    // poll reply — the block's request hangs to its timeout — so pinning today's
+    // members here would turn the host adding a value into a fleet-wide hang in
+    // every already-shipped block bundle. The types document that unknown values
+    // may arrive.
+    if (s.modelSubstitutions !== undefined) {
+        if (!Array.isArray(s.modelSubstitutions))
+            return false;
+        for (const m of s.modelSubstitutions) {
+            if (!isObject(m))
+                return false;
+            if (!isFiniteNumber(m.requested) || !isFiniteNumber(m.applied))
+                return false;
+            if (typeof m.reason !== 'string')
+                return false;
+        }
+    }
+    if (s.textOutputs !== undefined) {
+        if (!Array.isArray(s.textOutputs))
+            return false;
+        if (!s.textOutputs.every((t) => typeof t === 'string'))
+            return false;
+    }
+    if (s.textOutputWithheld !== undefined) {
+        if (!isObject(s.textOutputWithheld) || typeof s.textOutputWithheld.reason !== 'string') {
+            return false;
+        }
+    }
+    if (s.toolCalls !== undefined) {
+        if (!Array.isArray(s.toolCalls))
+            return false;
+        for (const c of s.toolCalls) {
+            if (!isObject(c))
+                return false;
+            if (typeof c.id !== 'string' || typeof c.type !== 'string')
+                return false;
+            if (!isObject(c.function))
+                return false;
+            if (typeof c.function.name !== 'string' || typeof c.function.arguments !== 'string') {
+                return false;
+            }
+        }
+    }
+    if (s.stepOutputs !== undefined) {
+        if (!Array.isArray(s.stepOutputs))
+            return false;
+        // `output` is `unknown` by contract — only the `$type` label is dereferenced.
+        for (const o of s.stepOutputs) {
+            if (!isObject(o) || typeof o.$type !== 'string')
+                return false;
+        }
+    }
+    if (s.trainedEpochs !== undefined) {
+        if (!Array.isArray(s.trainedEpochs))
+            return false;
+        for (const e of s.trainedEpochs) {
+            if (!isObject(e) || typeof e.$type !== 'string')
+                return false;
+            if (!Number.isInteger(e.epochNumber))
+                return false;
+        }
+    }
+    if (s.publishedModel !== undefined && !isValidPublishedModel(s.publishedModel))
+        return false;
     return true;
 }
+/**
+ * Shape check for `publishedModel` — shared by {@link isValidWorkflowSnapshot}
+ * and the `AppWorkflow` row guard, which carry the same field.
+ */
+function isValidPublishedModel(p) {
+    if (!isObject(p))
+        return false;
+    if (!isFiniteNumber(p.modelId) || !isFiniteNumber(p.modelVersionId))
+        return false;
+    return typeof p.published === 'boolean';
+}
 /**
  * Host-pushed token rotation. No `requestId` field; the host is the initiator.
  * Carries the same wrapped-token shape as the reply path.
@@ -823,6 +906,9 @@ function isValidAppWorkflow(w) {
         if (img.nsfwLevel !== null && !isFiniteNumber(img.nsfwLevel))
             return false;
     }
+    // OPTIONAL — absent on hosts that predate it; checked only when present.
+    if (w.publishedModel !== undefined && !isValidPublishedModel(w.publishedModel))
+        return false;
     return true;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civitai/blocks-react",
-  "version": "0.63.1",
+  "version": "0.64.0",
   "description": "React hooks and iframe transport for Civitai Apps. Pairs with @civitai/app-sdk/blocks.",
   "license": "MIT",
   "type": "module",
@@ -38,11 +38,11 @@
   },
   "dependencies": {
     "@civitai/components": "^0.9.2",
-    "@civitai/theme": "^0.5.1"
+    "@civitai/theme": "^0.5.2"
   },
   "comment-peerDependencies": "This floor is DERIVED, not chosen — the lowest published app-sdk that exports every symbol this package imports. Do not edit it without reading ./PEER_FLOOR.md (in-repo, unpublished) and tests/guards/blocks-react-peer-floor.test.mjs.",
   "peerDependencies": {
-    "@civitai/app-sdk": ">=0.55.0 <1.0.0",
+    "@civitai/app-sdk": ">=0.57.0 <1.0.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
@@ -58,7 +58,7 @@
     "typescript": "^5.9.2",
     "vite": "^8.0.14",
     "vitest": "^4.1.11",
-    "@civitai/app-sdk": "^0.56.0"
+    "@civitai/app-sdk": "^0.57.0"
   },
   "publishConfig": {
     "access": "public"