@joewinke/jatui 0.37.0 → 0.38.1

package/dist/artifact-blocks/blocks/media-picker/types.js

@@ -0,0 +1 @@
+export {};

package/dist/artifact-blocks/blocks/media-picker/versions.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Versions vs views for the media-picker (mos-0wvol).
+ *
+ * A review round's variants mix two different things: VERSIONS of the asset
+ * (v6 under review, v5 as last reviewed) and VIEWS of one version (the loop,
+ * an old-vs-new strip, a water-over-time map). Shown as one flat filmstrip
+ * the caption read "1 of 4 · v6 · v6" — meaningless. These helpers split an
+ * item into versions (newest first, the one under review marked) and, inside
+ * a version, labelled views.
+ *
+ * Pure: no DOM, no Svelte — the component and the tests share them.
+ * Backward compatible: an item whose variants carry fewer than two distinct
+ * versions has no version row (`versionsOf` returns []), exactly as before.
+ */
+import type { MediaItem, MediaVariant } from "./types.js";
+/** The version under review: explicit, else the first versioned variant's. */
+export declare function currentVersionOf(item: MediaItem): string | null;
+/** Which version a variant belongs to. Unversioned variants sit with the
+ * version under review (they are views of what is being judged). */
+export declare function versionOfVariant(item: MediaItem, variant: MediaVariant): string | null;
+/**
+ * Versions in display order: the one under review first, then the others
+ * in the order the publisher listed them (review-kit puts the newest first).
+ * Fewer than two distinct versions → [] (no switcher; render as before).
+ */
+export declare function versionsOf(item: MediaItem): string[];
+/** The views (variants) of one version; with no versions, every variant. */
+export declare function viewsOf(item: MediaItem, version: string | null): MediaVariant[];
+/**
+ * A view's human label with the redundant version prefix stripped:
+ * "v6" on a v6 video → "Loop"; "v6 · strip" → "strip"; "v5 (as reviewed)"
+ * → "Loop (as reviewed)". A label that says something else is kept as is.
+ */
+export declare function cleanViewLabel(label: string | undefined | null, version: string | undefined | null, kind: MediaVariant["kind"]): string;
+/** The label a view thumbnail and the caption show. */
+export declare function viewLabel(item: MediaItem, variant: MediaVariant): string;
+/**
+ * The card caption under the media:
+ *   versioned → "v6 (reviewing) · Loop · 1 of 3" / "v5 (previous) · Loop · 1 of 1"
+ *   flat      → "1 of 4 · warm" (as before, minus a label that only repeats the version)
+ */
+export declare function captionFor(item: MediaItem, variant: MediaVariant, version: string | null): string;
+/**
+ * "Your verdict then: needs work. Note: “water not natural”" (or a no-record
+ * line). Takes the locked round line for the version (viewer or publisher
+ * history, merged by ../../review/rounds.ts).
+ */
+export declare function historyLine(h: {
+    verdict?: string | null;
+    note?: string | null;
+} | null | undefined): string;

package/dist/artifact-blocks/blocks/media-picker/versions.js

