@civitai/app-sdk 0.56.1 → 0.58.0

package/README.md

@@ -137,8 +137,9 @@ interface BlockInitPayload {
 | `BLOCK_SCOPES` / `BLOCK_SCOPE_PATTERN` | Every known block scope string (the authoritative enum the canonical schema validates `scopes` against) + the `domain:verb:target` format-helper regex. Read the current set from `BLOCK_SCOPES` itself — scopes are added and retired, so no count is quoted here. A scope is valid only if it's a member of `BLOCK_SCOPES`, matching the [canonical schema](https://civitai.com/schemas/app-block/v1.json). |
 | `isMessage(data, type)` | Discriminator-only message narrowing (see above). |
 | `isModelSlotContext(ctx)` / `isPageSlotContext(ctx)` | Runtime narrowing for the `slotId`-discriminated `BlockContext` union. Real checks on a value that crossed a `postMessage` boundary — they verify every field they assert, not just `slotId`. |
+| `fetchNestedDocument(opts)` | Embed one of your OWN bundled documents as an iframe `srcdoc`, because a nested `<iframe src>` of your own content **cannot load** — see [Nested documents](#nested-documents) below. `NestedDocumentError` carries a `.code` of `'invalid-url' \| 'http-error' \| 'network-error'`. |
 | `isSignedIn(viewer)` | **The sign-in gate.** `isSignedIn(useBlockContext().viewer)` — do not open-code it as `viewer !== null` or `viewer?.signedIn === true`. Which of those is correct has already changed once with the host contract, and this is the one place it is decided. It reads neither `viewer.id` nor `viewer.username` (both `@deprecated`), so nothing written through it changes when those are removed. Need the identity rather than the presence? `useViewer()` — scope-gated and audited per call. |
-| types | `BlockManifestV1`, `ManifestSettings` (+ field types), `BlockContext`, `ModelSlotContext`, `BlockCheckpointInfo`, `ShowcaseImage`, `BlockToken`, `WrappedToken`, `BlockSettings`, `ViewerInfo`, `Theme`, `WorkflowBody`, `BlockTextToImageParams`, `WorkflowBodyCustomComfy` (+ its two arms `WorkflowBodyCustomComfyRecipe` / `WorkflowBodyCustomComfyInline`, and `InlineComfyNode`), `WorkflowBodyStep` / `WorkflowBodyPassThroughStep` (the two arms of `kind: 'step'`), `BlockWorkflowSnapshot`, `WorkflowStatus`, `BlockInitPayload`, `ParentToBlockMessage`, `BlockToParentMessage`. |
+| types | `BlockManifestV1`, `ManifestSettings` (+ field types), `BlockContext`, `ModelSlotContext`, `BlockCheckpointInfo`, `ShowcaseImage`, `BlockToken`, `WrappedToken`, `BlockSettings`, `ViewerInfo`, `Theme`, `WorkflowBody`, `BlockTextToImageParams`, `WorkflowBodyCustomComfy` (+ its two arms `WorkflowBodyCustomComfyRecipe` / `WorkflowBodyCustomComfyInline`, and `InlineComfyNode`), `WorkflowBodyStep` / `WorkflowBodyPassThroughStep` (the two arms of `kind: 'step'`), `WorkflowBodyTraining` (+ `AiToolkitTrainingParams`, `BlockTrainingQuote`, `BlockTrainingDatasetItem`, `BlockTrainingDatasetResult` and the `BLOCK_TRAINING_*` bounds), `BlockWorkflowSnapshot`, `WorkflowStatus`, `BlockInitPayload`, `ParentToBlockMessage`, `BlockToParentMessage`. |
 
 `WorkflowBody`'s `customComfy` member is a discriminated union on `mode`, mirroring
 the host's `blockCustomComfyMemberSchema`. Narrow on the VALUE (`body.mode === 'inline'`),
@@ -171,8 +172,29 @@ own key:
   and the host forwards `input` unmodified. There is no registry lookup, no param schema, no
   prompt audit and no AIR scan; what bounds it is a denylist of platform-internal `$type`s
   (scanners, moderation classifiers, hashing/model ingestion, web egress), a 64-character
-  `$type` cap, a 256 KB `input` cap, and `maxBuzz` — which, as on the inline arm, is **also the
-  step timeout in seconds**.
+  `$type` cap, a 256 KB `input` cap, and the spend reservation. **Unlike the inline arm, `maxBuzz`
+  is not always the timeout here**: on both `estimate` and `submit` the host asks the orchestrator
+  for a `whatif` quote of the step. **Quoted** → it reserves `max(maxBuzz, quote)`, gated against
+  the token's per-call budget (`token.buzzBudget`, capped at 1000 on a production token — so the
+  reservation can exceed the 1–250 `maxBuzz` range), and stamps **no** step timeout.
+  **Unquoted** → `maxBuzz` is both the reservation and the step timeout in seconds; the timeout
+  bounds wall-clock time, and spend only for a step billed by compute time — a step priced per
+  unit can bill above `maxBuzz`. `estimate` returns the reservation as `cost.total`; it is not a
+  guaranteed maximum. Full rules: `WorkflowBodyPassThroughStep.maxBuzz`.
+
+  `training` and `imageResourceTraining` are **not** on that denylist — the host allows them on
+  this arm by an explicit operator decision. They get no special treatment: the quoted/unquoted
+  rules above apply to them as to any other `$type`. Whether a given training input is quoted,
+  and at what price, is the orchestrator's answer — read it from `estimate` before submitting.
+  The trained checkpoint is not part of the block contract (an older
+  host may still leak checkpoint urls into `imageUrls` / `stepOutputs` — a host defect, never
+  something to build on); a host that supports it reports the trained epochs on
+  `snapshot.trainedEpochs` (and on each `AppWorkflow` row of the app-queue read) without the
+  checkpoint, and the viewer publishes
+  one by being navigated (`useCivitaiNavigate`, `scope: 'site'`) to Civitai's own model wizard at
+  `models/train/from-orchestrator?workflowId=<id>&epoch=<n>`. `snapshot.publishedModel` (and
+  `AppWorkflow.publishedModel`) then reports the resulting model. These fields are absent on hosts
+  that predate them.
 
 ```ts
 import type { WorkflowBody } from '@civitai/app-sdk/blocks';
@@ -186,6 +208,18 @@ const body: WorkflowBody = {
 };
 ```
 
+`WorkflowBodyTraining` (`kind: 'training'`) is the **quoted** way to train: an ai-toolkit LoRA
+run on a dataset Civitai prepared from the viewer's own images, mirroring the host's
+`blockTrainingBodySchema` (civitai/civitai#5434). There is no `maxBuzz` and no timeout — the
+`estimate` reply carries `snapshot.trainingQuote` (`quoteId`, `total`, `imageCount`,
+`expiresAt`), and the run starts only through the `RUN_TRAINING` bridge, after the viewer
+confirms that price in Civitai's own dialog. A confirmed run may exceed the token's per-call
+budget, up to `BLOCK_TRAINING_MAX_BUZZ_PER_RUN` (5,000). Page apps only, `ai:write:budgeted`,
+behind the host flag `app-blocks-training-kind` (off by default), and refused from development
+and review sessions. The dataset is prepared over `PREPARE_TRAINING_DATASET`
+(civitai/civitai#5438). Use it through `@civitai/blocks-react`'s `usePrepareTrainingDataset()`
+and `useRunTraining()`.
+
 ### `defineBlock` validator rules
 
 **There is no rule list here, and that is the point.** `defineBlock` does not
@@ -320,10 +354,58 @@ const { Viewer } = await import(viewerModuleSpecifier);
 for each global it actually replaced. `createMemoryStorage()` is exported too,
 if you want the standalone `Storage` work-alike.
 
+### Nested documents
+
+🔴 **A nested `<iframe src="…">` pointing at your own bundled content cannot
+load, and no manifest change fixes it** — your block'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
+are in one place: the header of
+[`src/blocks/nestedDocument.ts`](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, which avoids the whole problem class.
+
+When a separate document is genuinely required, fetch it and inline it as the
+iframe's `srcdoc` — that frame inherits your opaque origin and carries no
+response headers of its own:
+
+```ts
+import { fetchNestedDocument } from '@civitai/app-sdk/blocks';
+
+const { srcDoc, baseHref } = await fetchNestedDocument({ src: '/game/index.html' });
+// baseHref === 'https://<blockId>.civit.ai/game/'
+const frame = document.createElement('iframe');
+frame.setAttribute('sandbox', 'allow-scripts'); // your own; it does not inherit
+frame.srcdoc = srcDoc;
+```
+
+The injected `<base href>` is the mechanism: a `srcdoc` document's base URL is
+`about:srcdoc`, inheriting yours, so every relative `src=` in the fetched markup
+would otherwise resolve to nothing. The base is the directory of the
+**response's final URL**, so a redirect is followed rather than resolved one
+directory too high. A document that already declares a `<base href>` has that
+one resolved against the final URL and replaced — 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, and tag names match case-insensitively.
+
+**The returned string is NOT sanitized**, on purpose — it is your own markup and
+scripts, verbatim, and stripping them would remove the thing the nested document
+exists to run. Only pass a `src` you control. React callers want
+`useNestedDocument()` from
+[`@civitai/blocks-react`](../civitai-blocks-react/README.md).
+
 ### Version compatibility
 
 | `@civitai/app-sdk` | adds (blocks surface) |
 |---|---|
+| `0.57.0` | `fetchNestedDocument` / `NestedDocumentError` — the `srcdoc` escape hatch for embedding your own bundled documents |
 | `0.27.0` | `@civitai/app-sdk/safe-storage` — opaque-origin `localStorage`/`sessionStorage` shim, auto-installed by the `blocks` subpath |
 | `0.24.0` | `QUERY_APP_WORKFLOWS` / `CANCEL_APP_WORKFLOW` messages + the `AppWorkflow` type (app generator subqueue, PR #3164) |
 | `0.7.0` | `CANCEL_WORKFLOW` / `WORKFLOW_CANCELED` messages (real cancel, gotcha #51) |
@@ -446,7 +528,7 @@ The starters in `civitai/civitai-app-starters` wire this into framework-specific
 
 ## Choosing a workflow step type
 
-The orchestrator is a workflow API: each request submits a list of typed steps. `WORKFLOW_STEP_TYPES` is the in-code catalog of every step `$type` it accepts, with a one-line description for each — `textToImage`, `imageGen`, `videoGen`, `comfy`, `customComfy`, `textToSpeech`, `aceStepAudio`, `transcription`, `imageUpscaler` among them (51 in total).
+The orchestrator is a workflow API: each request submits a list of typed steps. `WORKFLOW_STEP_TYPES` is the in-code catalog of every step `$type` it accepts, with a one-line description for each — `textToImage`, `imageGen`, `videoGen`, `comfy`, `customComfy`, `textToSpeech`, `aceStepAudio`, `transcription`, `imageUpscaler` among them (53 in total).
 
 The catalog is pinned to the orchestrator's published OpenAPI spec two ways — an offline unit test against a transcribed copy of the spec's `WorkflowStepTemplate` discriminator mapping, and a CI job (`pnpm check:catalogs`) that re-fetches the live spec and diffs it. If a `$type` is listed here, the orchestrator accepts it.
 
@@ -521,15 +603,15 @@ What it exports:
 
 | Export | What |
 |---|---|
-| `WorkflowStepTemplates` | `$type` → template type, for 47 of the catalog's 51 step types. Keyed by the WIRE name, which the generated type names don't always match (`model3DPreview` → `Model3dPreviewStepTemplate`). |
+| `WorkflowStepTemplates` | `$type` → template type, for 47 of the catalog's 53 step types. Keyed by the WIRE name, which the generated type names don't always match (`model3DPreview` → `Model3dPreviewStepTemplate`). |
 | `WorkflowStepTemplateFor<'videoGen'>` | One step's template. |
 | `WorkflowStepInputFor<'videoGen'>` | One step's `input` shape, without needing the generated `*Input` name. |
 | `AnyWorkflowStepTemplate` | Discriminated union of all 47 mapped templates — `Extract<…, { $type: 'comfy' }>` and exhaustive `switch` work. `@civitai/client`'s base `WorkflowStepTemplate` has `$type` as a bare `string`, so it narrows nothing. |
 | `TypedWorkflowTemplate` | The submit envelope with `steps` narrowed to that union. Pass it straight to `submitWorkflow` / `estimateWorkflow`. |
 
-> 🔴 **The map is not total over the catalog, and that is the expected state.** `WORKFLOW_STEP_TYPES` documents 51 `$type`s; this map covers 47. The 4 with no generated template in the pinned `@civitai/client` are `imageScanning`, `preprocessVideo`, `soniloAudioGen`, `yuE2`, and `WorkflowStepTemplateFor<…>` is a compile error for each of them.
+> 🔴 **The map is not total over the catalog, and that is the expected state.** `WORKFLOW_STEP_TYPES` documents 53 `$type`s; this map covers 47. The 6 with no generated template in the pinned `@civitai/client` are `imageScanning`, `liveTranscription`, `merge`, `preprocessVideo`, `soniloAudioGen`, `yuE2`, and `WorkflowStepTemplateFor<…>` is a compile error for each of them.
 >
-> The two surfaces move independently on purpose: the catalog tracks the **live** orchestrator spec (a daily job syncs it), while these types track whatever `@civitai/client` was last published from. So the catalog runs ahead and the client catches up. The gap is never silent — `test/orchestrator/step-templates.test-d.ts` carries it as a `never` ledger plus one `@ts-expect-error` per gap `$type`, and `test/orchestrator/step-count-prose.test.ts` derives all four numbers (51, 47, 4, and the names) from `WORKFLOW_STEP_TYPES` and the map's own AST, then fails if this paragraph or its twin in `src/orchestrator/steps.ts` disagrees by one character.
+> The two surfaces move independently on purpose: the catalog tracks the **live** orchestrator spec (a daily job syncs it), while these types track whatever `@civitai/client` was last published from. So the catalog runs ahead and the client catches up. The gap is never silent — `test/orchestrator/step-templates.test-d.ts` carries it as a `never` ledger plus one `@ts-expect-error` per gap `$type`, and `test/orchestrator/step-count-prose.test.ts` derives all four numbers (53, 47, 6, and the names) from `WORKFLOW_STEP_TYPES` and the map's own AST, then fails if this paragraph or its twin in `src/orchestrator/steps.ts` disagrees by one character.
 
 The generated `*StepTemplate` and `*Input` types are **not** re-exported individually. Using this subpath already requires `@civitai/client` installed, so if you want one by name, import it straight from there — `import type { TextToImageStepTemplate } from '@civitai/client'`.
 
@@ -564,9 +646,11 @@ A `$type` having a type here says nothing about whether you may submit it.
 - **App Blocks** don't reach the orchestrator at all. A block posts a `WorkflowBody` to the host, which validates it server-side against its own schema. That contract is `@civitai/app-sdk/blocks` and is completely unaffected by this subpath.
 - **Standalone apps / BFFs** submit directly with the user's OAuth token, and the orchestrator applies its own authorization. A body that compiles can still come back 400 or 403.
 
-Several of the 47 exist to serve Civitai's own pipelines rather than third-party apps — `modelPickleScan`, `xGuardModeration`, `training`, `comfyNodepackSnapshot`, `qwenImageBench`, the `model*`/`media*` hashing and classification steps. They're in the consumer spec, so they're typed here. They are not an invitation.
+Several of the 47 exist to serve Civitai's own pipelines rather than third-party apps — `modelPickleScan`, `xGuardModeration`, `comfyNodepackSnapshot`, `qwenImageBench`, the `model*`/`media*` hashing and classification steps. They're in the consumer spec, so they're typed here. They are not an invitation.
+
+`training` and `imageResourceTraining` are the exception: an App Block's host explicitly **allows** them on the pass-through arm (see `WorkflowBodyPassThroughStep` under Primitives above for the `maxBuzz` bound, and how a trained epoch is published). For a standalone app, the orchestrator's own authorization still decides.
 
-Note that `WORKFLOW_STEP_TYPES` does **not** mark most of them: of its 51 entries exactly two — `comfyNodepackSnapshot` and `qwenImageBench` — sit under its "Platform internals" heading, and the rest are ordinary documented entries (`webScrape` even carries usage notes). The reason the platform steps are typed anyway is not that the catalog flags them as internal; it's that the catalog *documents* them, so skipping them would make `WorkflowStepTemplateFor<'training'>` a compile error for a step type the SDK documents — which is exactly what is live today for the 3 `$type`s the pinned client cannot type, and is why that gap is spelled out above rather than left to be discovered.
+Note that `WORKFLOW_STEP_TYPES` does **not** mark most of them: of its 53 entries exactly two — `comfyNodepackSnapshot` and `qwenImageBench` — sit under its "Platform internals" heading, and the rest are ordinary documented entries (`webScrape` even carries usage notes). The reason the platform steps are typed anyway is not that the catalog flags them as internal; it's that the catalog *documents* them, so skipping them would make `WorkflowStepTemplateFor<'training'>` a compile error for a step type the SDK documents — which is exactly what is live today for the 3 `$type`s the pinned client cannot type, and is why that gap is spelled out above rather than left to be discovered.
 
 ## Public vs. confidential clients
 

package/dist/blocks/appStorageErrors.d.ts

@@ -36,20 +36,16 @@
  *      `PAYLOAD_TOO_LARGE` sites, so it missed the entire authorization family.
  *   2. **Draft 2 (RETRACTED)** kept the six, added a table of eight
  *      authorization messages "measured in the same read", and presented THAT
- *      as the surface. Also wrong. It missed, in the same file: `Apps are not
- *      enabled`, thrown from TWO different gates with one spelling — the
- *      `enforceAppBlocksFlag` middleware (defined `:249`, throws at `:255`
- *      query / `:257` mutation), which is `.use()`d on all five storage
- *      procedures at `:470`, `:509`, `:938`, `:1022`, `:1106` BEFORE their
- *      `.input()`, so it fires before anything else on every call; and
- *      `assertAppBlocksEnabledForTokenUser` (`:139-155`, throwing at `:153`),
- *      reached from `resolveStorageContext`. Grepping `enforceAppBlocksFlag`
- *      will NOT find `:153`. Also missed: `block token subject could
- *      not be resolved` (`:148`, called unconditionally from
- *      `resolveStorageContext`), `review token subject could not be resolved`
- *      (`:82`) and `Apps authoring is not enabled for this account` (`:89`).
- *      `Apps are not enabled` is a feature-flag kill switch — neither a ceiling
- *      nor an authorization failure, so it fit neither published table.
+ *      as the surface. Also wrong: it missed four more messages in the same
+ *      host file, one of which was neither a ceiling nor an authorization
+ *      failure and so fit neither of its published tables.
+ *
+ * 🔴 **Which messages those were, and which host code raises them, is
+ * deliberately NOT recorded here.** The retracted drafts spelled it out down to
+ * line numbers in the host's router — a citation nothing in this repository can
+ * check, and one that any unrelated edit upstream invalidates silently. Read it
+ * off the host when you need it (see "Re-deriving it" below); do not write the
+ * answer back into this comment.
  *
  * Each enumeration was wider than the last and each was still short; the
  * router carries **21** `throw new TRPCError` sites and **17** distinct
@@ -248,10 +244,9 @@ export declare const APP_STORAGE_ERROR_REQUEST_FAILED = "storage request failed"
  *
  *   - The bridge's catch arms are blanket, so every other rejection the host
  *     raises arrives on the SAME field and is absent here on purpose. `invalid
- *     block token`, `block instance revoked`, `Apps are not enabled` and the
- *     `storage … scope` template are examples of what that covers —
- *     **illustrations, not a bound.** See this file's header for why no list
- *     of them lives in this repository.
+ *     block token`, `block instance revoked` and the `storage … scope` template
+ *     are examples of what that covers — **illustrations, not a bound.** See
+ *     this file's header for why no list of them lives in this repository.
  *   - 🔴 The host also enforces **size ceilings zod-side** (`key` capped at 200
  *     characters on the `.input()` schema, and three more on `list`). Those
  *     throw no `TRPCError`, so they are invisible to the re-derivation recipe
@@ -322,9 +317,8 @@ export type AppStorageRejectionReason = 'value-too-large' | 'app-quota-exceeded'
  *     failure.** The bridge's catch arms are blanket, so every other rejection
  *     the host raises arrives on the same field and classifies `null` — for
  *     example `invalid block token` (an expired token mid-session), `block
- *     instance revoked`, `storage set requires the apps:storage:write scope`,
- *     or `Apps are not enabled` (the feature flag, which fires before anything
- *     else on every storage call). 🔴 **Those are ILLUSTRATIONS, not the set**:
+ *     instance revoked`, or `storage set requires the apps:storage:write
+ *     scope`. 🔴 **Those are ILLUSTRATIONS, not the set**:
  *     see this module's header for why no list of them lives here.
  *   - 🔴 **and a zod INPUT-VALIDATION refusal, which never reaches a handler at
  *     all.** tRPC parses `.input()` before the procedure body, so a bound

package/dist/blocks/appStorageErrors.js

@@ -36,20 +36,16 @@
  *      `PAYLOAD_TOO_LARGE` sites, so it missed the entire authorization family.
  *   2. **Draft 2 (RETRACTED)** kept the six, added a table of eight
  *      authorization messages "measured in the same read", and presented THAT
- *      as the surface. Also wrong. It missed, in the same file: `Apps are not
- *      enabled`, thrown from TWO different gates with one spelling — the
- *      `enforceAppBlocksFlag` middleware (defined `:249`, throws at `:255`
- *      query / `:257` mutation), which is `.use()`d on all five storage
- *      procedures at `:470`, `:509`, `:938`, `:1022`, `:1106` BEFORE their
- *      `.input()`, so it fires before anything else on every call; and
- *      `assertAppBlocksEnabledForTokenUser` (`:139-155`, throwing at `:153`),
- *      reached from `resolveStorageContext`. Grepping `enforceAppBlocksFlag`
- *      will NOT find `:153`. Also missed: `block token subject could
- *      not be resolved` (`:148`, called unconditionally from
- *      `resolveStorageContext`), `review token subject could not be resolved`
- *      (`:82`) and `Apps authoring is not enabled for this account` (`:89`).
- *      `Apps are not enabled` is a feature-flag kill switch — neither a ceiling
- *      nor an authorization failure, so it fit neither published table.
+ *      as the surface. Also wrong: it missed four more messages in the same
+ *      host file, one of which was neither a ceiling nor an authorization
+ *      failure and so fit neither of its published tables.
+ *
+ * 🔴 **Which messages those were, and which host code raises them, is
+ * deliberately NOT recorded here.** The retracted drafts spelled it out down to
+ * line numbers in the host's router — a citation nothing in this repository can
+ * check, and one that any unrelated edit upstream invalidates silently. Read it
+ * off the host when you need it (see "Re-deriving it" below); do not write the
+ * answer back into this comment.
  *
  * Each enumeration was wider than the last and each was still short; the
  * router carries **21** `throw new TRPCError` sites and **17** distinct
@@ -251,10 +247,9 @@ export const APP_STORAGE_ERROR_REQUEST_FAILED = 'storage request failed';
  *
  *   - The bridge's catch arms are blanket, so every other rejection the host
  *     raises arrives on the SAME field and is absent here on purpose. `invalid
- *     block token`, `block instance revoked`, `Apps are not enabled` and the
- *     `storage … scope` template are examples of what that covers —
- *     **illustrations, not a bound.** See this file's header for why no list
- *     of them lives in this repository.
+ *     block token`, `block instance revoked` and the `storage … scope` template
+ *     are examples of what that covers — **illustrations, not a bound.** See
+ *     this file's header for why no list of them lives in this repository.
  *   - 🔴 The host also enforces **size ceilings zod-side** (`key` capped at 200
  *     characters on the `.input()` schema, and three more on `list`). Those
  *     throw no `TRPCError`, so they are invisible to the re-derivation recipe
@@ -327,9 +322,8 @@ export const APP_STORAGE_HOST_ERROR_MESSAGES = [
  *     failure.** The bridge's catch arms are blanket, so every other rejection
  *     the host raises arrives on the same field and classifies `null` — for
  *     example `invalid block token` (an expired token mid-session), `block
- *     instance revoked`, `storage set requires the apps:storage:write scope`,
- *     or `Apps are not enabled` (the feature flag, which fires before anything
- *     else on every storage call). 🔴 **Those are ILLUSTRATIONS, not the set**:
+ *     instance revoked`, or `storage set requires the apps:storage:write
+ *     scope`. 🔴 **Those are ILLUSTRATIONS, not the set**:
  *     see this module's header for why no list of them lives here.
  *   - 🔴 **and a zod INPUT-VALIDATION refusal, which never reaches a handler at
  *     all.** tRPC parses `.input()` before the procedure body, so a bound

package/dist/blocks/index.d.ts

@@ -29,6 +29,37 @@ export { BrowsingLevel, SFW_LEVELS, NSFW_LEVELS, isSfwCeiling, isLevelAllowed, e
 export type { BrowsingLevelKey, BrowsingLevelBit, ColorDomain } from './browsingLevel.js';
 export { APP_STORAGE_MAX_VALUE_BYTES, APP_STORAGE_MAX_BYTES, APP_STORAGE_MAX_ROWS, } from './appStorageLimits.js';
 export { BLOCK_IDEMPOTENCY_KEY_REGEX, BLOCK_IDEMPOTENCY_KEY_MAX_LENGTH, isValidBlockIdempotencyKey, blockIdempotencyKeyRejection, } from './idempotency.js';
+/**
+ * The `srcdoc` escape hatch for embedding one of your own bundled documents
+ * inside a block, because a plain `<iframe src>` of your own subdomain cannot
+ * load. Prefer a SINGLE-DOCUMENT design. The measured reason, the matrix and
+ * the limits live in ONE place: the header of `nestedDocument.ts`.
+ *
+ * 🔴 `injectBaseHref` and `InjectBaseHrefResult` ARE DELIBERATELY NOT HERE, and
+ * the omission is the same decision as the `appStorageErrors.ts` block below:
+ * publish the branching surface, not every internal the module happens to
+ * export. `fetchNestedDocument` covers every runnable example in this repo's
+ * four prose surfaces (this package's README, `@civitai/blocks-react`'s README,
+ * `docs/build-your-first-app-block.md` and the changeset); the only in-tree
+ * importers of the rewrite are this module's own unit tests, and
+ * `@civitai/blocks-react` does not value-import it. There can be no EXTERNAL
+ * consumer either. The DEFINING evidence is the git history, not a sample of
+ * tarballs: `nestedDocument.ts` is ADDED by the branch that introduced this
+ * helper — `git log --diff-filter=A` over it returns exactly one commit — so no
+ * version published before that commit can contain the symbol, whatever any
+ * individual tarball says. ⚠ An earlier revision of this comment derived that
+ * conclusion from a handful of tarball probes instead — a sample generalised
+ * into a claim about every published version. The conclusion was right; the
+ * grounds it stated were not, which is the part worth not repeating. The probes
+ * themselves, with their read dates and controls, are recorded in
+ * `packages/civitai-blocks-react/PEER_FLOOR.md`.
+ *
+ * Both stay exported from `nestedDocument.ts`, so the unit suite reaches them by
+ * file path — and adding one here later is a `minor`, while removing one once
+ * published is not.
+ */
+export { fetchNestedDocument, NestedDocumentError } from './nestedDocument.js';
+export type { FetchNestedDocumentOptions, NestedDocument, NestedDocumentErrorCode, } from './nestedDocument.js';
 /**
  * {@link classifyAppStorageError} — the matcher a block branches on — plus the
  * four rejection messages a MOCK HOST has to emit. The wire carries a
@@ -78,5 +109,10 @@ export { isModelSlotContext, isPageSlotContext } from './types.js';
  * in `types.ts` for which of the two it uses and why.
  */
 export { isSignedIn } from './types.js';
-export type { BlockContext, KnownSlotId, ModelSlotId, PageSlotContext, PageSlotId, UnknownSlotContext, BlockManifest, BlockManifestGood, BlockManifestV1, BlockSettings, BlockToken, ContentRating, ManifestBooleanField, ManifestIframe, ManifestNumberField, ManifestPage, ManifestPreview, ManifestSettingField, ManifestSettings, ManifestStringField, ManifestTarget, ModelSlotContext, SettingScope, SettingWidget, Theme, ViewerInfo, BlockCheckpointInfo, BlockResourceInfo, BlockResourcePickerType, BlockSourceImage, BlockUploadedImageInfo, BlockGenerationSourceImageInfo, BlockPendingImageInfo, BlockImageScanResult, BlockUploadPurpose, BlockNavigateScope, BlockTextToImageParams, BlockWorkflowSnapshot, BuzzAccountType, ShowcaseImage, WorkflowBody, WorkflowBodyTextToImage, WorkflowBodyCustomComfy, WorkflowBodyCustomComfyRecipe, WorkflowBodyCustomComfyInline, InlineComfyNode, WorkflowBodyStep, WorkflowBodyPassThroughStep, WorkflowStatus, BlockBuzzTransaction, BlockBuzzAccount, BlockDailyCompensationResource, BlockViewer, BlockWildcardPack, BlockWildcardPackErrorCode, AppWorkflow, AppWorkflowImage, BlockGatedImage, BlockCollectionFollowErrorCode, BlockCollectionFollowResult, BlockPostSource, BlockCreatePostRequest, BlockCreatePostResult, BlockCreatePostHostError, } from './types.js';
+export type { BlockContext, KnownSlotId, ModelSlotId, PageSlotContext, PageSlotId, UnknownSlotContext, BlockManifest, BlockManifestGood, BlockManifestV1, BlockSettings, BlockToken, ContentRating, ManifestBooleanField, ManifestIframe, ManifestNumberField, ManifestPage, ManifestPreview, ManifestSettingField, ManifestSettings, ManifestStringField, ManifestTarget, ModelSlotContext, SettingScope, SettingWidget, Theme, ViewerInfo, BlockCheckpointInfo, BlockResourceInfo, BlockResourcePickerType, BlockSourceImage, BlockUploadedImageInfo, BlockGenerationSourceImageInfo, BlockPendingImageInfo, BlockImageScanResult, BlockUploadPurpose, BlockNavigateScope, BlockTextToImageParams, BlockWorkflowSnapshot, BlockModelSubstitution, ModelSubstitutionReason, BlockStepToolCall, BlockTrainedEpoch, BlockPublishedModel, BuzzAccountType, ShowcaseImage, WorkflowBody, WorkflowBodyTextToImage, WorkflowBodyCustomComfy, WorkflowBodyCustomComfyRecipe, WorkflowBodyCustomComfyInline, InlineComfyNode, WorkflowBodyStep, WorkflowBodyPassThroughStep, WorkflowStatus, BlockBuzzTransaction, BlockBuzzAccount, BlockDailyCompensationResource, BlockViewer, BlockWildcardPack, BlockWildcardPackErrorCode, AppWorkflow, AppWorkflowImage, BlockGatedImage, BlockCollectionFollowErrorCode, BlockCollectionFollowResult, BlockPostSource, BlockCreatePostRequest, BlockCreatePostResult, BlockCreatePostHostError, WorkflowBodyTraining, AiToolkitTrainingParams, AiToolkitTrainingParamsBase, AiToolkitPlainEcosystem, AiToolkitLrScheduler, AiToolkitOptimizerType, BlockTrainingQuote, BlockTrainingDatasetItem, BlockTrainingDatasetResult, BlockTrainingRejectionReason, BlockPrepareTrainingDatasetHostError, BlockRunTrainingHostError, } from './types.js';
+/**
+ * Host bounds for the App Blocks `kind: 'training'` flow, mirrored from
+ * civitai/civitai's zod — see `WorkflowBodyTraining`.
+ */
+export { BLOCK_TRAINING_MAX_BUZZ_PER_RUN, BLOCK_TRAINING_DATASET_MAX_ITEMS, BLOCK_TRAINING_CAPTION_MAX_CHARS, BLOCK_TRAINING_SAMPLE_PROMPTS_MAX, BLOCK_TRAINING_SAMPLE_PROMPT_MAX_CHARS, BLOCK_TRAINING_TRIGGER_WORD_MAX_CHARS, BLOCK_TRAINING_MODEL_KEY_MAX_CHARS, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/blocks/index.js

@@ -32,6 +32,36 @@ export { BLOCK_SCOPES, BLOCK_SCOPE_PATTERN, BLOCK_CATEGORIES, BLOCK_TAGLINE_MAX_
 export { BrowsingLevel, SFW_LEVELS, NSFW_LEVELS, isSfwCeiling, isLevelAllowed, effectiveBrowsingCeiling, } from './browsingLevel.js';
 export { APP_STORAGE_MAX_VALUE_BYTES, APP_STORAGE_MAX_BYTES, APP_STORAGE_MAX_ROWS, } from './appStorageLimits.js';
 export { BLOCK_IDEMPOTENCY_KEY_REGEX, BLOCK_IDEMPOTENCY_KEY_MAX_LENGTH, isValidBlockIdempotencyKey, blockIdempotencyKeyRejection, } from './idempotency.js';
+/**
+ * The `srcdoc` escape hatch for embedding one of your own bundled documents
+ * inside a block, because a plain `<iframe src>` of your own subdomain cannot
+ * load. Prefer a SINGLE-DOCUMENT design. The measured reason, the matrix and
+ * the limits live in ONE place: the header of `nestedDocument.ts`.
+ *
+ * 🔴 `injectBaseHref` and `InjectBaseHrefResult` ARE DELIBERATELY NOT HERE, and
+ * the omission is the same decision as the `appStorageErrors.ts` block below:
+ * publish the branching surface, not every internal the module happens to
+ * export. `fetchNestedDocument` covers every runnable example in this repo's
+ * four prose surfaces (this package's README, `@civitai/blocks-react`'s README,
+ * `docs/build-your-first-app-block.md` and the changeset); the only in-tree
+ * importers of the rewrite are this module's own unit tests, and
+ * `@civitai/blocks-react` does not value-import it. There can be no EXTERNAL
+ * consumer either. The DEFINING evidence is the git history, not a sample of
+ * tarballs: `nestedDocument.ts` is ADDED by the branch that introduced this
+ * helper — `git log --diff-filter=A` over it returns exactly one commit — so no
+ * version published before that commit can contain the symbol, whatever any
+ * individual tarball says. ⚠ An earlier revision of this comment derived that
+ * conclusion from a handful of tarball probes instead — a sample generalised
+ * into a claim about every published version. The conclusion was right; the
+ * grounds it stated were not, which is the part worth not repeating. The probes
+ * themselves, with their read dates and controls, are recorded in
+ * `packages/civitai-blocks-react/PEER_FLOOR.md`.
+ *
+ * Both stay exported from `nestedDocument.ts`, so the unit suite reaches them by
+ * file path — and adding one here later is a `minor`, while removing one once
+ * published is not.
+ */
+export { fetchNestedDocument, NestedDocumentError } from './nestedDocument.js';
 /**
  * {@link classifyAppStorageError} — the matcher a block branches on — plus the
  * four rejection messages a MOCK HOST has to emit. The wire carries a
@@ -78,4 +108,9 @@ export { isModelSlotContext, isPageSlotContext } from './types.js';
  * in `types.ts` for which of the two it uses and why.
  */
 export { isSignedIn } from './types.js';
+/**
+ * Host bounds for the App Blocks `kind: 'training'` flow, mirrored from
+ * civitai/civitai's zod — see `WorkflowBodyTraining`.
+ */
+export { BLOCK_TRAINING_MAX_BUZZ_PER_RUN, BLOCK_TRAINING_DATASET_MAX_ITEMS, BLOCK_TRAINING_CAPTION_MAX_CHARS, BLOCK_TRAINING_SAMPLE_PROMPTS_MAX, BLOCK_TRAINING_SAMPLE_PROMPT_MAX_CHARS, BLOCK_TRAINING_TRIGGER_WORD_MAX_CHARS, BLOCK_TRAINING_MODEL_KEY_MAX_CHARS, } from './types.js';
 //# sourceMappingURL=index.js.map

package/dist/blocks/messages.d.ts

@@ -8,7 +8,7 @@
  * Wire format: `window.postMessage({ type, payload }, targetOrigin)`.
  */
 import type { ColorDomain } from './browsingLevel.js';
-import type { BlockCheckpointInfo, BlockResourceInfo, BlockResourcePickerType, BlockUploadedImageInfo, BlockGenerationSourceImageInfo, BlockPendingImageInfo, BlockImageScanResult, BlockUploadPurpose, BlockNavigateScope, BlockContext, BlockSettings, Theme, ViewerInfo, WorkflowBody, BlockWorkflowSnapshot, BlockBuzzTransaction, BlockBuzzAccount, BlockDailyCompensationResource, BlockViewer, BlockWildcardPack, BlockWildcardPackErrorCode, AppWorkflow, BlockGatedImage, BlockCollectionFollowErrorCode, BlockCollectionFollowResult, BlockPostSource, BlockCreatePostResult } from './types.js';
+import type { BlockCheckpointInfo, BlockResourceInfo, BlockResourcePickerType, BlockUploadedImageInfo, BlockGenerationSourceImageInfo, BlockPendingImageInfo, BlockImageScanResult, BlockUploadPurpose, BlockNavigateScope, BlockContext, BlockSettings, Theme, ViewerInfo, WorkflowBody, BlockWorkflowSnapshot, BlockBuzzTransaction, BlockBuzzAccount, BlockDailyCompensationResource, BlockViewer, BlockWildcardPack, BlockWildcardPackErrorCode, AppWorkflow, BlockGatedImage, BlockCollectionFollowErrorCode, BlockCollectionFollowResult, BlockPostSource, BlockCreatePostResult, BlockTrainingDatasetItem, BlockTrainingDatasetResult, WorkflowBodyTraining } from './types.js';
 /**
  * Filter params for `GET_BUZZ_TRANSACTIONS`. All optional; the host validates
  * them server-side (they are NEVER trusted for auth — the account is self-bound
@@ -464,6 +464,20 @@ export type ParentToBlockMessage = {
         result?: BlockCreatePostResult;
         error?: string;
     };
+} | {
+    type: 'TRAINING_DATASET_RESULT';
+    payload: {
+        requestId: string;
+        result?: BlockTrainingDatasetResult;
+        error?: string;
+    };
+} | {
+    type: 'TRAINING_RESULT';
+    payload: {
+        requestId: string;
+        snapshot?: BlockWorkflowSnapshot;
+        error?: string;
+    };
 } | {
     type: 'IMAGES_RESULT';
     payload: {
@@ -774,6 +788,18 @@ export type BlockToParentMessage = {
         /** Optional model-version gallery attach. Gated hard server-side. */
         modelVersionId?: number;
     };
+} | {
+    type: 'PREPARE_TRAINING_DATASET';
+    payload: {
+        requestId: string;
+        items: BlockTrainingDatasetItem[];
+    };
+} | {
+    type: 'RUN_TRAINING';
+    payload: {
+        requestId: string;
+        body: WorkflowBodyTraining;
+    };
 } | {
     type: 'GET_IMAGES_BY_IDS';
     payload: {
@@ -998,7 +1024,7 @@ export type BlockToParentMessageType = BlockToParentMessage['type'];
  * it is a measurement, not an invariant, and civitai's own compile-time gate
  * (published SDK union ⊆ `keyof INVENTORY`) is what holds one direction of it.
  */
-export declare const BLOCK_TO_PARENT_MESSAGE_TYPES: readonly ["BLOCK_HELLO", "BLOCK_READY", "BLOCK_ERROR", "BLOCK_MESSAGE_REJECTED", "REQUEST_TOKEN", "RESIZE_IFRAME", "SUBMIT_WORKFLOW", "ESTIMATE_WORKFLOW", "POLL_WORKFLOW", "CANCEL_WORKFLOW", "OPEN_BUZZ_PURCHASE", "GET_BUZZ_BALANCE", "GET_VIEWER", "GET_BUZZ_TRANSACTIONS", "GET_BUZZ_ACCOUNTS", "GET_DAILY_COMPENSATION", "GET_WILDCARD_PACK", "QUERY_APP_WORKFLOWS", "PUBLISH_GENERATION_OUTPUTS", "CREATE_POST_FROM_APP", "GET_IMAGES_BY_IDS", "CANCEL_APP_WORKFLOW", "OPEN_CHECKPOINT_PICKER", "OPEN_RESOURCE_PICKER", "OPEN_IMAGE_UPLOAD", "SET_USER_CHECKPOINT", "NAVIGATE", "REQUEST_SIGN_IN", "REQUEST_CONSENT", "TRACK_EVENT", "APP_STORAGE_GET", "APP_STORAGE_SET", "APP_STORAGE_DELETE", "APP_STORAGE_LIST", "APP_STORAGE_QUOTA", "SHARED_LIST", "SHARED_GET_COUNT", "SHARED_GET_COUNTS", "SHARED_APPEND", "SHARED_VOTE", "SHARED_UNVOTE", "SHARED_WITHDRAW", "SHARED_UPDATE", "SHARED_GET", "SHARED_REPORT", "SAVE_IMAGE", "SET_COLLECTION_FOLLOW"];
+export declare const BLOCK_TO_PARENT_MESSAGE_TYPES: readonly ["BLOCK_HELLO", "BLOCK_READY", "BLOCK_ERROR", "BLOCK_MESSAGE_REJECTED", "REQUEST_TOKEN", "RESIZE_IFRAME", "SUBMIT_WORKFLOW", "ESTIMATE_WORKFLOW", "POLL_WORKFLOW", "CANCEL_WORKFLOW", "OPEN_BUZZ_PURCHASE", "GET_BUZZ_BALANCE", "GET_VIEWER", "GET_BUZZ_TRANSACTIONS", "GET_BUZZ_ACCOUNTS", "GET_DAILY_COMPENSATION", "GET_WILDCARD_PACK", "QUERY_APP_WORKFLOWS", "PUBLISH_GENERATION_OUTPUTS", "CREATE_POST_FROM_APP", "PREPARE_TRAINING_DATASET", "RUN_TRAINING", "GET_IMAGES_BY_IDS", "CANCEL_APP_WORKFLOW", "OPEN_CHECKPOINT_PICKER", "OPEN_RESOURCE_PICKER", "OPEN_IMAGE_UPLOAD", "SET_USER_CHECKPOINT", "NAVIGATE", "REQUEST_SIGN_IN", "REQUEST_CONSENT", "TRACK_EVENT", "APP_STORAGE_GET", "APP_STORAGE_SET", "APP_STORAGE_DELETE", "APP_STORAGE_LIST", "APP_STORAGE_QUOTA", "SHARED_LIST", "SHARED_GET_COUNT", "SHARED_GET_COUNTS", "SHARED_APPEND", "SHARED_VOTE", "SHARED_UNVOTE", "SHARED_WITHDRAW", "SHARED_UPDATE", "SHARED_GET", "SHARED_REPORT", "SAVE_IMAGE", "SET_COLLECTION_FOLLOW"];
 /**
  * The bucket a message type falls into when the protocol does not declare it.
  *

package/dist/blocks/messages.js

@@ -69,6 +69,8 @@ export const BLOCK_TO_PARENT_MESSAGE_TYPES = [
     'QUERY_APP_WORKFLOWS',
     'PUBLISH_GENERATION_OUTPUTS',
     'CREATE_POST_FROM_APP',
+    'PREPARE_TRAINING_DATASET',
+    'RUN_TRAINING',
     'GET_IMAGES_BY_IDS',
     'CANCEL_APP_WORKFLOW',
     'OPEN_CHECKPOINT_PICKER',