studiograph 1.3.48-next.26 → 1.3.48-next.261

package/dist/core/artifact-asset-resolution.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The artifact asset-resolution contract.
+ *
+ * Every artifact render context resolves workspace-asset references in exactly
+ * ONE way, chosen once per render as an explicit `AssetResolution` value:
+ *
+ *   token    — in-app canvas / present + headless Playwright render (PNG/PDF/
+ *              inspect). URLs stay `/api/assets/...` and carry the `?at=`
+ *              capability token; CSP allowlists `<origin>/api/assets/` only.
+ *   share    — public share page. URLs are the token-scoped
+ *              `/api/share/<token>/asset/...` surface; CSP allowlists exactly
+ *              that token's path — never `/api/share/` broadly.
+ *   relative — self-contained HTML export. Bundled refs become relative
+ *              `./assets/...` paths; unbundled refs become labeled inline
+ *              placeholders. CSP carries NO network sources, unconditionally
+ *              (`file:` only, for opening from disk) — an exported file never
+ *              phones home, and a copy hosted on an http origin cannot beacon
+ *              same-origin either.
+ *   none     — no asset access (unsaved previews, tests).
+ *
+ * The one document builder (`buildFrameDocument` in core, used by every surface)
+ * derives the URL rewrite AND the CSP from the SAME resolution value via
+ * `applyAssetResolution` / `artifactCsp`, so a context can never mix models —
+ * "URLs from one scheme, CSP from another" (the share-page broken-images class)
+ * is unrepresentable.
+ *
+ * Fail-closed: a malformed origin or share token yields NO network source and
+ * NO rewrite rather than a permissive or splicable CSP.
+ */
+export type AssetResolution = {
+    mode: 'token';
+    /** Artifact-asset capability token (`?at=`). Null while the mint is in
+     *  flight — the CSP already allowlists `/api/assets/` so the rebuilt
+     *  document with the token doesn't change policy, only URLs. */
+    token: string | null;
+    /** App origin the asset URLs resolve against (CSP sources need an
+     *  absolute origin; the sandboxed iframe inherits the parent base URL). */
+    origin: string;
+} | {
+    mode: 'share';
+    shareToken: string;
+    origin: string;
+} | {
+    mode: 'relative';
+    /** Decoded `assetId/filename` identity keys actually written into the
+     *  export bundle. Refs NOT in the set render as labeled placeholders —
+     *  never absolutized back to the workspace. Omitted = relativize all
+     *  (caller bundles every ref). */
+    bundledKeys?: Set<string>;
+} | {
+    mode: 'none';
+};
+export declare function isValidShareToken(token: string): boolean;
+/**
+ * The network source expressions (if any) the resolution adds to the asset
+ * CSP directives (`img-src` / `media-src` / `font-src`).
+ *
+ * D4 invariants (pinned by tests):
+ *  - token    → `<origin>/api/assets/` and nothing else
+ *  - share    → `<origin>/api/share/<token>/asset/` (the exact token path)
+ *  - relative → `file:` ONLY, so the bundled `./assets/...` files load when
+ *               the export is opened from disk. Deliberately NOT `'self'`:
+ *               on an http(s)-hosted copy, `'self'` would let artifact JS
+ *               beacon same-origin via img/media/font loads — "no network,
+ *               unconditionally" means a hosted export shows placeholders
+ *               instead (codex P1). A hostable export would be its own
+ *               explicit mode, not a widening of this one.
+ *  - none     → nothing
+ */
+export declare function artifactCspAssetSources(resolution: AssetResolution): string[];
+/**
+ * The full iframe/document Content-Security-Policy for an artifact render.
+ * Single definition for BOTH builders (web srcdoc + core HTML export) so the
+ * policy can't drift between contexts. The asset directives are derived from
+ * the resolution; everything else is the fixed sandbox posture (inline + blob
+ * scripts allowed, no eval, no network, no frames/objects/forms).
+ *
+ * `allowBaseOrigin` — the Playwright render path injects `<base href>` so
+ * root-relative asset URLs resolve in a `setContent` document; `base-uri`
+ * must then allow exactly that origin (everything else keeps `'none'`).
+ */
+export declare function artifactCsp(resolution?: AssetResolution, opts?: {
+    allowBaseOrigin?: string;
+}): string;
+/**
+ * Rewrite every workspace-asset URL in a built document according to the
+ * resolution. This is the ONLY url-rewrite exit in both builders — the same
+ * value that produced the CSP produces the URLs.
+ */
+export declare function applyAssetResolution(html: string, resolution?: AssetResolution): string;