@@ -0,0 +1,118 @@
+/** The version under review: explicit, else the first versioned variant's. */
+export function currentVersionOf(item) {
+    if (item.currentVersion)
+        return item.currentVersion;
+    return item.variants.find((v) => v.version)?.version ?? null;
+}
+/** Which version a variant belongs to. Unversioned variants sit with the
+ * version under review (they are views of what is being judged). */
+export function versionOfVariant(item, variant) {
+    return variant.version ?? currentVersionOf(item);
+}
+/**
+ * Versions in display order: the one under review first, then the others
+ * in the order the publisher listed them (review-kit puts the newest first).
+ * Fewer than two distinct versions → [] (no switcher; render as before).
+ */
+export function versionsOf(item) {
+    const cur = currentVersionOf(item);
+    if (!cur)
+        return [];
+    const seen = [cur];
+    for (const v of item.variants) {
+        const ver = v.version ?? cur;
+        if (!seen.includes(ver))
+            seen.push(ver);
+    }
+    return seen.length > 1 ? seen : [];
+}
+/** The views (variants) of one version; with no versions, every variant. */
+export function viewsOf(item, version) {
+    if (versionsOf(item).length === 0 || version == null)
+        return item.variants;
+    return item.variants.filter((v) => versionOfVariant(item, v) === version);
+}
+const KIND_VIEW = {
+    video: "Loop",
+    image: "Still",
+    audio: "Audio",
+};
+/**
+ * A view's human label with the redundant version prefix stripped:
+ * "v6" on a v6 video → "Loop"; "v6 · strip" → "strip"; "v5 (as reviewed)"
+ * → "Loop (as reviewed)". A label that says something else is kept as is.
+ */
+export function cleanViewLabel(label, version, kind) {
+    const fallback = KIND_VIEW[kind];
+    let s = (label ?? "").trim();
+    if (version) {
+        const v = version.trim();
+        // repeat: an older spec may carry "v6 · v6"
+        for (let guard = 0; guard < 3 && v; guard++) {
+            if (s.toLowerCase() === v.toLowerCase()) {
+                s = "";
+                break;
+            }
+            if (s.toLowerCase().startsWith(v.toLowerCase())) {
+                const rest = s.slice(v.length);
+                if (/^[\s·:\-—–|/]/.test(rest) || rest.startsWith("(")) {
+                    s = rest.replace(/^[\s·:\-—–|/]+/, "").trim();
+                    continue;
+                }
+            }
+            break;
+        }
+    }
+    if (!s)
+        return fallback;
+    if (/^\(.*\)$/.test(s))
+        return `${fallback} ${s}`;
+    return s;
+}
+/** The label a view thumbnail and the caption show. */
+export function viewLabel(item, variant) {
+    const versioned = versionsOf(item).length > 0;
+    const version = versioned ? versionOfVariant(item, variant) : variant.version;
+    return cleanViewLabel(variant.label ?? variant.id, version, variant.kind);
+}
+/**
+ * The card caption under the media:
+ *   versioned → "v6 (reviewing) · Loop · 1 of 3" / "v5 (previous) · Loop · 1 of 1"
+ *   flat      → "1 of 4 · warm" (as before, minus a label that only repeats the version)
+ */
+export function captionFor(item, variant, version) {
+    const versions = versionsOf(item);
+    if (versions.length > 0 && version) {
+        const views = viewsOf(item, version);
+        const idx = Math.max(0, views.findIndex((v) => v.id === variant.id));
+        const role = version === currentVersionOf(item) ? "reviewing" : "previous";
+        return `${version} (${role}) · ${viewLabel(item, variant)} · ${idx + 1} of ${views.length}`;
+    }
+    const idx = Math.max(0, item.variants.findIndex((v) => v.id === variant.id));
+    const head = `${idx + 1} of ${item.variants.length}`;
+    const raw = variant.label?.trim();
+    if (!raw)
+        return head;
+    const label = variant.version && raw.toLowerCase() === variant.version.toLowerCase()
+        ? raw
+        : cleanViewLabel(raw, variant.version, variant.kind);
+    return `${head} · ${label}`;
+}
+const VERDICT_WORD = {
+    approve: "approved",
+    redo: "needs work",
+    reject: "rejected",
+};
+/**
+ * "Your verdict then: needs work. Note: “water not natural”" (or a no-record
+ * line). Takes the locked round line for the version (viewer or publisher
+ * history, merged by ../../review/rounds.ts).
+ */
+export function historyLine(h) {
+    if (!h || (!h.verdict && !h.note))
+        return "No verdict was recorded for this version.";
+    const word = h.verdict ? (VERDICT_WORD[h.verdict] ?? h.verdict) : "a note";
+    return h.note
+        ? `Your verdict then: ${word}. Note: “${h.note}”`
+        : `Your verdict then: ${word}`;
+}

package/dist/artifact-blocks/blocks/mockup/MockupBlock.svelte

