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

package/dist/core/artifact-frame-document.js

@@ -0,0 +1,1427 @@
+/**
+ * THE artifact document builder (frame model). Assembles a bundle into ONE
+ * sandboxed iframe document, consumed verbatim by every surface — the in-app
+ * canvas, the public present page, the standalone export, and the headless
+ * Playwright render. There is exactly one renderer.
+ *
+ * D13 boundary: a single `sandbox="allow-scripts"` document holds all frames in
+ * ONE script scope (shared code runs across frames). The platform owns layout —
+ * it injects CSS that absolutely-positions each frame container at the rect the
+ * shared {@link computeFrameLayout} engine computed; the HOST draws all chrome
+ * (labels, selection, pulse, a11y proxies) from those same rects, so chrome can
+ * never drift from content and nothing is measured through the sandbox wall.
+ *
+ * Asset URLs and the CSP both derive from the one {@link AssetResolution}
+ * (finalize step), so a document can never carry URLs from one asset model and
+ * a policy from another.
+ */
+import { DEFAULT_PAGE_MARGINS, isSafeBackgroundValue } from './artifact-frame-model.js';
+import { computeFrameLayout, FRAME_LAYOUT_DEFAULT_GAP } from './artifact-frame-layout.js';
+import { escapeAttribute, escapeHtml, escapeScript, escapeStyle } from './artifact-escape.js';
+import { applyAssetResolution, artifactCsp } from './artifact-asset-resolution.js';
+import { brokenImageScriptTag, libraryTags } from './artifact-libraries.js';
+import { SANITIZE_CSS_URLS_TWIN } from './artifact-paged-css.js';
+/** Cap (ms) on the in-sandbox `document.fonts.ready` wait before Paged.js
+ *  fragments. The host inlines workspace-asset fonts as data: URLs so this
+ *  normally resolves immediately; the cap only bites when a font falls back to a
+ *  slow network endpoint, trading a worst-case late-font reflow for not stalling
+ *  the canvas for many seconds. Interpolated into the pagination bootstrap. */
+const FONT_READY_TIMEOUT_MS = 2000;
+/** Artboard fill for a frame that opts into `neutral`. The DEFAULT (unset) is
+ *  transparent — the frame's appearance comes from its own content, so an opaque
+ *  slide never shows a white artboard peeking around its edges. Authors opt into
+ *  a white paper with `background: 'neutral'`. */
+const FRAME_ARTBOARD_BACKGROUND = '#ffffff';
+/** The whiteboard surface fill: paper + a dot grid (FigJam feel). The whiteboard
+ *  is the ONE artifact surface the platform themes (its dot grid is platform-drawn
+ *  chrome, not author-designed content) — slides/pages/artboard/app keep their
+ *  authored backgrounds. Two values, one source, shared across every surface (host
+ *  iframe, present, standalone HTML/PDF export) so the look can't drift:
+ *   - light: warm off-white paper + a near-black, low-opacity dot grid.
+ *   - dark:  warm slate paper (a step above the app's #09090b base, so the canvas
+ *     reads as a distinct surface) + a light, low-opacity dot grid.
+ *  Geometry (1.2px dots / 14px cell) is identical so only color/tone changes. The
+ *  paper hex is its own const so the surface gradient AND the `--sg-surface` ink
+ *  token below resolve to ONE value (no paper-vs-token drift). */
+const WB_PAPER_LIGHT = '#fbfaf8';
+const WB_PAPER_DARK = '#1c1a17';
+const WHITEBOARD_SURFACE_LIGHT = `${WB_PAPER_LIGHT} radial-gradient(circle, rgba(20,18,16,0.11) 1px, transparent 1.2px) 0 0 / 14px 14px`;
+const WHITEBOARD_SURFACE_DARK = `${WB_PAPER_DARK} radial-gradient(circle, rgba(240,238,233,0.10) 1px, transparent 1.2px) 0 0 / 14px 14px`;
+function whiteboardSurface(colorScheme) {
+    return colorScheme === 'dark' ? WHITEBOARD_SURFACE_DARK : WHITEBOARD_SURFACE_LIGHT;
+}
+/** The whiteboard theme-token CONTRACT. The platform injects these semantic CSS
+ *  custom properties into the whiteboard iframe so author content can opt into
+ *  theme-aware "ink" — connector lines, outlines, line-art, mono icons, body
+ *  type, labels — via `var(--sg-ink)` / `currentColor`, instead of hardcoding a
+ *  color that goes invisible when the surface flips. The platform NEVER
+ *  auto-recolors content; it only publishes tokens to opt into. Intentional fills
+ *  and media (a colored post-it, a photo) stay exactly as the author set them —
+ *  they sit on their own background, not the bare surface, so they need no token.
+ *  Tokens resolve from `colorScheme` for the live host; the standalone export
+ *  emits them under a `prefers-color-scheme` media query (it follows the OS).
+ *   - `--sg-ink`        primary foreground (default ink against the surface).
+ *   - `--sg-ink-muted`  secondary (labels, eyebrows, hairlines).
+ *   - `--sg-surface`    the paper color (so content can draw a panel that matches
+ *                       the board). */
+const WHITEBOARD_INK = { light: '#1c1a18', dark: '#f0eee9' };
+const WHITEBOARD_INK_MUTED = { light: '#6b675f', dark: '#a8a39a' };
+const WB_PAPER = { light: WB_PAPER_LIGHT, dark: WB_PAPER_DARK };
+/** The `:root` declarations for one scheme — the ink contract resolved to values. */
+function whiteboardTokenDecls(scheme) {
+    return `--sg-ink:${WHITEBOARD_INK[scheme]};--sg-ink-muted:${WHITEBOARD_INK_MUTED[scheme]};--sg-surface:${WB_PAPER[scheme]};`;
+}
+/** The whiteboard token `<style>` body for a render. Mirrors the surface emission
+ *  EXACTLY so ink can never disagree with the paper it's drawn on:
+ *   - live host ('iframe'): resolved to the one scheme the host threaded.
+ *   - standalone interactive (host 'none' + interactive): light + `@media dark`
+ *     (follows the OS, like the surface's standalone CSS).
+ *   - static export (host 'none', non-interactive): light only (print default,
+ *     like the surface's static frameLayoutCss path). */
+function whiteboardThemeTokensCss(colorScheme, host, standaloneInteractive) {
+    if (host === 'iframe')
+        return `:root{${whiteboardTokenDecls(colorScheme === 'dark' ? 'dark' : 'light')}}`;
+    if (standaloneInteractive)
+        return `:root{${whiteboardTokenDecls('light')}}\n@media (prefers-color-scheme: dark){:root{${whiteboardTokenDecls('dark')}}}`;
+    return `:root{${whiteboardTokenDecls('light')}}`;
+}
+/** The standalone-export body fill (the area outside the canvas in a downloaded
+ *  file). A touch darker/lighter than the paper so the canvas floats. */
+const WHITEBOARD_STANDALONE_BODY_LIGHT = '#f4f2ef';
+const WHITEBOARD_STANDALONE_BODY_DARK = '#121110';
+function backgroundValue(background) {
+    if (background === undefined)
+        return null;
+    // Trim first so a padded keyword still resolves and the emitted custom value is
+    // clean (mirrors validateBackground's normalization for legacy/unvalidated bodies).
+    const v = background.trim();
+    if (v === 'transparent')
+        return 'transparent';
+    if (v === 'neutral')
+        return FRAME_ARTBOARD_BACKGROUND;
+    // A custom CSS color/gradient (validated at write time by isSafeBackgroundValue).
+    // Re-check at emit so a legacy/unvalidated body can never inject a raw value into
+    // the `background:…;` declaration; an unsafe value falls back to the default.
+    return isSafeBackgroundValue(v) ? v : null;
+}
+/** A frame's effective artboard fill (CSS). Layout-aware default: `pages` and
+ *  `app` are solid surfaces (white) so a page / app isn't see-through; slides and
+ *  artboards default transparent so opaque content shows no white border. Explicit
+ *  `background` (frame- or artifact-level) — a keyword or a custom color/gradient —
+ *  always wins. */
+function frameBackground(layout, frameBg, displayBg) {
+    const solidByDefault = layout === 'pages' || layout === 'app';
+    const effective = frameBg ?? displayBg ?? (solidByDefault ? 'neutral' : 'transparent');
+    return backgroundValue(effective) ?? 'transparent';
+}
+/** `tokens` → `:root` custom properties. Values are escaped for the `<style>`
+ *  element AND stripped of `;{}` so a value can't break out of its declaration
+ *  or the rule (the emit-time guard the frame model documents). */
+function tokensStyleTag(tokens) {
+    if (!tokens)
+        return '';
+    const decls = Object.entries(tokens)
+        .map(([key, value]) => {
+        const name = key.startsWith('--') ? key : `--${key.replace(/^-+/, '')}`;
+        return `  ${name}: ${escapeStyle(value.replace(/[;{}]/g, ' '))};`;
+    })
+        .join('\n');
+    return decls ? `<style data-artifact-tokens>:root {\n${decls}\n}</style>` : '';
+}
+/** Shared stylesheets, inlined as `<style>` (one assembled document). */
+function sharedStyleTags(bundle) {
+    const files = bundle.shared?.files;
+    if (!files)
+        return '';
+    return Object.entries(files)
+        .filter(([path]) => path.toLowerCase().endsWith('.css'))
+        .map(([path, css]) => `<style data-artifact-file="${escapeAttribute(path)}">\n${escapeStyle(css)}\n</style>`)
+        .join('\n');
+}
+/** Concatenated shared stylesheet TEXT (raw CSS). Paged.js only honors break
+ *  rules (`break-before/after/inside`, named pages) from stylesheets handed to
+ *  its polisher — CSS that merely sits in the document head styles the content
+ *  visually but is invisible to the fragmenter. So the authored shared CSS is
+ *  passed to `preview()` alongside the `@page` rule (it is ALSO in the head for
+ *  global styling; double-application is idempotent). */
+function sharedCssText(bundle) {
+    const files = bundle.shared?.files;
+    if (!files)
+        return '';
+    return Object.entries(files)
+        .filter(([path]) => path.toLowerCase().endsWith('.css'))
+        .map(([, css]) => css)
+        .join('\n');
+}
+/** The platform layout CSS: a transparent canvas sized to the total extent, with
+ *  each frame container absolutely positioned at its computed rect. Fixed frames
+ *  get an exact height (content clips); auto-height frames grow to content
+ *  (`min-height` from the estimate, the host reflows once measured). */
+function frameLayoutCss(bundle, layout, colorScheme) {
+    const rules = layout.rects
+        .map((rect, index) => {
+        const frame = bundle.frames[index];
+        const auto = frame.geometry.height === 'auto';
+        const height = auto ? `min-height:${rect.height}px;height:auto;` : `height:${rect.height}px;`;
+        const background = frame.layout === 'whiteboard'
+            ? `background:${whiteboardSurface(colorScheme)};`
+            : `background:${frameBackground(frame.layout, frame.background, bundle.display?.background)};`;
+        // frame.id is constrained to a CSS-safe charset by the model's ID_RE.
+        return `[data-sg-frame-id="${frame.id}"]{left:${rect.x}px;top:${rect.y}px;width:${rect.width}px;${height}${background}}`;
+    })
+        .join('\n');
+    return `html,body{margin:0;padding:0;background:transparent;}
+body{position:relative;width:${layout.width}px;height:${layout.height}px;overflow:hidden;}
+[data-sg-frame]{position:absolute;box-sizing:border-box;overflow:hidden;}
+${rules}`;
+}
+/** The frame containers — each owns its content fragment; the platform CSS above
+ *  positions it. The host anchors drawn chrome to `data-sg-frame-id`.
+ *
+ *  `activeFirstFrame` statically marks frame 0 `data-sg-present-active` for a
+ *  host-less present render (PNG/PDF/inspect of the present stage): there is no
+ *  runtime to call `setActive(0)`, and the present CSS hides every unmarked
+ *  frame, so without it the capture would be blank. */
+function frameContainersHtml(bundle, activeFirstFrame = false) {
+    return bundle.frames
+        .map((frame, index) => {
+        const label = frame.title || `Frame ${index + 1}`;
+        const backgroundAttribute = frame.background ? ` data-sg-bg="${escapeAttribute(frame.background)}"` : '';
+        const activeAttribute = activeFirstFrame && index === 0 ? ' data-sg-present-active=""' : '';
+        return `<section data-sg-frame data-sg-frame-id="${escapeAttribute(frame.id)}" data-frame-index="${index}" data-frame-layout="${frame.layout}"${backgroundAttribute}${activeAttribute} role="group" aria-label="${escapeAttribute(label)}">${frame.content}</section>`;
+    })
+        .join('\n');
+}
+/** Shared scripts (cross-frame logic). When curated libraries are requested they
+ *  load async, so the scripts are deferred behind the library-ready promise;
+ *  otherwise they emit as plain tags. Per-frame inline scripts run inline. */
+function sharedScriptTags(bundle) {
+    const entries = Object.entries(bundle.shared?.files ?? {})
+        .filter(([path]) => /\.(m?js)$/i.test(path))
+        .map(([path, js]) => ({ path, js, module: path.toLowerCase().endsWith('.mjs') }));
+    if (entries.length === 0)
+        return '';
+    if ((bundle.libraries ?? []).length === 0) {
+        return entries
+            .map(({ path, js, module }) => `<script${module ? ' type="module"' : ''} data-artifact-file="${escapeAttribute(path)}">\n${escapeScript(js)}\n</script>`)
+            .join('\n');
+    }
+    const payload = JSON.stringify(entries.map((entry) => ({ path: entry.path, js: entry.js, kind: entry.module ? 'module' : 'classic' })));
+    return `<script data-artifact-user-scripts>
+(async () => {
+  await (window.__STUDIOGRAPH_ARTIFACT_LIBRARIES_READY__ || Promise.resolve());
+  const scripts = ${escapeScript(payload)};
+  for (const script of scripts) {
+    await new Promise((resolve, reject) => {
+      const url = URL.createObjectURL(new Blob([String(script.js) + '\\n//# sourceURL=studiograph-artifact://' + String(script.path)], { type: 'text/javascript' }));
+      if (script.kind === 'module') { import(url).then(resolve, reject); return; }
+      const element = document.createElement('script');
+      element.src = url; element.async = false;
+      element.onload = () => resolve(); element.onerror = () => reject(new Error('Could not load artifact script: ' + String(script.path)));
+      document.head.appendChild(element);
+    });
+  }
+})().catch((error) => { console.error('Artifact script error', error); throw error; });
+</script>`;
+}
+// ---------------------------------------------------------------------------
+// The host-iframe runtime. Frame-first: it reports per-frame sizes (auto frames
+// need measuring), applies host-computed layout rects, forwards pan/zoom to the
+// host (which owns the transform), and reports element/frame selection. There is
+// NO selector-detected stepper — frames are first-class containers now.
+// ---------------------------------------------------------------------------
+function frameRuntimeScript(artifactId, surface, fullBleed = false, whiteboard = false) {
+    return `
+(() => {
+  const artifactId = ${JSON.stringify(artifactId)};
+  const surface = ${JSON.stringify(surface)};
+  const fullBleed = ${JSON.stringify(fullBleed)};
+  const whiteboard = ${JSON.stringify(whiteboard)};
+  // A whiteboard pans/zooms in BOTH editor and present (it is a large pannable
+  // surface, not a stepped deck), so wheel AND hand-drag pan are forwarded to the
+  // host in either mode; elsewhere only the editor navigates. In a whiteboard
+  // present there is no pointer/hand toolbar, so the hand tool is the default —
+  // the surface pans on a plain drag. A whiteboard EDITOR keeps the pointer default
+  // (it has the Select / Pan toggle) and the host syncs the active tool.
+  const canNavigate = surface === 'editor' || whiteboard;
+  let tool = ${JSON.stringify(whiteboard && surface !== 'editor' ? 'hand' : 'pointer')};
+  const send = (payload) => { try { parent.postMessage({ channel: 'studiograph-artifact', artifactId, ...payload }, '*'); } catch {} };
+  // Show the grab cursor over the canvas (the iframe content) whenever the hand
+  // tool is active — the host stage cursor doesn't reach inside the iframe. The
+  // pan handlers below swap to 'grabbing' while dragging.
+  const applyCursor = () => { try { document.body.style.cursor = (canNavigate && tool === 'hand') ? 'grab' : ''; } catch {} };
+  applyCursor();
+  const frames = () => Array.from(document.querySelectorAll('[data-sg-frame]'));
+  const cssEscape = (value) => (window.CSS && CSS.escape) ? CSS.escape(value) : String(value);
+  const frameById = (id) => document.querySelector('[data-sg-frame-id="' + cssEscape(id) + '"]');
+
+  // --- per-frame size reporting (auto frames; host reflows from these) ---
+  const measure = () => frames().map((el) => ({
+    id: el.getAttribute('data-sg-frame-id'),
+    width: el.offsetWidth,
+    height: Math.max(el.scrollHeight, el.offsetHeight),
+  }));
+  let sizeTimer = null;
+  const reportSizes = () => send({ type: 'frame-sizes', sizes: measure() });
+  const queueSizes = () => { if (sizeTimer) clearTimeout(sizeTimer); sizeTimer = setTimeout(reportSizes, 150); };
+
+  // --- apply host-computed layout rects + extent ---
+  // The host recomputes the analytic layout when an auto-height frame measures,
+  // then sends the new rects AND the new total extent. Frame width comes from
+  // the rect; auto frames keep height:auto (content-driven). The body is resized
+  // to the extent so a grown auto frame isn't clipped by the baked body box
+  // (the host resizes the iframe element to the same extent in lockstep).
+  const applyLayout = (rects, width, height) => {
+    for (const rect of (rects || [])) {
+      const el = frameById(rect.id);
+      if (!el) continue;
+      el.style.left = rect.x + 'px';
+      el.style.top = rect.y + 'px';
+      el.style.width = rect.width + 'px';
+    }
+    if (typeof width === 'number' && width > 0) document.body.style.width = width + 'px';
+    if (typeof height === 'number' && height > 0) document.body.style.height = height + 'px';
+  };
+
+  window.addEventListener('message', (event) => {
+    const data = event.data;
+    if (!data || data.channel !== 'studiograph-artifact-host' || data.artifactId !== artifactId) return;
+    if (data.type === 'apply-layout') applyLayout(data.rects, data.width, data.height);
+    if (data.type === 'set-tool' && (data.tool === 'pointer' || data.tool === 'hand')) { tool = data.tool; applyCursor(); }
+    if (data.type === 'clear-selection') clearSelection();
+    if (data.type === 'select-ancestor' && typeof data.index === 'number') selectAncestor(data.index);
+  });
+
+  window.addEventListener('error', (event) => send({ status: 'error', message: String((event && event.message) || 'Artifact error') }));
+  window.addEventListener('unhandledrejection', (event) => send({ status: 'error', message: String((event && event.reason && event.reason.message) || (event && event.reason) || 'Artifact promise rejection') }));
+  // Observe frames for size changes. The observer is set up AFTER the body has
+  // parsed (frames exist) — at head-parse time querySelectorAll is empty — so
+  // async content growth (fonts, images, and document pagination, which only
+  // settles after load) is reported, not just the one-shot load measure.
+  let resizeObserver = null;
+  const observeFrames = () => {
+    try {
+      if (!resizeObserver) resizeObserver = new ResizeObserver(queueSizes);
+      else resizeObserver.disconnect();
+      for (const el of frames()) resizeObserver.observe(el);
+    } catch {}
+  };
+  // applyCursor() at init is a no-op (it runs in <head>, before <body> exists), so
+  // set the cursor again on load — otherwise a present whiteboard (default hand
+  // tool) shows the grab cursor only after the first pointer interaction.
+  window.addEventListener('load', () => { send({ status: 'ready' }); observeFrames(); reportSizes(); applyCursor(); });
+  try { if (document.fonts && document.fonts.ready) document.fonts.ready.then(() => { observeFrames(); reportSizes(); }); } catch {}
+
+  // --- selection (editor only) ---
+  const safeText = (value, limit = 160) => String(value || '').replace(/\\s+/g, ' ').trim().slice(0, limit);
+  // Content/interactive elements snap selection to themselves (a click on a
+  // heading's text selects the heading, on a button's label the button); any other
+  // element selects exactly as itself (see selectionTarget).
+  const specificContent = 'h1,h2,h3,h4,h5,h6,p,li,td,th,blockquote,figure,figcaption,label,svg,path,g,rect,circle,text,img,video,a,button,[role="button"]';
+  const selectorFor = (el) => {
+    if (!(el instanceof Element)) return '';
+    if (el.id) return '#' + cssEscape(el.id);
+    const parts = [];
+    let node = el;
+    while (node && node.nodeType === 1 && parts.length < 5 && !node.hasAttribute('data-sg-frame')) {
+      let part = node.tagName.toLowerCase();
+      const parent = node.parentElement;
+      if (parent) {
+        const twins = Array.from(parent.children).filter((child) => child.tagName === node.tagName);
+        if (twins.length > 1) part += ':nth-of-type(' + (twins.indexOf(node) + 1) + ')';
+      }
+      parts.unshift(part);
+      node = parent;
+    }
+    return parts.join(' > ');
+  };
+  const selected = new Map();
+  const clearSelection = (publish = true) => {
+    for (const entry of selected.values()) entry.el && entry.el.removeAttribute && entry.el.removeAttribute('data-sg-selected');
+    selected.clear();
+    if (publish) publishSelection();
+  };
+  // Human label for a breadcrumb segment: data-sg-name if authored, else a
+  // CSS-ish token (tag, tag#id, or tag.firstClass); the frame shows its name.
+  const labelFor = (el) => {
+    if (el.hasAttribute('data-sg-frame')) {
+      return el.getAttribute('data-sg-name') || ('Frame ' + ((parseInt(el.getAttribute('data-frame-index'), 10) || 0) + 1));
+    }
+    const name = el.getAttribute('data-sg-name');
+    if (name) return name;
+    const tag = el.tagName.toLowerCase();
+    if (el.id) return tag + '#' + el.id;
+    const cls = (el.getAttribute('class') || '').trim().split(/\\s+/).filter(Boolean)[0];
+    return cls ? tag + '.' + cls : tag;
+  };
+  // The selected element's ancestor chain within its frame: frame-first → el-last.
+  const ancestorChain = (el) => {
+    const frame = el.closest('[data-sg-frame]');
+    if (!frame) return [];
+    const chain = [];
+    let n = el;
+    while (n) { chain.unshift(n); if (n === frame) break; n = n.parentElement; }
+    return chain;
+  };
+  const publishSelection = () => {
+    const entries = Array.from(selected.values());
+    // Recompute each target's descriptor from the LIVE element so the rects reflect
+    // current geometry — a scroll/resize re-emit must carry where the element is NOW,
+    // not where it was when first selected (the targetId/selector stay stable, so the
+    // host repositions its overlay in place rather than treating it as a new target).
+    const targets = entries.map((entry) => { entry.target = descriptorFor(entry.el); return entry.target; });
+    // A single selection carries its ancestor labels for the host breadcrumb;
+    // a multi-selection has no single path.
+    const path = entries.length === 1 ? ancestorChain(entries[0].el).map(labelFor) : null;
+    send({ type: 'selection-change', primaryTargetId: (targets[targets.length - 1] || {}).targetId || '', targets, ...(path ? { path: path } : {}) });
+    if (targets.length === 0) send({ type: 'clear-selection' });
+  };
+  // Breadcrumb drill-out: re-select the ancestor at the given index of the current
+  // single selection's chain. The selected element itself (last) is a no-op.
+  const selectAncestor = (index) => {
+    const entries = Array.from(selected.values());
+    if (entries.length !== 1) return;
+    const chain = ancestorChain(entries[0].el);
+    const target = chain[index];
+    if (!(target instanceof Element) || target === entries[0].el) return;
+    clearSelection(false);
+    const t = descriptorFor(target);
+    target.setAttribute('data-sg-selected', 'true');
+    selected.set(t.targetId, { el: target, target: t });
+    publishSelection();
+  };
+  const descriptorFor = (el) => {
+    const frame = el.closest('[data-sg-frame]');
+    const rect = el.getBoundingClientRect();
+    const frameId = frame ? frame.getAttribute('data-sg-frame-id') : '';
+    // Never emit an empty selector (the host drops empty-selector targets): the
+    // frame element addresses by its frame id, anything else by its DOM path,
+    // falling back to the tag name.
+    const isFrame = el.hasAttribute('data-sg-frame');
+    const selector = isFrame
+      ? '[data-sg-frame-id="' + frameId + '"]'
+      : (selectorFor(el) || el.tagName.toLowerCase());
+    return {
+      frameId,
+      frameIndex: frame ? Number(frame.getAttribute('data-frame-index')) : -1,
+      selector,
+      tagName: el.tagName.toLowerCase(),
+      text: safeText(el.textContent),
+      rect: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
+      targetId: (frameId || '') + '::' + selector,
+    };
+  };
+  const selectionTarget = (node) => {
+    if (!(node instanceof Element)) return null;
+    const frame = node.closest('[data-sg-frame]');
+    if (!frame) return null; // bare stage → clears the selection
+    const explicit = node.closest('[data-sg-selectable]');
+    if (explicit) return explicit;
+    // EVERYTHING is selectable. Snap a click that lands inside a meaningful
+    // content/interactive element up to that element (clicking a heading's text
+    // selects the heading; a button's label selects the button); otherwise select
+    // the EXACT element clicked — a structural wrapper (header bar, nav rail, logo)
+    // selects as itself, never silently collapsing to the whole frame. The frame is
+    // selected only by clicking its own bare background. Use the breadcrumb to drill
+    // OUT to a container.
+    const specific = node.closest(specificContent);
+    if (specific && specific !== frame && frame.contains(specific)) return specific;
+    return node;
+  };
+  window.addEventListener('click', (event) => {
+    if (surface !== 'editor' || tool !== 'pointer') return;
+    if (handleLinkClick(event)) { /* still select the link element */ }
+    const el = selectionTarget(event.target);
+    if (!(el instanceof Element)) { clearSelection(); return; }
+    const target = descriptorFor(el);
+    const additive = event.shiftKey || event.metaKey || event.ctrlKey;
+    if (!additive) clearSelection(false);
+    if (additive && selected.has(target.targetId)) {
+      const prev = selected.get(target.targetId);
+      prev && prev.el && prev.el.removeAttribute('data-sg-selected');
+      selected.delete(target.targetId);
+    } else {
+      el.setAttribute('data-sg-selected', 'true');
+      selected.set(target.targetId, { el, target });
+    }
+    publishSelection();
+  }, { capture: true });
+  window.addEventListener('keydown', (event) => {
+    if (surface !== 'editor' || event.key !== 'Escape' || selected.size === 0) return;
+    clearSelection();
+    event.preventDefault();
+  }, { capture: true });
+
+  // Selection chrome lives in the HOST overlay, positioned from element rects. A
+  // scroll (the page or any inner scroll container) moves those elements, so re-emit
+  // the selection with fresh rects while a selection exists — rAF-throttled, mirroring
+  // the pan/zoom flush — or the overlay would lag behind the content it frames.
+  // Capture-phase catches non-bubbling scroll events from nested scrollers; passive
+  // keeps scrolling smooth.
+  let selectionReflowFrame = null;
+  const flushSelectionReflow = () => { selectionReflowFrame = null; if (selected.size > 0) publishSelection(); };
+  window.addEventListener('scroll', () => {
+    if (selected.size === 0 || selectionReflowFrame !== null) return;
+    selectionReflowFrame = requestAnimationFrame(flushSelectionReflow);
+  }, { capture: true, passive: true });
+
+  // Swallow in-sandbox navigation (a relative/external href would blank the frame).
+  const handleLinkClick = (event) => {
+    if (event.defaultPrevented || event.button) return false;
+    const anchor = event.target instanceof Element ? event.target.closest('a[href]') : null;
+    if (!anchor) return false;
+    const href = anchor.getAttribute('href') || '';
+    if (!href || /^javascript:/i.test(href)) return false;
+    event.preventDefault();
+    if (href.charAt(0) === '#') {
+      try { const dest = document.getElementById(href.slice(1)); dest && dest.scrollIntoView({ block: 'start', behavior: 'smooth' }); } catch {}
+    }
+    return true;
+  };
+  // Non-editor surfaces (a present document scrolls like a PDF): swallow in-frame
+  // navigation here too, so a relative/external href can't blank the sandboxed
+  // frame, and an in-document #anchor smooth-scrolls to its section while reading.
+  // Editor runs handleLinkClick from its own click handler above.
+  window.addEventListener('click', (event) => {
+    if (surface === 'editor') return;
+    handleLinkClick(event);
+  }, { capture: true });
+
+  // --- pan/zoom forwarding (the host owns the transform) ---
+  let panDelta = null, panFrame = null, zoomDelta = null, zoomFrame = null;
+  const flushPan = () => { panFrame = null; if (!panDelta) return; const d = panDelta; panDelta = null; send({ type: 'pan-delta', dx: d.dx, dy: d.dy }); };
+  const queuePan = (dx, dy) => { panDelta = panDelta ? { dx: panDelta.dx + dx, dy: panDelta.dy + dy } : { dx, dy }; if (panFrame === null) panFrame = requestAnimationFrame(flushPan); };
+  const flushZoom = () => { zoomFrame = null; if (!zoomDelta) return; const z = zoomDelta; zoomDelta = null; send({ type: 'zoom-delta', delta: z.delta, x: z.x, y: z.y }); };
+  const queueZoom = (delta, x, y) => { zoomDelta = zoomDelta ? { delta: zoomDelta.delta + delta, x, y } : { delta, x, y }; if (zoomFrame === null) zoomFrame = requestAnimationFrame(flushZoom); };
+  window.addEventListener('wheel', (event) => {
+    if (!canNavigate || fullBleed) return; // full-bleed: let the app scroll natively
+    const unit = event.deltaMode === 1 ? 16 : event.deltaMode === 2 ? window.innerHeight : 1;
+    const dx = event.deltaX * unit, dy = event.deltaY * unit;
+    if (Math.abs(dx) < 0.01 && Math.abs(dy) < 0.01) return;
+    if (event.ctrlKey || event.metaKey) { queueZoom(dy, event.clientX, event.clientY); event.preventDefault(); return; }
+    queuePan(dx, dy);
+    event.preventDefault();
+  }, { capture: true, passive: false });
+  let panPointer = null;
+  window.addEventListener('pointerdown', (event) => {
+    if (!canNavigate || fullBleed || tool !== 'hand' || event.button !== 0) return;
+    panPointer = event.pointerId;
+    try { event.target.setPointerCapture && event.target.setPointerCapture(event.pointerId); } catch {}
+    try { document.body.style.cursor = 'grabbing'; } catch {}
+    send({ type: 'pan', phase: 'start', x: event.screenX, y: event.screenY });
+    event.preventDefault();
+  }, { capture: true });
+  window.addEventListener('pointermove', (event) => {
+    if (panPointer !== event.pointerId) return;
+    send({ type: 'pan', phase: 'move', x: event.screenX, y: event.screenY });
+  }, { capture: true });
+  const endPan = (event) => { if (panPointer !== event.pointerId) return; send({ type: 'pan', phase: 'end', x: event.screenX, y: event.screenY }); panPointer = null; applyCursor(); };
+  window.addEventListener('pointerup', endPan, { capture: true });
+  window.addEventListener('pointercancel', endPan, { capture: true });
+  // If capture is stolen mid-drag (system gesture, target removed), end the pan so
+  // the 'grabbing' cursor doesn't stick.
+  window.addEventListener('lostpointercapture', endPan, { capture: true });
+})();`;
+}
+// ---------------------------------------------------------------------------
+// PRESENT layout + runtime. Present is single-frame: frames are STACKED at the
+// origin (each at its own size, only the active one shown), so stepping is a
+// visibility toggle — never a transform jump — which is flash-free and renders
+// only one frame (cheap). This is the stepper model. The host sizes the
+// iframe to the active frame and fit-scales it (a constant transform across
+// steps for a uniform deck), draws the controls, and forwards set-frame.
+// ---------------------------------------------------------------------------
+function presentLayoutCss(bundle) {
+    const rules = bundle.frames
+        .map((frame) => {
+        const height = frame.geometry.height === 'auto' ? 'height:auto;' : `height:${frame.geometry.height}px;`;
+        const background = `background:${frameBackground(frame.layout, frame.background, bundle.display?.background)};`;
+        return `[data-sg-frame-id="${frame.id}"]{width:${frame.geometry.width}px;${height}${background}}`;
+    })
+        .join('\n');
+    // left/top are forced because promoted document page-frames carry inline
+    // column coordinates (from pagination) that present must override to stack
+    // every frame at the origin (the stepper shows one at a time).
+    return `html,body{margin:0;padding:0;background:transparent;}
+body{position:relative;margin:0;}
+[data-sg-frame]{position:absolute;left:0 !important;top:0 !important;box-sizing:border-box;overflow:hidden;display:none;}
+[data-sg-frame][data-sg-present-active]{display:block;}
+${rules}`;
+}
+function presentRuntimeScript(artifactId) {
+    return `
+(() => {
+  const artifactId = ${JSON.stringify(artifactId)};
+  const send = (payload) => { try { parent.postMessage({ channel: 'studiograph-artifact', artifactId, ...payload }, '*'); } catch {} };
+  const frames = () => Array.from(document.querySelectorAll('[data-sg-frame]'));
+  let active = 0;
+  const sendState = () => { const all = frames(); if (all.length) send({ type: 'frame-state', index: active, count: all.length }); };
+  const sendSizes = () => send({ type: 'frame-sizes', sizes: frames().map((el) => ({ id: el.getAttribute('data-sg-frame-id'), width: el.offsetWidth, height: Math.max(el.scrollHeight, el.offsetHeight) })) });
+  const setActive = (index) => {
+    const all = frames();
+    if (!all.length) return;
+    active = Math.max(0, Math.min(all.length - 1, Number.isFinite(index) ? Math.round(index) : 0));
+    all.forEach((el, i) => { const on = i === active; el.toggleAttribute('data-sg-present-active', on); el.setAttribute('aria-hidden', on ? 'false' : 'true'); });
+    sendState();
+    sendSizes();
+  };
+  const step = (dir) => { const all = frames(); if (all.length) setActive((active + dir + all.length) % all.length); };
+  window.addEventListener('message', (event) => {
+    const data = event.data;
+    if (!data || data.channel !== 'studiograph-artifact-host' || data.artifactId !== artifactId) return;
+    if (data.type === 'set-frame') setActive(Number(data.index));
+    if (data.type === 'reset-frames') setActive(0);
+  });
+  window.addEventListener('error', (event) => send({ status: 'error', message: String((event && event.message) || 'Artifact error') }));
+  window.addEventListener('keydown', (event) => {
+    if (event.altKey || event.ctrlKey || event.metaKey) return;
+    if (event.key === 'ArrowRight' || event.key === 'PageDown' || event.key === ' ') { step(1); event.preventDefault(); return; }
+    if (event.key === 'ArrowLeft' || event.key === 'PageUp' || event.key === 'Backspace') { step(-1); event.preventDefault(); return; }
+    if (event.key === 'Home') { setActive(0); event.preventDefault(); return; }
+    if (event.key === 'End') { setActive(frames().length - 1); event.preventDefault(); return; }
+  });
+  // Navigation is via the host stepper controls + keyboard only — clicking a slide
+  // does NOT advance (the stepper is the clearer affordance; click-to-step was
+  // easy to trigger by accident). But pointer activity over the iframe (which the
+  // host can't see) must still re-reveal the auto-hiding controls: re-post the
+  // current frame-state (the host reveals on it) without changing the slide.
+  let activityRaf = null;
+  const signalActivity = () => { if (activityRaf !== null) return; activityRaf = requestAnimationFrame(() => { activityRaf = null; sendState(); }); };
+  window.addEventListener('pointermove', signalActivity, { passive: true });
+  window.addEventListener('click', signalActivity);
+  window.addEventListener('load', () => { send({ status: 'ready' }); setActive(0); });
+  try { if (document.fonts && document.fonts.ready) document.fonts.ready.then(sendSizes); } catch {}
+})();`;
+}
+/** A single-frame artifact whose frame spans the viewport (a responsive
+ *  prototype / full-screen app). The frame fills the iframe and reflows; the host
+ *  sizes the iframe to the canvas/present stage. The host (FrameCanvas) imports
+ *  this so its full-bleed predicate can't drift from the renderer. */
+export function isFullBleed(bundle) {
+    return bundle.frames.length === 1
+        // A whiteboard is its own mode (large fixed surface, pannable) — never treat
+        // it as full-bleed even if mis-authored with a 'fill' dimension, or it would
+        // become a chrome-less surface that can't be panned.
+        && bundle.frames[0].layout !== 'whiteboard'
+        && (bundle.frames[0].geometry.width === 'fill' || bundle.frames[0].geometry.height === 'fill');
+}
+/** Full-bleed layout: the body fills the iframe (which the host sizes to the
+ *  stage) and the single frame fills the body, scrolling internally if its
+ *  content overflows — no grid, no fixed artboard. A NUMERIC `geometry.width`
+ *  letterboxes the app: centered at that width (capped to the viewport), filling
+ *  height — so a fixed-width app screen doesn't stretch edge-to-edge. A `fill`
+ *  width spans the whole stage. */
+function fullBleedLayoutCss(bundle) {
+    const frame = bundle.frames[0];
+    const bg = frameBackground(frame.layout, frame.background, bundle.display?.background);
+    const width = frame.geometry.width;
+    const horizontal = typeof width === 'number'
+        ? `left:50%;transform:translateX(-50%);width:${width}px;max-width:100%;`
+        : `left:0;right:0;`;
+    return `html,body{margin:0;padding:0;background:transparent;height:100%;}
+body{position:relative;width:100%;height:100%;}
+[data-sg-frame]{position:absolute;top:0;bottom:0;${horizontal}box-sizing:border-box;overflow:auto;background:${bg};}`;
+}
+/** Every frame is a `pages` frame — the artifact reads as a continuous paged
+ *  document. In `present` it scrolls through its pages like a PDF (the
+ *  present-document path) instead of stepping frame-by-frame like a deck. The
+ *  host (FrameCanvas) imports this so its present-document predicate can't drift. */
+export function isPagesArtifact(bundle) {
+    return bundle.frames.length > 0 && bundle.frames.every((frame) => frame.layout === 'pages');
+}
+/** A whiteboard: ONE large freeform surface (FigJam/Miro feel). Single frame,
+ *  layout `whiteboard`. It is neither a deck (no stepper) nor full-bleed (it has
+ *  a real, fixed extent the user pans/zooms around). The host suppresses frame
+ *  chrome, pans the surface in BOTH editor and present, and fits-to-surface in
+ *  present (no stepper). The host (FrameCanvas) imports this so its whiteboard
+ *  predicate can't drift from the renderer. */
+export function isWhiteboard(bundle) {
+    return bundle.frames.length === 1 && bundle.frames[0].layout === 'whiteboard';
+}
+// ---------------------------------------------------------------------------
+// Standalone (host: 'none') interactive whiteboard. A downloaded HTML file has
+// no host to drive the transform, so the runtime SELF-HOSTS the same Figma-style
+// cover-clamp pan/zoom as the in-app present: the canvas always covers the
+// viewport, pan stops at every edge, and a small built-in toolbar offers zoom
+// in/out + reset. (A static PDF/PNG render leaves ctx.interactive unset and keeps
+// the full-canvas layout, so the render captures the whole surface.)
+// ---------------------------------------------------------------------------
+/** The whiteboard's fixed canvas size (px). A whiteboard frame should declare a
+ *  numeric box; coerce a mis-authored 'fill'/'auto' to a sane default so the
+ *  standalone math never divides by a non-number. */
+function whiteboardCanvasSize(bundle) {
+    const g = bundle.frames[0].geometry;
+    return {
+        width: typeof g.width === 'number' ? g.width : 1280,
+        height: typeof g.height === 'number' ? g.height : 800,
+    };
+}
+/** Shared standalone-export toolbar CSS (.sg-bar*) — mirrors the in-app toolbar
+ *  (.fc-toolbar / .fc-tool-btn) with the design tokens resolved to concrete values
+ *  (the sandbox has none). Used by every interactive standalone surface. */
+function sgStandaloneToolbarCss() {
+    return `.sg-bar{position:fixed;left:50%;bottom:16px;transform:translateX(-50%);display:flex;align-items:center;gap:3px;padding:4px;background:#fff;border:1px solid #e5e2dd;border-radius:8px;box-shadow:0 4px 16px rgba(0,0,0,0.08),0 1px 2px rgba(0,0,0,0.04);z-index:10;cursor:default;font:13px system-ui,-apple-system,sans-serif;}
+.sg-bar-btn{width:28px;height:28px;display:flex;align-items:center;justify-content:center;padding:0;border:0;border-radius:6px;color:#6b675f;background:transparent;cursor:pointer;transition:background 0.15s,color 0.15s;}
+.sg-bar-btn:hover{background:#f2efea;color:#1c1a18;}
+.sg-bar-btn svg{width:16px;height:16px;display:block;}
+.sg-bar-sep{width:1px;height:16px;background:#e5e2dd;margin:0 3px;}
+.sg-bar-zoom,.sg-bar-count{display:flex;align-items:center;justify-content:flex-end;min-width:44px;padding:0 6px;color:#6b675f;font-variant-numeric:tabular-nums;}
+.sg-bar-count{justify-content:center;min-width:54px;}`;
+}
+function whiteboardStandaloneLayoutCss(bundle) {
+    const { width, height } = whiteboardCanvasSize(bundle);
+    // A downloaded file has no host to ask for the app theme, so the whiteboard —
+    // the one platform-themed surface — follows the OS via prefers-color-scheme.
+    return `html,body{margin:0;padding:0;height:100%;overflow:hidden;background:${WHITEBOARD_STANDALONE_BODY_LIGHT};}
+body{position:relative;cursor:grab;}
+body.sg-grabbing{cursor:grabbing;}
+[data-sg-frame]{position:absolute;left:0;top:0;width:${width}px;height:${height}px;transform-origin:0 0;box-sizing:border-box;overflow:hidden;background:${WHITEBOARD_SURFACE_LIGHT};}
+@media (prefers-color-scheme: dark){
+html,body{background:${WHITEBOARD_STANDALONE_BODY_DARK};}
+[data-sg-frame]{background:${WHITEBOARD_SURFACE_DARK};}
+}
+${sgStandaloneToolbarCss()}`;
+}
+// The EXACT Carbon icon path data used by the in-app toolbar (carbon-icons-svelte
+// Reset / ZoomOut / ZoomIn / ChevronLeft / ChevronRight), inlined so a downloaded
+// standalone file renders the same glyphs with no dependency. Carbon icons are a
+// 32×32 viewBox, filled with currentColor.
+const SG_CARBON = {
+    reset: '<path d="M18,28A12,12,0,1,0,6,16v6.2L2.4,18.6,1,20l6,6,6-6-1.4-1.4L8,22.2V16H8A10,10,0,1,1,18,26Z"/>',
+    zoomOut: '<path d="M8 12H18V14H8z"/><path d="M21.4479,20A10.856,10.856,0,0,0,24,13,11,11,0,1,0,13,24a10.856,10.856,0,0,0,7-2.5521L27.5859,29,29,27.5859ZM13,22a9,9,0,1,1,9-9A9.01,9.01,0,0,1,13,22Z"/>',
+    zoomIn: '<path d="M18 12 14 12 14 8 12 8 12 12 8 12 8 14 12 14 12 18 14 18 14 14 18 14 18 12z"/><path d="M21.4479,20A10.856,10.856,0,0,0,24,13,11,11,0,1,0,13,24a10.856,10.856,0,0,0,7-2.5521L27.5859,29,29,27.5859ZM13,22a9,9,0,1,1,9-9A9.01,9.01,0,0,1,13,22Z"/>',
+    chevronLeft: '<path d="M10 16 20 6 21.4 7.4 12.8 16 21.4 24.6 20 26z"/>',
+    chevronRight: '<path d="M22 16 12 26 10.6 24.6 19.2 16 10.6 7.4 12 6z"/>',
+};
+const sgIcon = (key) => `<svg viewBox="0 0 32 32" fill="currentColor" aria-hidden="true">${SG_CARBON[key]}</svg>`;
+function whiteboardStandaloneToolbarHtml() {
+    return `<div id="sg-wb-bar" class="sg-bar" role="toolbar" aria-label="Canvas controls">`
+        + `<button id="sg-wb-reset" class="sg-bar-btn" type="button" title="Reset view" aria-label="Reset view">${sgIcon('reset')}</button>`
+        + `<span class="sg-bar-sep" aria-hidden="true"></span>`
+        + `<button id="sg-wb-zoomout" class="sg-bar-btn" type="button" title="Zoom out" aria-label="Zoom out">${sgIcon('zoomOut')}</button>`
+        + `<button id="sg-wb-zoomin" class="sg-bar-btn" type="button" title="Zoom in" aria-label="Zoom in">${sgIcon('zoomIn')}</button>`
+        + `<span class="sg-bar-sep" aria-hidden="true"></span>`
+        + `<span id="sg-wb-zoom" class="sg-bar-zoom">100%</span>`
+        + `</div>`;
+}
+/** The self-hosted cover-clamp pan/zoom runtime for a standalone whiteboard. No
+ *  parent host: it owns the transform on the single frame element, clamping so a
+ *  canvas edge never enters the viewport (mirrors clampWhiteboardPan in the host
+ *  view-state), and wires the built-in toolbar. */
+function whiteboardStandaloneRuntime(canvasWidth, canvasHeight) {
+    return `
+(() => {
+  const W = ${canvasWidth}, H = ${canvasHeight}, MAXZOOM = 4;
+  // The runtime is injected in <head>, before the body parses, so the frame
+  // element is looked up lazily (capturing it at parse time would be null).
+  const elOf = () => document.querySelector('[data-sg-frame]');
+  let zoom = 1, x = 0, y = 0;
+  const vw = () => window.innerWidth, vh = () => window.innerHeight;
+  const cover = () => Math.max(vw() / W, vh() / H);
+  const clamp = (v, a, b) => Math.min(b, Math.max(a, v));
+  const clampPan = () => {
+    const w = W * zoom, h = H * zoom;
+    x = w >= vw() ? clamp(x, vw() - w, 0) : (vw() - w) / 2;
+    y = h >= vh() ? clamp(y, vh() - h, 0) : (vh() - h) / 2;
+  };
+  const label = () => { const l = document.getElementById('sg-wb-zoom'); if (l) l.textContent = Math.round(zoom * 100) + '%'; };
+  const apply = () => { const el = elOf(); if (el) el.style.transform = 'translate(' + x + 'px,' + y + 'px) scale(' + zoom + ')'; label(); };
+  // Open (and reset) at 100% centered; a canvas too small to cover the viewport
+  // at 1:1 scales up to the cover scale so no edge shows.
+  const fit = () => { zoom = Math.max(1, cover()); x = (vw() - W * zoom) / 2; y = (vh() - H * zoom) / 2; clampPan(); apply(); };
+  const setZoom = (nz, fx, fy) => {
+    // The cover scale is the min zoom; the max must be at least cover so the clamp
+    // never inverts (a small canvas can need >MAXZOOM just to cover the viewport).
+    const lo = cover(); nz = clamp(nz, lo, Math.max(MAXZOOM, lo));
+    fx = (fx == null) ? vw() / 2 : fx; fy = (fy == null) ? vh() / 2 : fy;
+    const ax = (fx - x) / zoom, ay = (fy - y) / zoom;
+    zoom = nz; x = fx - ax * zoom; y = fy - ay * zoom; clampPan(); apply();
+  };
+  let dragging = false, px = 0, py = 0;
+  window.addEventListener('pointerdown', (e) => {
+    if (e.button !== 0 || (e.target && e.target.closest && e.target.closest('#sg-wb-bar'))) return;
+    dragging = true; px = e.clientX; py = e.clientY; document.body.classList.add('sg-grabbing');
+    try { e.target.setPointerCapture && e.target.setPointerCapture(e.pointerId); } catch {}
+  });
+  window.addEventListener('pointermove', (e) => { if (!dragging) return; x += e.clientX - px; y += e.clientY - py; px = e.clientX; py = e.clientY; clampPan(); apply(); });
+  const end = () => { dragging = false; document.body.classList.remove('sg-grabbing'); };
+  window.addEventListener('pointerup', end); window.addEventListener('pointercancel', end); window.addEventListener('lostpointercapture', end);
+  window.addEventListener('wheel', (e) => {
+    e.preventDefault();
+    const unit = e.deltaMode === 1 ? 16 : e.deltaMode === 2 ? vh() : 1;
+    if (e.ctrlKey || e.metaKey) { setZoom(zoom * Math.exp(-e.deltaY * unit * 0.0015), e.clientX, e.clientY); return; }
+    x -= e.deltaX * unit; y -= e.deltaY * unit; clampPan(); apply();
+  }, { passive: false });
+  // Wire the toolbar + do the first fit once the DOM exists (the runtime runs in
+  // <head>, before the toolbar buttons parse).
+  const wire = () => {
+    const onBar = (id, fn) => { const b = document.getElementById(id); if (b) b.addEventListener('click', fn); };
+    onBar('sg-wb-zoomout', () => setZoom(zoom / 1.2));
+    onBar('sg-wb-zoomin', () => setZoom(zoom * 1.2));
+    onBar('sg-wb-reset', () => fit());
+    fit();
+  };
+  window.addEventListener('resize', fit);
+  if (document.readyState === 'loading') window.addEventListener('DOMContentLoaded', wire); else wire();
+  window.addEventListener('load', fit);
+})();`;
+}
+// ---------------------------------------------------------------------------
+// Standalone (host: 'none') interactive DECK (slides / artboard set). A
+// downloaded HTML file reproduces the in-app PRESENT stepper: frames stacked at
+// the origin (one shown at a time), the active frame fit-centered on the stage,
+// with prev/next + restart controls + keyboard/click stepping. No host — the
+// runtime self-hosts the fit transform and draws its own controls (same dark
+// pill + Carbon chevrons/reset as the in-app present controls).
+// ---------------------------------------------------------------------------
+/** Present-controls CSS for the standalone deck — mirrors .fc-present-controls
+ *  (dark blurred pill) with tokens resolved to concrete values. */
+function sgStandalonePresentControlsCss() {
+    return `.sg-present{position:fixed;left:0;right:0;bottom:24px;display:flex;align-items:center;justify-content:center;pointer-events:none;opacity:0;transition:opacity 300ms ease;z-index:10;font:13px system-ui,-apple-system,sans-serif;}
+.sg-present.visible{opacity:1;}
+.sg-present-group{display:flex;align-items:center;gap:2px;padding:4px;background:rgba(30,30,30,0.85);border-radius:8px;pointer-events:auto;-webkit-backdrop-filter:blur(12px);backdrop-filter:blur(12px);}
+.sg-present-btn{width:32px;height:32px;display:flex;align-items:center;justify-content:center;padding:0;border:0;border-radius:6px;color:rgba(255,255,255,0.6);background:transparent;cursor:pointer;transition:color 120ms,background 120ms;}
+.sg-present-btn svg{width:16px;height:16px;display:block;}
+.sg-present-btn:hover{background:rgba(255,255,255,0.1);color:#fff;}
+.sg-present-count{height:32px;display:flex;align-items:center;justify-content:center;padding:0 8px;color:rgba(255,255,255,0.6);font-weight:500;font-variant-numeric:tabular-nums;white-space:nowrap;user-select:none;}
+.sg-present-reset{position:absolute;right:24px;}
+.sg-present-restart{width:auto;gap:6px;padding:0 8px;font-weight:500;white-space:nowrap;}`;
+}
+function deckStandaloneLayoutCss(bundle) {
+    const rules = bundle.frames
+        .map((frame) => {
+        const width = typeof frame.geometry.width === 'number' ? `${frame.geometry.width}px` : '100%';
+        const height = frame.geometry.height === 'auto' || frame.geometry.height === 'fill'
+            ? 'height:auto;'
+            : `height:${frame.geometry.height}px;`;
+        const background = `background:${frameBackground(frame.layout, frame.background, bundle.display?.background)};`;
+        return `[data-sg-frame-id="${frame.id}"]{width:${width};${height}${background}}`;
+    })
+        .join('\n');
+    return `html,body{margin:0;padding:0;height:100%;overflow:hidden;background:#4a4a4a;}
+body{position:relative;}
+[data-sg-frame]{position:absolute;left:0;top:0;transform-origin:0 0;box-sizing:border-box;overflow:hidden;display:none;}
+[data-sg-frame][data-sg-present-active]{display:block;}
+${rules}
+${sgStandalonePresentControlsCss()}`;
+}
+function deckStandaloneControlsHtml() {
+    return `<div id="sg-present" class="sg-present">`
+        + `<div class="sg-present-group" role="group" aria-label="Slide navigation">`
+        + `<button id="sg-prev" class="sg-present-btn" type="button" title="Previous" aria-label="Previous">${sgIcon('chevronLeft')}</button>`
+        + `<span id="sg-count" class="sg-present-count">1 / 1</span>`
+        + `<button id="sg-next" class="sg-present-btn" type="button" title="Next" aria-label="Next">${sgIcon('chevronRight')}</button>`
+        + `</div>`
+        + `<div class="sg-present-group sg-present-reset">`
+        + `<button id="sg-restart" class="sg-present-btn sg-present-restart" type="button" title="Restart" aria-label="Restart">${sgIcon('reset')}<span>Restart</span></button>`
+        + `</div>`
+        + `</div>`;
+}
+/** The self-hosted present stepper for a standalone deck: fit the active frame
+ *  centered, step prev/next (keyboard + click-zones), restart, auto-hiding
+ *  controls. Mirrors presentRuntimeScript + the in-app present fit. */
+function deckStandaloneRuntime() {
+    return `
+(() => {
+  const MAX_SCALE = 6;
+  const frames = () => Array.prototype.slice.call(document.querySelectorAll('[data-sg-frame]'));
+  let active = 0, hideTimer = null;
+  const fitActive = () => {
+    const all = frames(); if (!all.length) return;
+    const el = all[active]; const fw = el.offsetWidth || 1, fh = el.offsetHeight || 1;
+    const pad = 48; const scale = Math.min((window.innerWidth - pad) / fw, (window.innerHeight - pad) / fh, MAX_SCALE);
+    const s = Math.max(0.05, scale);
+    el.style.transform = 'translate(' + ((window.innerWidth - fw * s) / 2) + 'px,' + ((window.innerHeight - fh * s) / 2) + 'px) scale(' + s + ')';
+  };
+  const updateCount = () => { const c = document.getElementById('sg-count'); if (c) c.textContent = (active + 1) + ' / ' + frames().length; };
+  const show = (i) => {
+    const all = frames(); if (!all.length) return;
+    active = ((i % all.length) + all.length) % all.length;
+    all.forEach((el, idx) => { el.toggleAttribute('data-sg-present-active', idx === active); el.setAttribute('aria-hidden', idx === active ? 'false' : 'true'); });
+    fitActive(); updateCount();
+  };
+  const step = (d) => show(active + d);
+  const reveal = () => { const c = document.getElementById('sg-present'); if (!c) return; c.classList.add('visible'); if (hideTimer) clearTimeout(hideTimer); hideTimer = setTimeout(() => c.classList.remove('visible'), 2500); };
+  const wire = () => {
+    const on = (id, fn) => { const b = document.getElementById(id); if (b) b.addEventListener('click', (e) => { e.stopPropagation(); fn(); reveal(); }); };
+    on('sg-prev', () => step(-1)); on('sg-next', () => step(1)); on('sg-restart', () => show(0));
+    show(0); reveal();
+  };
+  window.addEventListener('keydown', (e) => {
+    if (e.altKey || e.ctrlKey || e.metaKey) return;
+    // Don't hijack keys aimed at a focused control or text field: typing in a slide
+    // input must work, and Space on a focused button should activate it natively
+    // (not double-step). Mirrors the in-app present keyboard guard.
+    const t = e.target;
+    if (t && t.closest && t.closest('input,textarea,select,[contenteditable="true"],button,a[href],[role="button"]')) return;
+    if (e.key === 'ArrowRight' || e.key === 'PageDown' || e.key === ' ') { step(1); reveal(); e.preventDefault(); }
+    else if (e.key === 'ArrowLeft' || e.key === 'PageUp' || e.key === 'Backspace') { step(-1); reveal(); e.preventDefault(); }
+    else if (e.key === 'Home') { show(0); reveal(); e.preventDefault(); }
+    else if (e.key === 'End') { show(frames().length - 1); reveal(); e.preventDefault(); }
+  });
+  // Navigation is via the stepper controls + keyboard only — clicking a slide does
+  // NOT advance (the stepper is the clearer affordance). A click still reveals the
+  // auto-hiding controls.
+  window.addEventListener('click', reveal);
+  window.addEventListener('mousemove', reveal);
+  window.addEventListener('resize', fitActive);
+  if (document.readyState === 'loading') window.addEventListener('DOMContentLoaded', wire); else wire();
+  window.addEventListener('load', () => { show(active); reveal(); });
+})();`;
+}
+/** Present a `document` artifact as a continuous vertical scroll through its
+ *  pages — read like a PDF, not stepped like a deck. The pages are Paged.js's
+ *  natural `.pagedjs_page` boxes (present-document does NOT promote them — see the
+ *  bootstrap's `promote` gate — so they keep Paged.js's vertical flow); a
+ *  non-paginated (auto/fill-height) document frame flows as a single page. The
+ *  host sizes the iframe to the present stage; the page column scrolls internally.
+ *  Mirrors the `pagedFullscreenCss` reader model — `!important` + the surface
+ *  scope win over Paged.js's runtime-injected `.pagedjs_*` styles (which reset
+ *  left/top/transform and would otherwise absolutely-position the pages). */
+function presentDocumentLayoutCss(bundle, surfaceAttr = 'present') {
+    const surface = `html[data-artifact-surface="${surfaceAttr}"]`;
+    // A non-paginated (auto/fill-height) document frame IS the page — give the frame
+    // itself page chrome. A paginated frame's wrapper stays transparent; its pages
+    // get chrome via .pagedjs_page below.
+    const rules = bundle.frames
+        .map((frame) => {
+        const width = typeof frame.geometry.width === 'number' ? `${frame.geometry.width}px` : '100%';
+        const minHeight = typeof frame.geometry.height === 'number' ? `min-height:${frame.geometry.height}px;` : '';
+        const background = frameBackground(frame.layout, frame.background, bundle.display?.background);
+        return `[data-sg-frame-id="${frame.id}"]:not([data-sg-paginated]){width:${width};max-width:100%;margin:0 auto 32px;${minHeight}background:${background};box-shadow:0 6px 24px rgba(0,0,0,0.18);}`;
+    })
+        .join('\n');
+    // The page column MUST use block flow, not flex: Chromium does not accumulate
+    // `counter-increment` across FLEX items, so a flex `.pagedjs_pages` renders the
+    // "Page N of M" footer (which resolves `counter(page)`) as "Page 1" on every
+    // page. Block boxes accumulate the page counter correctly. Pages center with
+    // `margin:0 auto` (fixed-width box in a full-width column) and gap with
+    // `margin-bottom`; the body block-stacks frames + scrolls.
+    return `html,body{margin:0;padding:0;background:transparent;height:100%;}
+body{box-sizing:border-box;min-height:100%;overflow:auto;padding:48px 0;}
+[data-sg-frame]{position:relative;box-sizing:border-box;background:transparent;overflow:visible;}
+[data-sg-frame][data-sg-paginated]{display:block;width:100%;}
+${surface} .pagedjs_pages{display:block !important;width:auto !important;margin:0 !important;padding:0 !important;background:transparent !important;}
+${surface} .pagedjs_page{position:relative !important;left:auto !important;top:auto !important;margin:0 auto 32px !important;transform:none !important;background:#fff;box-shadow:0 6px 24px rgba(0,0,0,0.18);}
+${surface} .pagedjs_sheet{box-shadow:none !important;}
+${furniturePositionCss()}
+${rules}`;
+}
+// ---------------------------------------------------------------------------
+// Document pagination (P3.3). A `document` frame holds ONE flowing content
+// stream; when a Paged.js source is supplied the platform fragments it into page
+// boxes INSIDE the sandbox (CSS Paged Media — @page geometry, running headers/
+// footers, page counters, break rules). The page count is a render OUTPUT, never
+// authored or persisted (the authored `document` frame is the single source of
+// truth — frame model `ResolvedFrame.origin: 'derived'`). Print shares the same
+// fragmentation, so PDF export gets faithful page breaks for free.
+//
+// A `document` frame paginates only when its height is a fixed page box (e.g.
+// US Letter 816×1056); a `document` with `height:'auto'` stays a single flowing
+// page (auto-height reflow). The default page margin leaves room for furniture.
+// Defaults live in the model (DEFAULT_PAGE_MARGINS) so the validation cross-check
+// and this render agree on what an absent `pageMargins` side resolves to.
+// ---------------------------------------------------------------------------
+// The Paged.js source is a large (~500KB) static library; escapeScript scans it
+// for `</script` on every build. Memoize by identity so a session pays once.
+let escapedPagedCache = null;
+function escapedPagedSource(source) {
+    if (escapedPagedCache && escapedPagedCache.source === source)
+        return escapedPagedCache.escaped;
+    const escaped = escapeScript(source);
+    escapedPagedCache = { source, escaped };
+    return escaped;
+}
+/** The frames the platform paginates: `pages` layout with a fixed page box
+ *  (numeric width AND height). A `'fill'`/`'auto'` pages frame is a single flowing
+ *  page, not paginated. */
+function paginatedFrames(bundle) {
+    return bundle.frames.filter((frame) => frame.layout === 'pages'
+        && typeof frame.geometry.width === 'number'
+        && typeof frame.geometry.height === 'number');
+}
+/** Whether a HOST-LESS render (PNG/PDF/inspect/standalone download) should carry
+ *  the Paged.js source to fragment this bundle into a page column. THE single
+ *  source of truth for that decision across every host-less caller (the headless
+ *  render, the export route, the MCP export tool), so none drifts from the
+ *  builder's actual column layout.
+ *
+ *  Requires a FULLY-paginated document — every frame is a `pages` frame — with at
+ *  least one fixed page box. A MIXED artifact (pages + other layouts) is NOT
+ *  paginated host-less: the column layout ({@link isPagesArtifact}) wouldn't
+ *  apply, so it would fall to the clipped grid AND the render's page-box selector
+ *  would switch to `.pagedjs_page` and drop the non-page frames entirely. Instead
+ *  a mixed artifact renders as the grid with every frame present (the live editor,
+ *  which PROMOTES pages into the grid, is the surface that paginates mixed). This
+ *  also drops the `.some(layout === 'pages')` variants that shipped ~500KB of
+ *  Paged.js for an auto/fill `pages` frame the builder never paginates. */
+export function bundleNeedsPagination(bundle) {
+    return isPagesArtifact(bundle) && paginatedFrames(bundle).length > 0;
+}
+/** The effective page margins: author `pageMargins` overrides per side, each
+ *  absent side falling back to the platform default. The single source the
+ *  `@page` rule and the furniture positioning both read, so they can't diverge. */
+function resolvePageMargins(frame) {
+    const m = frame.pageMargins;
+    return {
+        top: m?.top ?? DEFAULT_PAGE_MARGINS.top,
+        right: m?.right ?? DEFAULT_PAGE_MARGINS.right,
+        bottom: m?.bottom ?? DEFAULT_PAGE_MARGINS.bottom,
+        left: m?.left ?? DEFAULT_PAGE_MARGINS.left,
+    };
+}
+/** The OVERRIDABLE `@page` defaults for one document frame: author margins and a
+ *  "Page N of M" counter in the bottom-RIGHT corner. Bottom-right (not -center) so
+ *  it never sits under a centered/left footer furniture band, which also lives in
+ *  the bottom margin. This sheet is applied BEFORE the author's shared CSS, so an
+ *  author can override the margin and the counter box with their own CSS Paged
+ *  Media. The page SIZE is NOT here — it is locked to the frame geometry by
+ *  pageSizeRuleCss (applied LAST) so author CSS can't desync the page box from the
+ *  canvas frame. Passed to Paged.js as stylesheet TEXT (never a URL — no fetch
+ *  under `connect-src 'none'`). */
+function pageRuleCss(frame) {
+    const m = resolvePageMargins(frame);
+    return `@page{margin:${m.top}px ${m.right}px ${m.bottom}px ${m.left}px;`
+        + `@bottom-right{content:"Page " counter(page) " of " counter(pages);`
+        + `font:12px var(--sg-furniture-font, system-ui, -apple-system, sans-serif);color:#6b7280;}}`;
+}
+/** The AUTHORITATIVE `@page { size }` rule, locked to the frame geometry. Applied
+ *  as the LAST sheet (after author CSS) so the paginated page box always matches
+ *  the canvas frame's geometry — the page SIZE is the frame's `geometry`, not
+ *  something author CSS overrides (which would clip/gap the geometry-forced frame
+ *  box and desync the reported page count). Margins/margin-boxes stay overridable.
+ *  This locks the GENERIC `@page` size (the common case); a named/pseudo page with
+ *  its own size (e.g. `@page cover { size: A4 }`) is a deliberate advanced
+ *  divergence and is left to the author — it will simply not match the canvas
+ *  frame box, which is their choice. */
+function pageSizeRuleCss(frame) {
+    const width = frame.geometry.width;
+    const height = frame.geometry.height;
+    return `@page{size:${width}px ${height}px;}`;
+}
+/** Base style for the injected per-page furniture (running header/footer). Only
+ *  font/color/positioning-context here — the actual top/bottom/left/right offset
+ *  is set INLINE per page in the bootstrap's addFurniture, because it depends on
+ *  the frame's (possibly author-overridden) page margins. Shared by the
+ *  editor/export page sheet (paginationHostCss) and the present scroll column
+ *  (presentDocumentLayoutCss) so the placement can't drift. */
+function furniturePositionCss() {
+    return `[data-sg-furniture]{position:absolute;font:12px var(--sg-furniture-font, system-ui, -apple-system, sans-serif);color:#374151;pointer-events:none;}`;
+}
+/** Host CSS that neutralizes Paged.js's default preview chrome (gray backdrop,
+ *  centering, shadows) so each promoted page sits flush as a white artboard, and
+ *  carries the base style for the injected header/footer furniture (its offset is
+ *  set inline per page from the frame's margins). */
+function paginationHostCss() {
+    return `.pagedjs_pages{display:block;width:auto;padding:0;background:transparent;}
+.pagedjs_page{margin:0;background:#fff;position:relative;box-shadow:none;}
+.pagedjs_sheet{box-shadow:none;}
+[data-sg-derived] .pagedjs_page{margin:0;}
+${furniturePositionCss()}`;
+}
+/** The in-sandbox pagination bootstrap. After fonts settle it fragments each
+ *  paginated `document` frame's flowing content via Paged.js and injects per-page
+ *  running header/footer furniture (the first/last page variants override middle).
+ *
+ *  `promote` selects the DOM outcome:
+ *   - true (live host: editor/present): every page box is PROMOTED to a top-level
+ *     `[data-sg-frame]` with a derived id (`<sourceId>__p<n>`) so derived pages
+ *     reuse the same per-frame machinery as authored frames (host chrome,
+ *     selection, present, inspect); a `frame-pages` message tells the host to lay
+ *     them out in a column.
+ *   - false (export/print, host:'none'): pages stay in Paged.js's native
+ *     `.pagedjs_page` structure in place, so Chromium's print engine maps each
+ *     page box to one PDF page (`preferCSSPageSize`) — no guillotine.
+ *
+ *  Runs after the Paged.js source defines the UMD global. */
+function paginationBootstrap(frames, artifactId, promote, sharedCss, renderId, hostedCanvas) {
+    const configById = {};
+    for (const frame of frames) {
+        configById[frame.id] = {
+            css: pageRuleCss(frame),
+            sizeCss: pageSizeRuleCss(frame),
+            width: frame.geometry.width,
+            height: frame.geometry.height,
+            title: frame.title || 'Document',
+            margins: resolvePageMargins(frame),
+            ...(frame.furniture ? { furniture: frame.furniture } : {}),
+        };
+    }
+    return `
+(() => {
+  const artifactId = ${JSON.stringify(artifactId)};
+  const renderId = ${JSON.stringify(renderId)};
+  const GAP = ${FRAME_LAYOUT_DEFAULT_GAP};
+  const PROMOTE = ${JSON.stringify(promote)};
+  const HOSTED_CANVAS = ${JSON.stringify(hostedCanvas)};
+  // Runtime twin of the core sanitizer (src/core/artifact-paged-css.ts), injected
+  // verbatim. Neutralizes every non-absolute url() to about:blank in the CSS handed
+  // to Paged.js, because Paged.js calls new URL(value) (no base) on each url() token
+  // and a scheme-less ref throws synchronously, aborting the whole pagination run.
+  // Only the Paged-fed copy is sanitized — the head <style> keeps real url()s and
+  // paints fonts/backgrounds. Runs AFTER asset resolution (the embedded SHARED_CSS
+  // is already token-rewritten), so it can't fight the ?at= rewrite.
+  ${SANITIZE_CSS_URLS_TWIN}
+  const SHARED_CSS = sanitizeCssUrlsForPagination(${JSON.stringify(sharedCss)});
+  const PAGINATE = ${JSON.stringify(configById)};
+  const cssEscape = (value) => (window.CSS && CSS.escape) ? CSS.escape(value) : String(value);
+  // The UMD global is Paged (paged.js) or PagedModule (paged.min.js).
+  const Paged = window.Paged || window.PagedModule;
+  // Pick the page-position variant: page 1 -> first (or middle), last page -> last
+  // (or middle), every other page -> middle.
+  const pickSlot = (slots, index, count) => index === 0
+    ? (slots.first || slots.middle)
+    : (index === count - 1 ? (slots.last || slots.middle) : slots.middle);
+  const addRegion = (page, html, region, margins) => {
+    if (!html) return;
+    const el = document.createElement('div');
+    el.setAttribute('data-sg-furniture', '');
+    el.setAttribute('data-sg-furniture-region', region);
+    // left/right inset to the side margins so the band aligns to the content column.
+    el.style.left = margins.left + 'px';
+    el.style.right = margins.right + 'px';
+    el.innerHTML = html;
+    page.appendChild(el);
+    // Position from the MEASURED height so a tall letterhead never overlaps the
+    // body: bottom-align the header to just above the content (within the top
+    // margin), top-align the footer to just below the content (within the bottom
+    // margin). Clamp to a min inset from the page edge. The auto "Page N of M"
+    // counter is bottom-RIGHT, so a centered/left footer band clears it. If a
+    // margin is smaller than its furniture the author must grow pageMargins —
+    // out-of-flow furniture can't reserve space.
+    const GAP = 10, MIN_INSET = 8;
+    const place = () => {
+      const h = el.offsetHeight;
+      if (region === 'header') el.style.top = Math.max(MIN_INSET, margins.top - GAP - h) + 'px';
+      else el.style.bottom = Math.max(MIN_INSET, margins.bottom - GAP - h) + 'px';
+    };
+    place();
+    // A logo <img> without a fixed height measures 0 until it loads, which would
+    // mis-place the band; re-place once each image settles (the render waits for
+    // network-idle, so the reposition lands before capture).
+    el.querySelectorAll('img').forEach((img) => { if (!img.complete) img.addEventListener('load', place); });
+  };
+  const addFurniture = (page, furniture, index, count, margins) => {
+    if (furniture.header) addRegion(page, pickSlot(furniture.header, index, count), 'header', margins);
+    if (furniture.footer) addRegion(page, pickSlot(furniture.footer, index, count), 'footer', margins);
+  };
+  const paginate = async () => {
+    if (!Paged || !Paged.Previewer) return;
+    // Paged.js fragments after fonts settle so line breaks match the final type.
+    // The host inlines workspace-asset fonts as data: URLs, so this normally
+    // resolves immediately; but TIME-BOX it so a font that falls back to a slow
+    // network endpoint can't stall pagination for many seconds — past the cap we
+    // paginate with whatever loaded (worst case: a fallback-metric reflow when the
+    // late font swaps in, far better than a multi-second blank canvas).
+    try {
+      if (document.fonts && document.fonts.ready) {
+        await Promise.race([document.fonts.ready, new Promise(function (r) { setTimeout(r, ${FONT_READY_TIMEOUT_MS}); })]);
+      }
+    } catch {}
+    const expansions = [];
+    // Frames whose pagination THREW (e.g. a CSS pattern Paged.js still chokes on).
+    // Reported to the host so it can surface a non-blocking "couldn't paginate"
+    // hint instead of silently showing a clipped, margin-less single page.
+    const failed = [];
+    for (const id of Object.keys(PAGINATE)) {
+      const source = document.querySelector('[data-sg-frame-id="' + cssEscape(id) + '"]');
+      if (!source || !source.parentNode) continue;
+      const cfg = PAGINATE[id];
+      const content = document.createElement('div');
+      // Wrap the flowing stream in a single container element. Paged.js's
+      // createBreakToken walks up from the break node and dereferences a null
+      // parent when the paginated root's DIRECT children are the breakable blocks
+      // (a long paragraph split mid-element crashes); a wrapper gives every block
+      // a non-null parent chain within the root. (Verified: bare children throw
+      // "Cannot read properties of null (reading 'getAttribute')"; wrapped works.)
+      content.innerHTML = '<div data-sg-doc-flow>' + source.innerHTML + '</div>';
+      // Hoist any <style>/<link> out of the flowing stream into <head>. A style
+      // node sitting IN the paginated flow trips Paged.js's fragmenter (it counts
+      // as a child to walk but has no box) — in the editor surface it yields a
+      // blank first page + over-pagination (e.g. an inline @font-face block paged a
+      // 2-page letter to 4). Styles still apply globally from <head>, where they
+      // belong. Only document frames reach this bootstrap, so decks/apps are
+      // untouched. We ALSO collect inline <style> text into inlineCss and feed it
+      // to the paginator below: Paged.js only honors @page / break / running rules
+      // from the sheets passed to preview(), so an author who put those in an
+      // inline <style> (rather than shared.files) would otherwise see them painted
+      // but ignored for pagination.
+      let inlineCss = '';
+      content.querySelectorAll('style, link[rel="stylesheet"]').forEach((node) => {
+        if (node.tagName === 'STYLE') inlineCss += (node.textContent || '') + ' ';
+        document.head.appendChild(node);
+      });
+      // Render straight into the source frame in BOTH modes (in place). Promote
+      // then moves each page box out to a top-level frame (the canvas owns layout);
+      // export leaves them in place so Paged.js's print structure maps to PDF pages.
+      // Rendering promote into an OFFSCREEN position:absolute container made Paged.js
+      // spuriously split the flow wrapper and emit a blank leading page (plus a
+      // tightened first page) whenever an author used a position:running() letterhead
+      // band — an editor-canvas-only defect (export, which always rendered in place,
+      // was clean). Rendering in place gives promote the exact in-flow geometry
+      // export uses, so the running-element pagination matches. data-sg-derived
+      // still tags the source so paginationHostCss neutralizes Paged.js preview
+      // chrome while the pages live inside it (before promotion).
+      // Capture the authored markup before clearing so a pagination FAILURE restores
+      // the frame to its EXACT original DOM (an un-paginated single flow), not the
+      // doc-flow-wrapped, style-hoisted content copy — which would drop direct-child
+      // selectors like [data-sg-frame-id] > .cover. (source still holds its original
+      // inline styles here: the hoist above moved style/link out of the content clone.)
+      const originalHtml = source.innerHTML;
+      if (PROMOTE) source.setAttribute('data-sg-derived', '');
+      source.innerHTML = '';
+      let pageEls;
+      try {
+        const previewer = new Paged.Previewer();
+        // Sheet ORDER is the cascade, in three layers:
+        //   1. sg-pagination.css — the OVERRIDABLE platform defaults (margins +
+        //      bottom-right page counter), FIRST so author CSS can override them.
+        //   2. sg-shared.css — the AUTHOR's CSS, so their @page margins, margin
+        //      boxes (@top-center/@bottom-left/…), named pages, running elements
+        //      (position:running()), and break rules win over our defaults. This is
+        //      what keeps documents fully open to divergent CSS Paged Media layouts.
+        //   3. sg-page-size.css — the AUTHORITATIVE @page{size}, LAST, locked to the
+        //      frame geometry so author CSS can't desync the page box from the
+        //      canvas frame (which is sized + laid out from geometry).
+        // (1b) sg-frame-inline.css — CSS lifted from the frame's own inline <style>
+        //      blocks, in the author layer so its @page/break/running rules paginate
+        //      too. Objects are CSS TEXT (no fetch under connect-src 'none').
+        const sheets = [{ 'sg-pagination.css': cfg.css }];
+        if (SHARED_CSS) sheets.push({ 'sg-shared.css': SHARED_CSS });
+        // Sanitize inline frame CSS too: a frame <style> with a relative url()
+        // would crash Paged.js exactly like the shared sheet. (SHARED_CSS is
+        // sanitized once up top.)
+        const safeInlineCss = sanitizeCssUrlsForPagination(inlineCss);
+        if (safeInlineCss) sheets.push({ 'sg-frame-inline.css': safeInlineCss });
+        sheets.push({ 'sg-page-size.css': cfg.sizeCss });
+        await previewer.preview(content, sheets, source);
+        pageEls = Array.prototype.slice.call(source.querySelectorAll('.pagedjs_page'));
+      } catch (error) {
+        console.error('Artifact pagination failed for frame ' + id, error);
+        failed.push({ id: id, reason: String((error && error.message) || error) });
+        // Restore the source to its exact authored DOM as an un-paginated single flow
+        // (both modes now render in place, so the source was cleared above).
+        source.removeAttribute('data-sg-derived');
+        source.innerHTML = originalHtml;
+        continue;
+      }
+      const furniture = cfg.furniture || {};
+      const margins = cfg.margins;
+      if (!PROMOTE) {
+        pageEls.forEach((page, index) => addFurniture(page, furniture, index, pageEls.length, margins));
+        source.setAttribute('data-sg-paginated', '');
+        source.setAttribute('data-sg-pages', String(pageEls.length));
+        continue;
+      }
+      const startLeft = source.offsetLeft;
+      let cursorTop = source.offsetTop;
+      const reported = [];
+      pageEls.forEach((page, index) => {
+        addFurniture(page, furniture, index, pageEls.length, margins);
+        // Force the page-box size on the moved element so it survives leaving the
+        // Paged.js .pagedjs_pages flow; margin boxes use custom props set on
+        // .pagedjs_page itself, which travel with it.
+        page.style.width = cfg.width + 'px';
+        page.style.height = cfg.height + 'px';
+        const pid = id + '__p' + (index + 1);
+        const frame = document.createElement('section');
+        frame.setAttribute('data-sg-frame', '');
+        frame.setAttribute('data-sg-frame-id', pid);
+        frame.setAttribute('data-frame-layout', 'pages');
+        frame.setAttribute('data-sg-derived-from', id);
+        frame.setAttribute('data-sg-page', String(index + 1));
+        frame.setAttribute('role', 'group');
+        frame.setAttribute('aria-label', cfg.title + ' — page ' + (index + 1));
+        frame.style.width = cfg.width + 'px';
+        frame.style.height = cfg.height + 'px';
+        // Re-establish BOTH page counters that Paged.js kept on the .pagedjs_pages
+        // container we removed by promoting each page to its own top-level frame:
+        // the pages-total on EVERY page so "of M" resolves M (not 0), and a
+        // page-zero reset on the FIRST page so the running number accumulates across
+        // the promoted sibling frames (1..M). Without an explicit reset of the page
+        // counter on a common scope, Chromium implicitly resets it per element and
+        // every footer reads "Page 1". counter-reset scopes to following siblings,
+        // so resetting on the first page also restarts numbering per document when an
+        // artifact has more than one paginated frame.
+        frame.style.counterReset = (index === 0 ? 'page 0 ' : '') + 'pages ' + pageEls.length;
+        // Initial column placement (host apply-layout refines with the same math).
+        frame.style.left = startLeft + 'px';
+        frame.style.top = cursorTop + 'px';
+        cursorTop += cfg.height + GAP;
+        frame.appendChild(page);
+        source.parentNode.insertBefore(frame, source);
+        reported.push({ id: pid, width: cfg.width, height: cfg.height });
+      });
+      // Promotion moved every page box out of the source frame; drop the now-empty
+      // source (its Paged.js .pagedjs_pages shell). Both modes render in place now,
+      // so there is no separate offscreen container to remove.
+      source.parentNode.removeChild(source);
+      expansions.push({ sourceId: id, title: cfg.title, pages: reported });
+    }
+    // A document's author CSS usually sets a body background (the page color). The
+    // bootstrap hoists the frame's inline style to head at runtime, so that rule wins
+    // over the platform's transparent canvas and paints the WHOLE hosted surface
+    // behind the page boxes -- the editor grid reads as a solid slab, the present
+    // view loses its page separation -- instead of pages floating on the canvas.
+    // Re-assert the transparent canvas LAST (after the hoisted author styles): the
+    // page boxes keep their own background, so pages stay their page color and the
+    // gaps show the canvas. HOSTED_CANVAS only (host iframe: editor grid + live
+    // present), so standalone export / PDF / PNG -- where body IS the document
+    // backdrop -- are untouched. Runs for both promote and present (present returns
+    // just below). (Only document frames reach this bootstrap. NOTE: no backticks in
+    // this string-built bootstrap -- they close the template literal.)
+    if (HOSTED_CANVAS) {
+      const canvasReset = document.createElement('style');
+      canvasReset.setAttribute('data-sg-canvas-reset', '');
+      canvasReset.textContent = 'html,body{background:transparent !important;}';
+      document.head.appendChild(canvasReset);
+    }
+    if (!PROMOTE) return;
+    // Renumber data-frame-index across all top-level frames in DOM order so
+    // selection's frameIndex stays consistent after promotion.
+    Array.prototype.slice.call(document.querySelectorAll('[data-sg-frame]'))
+      .forEach((el, i) => el.setAttribute('data-frame-index', String(i)));
+    // Always post — even with zero successful expansions — so the host knows
+    // pagination has SETTLED and stops holding the reveal (a frame that failed
+    // to paginate just renders as its un-paginated single flow).
+    try { parent.postMessage({ channel: 'studiograph-artifact', artifactId, type: 'frame-pages', renderId, expansions, failed }, '*'); } catch {}
+  };
+  if (document.readyState === 'loading') window.addEventListener('DOMContentLoaded', () => { paginate(); });
+  else paginate();
+})();`;
+}
+/**
+ * Build the single sandboxed-iframe document for a frame-model bundle. Every
+ * surface calls this; `host` selects whether a live host drives chrome/transform
+ * (`iframe`) or the file is self-contained (`none`).
+ */
+export function buildFrameDocument(bundle, ctx) {
+    const surface = ctx.surface ?? (ctx.host === 'iframe' ? 'editor' : 'export');
+    const isPresent = surface === 'present';
+    const fullBleed = isFullBleed(bundle);
+    // A whiteboard is one large pannable surface: present fits + pans it (host-
+    // driven) rather than stepping, so it stays on the grid layout + frame runtime.
+    const whiteboard = isWhiteboard(bundle);
+    // A whiteboard outside the editor (present) is always in the hand tool, so the
+    // grab cursor is baked into the static CSS — instant from first paint, rather
+    // than waiting for the runtime's load handler (the source of the cursor lag).
+    // The editor keeps the JS-driven cursor because its tool toggles.
+    const handCursorByDefault = whiteboard && surface !== 'editor' && ctx.host === 'iframe';
+    // A standalone INTERACTIVE whiteboard (downloaded HTML): no host, so the file
+    // self-hosts the cover-clamp pan/zoom + a built-in toolbar. A static PDF/PNG
+    // render (interactive unset) keeps the full-canvas grid so it captures it all.
+    const whiteboardStandalone = whiteboard && ctx.host === 'none' && !!ctx.interactive;
+    // A standalone INTERACTIVE deck (downloaded HTML for slides / an artboard set):
+    // no host, so the file self-hosts the present STEPPER (fit-centered active frame
+    // + prev/next/restart controls), reproducing the in-app present experience. A
+    // whiteboard pans, a pages artifact scrolls, a full-bleed app fills — those are
+    // not stepped, so they are excluded here.
+    const deckStandalone = ctx.host === 'none' && !!ctx.interactive
+        && !whiteboard && !fullBleed && !isPagesArtifact(bundle);
+    // A present document scrolls through its pages (PDF-style) instead of stepping
+    // frame-by-frame: it keeps Paged.js's natural vertical .pagedjs_pages flow (no
+    // promotion) and uses the scroll-column layout + a non-stepper runtime.
+    const presentDocument = isPresent && !fullBleed && isPagesArtifact(bundle);
+    // A standalone (downloaded HTML) document reads the same way: a PDF-style page
+    // column that scrolls natively. surface is 'export' (not 'present') and there is
+    // no host, so it gets the scroll-reader layout + pagination but no stepper/pan
+    // chrome — without this it falls through to the editor GRID (frames stacked at
+    // the origin, no scroll).
+    const documentStandalone = ctx.host === 'none' && !!ctx.interactive && !fullBleed && isPagesArtifact(bundle);
+    // A STATIC document export (PNG/PDF — host:'none', non-interactive) lays pages
+    // out as a column too. The grid would give the single `pages` source frame a
+    // one-page fixed height + overflow:hidden, clipping every page after the first
+    // (Paged.js stacks them inside that clipped box); the column stacks each
+    // `.pagedjs_page` as a visible, measurable box so per-page PNG/PDF capture sees
+    // every page.
+    const documentExport = ctx.host === 'none' && !ctx.interactive && !fullBleed && isPagesArtifact(bundle);
+    // Every path that lays pages out as a column rather than the grid.
+    const scrollDocument = presentDocument || documentStandalone || documentExport;
+    const layout = computeFrameLayout(bundle.frames, { ...ctx.layout, measuredHeights: ctx.measuredHeights });
+    const csp = artifactCsp(ctx.assets, ctx.baseHref ? { allowBaseOrigin: ctx.baseHref } : undefined);
+    const finalize = (html) => applyAssetResolution(html, ctx.assets);
+    // Full-bleed fills the stage; a present document scrolls its page column; else
+    // present stacks frames (stepper) and editor/export use the grid.
+    const layoutCss = whiteboardStandalone
+        ? whiteboardStandaloneLayoutCss(bundle)
+        : deckStandalone
+            ? deckStandaloneLayoutCss(bundle)
+            : fullBleed
+                ? fullBleedLayoutCss(bundle)
+                : scrollDocument
+                    ? presentDocumentLayoutCss(bundle, surface)
+                    : isPresent && !whiteboard
+                        ? presentLayoutCss(bundle)
+                        : frameLayoutCss(bundle, layout, ctx.host === 'iframe' ? ctx.colorScheme : undefined);
+    // A present document reads natively (scroll): the frame runtime with a
+    // non-editor surface neither hijacks the wheel nor selects — exactly the
+    // read-only scroll we want. A whiteboard present pans/zooms (host-driven), so
+    // it also uses the frame runtime (with navigation forwarding), not the stepper.
+    // A standalone whiteboard self-hosts pan/zoom (no parent host). Slides present
+    // uses the stepper runtime.
+    const whiteboardCanvas = whiteboardStandalone ? whiteboardCanvasSize(bundle) : null;
+    const runtimeScript = whiteboardStandalone
+        ? whiteboardStandaloneRuntime(whiteboardCanvas.width, whiteboardCanvas.height)
+        : deckStandalone
+            ? deckStandaloneRuntime()
+            : isPresent && !presentDocument && !whiteboard
+                ? presentRuntimeScript(bundle.artifactId)
+                : frameRuntimeScript(bundle.artifactId, surface, fullBleed, whiteboard);
+    // Document frames paginate when a Paged.js source is supplied (full-bleed is a
+    // single non-document frame, never paginated).
+    const paginate = !fullBleed && ctx.pagedSource ? paginatedFrames(bundle) : [];
+    // Promote each page to a top-level frame for the live host's grid (editor) — but
+    // NOT for a present document, which keeps Paged.js's native vertical flow so its
+    // pages scroll as one column (export/host:none never promotes either).
+    const promote = ctx.host === 'iframe' && !presentDocument;
+    const head = [
+        '<meta charset="utf-8">',
+        `<meta http-equiv="Content-Security-Policy" content="${csp}">`,
+        ctx.baseHref ? `<base href="${escapeAttribute(ctx.baseHref)}">` : '',
+        '<meta name="generator" content="Studiograph Artifact Canvas">',
+        `<title>${escapeHtml(bundle.title)}</title>`,
+        bundle.shared?.head ?? '',
+        tokensStyleTag(bundle.tokens),
+        // The whiteboard ink-token contract (theme-aware --sg-ink/-muted/-surface).
+        // Before the author's shared CSS so authored rules can reference the vars;
+        // only a whiteboard surface is platform-themed, so other layouts emit nothing.
+        whiteboard ? `<style data-artifact-whiteboard-tokens>${whiteboardThemeTokensCss(ctx.colorScheme, ctx.host, whiteboardStandalone)}</style>` : '',
+        sharedStyleTags(bundle),
+        `<style data-artifact-frame-layout>\n${layoutCss}\n</style>`,
+        // Bake the grab cursor for an always-hand surface (present whiteboard) so it
+        // shows from first paint instead of waiting for the runtime's load handler.
+        handCursorByDefault ? '<style data-artifact-cursor>html,body{cursor:grab;}</style>' : '',
+        // The editor/export page-neutralization + furniture CSS. A present document
+        // folds its own page chrome + furniture into presentDocumentLayoutCss (its
+        // pages scroll, they aren't promoted/printed), so it skips this.
+        paginate.length && !scrollDocument ? `<style data-artifact-pagination>\n${paginationHostCss()}\n</style>` : '',
+        libraryTags(bundle.libraries ?? [], ctx.librarySources),
+        // A live host (iframe) drives chrome/transform; a standalone interactive
+        // whiteboard / deck self-hosts its own pan-zoom / stepper — all need the runtime.
+        ctx.host === 'iframe' || whiteboardStandalone || deckStandalone ? `<script data-artifact-runtime>${escapeScript(runtimeScript)}</script>` : '',
+    ].filter(Boolean).join('\n');
+    // A host-less present render (PNG/PDF/inspect of the present stage) has no
+    // runtime to activate a frame, and present CSS hides all but the active one —
+    // so statically mark frame 0 active. Only the stepper-present path needs it
+    // (a present document scrolls; a whiteboard/full-bleed present fills).
+    const staticPresentActive = ctx.host === 'none' && isPresent && !scrollDocument && !whiteboard && !fullBleed;
+    const body = [
+        frameContainersHtml(bundle, staticPresentActive),
+        whiteboardStandalone ? whiteboardStandaloneToolbarHtml() : '',
+        deckStandalone ? deckStandaloneControlsHtml() : '',
+        paginate.length ? `<script data-artifact-paged>${escapedPagedSource(ctx.pagedSource)}</script>` : '',
+        paginate.length ? `<script data-artifact-pagination>${escapeScript(paginationBootstrap(paginate, bundle.artifactId, promote, sharedCssText(bundle), ctx.renderId ?? '', ctx.host === 'iframe'))}</script>` : '',
+        brokenImageScriptTag(),
+        sharedScriptTags(bundle),
+    ].filter(Boolean).join('\n');
+    return finalize(`<!doctype html>
+<html data-artifact-surface="${escapeAttribute(surface)}">
+<head>
+${head}
+</head>
+<body>
+${body}
+</body>
+</html>`);
+}
+//# sourceMappingURL=artifact-frame-document.js.map