package/dist/core/artifact-asset-resolution.js

@@ -0,0 +1,138 @@
+/**
+ * The artifact asset-resolution contract.
+ *
+ * Every artifact render context resolves workspace-asset references in exactly
+ * ONE way, chosen once per render as an explicit `AssetResolution` value:
+ *
+ *   token    — in-app canvas / present + headless Playwright render (PNG/PDF/
+ *              inspect). URLs stay `/api/assets/...` and carry the `?at=`
+ *              capability token; CSP allowlists `<origin>/api/assets/` only.
+ *   share    — public share page. URLs are the token-scoped
+ *              `/api/share/<token>/asset/...` surface; CSP allowlists exactly
+ *              that token's path — never `/api/share/` broadly.
+ *   relative — self-contained HTML export. Bundled refs become relative
+ *              `./assets/...` paths; unbundled refs become labeled inline
+ *              placeholders. CSP carries NO network sources, unconditionally
+ *              (`file:` only, for opening from disk) — an exported file never
+ *              phones home, and a copy hosted on an http origin cannot beacon
+ *              same-origin either.
+ *   none     — no asset access (unsaved previews, tests).
+ *
+ * The one document builder (`buildFrameDocument` in core, used by every surface)
+ * derives the URL rewrite AND the CSP from the SAME resolution value via
+ * `applyAssetResolution` / `artifactCsp`, so a context can never mix models —
+ * "URLs from one scheme, CSP from another" (the share-page broken-images class)
+ * is unrepresentable.
+ *
+ * Fail-closed: a malformed origin or share token yields NO network source and
+ * NO rewrite rather than a permissive or splicable CSP.
+ */
+import { appendAssetToken, rewriteAssetsToRelative, rewriteAssetsToShare, } from './artifact-asset-urls.js';
+/** Normalize + validate an origin for use as a CSP source / URL prefix.
+ *  Returns the bare `scheme://host[:port]` origin, or null when the value
+ *  isn't a plain http(s) origin (fail-closed: no CSP source). */
+function safeOrigin(value) {
+    try {
+        const url = new URL(value);
+        if (url.protocol !== 'http:' && url.protocol !== 'https:')
+            return null;
+        return url.origin;
+    }
+    catch {
+        return null;
+    }
+}
+/** Share tokens are server-minted (`shr_` + base64url), so anything outside
+ *  this charset is not a token — and must never be spliced into a CSP source
+ *  or URL path (`;`/whitespace would terminate the directive; `/`/`..` would
+ *  widen the path scope). */
+const SHARE_TOKEN_RE = /^[A-Za-z0-9._-]+$/;
+export function isValidShareToken(token) {
+    return token.length > 0 && SHARE_TOKEN_RE.test(token);
+}
+/**
+ * The network source expressions (if any) the resolution adds to the asset
+ * CSP directives (`img-src` / `media-src` / `font-src`).
+ *
+ * D4 invariants (pinned by tests):
+ *  - token    → `<origin>/api/assets/` and nothing else
+ *  - share    → `<origin>/api/share/<token>/asset/` (the exact token path)
+ *  - relative → `file:` ONLY, so the bundled `./assets/...` files load when
+ *               the export is opened from disk. Deliberately NOT `'self'`:
+ *               on an http(s)-hosted copy, `'self'` would let artifact JS
+ *               beacon same-origin via img/media/font loads — "no network,
+ *               unconditionally" means a hosted export shows placeholders
+ *               instead (codex P1). A hostable export would be its own
+ *               explicit mode, not a widening of this one.
+ *  - none     → nothing
+ */
+export function artifactCspAssetSources(resolution) {
+    switch (resolution.mode) {
+        case 'token': {
+            const origin = safeOrigin(resolution.origin);
+            return origin ? [`${origin}/api/assets/`] : [];
+        }
+        case 'share': {
+            const origin = safeOrigin(resolution.origin);
+            if (!origin || !isValidShareToken(resolution.shareToken))
+                return [];
+            return [`${origin}/api/share/${resolution.shareToken}/asset/`];
+        }
+        case 'relative':
+            return ['file:'];
+        case 'none':
+            return [];
+    }
+}
+/**
+ * The full iframe/document Content-Security-Policy for an artifact render.
+ * Single definition for BOTH builders (web srcdoc + core HTML export) so the
+ * policy can't drift between contexts. The asset directives are derived from
+ * the resolution; everything else is the fixed sandbox posture (inline + blob
+ * scripts allowed, no eval, no network, no frames/objects/forms).
+ *
+ * `allowBaseOrigin` — the Playwright render path injects `<base href>` so
+ * root-relative asset URLs resolve in a `setContent` document; `base-uri`
+ * must then allow exactly that origin (everything else keeps `'none'`).
+ */
+export function artifactCsp(resolution = { mode: 'none' }, opts = {}) {
+    const sources = artifactCspAssetSources(resolution);
+    const withAsset = (base) => (sources.length ? `${base} ${sources.join(' ')}` : base);
+    const baseOrigin = opts.allowBaseOrigin ? safeOrigin(opts.allowBaseOrigin) : null;
+    return [
+        "default-src 'none'",
+        baseOrigin ? `base-uri ${baseOrigin}` : "base-uri 'none'",
+        "connect-src 'none'",
+        withAsset('font-src data: blob:'),
+        "form-action 'none'",
+        "frame-src 'none'",
+        withAsset('img-src data: blob:'),
+        withAsset('media-src data: blob:'),
+        "object-src 'none'",
+        "script-src 'unsafe-inline' blob:",
+        "style-src 'unsafe-inline'",
+    ].join('; ');
+}
+/**
+ * Rewrite every workspace-asset URL in a built document according to the
+ * resolution. This is the ONLY url-rewrite exit in both builders — the same
+ * value that produced the CSP produces the URLs.
+ */
+export function applyAssetResolution(html, resolution = { mode: 'none' }) {
+    switch (resolution.mode) {
+        case 'token':
+            return resolution.token ? appendAssetToken(html, resolution.token) : html;
+        case 'share':
+            // Fail-closed symmetry: an invalid token produced no CSP source above,
+            // so don't emit URLs either — the refs stay `/api/assets/...`, which the
+            // share CSP blocks (visible as missing images, never as a leak).
+            return isValidShareToken(resolution.shareToken)
+                ? rewriteAssetsToShare(html, resolution.shareToken)
+                : html;
+        case 'relative':
+            return rewriteAssetsToRelative(html, './assets', { bundledKeys: resolution.bundledKeys });
+        case 'none':
+            return html;
+    }
+}
+//# sourceMappingURL=artifact-asset-resolution.js.map