@@ -0,0 +1,247 @@
+<script lang="ts">
+  /**
+   * MockupBlock — agent-authored HTML in device frames (mos-vzame).
+   *
+   * Each variant renders inside its own iframe. The iframe's sandbox
+   * attribute comes from mockupSandboxAttr() in ./sandbox.ts — the artifact
+   * sandbox's token list (a host may override it via services.sandboxAttr),
+   * which NEVER includes allow-same-origin (see that module for the threat
+   * model: opaque origin, no session, no cookies, no parent DOM). Scripts run
+   * only when the author passed allowScripts, and even then inside the opaque
+   * origin, with `sandbox="allow-scripts"` only and a no-beacon CSP in the
+   * document (jat-4yffn) — plus a "runs scripts" notice drawn HERE, in the
+   * parent, where the script cannot reach or restyle it. Scripts also need
+   * the HOST's word that its page enforces `frame-src 'self'`
+   * (`services.framePolicy.frameSrcSelfEnforced`, jatui-2qhbr): without it a
+   * script could navigate its own frame to an attacker URL, so the mockup
+   * renders script-free under a "scripts disabled" notice instead.
+   * referrerpolicy="no-referrer" mirrors ArtifactShell.
+   *
+   * The frame is a scaled viewport: the iframe is laid out at the DEVICE's
+   * pixel width and transform-scaled to the column, so a "desktop" mockup is
+   * laid out at 1440px even on a phone screen — not reflowed to column width.
+   * bind:clientWidth measures the wrapper; the scale correction lands on
+   * hydrate, so server HTML ships a sensible default.
+   *
+   * The theme toggle passes data-theme=light|dark into every fragment (see
+   * ./doc.ts) — the snippet's own CSS decides what the attribute means.
+   */
+  import { mockupSandboxAttr, mockupScriptsAllowed } from "./sandbox.js"
+  import type { BlockProps } from "../../types.js"
+  import { mockupDocument } from "./doc.js"
+  import {
+    MOCKUP_DIMS,
+    type MockupDevice,
+    type MockupDims,
+    type MockupParams,
+  } from "./types.js"
+  import SectionTools from "../../SectionTools.svelte"
+
+  let { params, ctx }: BlockProps<MockupParams> = $props()
+
+  let theme = $state<"light" | "dark">("light")
+  /** Measured on-screen width of each frame's viewport, by variant id. */
+  let frameWidths = $state<Record<string, number>>({})
+
+  const requested = $derived(params.allowScripts === true)
+  const scripted = $derived(
+    mockupScriptsAllowed(requested, ctx?.services?.framePolicy),
+  )
+  /** Asked for scripts, but the host has not asserted frame-src 'self'. */
+  const scriptsBlocked = $derived(requested && !scripted)
+  const sandbox = $derived(
+    mockupSandboxAttr(scripted, ctx?.services?.sandboxAttr),
+  )
+
+  /**
+   * Normalize any device value to a real MockupDevice (mos-659rz): the
+   * schema now guarantees a variant carries one, but a stale or malformed
+   * params object (history restored, a value the schema once accepted) must
+   * render a frame — anything unknown falls back to desktop, never to
+   * MOCKUP_DIMS[undefined].maxFrameW.
+   */
+  function deviceOf(device: unknown): MockupDevice {
+    return typeof device === "string" && device in MOCKUP_DIMS
+      ? (device as MockupDevice)
+      : "desktop"
+  }
+
+  /** Device dims — never undefined (mos-659rz): an unknown value falls back
+   * to desktop dims instead of crashing on `.maxFrameW`. */
+  function dims(device: unknown): MockupDims {
+    return MOCKUP_DIMS[deviceOf(device)] ?? MOCKUP_DIMS.desktop
+  }
+
+  /** device px → screen px for this frame (falls back to the frame cap). */
+  function scale(id: string, device: unknown): number {
+    const d = dims(device)
+    const measured = frameWidths[id]
+    const w = measured && measured > 0 ? measured : d.maxFrameW
+    return w / d.w
+  }
+
+  function frameStyle(id: string, device: unknown): string {
+    const d = dims(device)
+    return `max-width:${d.maxFrameW}px;aspect-ratio:${d.w}/${d.h};`
+  }
+</script>
+
+<section
+  class="border-base-content/10 bg-base-100 rounded-box border"
+  aria-label={params.title ?? "Mockup"}
+>
+  <header
+    class="flex flex-wrap items-center gap-x-3 gap-y-2 px-4 pt-4 pb-1 sm:px-5"
+  >
+    <div class="min-w-0 flex-1">
+      {#if params.title}
+        <h2 class="text-lg font-semibold tracking-tight">{params.title}</h2>
+      {/if}
+      {#if params.intro}
+        <p class="text-base-content/60 mt-0.5 text-sm whitespace-pre-line">
+          {params.intro}
+        </p>
+      {/if}
+    </div>
+    <!-- Light / dark toggle: re-wraps every fragment with data-theme -->
+    <div
+      class="flex items-center gap-1"
+      role="group"
+      aria-label="Preview theme"
+    >
+      <button
+        type="button"
+        class="btn btn-xs rounded-field {theme === 'light'
+          ? 'btn-primary'
+          : 'border-base-content/10 bg-transparent text-base-content/70'}"
+        aria-pressed={theme === "light"}
+        onclick={() => (theme = "light")}
+      >
+        Light
+      </button>
+      <button
+        type="button"
+        class="btn btn-xs rounded-field {theme === 'dark'
+          ? 'btn-primary'
+          : 'border-base-content/10 bg-transparent text-base-content/70'}"
+        aria-pressed={theme === "dark"}
+        onclick={() => (theme = "dark")}
+      >
+        Dark
+      </button>
+    </div>
+    <SectionTools {ctx} inline />
+  </header>
+
+  {#if scripted}
+    <!-- Parent-drawn label (jat-4yffn): the frame's script cannot touch it. -->
+    <p
+      class="border-warning/40 bg-warning/10 text-base-content/80 rounded-field mx-4 mt-2 border px-3 py-2 text-xs sm:mx-5"
+      data-mockup-scripted
+    >
+      <strong class="font-semibold">This mockup runs scripts.</strong>
+      It is a sketch, not a real form — never type a password or a code into it.
+    </p>
+  {:else if scriptsBlocked}
+    <!-- jatui-2qhbr: degraded to script-free; say so, never fail silently. -->
+    <p
+      class="border-base-content/15 bg-base-200 text-base-content/70 rounded-field mx-4 mt-2 border px-3 py-2 text-xs sm:mx-5"
+      data-mockup-scripts-disabled
+    >
+      <strong class="font-semibold">Scripts disabled:</strong>
+      this host page does not restrict frame navigation, so the mockup is shown
+      without its interactive parts.
+    </p>
+  {/if}
+
+  <div class="flex flex-wrap items-start gap-5 px-4 pt-2 pb-5 sm:px-5">
+    {#each params.variants as v (v.id)}
+      {@const dev = deviceOf(v.device)}
+      {@const d = dims(dev)}
+      {@const s = scale(v.id, dev)}
+      <figure class="m-0">
+        <!-- Frame chrome per device; the viewport inside is the scaled iframe. -->
+        <div
+          class="relative mx-auto"
+          style={frameStyle(v.id, dev)}
+          bind:clientWidth={frameWidths[v.id]}
+        >
+          {#if dev === "desktop"}
+            <!-- Browser chrome -->
+            <div
+              class="border-base-content/15 bg-base-200 rounded-box overflow-hidden border"
+              style="height:100%"
+            >
+              <div
+                class="border-base-content/10 flex items-center gap-2 border-b px-3 py-1.5"
+              >
+                <span class="flex gap-1" aria-hidden="true">
+                  <span class="bg-error size-2 rounded-full"></span>
+                  <span class="bg-warning size-2 rounded-full"></span>
+                  <span class="bg-success size-2 rounded-full"></span>
+                </span>
+                <span
+                  class="bg-base-100 border-base-content/10 text-base-content/50 mx-auto rounded-field max-w-[60%] flex-1 truncate px-2 py-0.5 text-center text-2xs"
+                  aria-hidden="true"
+                >
+                  {v.label ?? v.id}
+                </span>
+              </div>
+              <iframe
+                data-mock-id={v.id}
+                srcdoc={mockupDocument(v.html, theme, scripted)}
+                {sandbox}
+                title="{v.label ?? v.id} — desktop preview"
+                referrerpolicy="no-referrer"
+                loading="lazy"
+                style="width:{d.w}px;height:{d.h -
+                  30 / s}px;transform:scale({s});transform-origin:0 0;border:0;"
+              ></iframe>
+            </div>
+          {:else}
+            <!-- Phone / tablet chrome: bezel + notch or camera dot -->
+            <div
+              class="bg-base-300 border-base-content/15 relative h-full overflow-hidden {dev ===
+              'phone'
+                ? 'rounded-[2.25rem] border-[6px]'
+                : 'rounded-[1.5rem] border-[8px]'}"
+            >
+              <span
+                class="bg-base-content/20 absolute top-2 left-1/2 h-1.5 w-16 -translate-x-1/2 rounded-full {dev ===
+                'tablet'
+                  ? 'hidden'
+                  : ''}"
+                aria-hidden="true"
+              ></span>
+              <span
+                class="bg-base-content/20 absolute top-2.5 left-3 size-1.5 rounded-full {dev ===
+                'phone'
+                  ? 'hidden'
+                  : ''}"
+                aria-hidden="true"
+              ></span>
+              <iframe
+                data-mock-id={v.id}
+                srcdoc={mockupDocument(v.html, theme, scripted)}
+                {sandbox}
+                title="{v.label ?? v.id} — {dev} preview"
+                referrerpolicy="no-referrer"
+                loading="lazy"
+                style="width:{d.w}px;height:{d.h}px;transform:scale({s});transform-origin:0 0;border:0;"
+              ></iframe>
+            </div>
+          {/if}
+        </div>
+        <figcaption
+          class="text-base-content/60 mt-1.5 text-center text-xs tabular-nums"
+        >
+          {v.label ?? v.id}
+          <span class="text-base-content/40">
+            &middot; {dev}
+            {d.w}&times;{d.h}
+          </span>
+        </figcaption>
+      </figure>
+    {/each}
+  </div>
+</section>

