@civitai/app-sdk 0.56.1 → 0.57.0

package/README.md

@@ -137,6 +137,7 @@ 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`. |
 
@@ -171,8 +172,28 @@ 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` 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. Both fields are absent on hosts
+  that predate them.
 
 ```ts
 import type { WorkflowBody } from '@civitai/app-sdk/blocks';
@@ -320,10 +341,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 +515,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 +590,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 +633,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,5 @@ 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, } 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

package/dist/blocks/nestedDocument.d.ts

@@ -0,0 +1,255 @@
+/**
+ * Embedding one of your own bundled documents inside a block — the `srcdoc`
+ * pattern, and why a plain `<iframe src>` cannot work.
+ *
+ * WHY THIS EXISTS
+ * ===============
+ * Two platform policies combine so that a block can never frame its own
+ * bundled content by URL. Neither is a bug, and neither has a manifest-side
+ * workaround:
+ *
+ *   1. A block's own frame is sandboxed with the manifest's `iframe.sandbox`
+ *      tokens intersected by a trust-tier allowlist. An unverified block keeps
+ *      `allow-scripts allow-forms` and nothing else — `allow-same-origin` is
+ *      refused at `civitai app validate` time ("forbidden outside the internal
+ *      trust tier") and re-stripped host-side even if it reached the manifest.
+ *      So the block document's origin is OPAQUE: `window.origin === "null"`.
+ *
+ *   2. Every path served from `https://<blockId>.civit.ai/` — `.html`, `.js`,
+ *      `.wasm`, archive files, all of it — carries
+ *      `Content-Security-Policy: frame-ancestors …` plus
+ *      `X-Frame-Options: SAMEORIGIN`. Those headers are stamped at the platform
+ *      edge, not by the block's own server, so a block cannot override them.
+ *
+ * `frame-ancestors` is checked against EVERY ancestor of the framed document.
+ * An opaque origin matches no source list — measured, including the wide-open
+ * `frame-ancestors *` — because CSP3 ASCII-serializes the ancestor origin and
+ * then URL-parses it, and the string `"null"` fails that parse, returning
+ * Blocked before any source matching happens. So widening the allowlist cannot
+ * fix this, and `X-Frame-Options: SAMEORIGIN` blocks it a second time on its
+ * own.
+ *
+ * 🔴 EXTERNAL PLATFORM MEASUREMENT — NOTHING IN THIS REPO VERIFIES THE MATRIX
+ * BELOW. It was taken on 2026-10-03 against a local two-origin Chromium replica
+ * of the platform's frame topology (sandbox `allow-scripts allow-forms`, nested
+ * document framed from the opaque-origin parent). That replica is deliberately
+ * NOT committed here — it would be a second, drifting model of a platform this
+ * package does not own — so no test in this package exercises any row, and a
+ * green suite says nothing about them. Treat the table as a dated observation of
+ * the platform, not as a pinned property of this code: RE-MEASURE IT if the
+ * platform changes its sandbox trust tiers or the response headers its static
+ * host stamps.
+ *
+ *   headers on the nested document            result
+ *   ----------------------------------------  ---------
+ *   (none)  ← positive control                LOADED
+ *   frame-ancestors *                         BLOCKED
+ *   frame-ancestors <app-host> <top-host>     BLOCKED
+ *   frame-ancestors <unrelated>  ← control    BLOCKED
+ *   X-Frame-Options: SAMEORIGIN only          BLOCKED
+ *
+ * Within that replica the positive control is what makes the four BLOCKEDs mean
+ * something: the harness CAN load a nested document, so the blocks are the
+ * headers and not the replica. That is a claim about the replica's internal
+ * consistency; it is not a claim that the replica matches production.
+ *
+ * WHAT THIS MODULE DOES
+ * =====================
+ * The one thing that works: fetch the nested document's HTML (the static host
+ * sends `Access-Control-Allow-Origin: *`, so a null-origin `fetch` succeeds
+ * where a frame load does not), rewrite its base URL to the absolute location
+ * it was fetched from, and hand the string to an iframe's `srcdoc`. A `srcdoc`
+ * frame inherits the parent's opaque origin and carries NO response headers of
+ * its own, so neither policy applies to it.
+ *
+ * 🔴 PREFER A SINGLE-DOCUMENT DESIGN. An engine build (Defold, Unity, Phaser,
+ * …) is a `<canvas>` plus a JS loader and normally mounts straight into the
+ * block's own document — no nested frame, no `<base>` rewrite, none of this
+ * module. Reach for the helper only when a separate document is genuinely
+ * required (a third-party viewer that insists on owning `document`, a build you
+ * cannot alter).
+ *
+ * 🔴 THE RETURNED STRING IS NOT SANITIZED, ON PURPOSE. It is your own bundled
+ * markup and scripts; stripping them would remove the thing the nested document
+ * exists to run. The consequence is the contract: pass a `src` you control.
+ * `fetchNestedDocument` is not a way to inline a document from somewhere else,
+ * and the returned string carries whatever the fetched bytes said. Put your own
+ * `sandbox` attribute on the iframe you hand it to.
+ *
+ * 🔴 KNOWN LIMITS. {@link injectBaseHref} is a SINGLE-PASS TOKENIZER, not an
+ * HTML parse (see `scanDocument`): it walks the document left to right once,
+ * tracking comments, `<script>`/`<style>` raw-text bodies and quoted attribute
+ * values, and locates the opening `<head>` and the first base-setting `<base>`
+ * only in real markup. It builds no tree, so it does not know element nesting,
+ * implied tags, or which `<head>` a stray tag would really have landed in.
+ * The cases it still gets wrong, none of which it previously got right either:
+ *
+ *   - `<title>` and `<textarea>` hold ESCAPABLE raw text, which this scanner
+ *     does not model — a literal `<base href=…>` written inside one is read as
+ *     markup. (`<script>`/`<style>`, the two bodies a build tool actually emits
+ *     markup-shaped strings into, ARE skipped.)
+ *   - A `<base>` inside a conditional comment, a `<template>`, or markup a
+ *     script writes at runtime is invisible or treated at face value, because
+ *     there is no DOM here to ask.
+ *   - It does nothing about assets a script resolves by hand from `location.*`:
+ *     `<base>` moves `document.baseURI` and relative URLs in markup, not a
+ *     string a loader built from `location.pathname`.
+ *
+ * A real parse would mean a DOM dependency on a zero-dependency, worker-safe
+ * surface, which is the trade this scanner exists to avoid.
+ */
+/** Why a {@link NestedDocumentError} was thrown. Branch on this, not on the message. */
+export type NestedDocumentErrorCode = 
+/** `src` (against `baseUrl`, or the current document) is not a resolvable URL. */
+'invalid-url'
+/** The document was fetched and the host answered with a non-2xx status. */
+ | 'http-error'
+/** The fetch itself failed — offline, DNS, TLS, a CORS rejection, no `fetch` global. */
+ | 'network-error';
+/**
+ * Thrown by {@link fetchNestedDocument} and {@link injectBaseHref}. Carries a
+ * {@link NestedDocumentErrorCode} so a caller can tell "you gave me a bad URL"
+ * from "the host said 404" from "the network refused", which are three
+ * different things to show a user.
+ */
+export declare class NestedDocumentError extends Error {
+    readonly name = "NestedDocumentError";
+    /** Machine-readable reason. */
+    readonly code: NestedDocumentErrorCode;
+    /** The absolute URL involved, when one was resolved before the failure. */
+    readonly url: string | undefined;
+    /** HTTP status, set only for `code: 'http-error'`. */
+    readonly status: number | undefined;
+    constructor(message: string, options: {
+        code: NestedDocumentErrorCode;
+        url?: string | undefined;
+        status?: number | undefined;
+        cause?: unknown;
+    });
+}
+/** What {@link injectBaseHref} returns. */
+export interface InjectBaseHrefResult {
+    /**
+     * The document, with the `<base href>` the parser will USE made absolute.
+     *
+     * 🔴 NOT a de-duplication, and the difference is observable. What is
+     * guaranteed is that the FIRST base-setting `<base>` — the only one an HTML
+     * parser honours — carries {@link baseHref} as an absolute URL. Other
+     * `<base>` tags are left exactly as they were: a document declaring
+     * `<base href="/a/"><base href="/b/">` comes back with two, the first
+     * rewritten and the second untouched (inert, as it already was), and a
+     * `<base target>` with no `href` is left in place beside the inserted one.
+     */
+    html: string;
+    /** The absolute href that `<base>` now carries. */
+    baseHref: string;
+    /** `true` if the input already declared a `<base href>`, which was replaced. */
+    hadExistingBase: boolean;
+}
+/**
+ * Give a document an absolute `<base href>` so its relative asset URLs still
+ * resolve once it is running from a `srcdoc` frame.
+ *
+ * This is the whole mechanism, and the reason it is a separate function with
+ * tests of its own: a `srcdoc` document's own base URL is `about:srcdoc`, which
+ * inherits the embedder's — an opaque origin — so every `src="loader.js"` and
+ * `url(font.woff2)` in the fetched markup resolves to nothing. A wrong or
+ * missing `<base>` breaks every relative load in the document **with no error
+ * naming the base**, which is why it is pinned by its own test.
+ *
+ * 🔴 MODULE-INTERNAL — NOT part of the public `./blocks` surface. It is exported
+ * from this FILE so the unit suite can import it by path; `index.ts`
+ * deliberately does not re-export it, because nothing in or out of the tree
+ * calls the rewrite on its own and an export is far cheaper to add later than to
+ * remove once published. Same for {@link InjectBaseHrefResult}. See the note
+ * beside the `./nestedDocument.js` re-export in `index.ts`.
+ *
+ * ONE RULE, in both directions:
+ *
+ *   - no `<base href>` in the input → the base becomes the DIRECTORY of
+ *     `documentUrl` (`…/game/index.html` → `…/game/`), which is what the
+ *     document's relative URLs were written against.
+ *   - a `<base href>` already present → it is RESOLVED against `documentUrl`
+ *     and REPLACED by the absolute result. The author's intent is kept; only
+ *     its form changes. A root-relative `<base href="/">`, which engine builds
+ *     ship routinely, would otherwise resolve against the opaque origin and
+ *     take every asset with it.
+ *
+ * Insertion point, in order: replacing the existing `<base href>`; immediately
+ * after the opening `<head>` tag; immediately after a leading `<!doctype>`;
+ * otherwise at the very start. A `<base>` in any of those positions is parsed
+ * into the head and precedes every asset reference, which is the property that
+ * matters.
+ *
+ * A `<base>` that declares only `target` and no `href` is left alone — per the
+ * HTML spec it sets no document base URL — and the new absolute `<base href>` is
+ * inserted as if there were none, so the output then holds two `<base>` tags.
+ * See {@link InjectBaseHrefResult.html} for what is and is not guaranteed about
+ * the count.
+ *
+ * 🔴 BUT `href=""` IS AN `href`, so it is base-setting and is REWRITTEN. The
+ * spec keys on the `href` CONTENT ATTRIBUTE being present, not on its value
+ * resolving to something new: `""` parses successfully against the document's
+ * own URL, so `<base href="">` sets the base to `documentUrl` itself (not its
+ * directory), and a whitespace-only value does the same because the URL parser
+ * strips leading and trailing spaces. The distinction is load-bearing, not
+ * pedantic — see the comment at the `wantHref` test in `scanDocument` for what
+ * treating it as absent did to a document declaring `<base href=""><base
+ * href="/real/">`.
+ *
+ * Only REAL MARKUP is considered: a `<base href>` or a `<head>` written inside
+ * an HTML comment, or inside a `<script>`/`<style>` body, is ignored, and tag
+ * names match case-insensitively. A quoted attribute value may contain `>`.
+ *
+ * @param html The document's markup, as fetched.
+ * @param documentUrl The absolute URL `html` was fetched from.
+ * @throws {NestedDocumentError} `code: 'invalid-url'` if `documentUrl` is not absolute.
+ */
+export declare function injectBaseHref(html: string, documentUrl: string): InjectBaseHrefResult;
+/** Options for {@link fetchNestedDocument}. */
+export interface FetchNestedDocumentOptions {
+    /**
+     * The nested document to inline. Absolute, or relative — a relative `src`
+     * resolves against `baseUrl` when given, otherwise against the current
+     * document's base URL (`document.baseURI`, falling back to `location.href`).
+     * In a runtime with neither, a relative `src` is an `'invalid-url'`.
+     */
+    src: string;
+    /** Explicit base for resolving a relative `src`. Defaults to the current document. */
+    baseUrl?: string;
+    /** Abort the fetch. Rejects with the underlying `AbortError`, not a `NestedDocumentError`. */
+    signal?: AbortSignal;
+}
+/** What {@link fetchNestedDocument} resolves to. */
+export interface NestedDocument {
+    /** Hand this to an iframe's `srcdoc`. NOT sanitized — see the module header. */
+    srcDoc: string;
+    /**
+     * The absolute URL the document was fetched from — the response's FINAL URL,
+     * so a redirect is reflected here and `baseHref` is its directory. Falls back
+     * to the requested URL in a runtime whose `Response` carries no `url`.
+     */
+    url: string;
+    /** The absolute href the injected `<base>` carries. */
+    baseHref: string;
+    /** `true` if the fetched document already declared a `<base href>`, which was replaced. */
+    hadExistingBase: boolean;
+}
+/**
+ * Fetch one of your own bundled documents and return it as a `srcdoc` string
+ * with an absolute `<base href>` injected.
+ *
+ * @example
+ * ```ts
+ * const { srcDoc } = await fetchNestedDocument({ src: '/game/index.html' });
+ * iframe.setAttribute('sandbox', 'allow-scripts');
+ * iframe.srcdoc = srcDoc;
+ * ```
+ *
+ * @throws {NestedDocumentError} `'invalid-url'`, `'http-error'` (with `.status`)
+ * or `'network-error'`. An abort via `options.signal` rejects with the
+ * platform's own `AbortError` instead, so `signal.aborted` stays the way to tell
+ * a cancellation from a failure.
+ */
+export declare function fetchNestedDocument(options: FetchNestedDocumentOptions): Promise<NestedDocument>;
+//# sourceMappingURL=nestedDocument.d.ts.map