@civitai/app-sdk 0.56.1 → 0.58.0

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