package/dist/artifact-blocks/blocks/mockup/MockupBlock.svelte.d.ts

@@ -0,0 +1,5 @@
+import type { BlockProps } from "../../types.js";
+import { type MockupParams } from "./types.js";
+declare const MockupBlock: import("svelte").Component<BlockProps<MockupParams>, {}, "">;
+type MockupBlock = ReturnType<typeof MockupBlock>;
+export default MockupBlock;

package/dist/artifact-blocks/blocks/mockup/block.d.ts

@@ -0,0 +1,27 @@
+/**
+ * mockup — agent-authored HTML shown in device frames (mos-vzame, epic
+ * mos-m1qrx).
+ *
+ * Params are DATA: one or more variants, each an HTML snippet rendered
+ * verbatim inside a sandboxed iframe shaped like a phone, tablet, or desktop
+ * frame. The iframe's sandbox attribute comes from `mockupSandboxAttr()` in
+ * ./sandbox.ts and allow-same-origin is NEVER emitted: the frame is an
+ * opaque origin with no session, no cookies, no parent DOM (see that module
+ * for the threat model). Scripts stay off unless `allowScripts` is true, and
+ * then the frame is `allow-scripts` only — no popups, no remote images or
+ * media, no network (jat-4yffn) — under a parent-drawn "runs scripts" notice,
+ * and only on a host that asserts an enforced `frame-src 'self'`
+ * (`services.framePolicy`, jatui-2qhbr); elsewhere it degrades to script-free.
+ *
+ * The light/dark toggle re-wraps fragments with `data-theme` on <html> (see
+ * ./doc.ts); the snippet's own CSS decides what that attribute means.
+ *
+ * Use it when the artifact IS a design artifact: a homepage concept, a
+ * component state exploration, an email template. One-line tip: publish each
+ * design option as its own variant (side by side) rather than a separate
+ * block per option — reviewers compare them at a glance.
+ */
+import type { ArtifactBlockDef } from "../../types.js";
+import type { MockupParams } from "./types.js";
+declare const mockup: ArtifactBlockDef<MockupParams>;
+export default mockup;