package/dist/core/artifact-asset-resolution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-asset-resolution.js","sourceRoot":"","sources":["../../src/core/artifact-asset-resolution.ts"],"names":[],"mappings":"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"}

package/dist/core/artifact-asset-urls.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Shared parser/rewriter for workspace asset URLs embedded in an artifact
+ * bundle. One implementation behind every surface that has to reason about
+ * `/api/assets/...` references, so they can't drift:
+ *   - mint  → enumerate the exact asset keys an artifact references (allowlist)
+ *   - in-app srcdoc + headless PNG/PDF render → append the `?at=` capability token
+ *   - public share page → rewrite to `/api/share/<token>/asset/...` paths
+ *   - HTML export → rewrite to relative `./assets/...` paths (placeholders for
+ *     anything not bundled)
+ * Which rewrite applies is decided once per render by the `AssetResolution`
+ * contract (artifact-asset-resolution.ts), which derives the CSP from the
+ * same value.
+ *
+ * Matches BOTH forms that appear in bundles:
+ *   - root-relative   `/api/assets/<assetId>/<filename>`
+ *   - absolute        `https://host/api/assets/<assetId>/<filename>`
+ * in any textual context — `<img src>`, `srcset` descriptors, CSS `url(...)`,
+ * inline `style=`, and (acceptably) JS string literals. assetId is a UUID and
+ * the filename segment is percent-encoded by `publicUrlFor`/`publicUrlForAssetId`
+ * (`encodeAssetFilename`) to `[A-Za-z0-9._-]` + `%XX`, so the path never holds a
+ * quote/space/paren even when the stored filename does (e.g. a screenshot named
+ * `page(Desktop 1920x1080) (1).png`) — we can match the URL token directly
+ * without parsing HTML/CSS. (Raw special chars would truncate the match at the
+ * first delimiter, splicing `?at=` into a partial URL → broken sandbox images.)
+ *
+ * Only the IMMUTABLE two-segment scheme is handled. The negative lookahead
+ * after the filename means a legacy three-segment `/api/assets/<type>/<id>/<file>`
+ * URL is left untouched rather than mis-parsed (legacy is out of scope).
+ */
+export interface ArtifactAssetRef {
+    /** The two-segment immutable key: `<assetId>/<filename>`. */
+    key: string;
+    assetId: string;
+    filename: string;
+}
+/**
+ * Decode a URL filename segment back to the RAW stored filename — the canonical
+ * IDENTITY used to match the asset index (`row.filename`), the capability-token
+ * allowlist (`artifactAssetKey`), and the decoded serve-route path param. The URL
+ * segment itself is percent-encoded by `encodeAssetFilename` (e.g. a screenshot
+ * `page(1).png` → `page%281%29.png`); everything that reasons about asset identity
+ * must use this decoded form, or it won't match the raw name the index/serve speak
+ * (which is exactly the encoded-vs-raw mismatch that left special-char images 404).
+ * URL emitters below keep the encoded segment. Falls back to the raw input on a
+ * malformed `%` sequence (never throws).
+ */
+export declare function decodeAssetFilenameSegment(segment: string): string;
+/**
+ * Percent-encode a RAW stored filename into the URL segment form — the single
+ * inverse of {@link decodeAssetFilenameSegment} (encode on emit, decode on
+ * parse). `encodeURIComponent` alone is not enough: it leaves `!~*'()`
+ * unescaped, and `()` are exactly the delimiters `ASSET_URL_RE` rejects — so
+ * encode those too. Result chars ∈ `[A-Za-z0-9._-]` + `%XX`, which the
+ * matcher's filename class accepts; the serve route decodes the path param
+ * back to the raw stored filename, so the round-trip is exact.
+ */
+export declare function encodeAssetFilename(filename: string): string;
+/** Every distinct asset referenced in the text, in first-seen order. `filename`
+ *  and `key` are the DECODED (raw) identity — matchable against the asset index
+ *  and token allowlist — not the percent-encoded URL segment. */
+export declare function findArtifactAssetRefs(text: string): ArtifactAssetRef[];
+/**
+ * Set the `at=<token>` capability param on every asset URL. Preserves any other
+ * existing query params and **replaces** a pre-existing `at` with the fresh
+ * token (so a stale or embedded `?at=` in artifact HTML can't shadow a
+ * freshly-minted render/preview token). Idempotent: re-applying the same token
+ * yields the same string.
+ */
+export declare function appendAssetToken(text: string, token: string): string;
+/**
+ * Single-pass rewrite of every `/api/assets/<id>/<file>` URL in `text` through
+ * `replace`, which receives the decoded ref + the original encoded filename
+ * segment and returns the replacement string (or null to leave that URL as-is).
+ * Uses the one canonical {@link ASSET_URL_RE} grammar, so a font URL that is a
+ * substring of a longer ref can't be corrupted the way a blind string replace
+ * would (the engine matches whole URL tokens, not substrings).
+ */
+export declare function rewriteArtifactAssetUrls(text: string, replace: (ref: ArtifactAssetRef, encodedFilename: string) => string | null): string;
+/**
+ * Rewrite asset URLs to the public-share scheme:
+ * `/api/share/<shareToken>/asset/<assetId>/<filename>`. Used by the share-mode
+ * asset resolution so the document's URLs and its CSP allowlist come from the
+ * same token. The filename segment stays in its encoded URL form. Idempotent:
+ * the output no longer matches the `/api/assets/` grammar, and the server-side
+ * share read may have already rewritten the body — re-applying is a no-op.
+ * Legacy 3-segment URLs aren't matched and pass through unchanged.
+ */
+export declare function rewriteAssetsToShare(text: string, shareToken: string): string;
+/**
+ * A labeled inline placeholder for an asset the export could not bundle
+ * (exporter lacks access / blob missing): a neutral framed box carrying the
+ * filename, as a `data:image/svg+xml` URI so it renders wherever the original
+ * URL appeared (`<img src>`, `srcset`, CSS `url(...)`) under the export's
+ * no-network CSP. Every output char is `%XX`-escaped past encodeURIComponent's
+ * leftovers (`!~*'()`), so the URI never carries a quote/paren/comma that
+ * would terminate an attribute, CSS `url()`, or srcset candidate.
+ */
+export declare function assetPlaceholderDataUri(filename: string): string;
+/**
+ * Rewrite asset URLs for the self-contained HTML export. Refs whose key is in
+ * `bundledKeys` (the assets actually written into the zip) become relative
+ * `./assets/<id>/<file>` (offline-resolvable); any OTHER `/api/assets/...` ref
+ * (exporter lacks access / blob missing — not bundled) becomes an explicit
+ * labeled placeholder. NEVER absolutized back to the workspace: an exported
+ * file must not phone home, and its no-network CSP would block the load anyway
+ * (D11b). With no `bundledKeys` every ref is relativized (caller bundles all
+ * of them). Legacy 3-segment URLs aren't matched and pass through unchanged.
+ */
+export declare function rewriteAssetsToRelative(text: string, baseDir?: string, opts?: {
+    bundledKeys?: Set<string>;
+}): string;