package/dist/artifact-blocks/blocks/mockup/block.js

@@ -0,0 +1,52 @@
+import { mockupSchema } from "./schema.js";
+import MockupBlock from "./MockupBlock.svelte";
+const example = {
+    title: "Checkout — concept A/B",
+    intro: "Same flow, two treatments. Toggle the theme to check both.",
+    variants: [
+        {
+            id: "a-phone",
+            label: "Concept A",
+            device: "phone",
+            html: `<main style="font:16px/1.5 system-ui;padding:24px">
+  <h1 style="font-size:20px;margin:0 0 8px">Checkout</h1>
+  <p style="margin:0 0 16px;color:#666">Concept A — single column</p>
+  <div style="height:44px;border-radius:12px;background:#eee"></div>
+</main>`,
+        },
+        {
+            id: "b-phone",
+            label: "Concept B",
+            device: "phone",
+            html: `<main style="font:16px/1.5 system-ui;padding:24px">
+  <h1 style="font-size:20px;margin:0 0 8px">Checkout</h1>
+  <p style="margin:0 0 16px;color:#666">Concept B — summary card</p>
+  <div style="height:44px;border-radius:12px;background:#ddd"></div>
+</main>`,
+        },
+        {
+            id: "a-desktop",
+            label: "Concept A · desktop",
+            device: "desktop",
+            html: `<main style="font:16px/1.5 system-ui;padding:48px;max-width:960px">
+  <h1 style="font-size:28px;margin:0 0 12px">Checkout — desktop</h1>
+  <div style="display:flex;gap:24px">
+    <div style="flex:1;height:180px;border-radius:12px;background:#eee"></div>
+    <div style="width:280px;height:180px;border-radius:12px;background:#ddd"></div>
+  </div>
+</main>`,
+        },
+    ],
+};
+const mockup = {
+    type: "mockup",
+    title: "Mockup (sandboxed HTML in device frames)",
+    description: "Renders agent-authored HTML snippets inside phone, tablet, or desktop device frames — the way to put a UI concept into an artifact WITHOUT giving that HTML the page's origin: each variant is an iframe whose sandbox attribute comes from the artifact sandbox module (opaque origin, allow-same-origin never emitted, scripts only when allowScripts is true), so the mockup can never touch the session. allowScripts is for interaction only and is locked down: the frame gets no popups (links that open a new tab do nothing), no network, and images/media/fonts only as data: URIs (Google Fonts excepted), and the page shows a \"runs scripts\" notice above it; scripts also need the host to assert an enforced frame-src 'self', and on a host that does not, the mockup renders script-free under a \"scripts disabled\" notice — leave it off unless the concept needs JS. Pass a FRAGMENT per variant; the block wraps it and drives data-theme=light|dark on <html> so the block-level theme toggle re-skins designs that honor the attribute (a full document passes through unwrapped and owns its own theming). Variants render side by side for A/B comparison. A top-level `device` param is shorthand: it becomes the device of every variant that does not name its own (a variant's own device wins); a variant without any device defaults to phone. Budget: 48KB of HTML per variant, 256KB for the whole block. One-line tip: name variant ids after the option they show (a-phone, b-phone) — reviewers reference them in notes.",
+    schema: mockupSchema,
+    component: MockupBlock,
+    // mos-8fvt9: the section's Listen + comment sit on the heading row.
+    hostsTools: () => true,
+    example,
+    reviewableByDefault: true,
+};
+export default mockup;

package/dist/artifact-blocks/blocks/mockup/doc.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The sandboxed document a mockup iframe renders (mos-vzame).
+ *
+ * The iframe gets its sandbox from mockupSandboxAttr() in ./sandbox.ts.
+ * allow-same-origin is absent in every mode that helper can emit; the frame
+ * is an opaque origin and can never reach the app session, cookies, or DOM.
+ * That module is the single source of truth for the boundary and its threat
+ * model — this file decides WHAT the opaque-origin document contains, and
+ * for a SCRIPTED mockup that includes the policy head (jat-4yffn):
+ * MOCKUP_SCRIPTED_CSP as a `<meta http-equiv>` plus DNS prefetch off. A
+ * srcdoc document has no response headers, so meta is the only carrier. It
+ * is the first element in <head> (before <meta charset>, which only has to
+ * sit in the first 1024 bytes — the policy head is well under that), so it
+ * governs everything the author wrote, and a script removing the element
+ * later does not lift an applied policy.
+ *
+ * Whether a mockup is rendered scripted at all is decided by the caller
+ * (mockupScriptsAllowed in ./sandbox.ts, jatui-2qhbr): this function trusts
+ * its `scripted` argument and emits the policy head for it.
+ *
+ * The light/dark toggle works by re-wrapping the snippet with `data-theme` on
+ * the <html> element — the author's CSS decides what that attribute means
+ * (DaisyUI themes, Tailwind `dark:` with a data-theme selector, hand CSS).
+ * A full document (one that already has <html>) passes through untouched:
+ * rewriting untrusted markup by regex is exactly the fragility this block
+ * refuses; authors who bring their own document own their own theming.
+ */
+/**
+ * Wrap a mockup snippet into a full document carrying `data-theme`. A
+ * fragment gets the wrapper (body margin 0 — a mockup is full-bleed); a
+ * document that already brings `<html>` passes through verbatim — unless it
+ * is scripted, when the policy head is PREPENDED rather than spliced in
+ * (no regex surgery on untrusted markup). The parser puts those metas in an
+ * implied <head>; the author's own doctype/<html>/<head> tags that follow
+ * are then parse errors that merge or drop harmlessly (their <html>
+ * attributes still apply). The prefix carries a doctype so the document
+ * stays in standards mode.
+ */
+export declare function mockupDocument(html: string, theme: "light" | "dark", scripted?: boolean): string;