package/dist/core/artifact-asset-urls.js

@@ -0,0 +1,174 @@
+/**
+ * Shared parser/rewriter for workspace asset URLs embedded in an artifact
+ * bundle. One implementation behind every surface that has to reason about
+ * `/api/assets/...` references, so they can't drift:
+ *   - mint  → enumerate the exact asset keys an artifact references (allowlist)
+ *   - in-app srcdoc + headless PNG/PDF render → append the `?at=` capability token
+ *   - public share page → rewrite to `/api/share/<token>/asset/...` paths
+ *   - HTML export → rewrite to relative `./assets/...` paths (placeholders for
+ *     anything not bundled)
+ * Which rewrite applies is decided once per render by the `AssetResolution`
+ * contract (artifact-asset-resolution.ts), which derives the CSP from the
+ * same value.
+ *
+ * Matches BOTH forms that appear in bundles:
+ *   - root-relative   `/api/assets/<assetId>/<filename>`
+ *   - absolute        `https://host/api/assets/<assetId>/<filename>`
+ * in any textual context — `<img src>`, `srcset` descriptors, CSS `url(...)`,
+ * inline `style=`, and (acceptably) JS string literals. assetId is a UUID and
+ * the filename segment is percent-encoded by `publicUrlFor`/`publicUrlForAssetId`
+ * (`encodeAssetFilename`) to `[A-Za-z0-9._-]` + `%XX`, so the path never holds a
+ * quote/space/paren even when the stored filename does (e.g. a screenshot named
+ * `page(Desktop 1920x1080) (1).png`) — we can match the URL token directly
+ * without parsing HTML/CSS. (Raw special chars would truncate the match at the
+ * first delimiter, splicing `?at=` into a partial URL → broken sandbox images.)
+ *
+ * Only the IMMUTABLE two-segment scheme is handled. The negative lookahead
+ * after the filename means a legacy three-segment `/api/assets/<type>/<id>/<file>`
+ * URL is left untouched rather than mis-parsed (legacy is out of scope).
+ */
+// g1 origin (optional, host has no slash) · g2 assetId · g3 filename · g4 query (incl leading ?)
+// The (?![A-Za-z0-9._%/-]) after the filename forbids ANY trailing path char so
+// the engine can't backtrack the filename into a partial segment — that both
+// stops mid-segment matches and leaves legacy 3-segment URLs untouched.
+const ASSET_URL_RE = /(https?:\/\/[^\s"'()<>\/]+)?\/api\/assets\/([A-Za-z0-9._%-]+)\/([A-Za-z0-9._%-]+)(?![A-Za-z0-9._%/-])(\?[^\s"'()<>]*)?/g;
+/**
+ * Decode a URL filename segment back to the RAW stored filename — the canonical
+ * IDENTITY used to match the asset index (`row.filename`), the capability-token
+ * allowlist (`artifactAssetKey`), and the decoded serve-route path param. The URL
+ * segment itself is percent-encoded by `encodeAssetFilename` (e.g. a screenshot
+ * `page(1).png` → `page%281%29.png`); everything that reasons about asset identity
+ * must use this decoded form, or it won't match the raw name the index/serve speak
+ * (which is exactly the encoded-vs-raw mismatch that left special-char images 404).
+ * URL emitters below keep the encoded segment. Falls back to the raw input on a
+ * malformed `%` sequence (never throws).
+ */
+export function decodeAssetFilenameSegment(segment) {
+    try {
+        return decodeURIComponent(segment);
+    }
+    catch {
+        return segment;
+    }
+}
+/**
+ * Percent-encode a RAW stored filename into the URL segment form — the single
+ * inverse of {@link decodeAssetFilenameSegment} (encode on emit, decode on
+ * parse). `encodeURIComponent` alone is not enough: it leaves `!~*'()`
+ * unescaped, and `()` are exactly the delimiters `ASSET_URL_RE` rejects — so
+ * encode those too. Result chars ∈ `[A-Za-z0-9._-]` + `%XX`, which the
+ * matcher's filename class accepts; the serve route decodes the path param
+ * back to the raw stored filename, so the round-trip is exact.
+ */
+export function encodeAssetFilename(filename) {
+    return encodeURIComponent(filename).replace(/[!~*'()]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+/** Every distinct asset referenced in the text, in first-seen order. `filename`
+ *  and `key` are the DECODED (raw) identity — matchable against the asset index
+ *  and token allowlist — not the percent-encoded URL segment. */
+export function findArtifactAssetRefs(text) {
+    const seen = new Map();
+    for (const m of text.matchAll(ASSET_URL_RE)) {
+        const assetId = m[2];
+        const filename = decodeAssetFilenameSegment(m[3]);
+        const key = `${assetId}/${filename}`;
+        if (!seen.has(key))
+            seen.set(key, { key, assetId, filename });
+    }
+    return [...seen.values()];
+}
+/**
+ * Set the `at=<token>` capability param on every asset URL. Preserves any other
+ * existing query params and **replaces** a pre-existing `at` with the fresh
+ * token (so a stale or embedded `?at=` in artifact HTML can't shadow a
+ * freshly-minted render/preview token). Idempotent: re-applying the same token
+ * yields the same string.
+ */
+export function appendAssetToken(text, token) {
+    const enc = encodeURIComponent(token);
+    return text.replace(ASSET_URL_RE, (_full, origin, assetId, filename, query) => {
+        const base = `${origin ?? ''}/api/assets/${assetId}/${filename}`;
+        const params = query ? query.slice(1).split('&').filter((p) => p && !/^at=/i.test(p)) : [];
+        params.push(`at=${enc}`);
+        return `${base}?${params.join('&')}`;
+    });
+}
+/**
+ * Single-pass rewrite of every `/api/assets/<id>/<file>` URL in `text` through
+ * `replace`, which receives the decoded ref + the original encoded filename
+ * segment and returns the replacement string (or null to leave that URL as-is).
+ * Uses the one canonical {@link ASSET_URL_RE} grammar, so a font URL that is a
+ * substring of a longer ref can't be corrupted the way a blind string replace
+ * would (the engine matches whole URL tokens, not substrings).
+ */
+export function rewriteArtifactAssetUrls(text, replace) {
+    return text.replace(ASSET_URL_RE, (full, _origin, assetId, filename) => {
+        const decoded = decodeAssetFilenameSegment(filename);
+        const out = replace({ key: `${assetId}/${decoded}`, assetId, filename: decoded }, filename);
+        return out ?? full;
+    });
+}
+/**
+ * Rewrite asset URLs to the public-share scheme:
+ * `/api/share/<shareToken>/asset/<assetId>/<filename>`. Used by the share-mode
+ * asset resolution so the document's URLs and its CSP allowlist come from the
+ * same token. The filename segment stays in its encoded URL form. Idempotent:
+ * the output no longer matches the `/api/assets/` grammar, and the server-side
+ * share read may have already rewritten the body — re-applying is a no-op.
+ * Legacy 3-segment URLs aren't matched and pass through unchanged.
+ */
+export function rewriteAssetsToShare(text, shareToken) {
+    return text.replace(ASSET_URL_RE, (_full, _origin, assetId, filename) => `/api/share/${shareToken}/asset/${assetId}/${filename}`);
+}
+/** Escape text for embedding inside an SVG source string. */
+function escapeXml(s) {
+    return s.replace(/[&<>"']/g, (c) => c === '&' ? '&amp;' : c === '<' ? '&lt;' : c === '>' ? '&gt;' : c === '"' ? '&quot;' : '&#39;');
+}
+/**
+ * A labeled inline placeholder for an asset the export could not bundle
+ * (exporter lacks access / blob missing): a neutral framed box carrying the
+ * filename, as a `data:image/svg+xml` URI so it renders wherever the original
+ * URL appeared (`<img src>`, `srcset`, CSS `url(...)`) under the export's
+ * no-network CSP. Every output char is `%XX`-escaped past encodeURIComponent's
+ * leftovers (`!~*'()`), so the URI never carries a quote/paren/comma that
+ * would terminate an attribute, CSS `url()`, or srcset candidate.
+ */
+export function assetPlaceholderDataUri(filename) {
+    const label = filename.length > 48 ? `${filename.slice(0, 45)}…` : filename;
+    const svg = '<svg xmlns="http://www.w3.org/2000/svg" width="640" height="360" viewBox="0 0 640 360">' +
+        '<rect width="640" height="360" fill="#f4f4f4"/>' +
+        '<rect x="0.5" y="0.5" width="639" height="359" fill="none" stroke="#d0d0d0"/>' +
+        '<g fill="#8a8a8a" font-family="system-ui, -apple-system, sans-serif" text-anchor="middle">' +
+        '<text x="320" y="168" font-size="15">Image not included in export</text>' +
+        `<text x="320" y="196" font-size="13">${escapeXml(label)}</text>` +
+        '</g></svg>';
+    // encodeAssetFilename is the strict percent-encoder (encodeURIComponent +
+    // the `!~*'()` leftovers) — exactly the delimiter-free guarantee the URI
+    // needs, applied to the whole SVG payload.
+    return `data:image/svg+xml,${encodeAssetFilename(svg)}`;
+}
+/**
+ * Rewrite asset URLs for the self-contained HTML export. Refs whose key is in
+ * `bundledKeys` (the assets actually written into the zip) become relative
+ * `./assets/<id>/<file>` (offline-resolvable); any OTHER `/api/assets/...` ref
+ * (exporter lacks access / blob missing — not bundled) becomes an explicit
+ * labeled placeholder. NEVER absolutized back to the workspace: an exported
+ * file must not phone home, and its no-network CSP would block the load anyway
+ * (D11b). With no `bundledKeys` every ref is relativized (caller bundles all
+ * of them). Legacy 3-segment URLs aren't matched and pass through unchanged.
+ */
+export function rewriteAssetsToRelative(text, baseDir = './assets', opts = {}) {
+    const prefix = baseDir.replace(/\/+$/, '');
+    return text.replace(ASSET_URL_RE, (_full, _origin, assetId, filename) => {
+        // `bundledKeys` are DECODED identity keys (artifactAssetKey over the raw
+        // filename), so decode the URL segment to look them up; the rewritten URL
+        // itself keeps the encoded segment (the browser decodes it back to the
+        // raw on-disk path in the export zip).
+        const raw = decodeAssetFilenameSegment(filename);
+        if (!opts.bundledKeys || opts.bundledKeys.has(`${assetId}/${raw}`)) {
+            return `${prefix}/${assetId}/${filename}`;
+        }
+        return assetPlaceholderDataUri(raw);
+    });
+}
+//# sourceMappingURL=artifact-asset-urls.js.map

package/dist/core/artifact-asset-urls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-asset-urls.js","sourceRoot":"","sources":["../../src/core/artifact-asset-urls.ts"],"names":[],"mappings":"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"}

package/dist/core/artifact-bundle.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Shared contract for agent-produced canvas artifacts.
+ *
+ * V1 is deliberately text-only: HTML, CSS, JS, SVG, JSON, and plain text files.
+ * Binary assets and network-dependent files are follow-up work, because this
+ * bundle is persisted in chat message metadata and rendered in a sandboxed
+ * iframe.
+ */
+export declare const ARTIFACT_BUNDLE_SCHEMA_VERSION = 1;
+export declare const ARTIFACT_BUNDLE_MAX_BYTES: number;
+export declare const ARTIFACT_KINDS: readonly ["html", "document", "slides", "social", "app", "custom"];
+export type ArtifactKind = typeof ARTIFACT_KINDS[number];
+export declare const ARTIFACT_VIEWPORT_MODES: readonly ["fixed", "responsive", "paged"];
+export type ArtifactViewportMode = typeof ARTIFACT_VIEWPORT_MODES[number];
+export declare const ARTIFACT_FULLSCREEN_FITS: readonly ["contain", "width", "none"];
+export type ArtifactFullscreenFit = typeof ARTIFACT_FULLSCREEN_FITS[number];
+export declare const ARTIFACT_DISPLAY_BACKGROUNDS: readonly ["neutral", "transparent"];
+export type ArtifactDisplayBackground = typeof ARTIFACT_DISPLAY_BACKGROUNDS[number];
+export declare const ARTIFACT_LIBRARY_KEYS: readonly ["three", "d3", "motion"];
+export type ArtifactLibraryKey = typeof ARTIFACT_LIBRARY_KEYS[number];
+export interface ArtifactDisplayViewport {
+    width: number;
+    height: number;
+}
+export interface ArtifactDisplayStepperControl {
+    selector?: string;
+    label?: string;
+}
+export interface ArtifactDisplayControls {
+    stepper?: ArtifactDisplayStepperControl;
+    reset?: boolean;
+}
+export interface ArtifactViewport {
+    width: number;
+    height: number;
+    mode: ArtifactViewportMode;
+}
+export interface ArtifactDisplay {
+    fullscreenFit?: ArtifactFullscreenFit;
+    background?: ArtifactDisplayBackground;
+    fullscreenViewport?: ArtifactDisplayViewport;
+    controls?: ArtifactDisplayControls;
+}
+export interface ArtifactSource {
+    repo?: string;
+    entityType?: string;
+    entityId?: string;
+    skillId?: string;
+}
+export interface ArtifactBundle {
+    schemaVersion: typeof ARTIFACT_BUNDLE_SCHEMA_VERSION;
+    artifactId: string;
+    title: string;
+    kind: ArtifactKind;
+    viewport: ArtifactViewport;
+    display?: ArtifactDisplay;
+    libraries?: ArtifactLibraryKey[];
+    files: Record<string, string>;
+    entrypoint: string;
+    source?: ArtifactSource;
+}
+export interface ArtifactValidationResult {
+    ok: boolean;
+    bundle?: ArtifactBundle;
+    errors: string[];
+    byteSize: number;
+}
+export declare function validateArtifactBundle(input: unknown): ArtifactValidationResult;
+export declare function assertArtifactBundle(input: unknown): ArtifactBundle;