package/dist/artifact-blocks/blocks/mockup/doc.js

@@ -0,0 +1,65 @@
+/**
+ * The sandboxed document a mockup iframe renders (mos-vzame).
+ *
+ * The iframe gets its sandbox from mockupSandboxAttr() in ./sandbox.ts.
+ * allow-same-origin is absent in every mode that helper can emit; the frame
+ * is an opaque origin and can never reach the app session, cookies, or DOM.
+ * That module is the single source of truth for the boundary and its threat
+ * model — this file decides WHAT the opaque-origin document contains, and
+ * for a SCRIPTED mockup that includes the policy head (jat-4yffn):
+ * MOCKUP_SCRIPTED_CSP as a `<meta http-equiv>` plus DNS prefetch off. A
+ * srcdoc document has no response headers, so meta is the only carrier. It
+ * is the first element in <head> (before <meta charset>, which only has to
+ * sit in the first 1024 bytes — the policy head is well under that), so it
+ * governs everything the author wrote, and a script removing the element
+ * later does not lift an applied policy.
+ *
+ * Whether a mockup is rendered scripted at all is decided by the caller
+ * (mockupScriptsAllowed in ./sandbox.ts, jatui-2qhbr): this function trusts
+ * its `scripted` argument and emits the policy head for it.
+ *
+ * The light/dark toggle works by re-wrapping the snippet with `data-theme` on
+ * the <html> element — the author's CSS decides what that attribute means
+ * (DaisyUI themes, Tailwind `dark:` with a data-theme selector, hand CSS).
+ * A full document (one that already has <html>) passes through untouched:
+ * rewriting untrusted markup by regex is exactly the fragility this block
+ * refuses; authors who bring their own document own their own theming.
+ */
+import { MOCKUP_SCRIPTED_CSP } from "./sandbox.js";
+/** The scripted document's policy head (jat-4yffn). Attribute-safe: the CSP has no `"`. */
+const SCRIPTED_POLICY = `<meta http-equiv="Content-Security-Policy" content="${MOCKUP_SCRIPTED_CSP}">
+<meta http-equiv="x-dns-prefetch-control" content="off">
+`;
+const WRAPPER_HEAD = `<!doctype html>
+<html lang="en" data-theme="THEME">
+<head>
+POLICY<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<style>
+  html[data-theme="light"] { color-scheme: light; }
+  html[data-theme="dark"] { color-scheme: dark; }
+  body { margin: 0; padding: 0; }
+</style>
+</head>
+<body>
+`;
+const WRAPPER_TAIL = `
+</body>
+</html>`;
+/**
+ * Wrap a mockup snippet into a full document carrying `data-theme`. A
+ * fragment gets the wrapper (body margin 0 — a mockup is full-bleed); a
+ * document that already brings `<html>` passes through verbatim — unless it
+ * is scripted, when the policy head is PREPENDED rather than spliced in
+ * (no regex surgery on untrusted markup). The parser puts those metas in an
+ * implied <head>; the author's own doctype/<html>/<head> tags that follow
+ * are then parse errors that merge or drop harmlessly (their <html>
+ * attributes still apply). The prefix carries a doctype so the document
+ * stays in standards mode.
+ */
+export function mockupDocument(html, theme, scripted = false) {
+    if (/<html[\s>]/i.test(html)) {
+        return scripted ? `<!doctype html>\n${SCRIPTED_POLICY}${html}` : html;
+    }
+    return `${WRAPPER_HEAD.replace("THEME", theme).replace("POLICY", scripted ? SCRIPTED_POLICY : "")}${html}${WRAPPER_TAIL}`;
+}