@vosjs/studio-core 0.18.1 → 0.19.1

package/dist/index.js

@@ -98,6 +98,9 @@ function clipLength(clip) {
   return clip.loop ? Math.max(span, clip.loopLen ?? span) : span;
 }
 var MOTION_EASE = "power2.inOut";
+function isKeyedOverlay(c) {
+  return c.kind === "image" || c.kind === "video";
+}
 var LAYER_CARD_SHADOW = 0.32;
 var MEDIA_KEY_PREFIX = "media:";
 var OVERLAY_SCALE_MAX = 8;
@@ -1904,11 +1907,329 @@ function cardPointToScreen(u, v) {
 
 // src/overlayText.ts
 import {
-  findFontFamily,
-  fontFaceUrl,
+  findFontFamily as findFontFamily2,
+  fontFaceUrl as fontFaceUrl2,
   fontStack,
-  nearestFontWeight
+  nearestFontWeight as nearestFontWeight2
 } from "@vosjs/shared";
+
+// src/htmlLayer.ts
+import { findFontFamily, fontFaceUrl, nearestFontWeight } from "@vosjs/shared";
+var DESIGN_FRAME_WIDTH = 1920;
+var HTML_LAYER_WARN_BYTES = 32e3;
+var HTML_LAYER_MAX_BYTES = 128e3;
+function splitTopLevel(value) {
+  const out = [];
+  let depth = 0;
+  let cur = "";
+  for (const ch of value) {
+    if (ch === "(") depth++;
+    else if (ch === ")") depth--;
+    if (ch === "," && depth === 0) {
+      out.push(cur);
+      cur = "";
+    } else cur += ch;
+  }
+  if (cur.trim()) out.push(cur);
+  return out;
+}
+var unquote = (s) => s.trim().replace(/^['"]/, "").replace(/['"]$/, "").trim();
+var GENERIC_FAMILIES = /* @__PURE__ */ new Set([
+  "serif",
+  "sans-serif",
+  "monospace",
+  "cursive",
+  "fantasy",
+  "system-ui",
+  "ui-sans-serif",
+  "ui-serif",
+  "ui-monospace",
+  "ui-rounded",
+  "emoji",
+  "math",
+  "fangsong",
+  "inherit",
+  "initial",
+  "unset"
+]);
+function cssFamilies(css) {
+  if (!css) return [];
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const decl of css.match(/font-family\s*:[^;}]+/gi) ?? []) {
+    for (const item of splitTopLevel(decl.replace(/^[^:]*:/, ""))) {
+      const name = unquote(item.replace(/!important/i, ""));
+      if (!name) continue;
+      const lower = name.toLowerCase();
+      if (GENERIC_FAMILIES.has(lower) || lower.startsWith("-apple-")) continue;
+      if (seen.has(lower)) continue;
+      seen.add(lower);
+      out.push(name);
+    }
+  }
+  return out;
+}
+function cssWeights(css, html = "") {
+  const out = /* @__PURE__ */ new Set([400]);
+  for (const decl of css?.match(/font-weight\s*:[^;}]+/gi) ?? []) {
+    const value = decl.replace(/^[^:]*:/, "").toLowerCase();
+    for (const n of value.match(/\b[1-9]00\b/g) ?? []) out.add(Number(n));
+    if (/\bbold(er)?\b/.test(value)) out.add(700);
+  }
+  if (/<(b|strong|h[1-6])[\s>]/i.test(html)) out.add(700);
+  return [...out].sort((a, b) => a - b);
+}
+function htmlLayerFaces(clip) {
+  const faces = [];
+  const seen = /* @__PURE__ */ new Set();
+  const add = (f) => {
+    const key = `${f.family.toLowerCase()}|${f.weight}|${f.style}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    faces.push(f);
+  };
+  const weights = cssWeights(clip.css, clip.html);
+  for (const family of cssFamilies(clip.css)) {
+    const entry = findFontFamily(family);
+    if (!entry) continue;
+    for (const w of weights)
+      add({
+        family: entry.family,
+        url: fontFaceUrl(entry.slug, nearestFontWeight(entry, w)),
+        weight: nearestFontWeight(entry, w),
+        style: "normal"
+      });
+  }
+  for (const f of clip.fonts ?? [])
+    add({
+      family: f.family,
+      url: f.url,
+      weight: f.weight ?? 400,
+      style: f.style ?? "normal"
+    });
+  return faces;
+}
+function htmlLayerUnhostedFamilies(clip) {
+  const explicit = new Set(
+    (clip.fonts ?? []).map((f) => f.family.toLowerCase())
+  );
+  return cssFamilies(clip.css).filter(
+    (f) => !findFontFamily(f) && !explicit.has(f.toLowerCase())
+  );
+}
+function htmlLayerBleedFor(css) {
+  if (!css) return 0;
+  let worst = 0;
+  const consider = (layer) => {
+    if (/\binset\b/i.test(layer)) return;
+    const lengths = layer.replace(/[a-z-]+\([^)]*\)/gi, " ").replace(/#[0-9a-f]{3,8}/gi, " ").match(/-?\d*\.?\d+/g);
+    if (!lengths) return;
+    const [x = 0, y = 0, blur = 0, spread = 0] = lengths.map(Number);
+    worst = Math.max(
+      worst,
+      Math.abs(x) + blur + spread,
+      Math.abs(y) + blur + spread
+    );
+  };
+  for (const decl of css.match(/box-shadow\s*:[^;}]+/gi) ?? [])
+    for (const layer of splitTopLevel(decl.replace(/^[^:]*:/, "")))
+      consider(layer);
+  for (const fn of css.match(/drop-shadow\(([^)]*)\)/gi) ?? [])
+    consider(fn.replace(/^drop-shadow\(/i, "").replace(/\)$/, ""));
+  return worst ? Math.ceil(worst * 1.15) : 0;
+}
+function htmlLayerBleed(clip) {
+  return Math.max(0, Math.round(clip.bleed ?? htmlLayerBleedFor(clip.css)));
+}
+function htmlLayerPictureBox(clip) {
+  const bleed = htmlLayerBleed(clip);
+  return {
+    width: clip.box.width + bleed * 2,
+    height: clip.box.height + bleed * 2,
+    bleed
+  };
+}
+function htmlLayerWidth(clip) {
+  if (clip.width != null) return clip.width;
+  return Math.min(1, htmlLayerPictureBox(clip).width / DESIGN_FRAME_WIDTH);
+}
+var ENTITIES = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  nbsp: " "
+};
+function htmlLayerText(html) {
+  return html.replace(/<style[\s\S]*?<\/style>/gi, " ").replace(/<[^>]*>/g, " ").replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (m, ref) => {
+    if (ref[0] === "#")
+      return String.fromCodePoint(
+        ref[1] === "x" ? parseInt(ref.slice(2), 16) : parseInt(ref.slice(1))
+      );
+    return ENTITIES[ref.toLowerCase()] ?? m;
+  }).replace(/\s+/g, " ").trim();
+}
+function htmlLayerLabel(clip) {
+  const words = htmlLayerText(clip.html);
+  return words ? words.slice(0, 24) : "HTML";
+}
+var VOID_TAGS = [
+  "br",
+  "img",
+  "hr",
+  "input",
+  "source",
+  "col",
+  "area",
+  "base",
+  "wbr",
+  "meta",
+  "link"
+];
+var HTML_LAYER_FOREIGN_FIELDS = [
+  "key",
+  "radius",
+  "shadow",
+  "border",
+  "loop",
+  "frame",
+  "fx",
+  "text",
+  "preset"
+];
+function htmlLayerProblems(clip) {
+  const html = clip.html ?? "";
+  const css = clip.css;
+  const raw = clip;
+  const problems = [];
+  const push2 = (code, level, message) => problems.push({ code, level, message });
+  if (!html.trim()) push2("empty", "problem", "The layer has no markup.");
+  for (const tag of VOID_TAGS) {
+    const open = new RegExp(`<${tag}(\\s[^>]*?)?>`, "gi");
+    let m;
+    let said = false;
+    while (m = open.exec(html)) {
+      if (!m[0].trimEnd().endsWith("/>") && !said) {
+        said = true;
+        push2(
+          "unclosed-void",
+          "problem",
+          `<${tag}> must close itself as <${tag} /> inside a foreignObject.`
+        );
+      }
+    }
+  }
+  const bare = html.match(/&(?!(#\d+|#x[0-9a-fA-F]+|[a-zA-Z][a-zA-Z0-9]*);)/g);
+  if (bare)
+    push2(
+      "bare-ampersand",
+      "problem",
+      `A bare "&" is a parse error; write &amp;. Found ${bare.length}.`
+    );
+  if (/<[a-zA-Z][^>]*?\s[a-zA-Z-]+=(?!["'])[^\s>]+/.test(html))
+    push2(
+      "unquoted-attr",
+      "problem",
+      "Attribute values must be quoted inside a foreignObject."
+    );
+  const bytes = html.length + (css?.length ?? 0);
+  if (bytes > HTML_LAYER_MAX_BYTES)
+    push2(
+      "too-large",
+      "problem",
+      `The layer's source is ${Math.round(bytes / 1e3)} KB; the ceiling is ${HTML_LAYER_MAX_BYTES / 1e3} KB. Inline less, or split the layer.`
+    );
+  else if (bytes > HTML_LAYER_WARN_BYTES)
+    push2(
+      "too-large",
+      "warning",
+      `The layer's source is ${Math.round(bytes / 1e3)} KB. A document carries it twice (the doc and the composed config); keep a layer under ${HTML_LAYER_WARN_BYTES / 1e3} KB.`
+    );
+  for (const field of HTML_LAYER_FOREIGN_FIELDS)
+    if (raw[field] !== void 0)
+      push2(
+        "foreign-field",
+        "problem",
+        `An HTML layer has no "${field}": its CSS is its chrome (shadow, radius, border) and its markup its content.`
+      );
+  const needed = htmlLayerBleedFor(css);
+  if (clip.bleed != null && needed > clip.bleed)
+    push2(
+      "shadow-clipped",
+      "warning",
+      `The CSS paints up to ${needed}px outside the component and bleed is ${clip.bleed}, so the shadow is clipped square at the layer's edge. Set bleed to ${needed}, or leave it out to derive it.`
+    );
+  const external = /\b(src|href)\s*=\s*["']\s*(https?:)?\/\//i.test(html) || /url\(\s*["']?\s*(https?:)?\/\//i.test(css ?? "") || /url\(\s*["']?\s*(https?:)?\/\//i.test(html);
+  if (external)
+    push2(
+      "external-resource",
+      "warning",
+      "The source names a resource by URL. An SVG image fetches nothing, so it will not paint; inline it as a data: URI (faces are inlined for you when the CSS names a hosted family)."
+    );
+  if (/\b(animation|transition)(-[a-z-]+)?\s*:/i.test(css ?? ""))
+    push2(
+      "wall-clock",
+      "warning",
+      "CSS animations inside a layer run on the wall clock, not the timeline: the export will not match the preview. Animate the layer with motion and anim instead."
+    );
+  for (const family of htmlLayerUnhostedFamilies(clip))
+    push2(
+      "unhosted-family",
+      "warning",
+      `The CSS names "${family}", which is not a hosted family (GET https://vos.so/api/fonts); the system stack stands in.`
+    );
+  return problems;
+}
+function wellFormedXml(svg, parseXml) {
+  const doc = parseXml(svg);
+  const errors = doc.getElementsByTagName("parsererror");
+  if (!errors.length) return { ok: true };
+  const text = (errors[0].textContent ?? "").replace(/\s+/g, " ").trim();
+  return { ok: false, error: text || "The markup is not well-formed XML." };
+}
+function fontFaceCss(faces) {
+  let out = "";
+  for (const f of faces)
+    out += `@font-face{font-family:'${f.family}';src:url(${f.dataUri}) format('woff2');font-weight:${f.weight};font-style:${f.style};font-display:block}`;
+  return out;
+}
+function htmlLayerSvg(src, faces = []) {
+  const bleed = Math.max(0, Math.round(src.bleed ?? 0));
+  const boxW = src.box.width + bleed * 2;
+  const boxH = src.box.height + bleed * 2;
+  const wrapper = `.vos-html-layer{width:${boxW}px;height:${boxH}px;box-sizing:border-box;margin:0;padding:${bleed}px;font-family:-apple-system,system-ui,sans-serif;-webkit-font-smoothing:antialiased;text-rendering:geometricPrecision}`;
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${boxW}" height="${boxH}" viewBox="0 0 ${boxW} ${boxH}"><foreignObject x="0" y="0" width="${boxW}" height="${boxH}"><div xmlns="http://www.w3.org/1999/xhtml" class="vos-html-layer"><style>${fontFaceCss(faces)}${wrapper}${src.css ?? ""}</style>` + src.html + `</div></foreignObject></svg>`;
+}
+function fnv1a(s) {
+  let h = 2166136261;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619) >>> 0;
+  }
+  return h.toString(36);
+}
+function htmlLayerKey(clip, faces, bleed) {
+  const src = clip.html + "\0" + (clip.css ?? "") + "\0" + clip.box.width + "x" + clip.box.height + "\0" + bleed + "\0" + faces.map((f) => `${f.family}:${f.url}:${f.weight}:${f.style}`).join("|");
+  return `html:${clip.id}:${fnv1a(src)}`;
+}
+function htmlLayerPayload(clip) {
+  const faces = htmlLayerFaces(clip);
+  const bleed = htmlLayerBleed(clip);
+  return {
+    key: htmlLayerKey(clip, faces, bleed),
+    width: htmlLayerWidth(clip),
+    html: {
+      markup: clip.html,
+      css: clip.css ?? "",
+      box: { width: clip.box.width, height: clip.box.height },
+      bleed,
+      faces
+    }
+  };
+}
+
+// src/overlayText.ts
 var OVERLAY_BOX_PAD_X = 0.6;
 var OVERLAY_BOX_PAD_Y = 0.35;
 var OVERLAY_BOX_RADIUS = 0.25;
@@ -1954,12 +2275,12 @@ var TEXT_PRESETS = {
 var OVERLAY_SIZE_MIN = 12;
 var OVERLAY_SIZE_MAX = 200;
 var OVERLAY_FONT_FACES = [
-  { family: "Lexend", weight: 400, url: fontFaceUrl("lexend", 400) },
-  { family: "Lexend", weight: 600, url: fontFaceUrl("lexend", 600) },
+  { family: "Lexend", weight: 400, url: fontFaceUrl2("lexend", 400) },
+  { family: "Lexend", weight: 600, url: fontFaceUrl2("lexend", 600) },
   {
     family: "JetBrains Mono",
     weight: 400,
-    url: fontFaceUrl("jetbrains-mono", 400)
+    url: fontFaceUrl2("jetbrains-mono", 400)
   }
 ];
 function resolveOverlayStyle(clip) {
@@ -1967,14 +2288,14 @@ function resolveOverlayStyle(clip) {
   const base = TEXT_PRESETS[presetName];
   let stack = base.stack;
   let weight = base.weight;
-  const familyEntry = findFontFamily(clip.family ?? PRESET_FAMILY[presetName]);
+  const familyEntry = findFontFamily2(clip.family ?? PRESET_FAMILY[presetName]);
   if (clip.family) {
     const quoted = clip.family.includes(" ") ? `'${clip.family}'` : clip.family;
     stack = familyEntry ? fontStack(familyEntry) : `${quoted}, ${base.stack}`;
   }
   if (clip.weight !== void 0 || clip.family) {
     const wanted = clip.weight ?? base.weight;
-    weight = familyEntry ? nearestFontWeight(familyEntry, wanted) : wanted;
+    weight = familyEntry ? nearestFontWeight2(familyEntry, wanted) : wanted;
   }
   return {
     ...base,
@@ -1996,7 +2317,7 @@ function resolveOverlayStyle(clip) {
   };
 }
 function overlayFaceFor(clip) {
-  const entry = findFontFamily(
+  const entry = findFontFamily2(
     clip.family ?? PRESET_FAMILY[clip.preset in TEXT_PRESETS ? clip.preset : "title"]
   );
   if (!entry) return null;
@@ -2008,7 +2329,7 @@ function overlayFaceFor(clip) {
   return {
     family: entry.family,
     weight,
-    url: fontFaceUrl(entry.slug, weight)
+    url: fontFaceUrl2(entry.slug, weight)
   };
 }
 function overlayFontFaces(doc) {
@@ -2116,6 +2437,11 @@ function overlayRect(clip, measure, frameW, frameH = 1080, mediaAspect) {
     cy: clip.transform.y * frameH,
     rotation: clip.transform.rotation || 0
   };
+  if (clip.kind === "html") {
+    const pb = htmlLayerPictureBox(clip);
+    const w2 = htmlLayerWidth(clip) * frameW * scale;
+    return { ...base, w: w2, h: w2 * (pb.height / pb.width) };
+  }
   if (clip.kind !== "text") {
     const w2 = (clip.width ?? OVERLAY_MEDIA_DEFAULT_WIDTH) * frameW * scale;
     return { ...base, w: w2, h: w2 / (mediaAspect || 16 / 9) };
@@ -2523,6 +2849,19 @@ function studioEntry(data) {
     onFrame: STUDIO_FRAME
   };
 }
+var HTML_LAYER_SVG_CODE = `(src, faces) => {
+  const bleed = Math.max(0, Math.round(src.bleed || 0))
+  const boxW = src.box.width + bleed * 2
+  const boxH = src.box.height + bleed * 2
+  let fontCss = ''
+  for (const f of faces || []) fontCss += "@font-face{font-family:'" + f.family + "';src:url(" + f.dataUri + ") format('woff2');font-weight:" + f.weight + ";font-style:" + f.style + ";font-display:block}"
+  const wrapper = '.vos-html-layer{width:' + boxW + 'px;height:' + boxH + 'px;box-sizing:border-box;margin:0;padding:' + bleed + 'px;font-family:-apple-system,system-ui,sans-serif;-webkit-font-smoothing:antialiased;text-rendering:geometricPrecision}'
+  return '<svg xmlns="http://www.w3.org/2000/svg" width="' + boxW + '" height="' + boxH + '" viewBox="0 0 ' + boxW + ' ' + boxH + '">' +
+    '<foreignObject x="0" y="0" width="' + boxW + '" height="' + boxH + '">' +
+    '<div xmlns="http://www.w3.org/1999/xhtml" class="vos-html-layer">' +
+    '<style>' + fontCss + wrapper + (src.css || '') + '</style>' + src.html +
+    '</div></foreignObject></svg>'
+}`;
 var STUDIO_SETUP = `async (ctx) => {
   if (!globalThis.__vosTimeline) { ${timelineRuntimeCode} }
   const ns = (window.__vos__ = window.__vos__ || {})
@@ -2589,9 +2928,105 @@ var STUDIO_SETUP = `async (ctx) => {
       ])
     } catch (e) { console.warn('[voila] overlay fonts failed to load', e) }
   }
+  // An HTML layer arrives as SOURCE, and the picture is built HERE.
+  //
+  // Two rules force this shape. An SVG carrying a <foreignObject> is
+  // origin-clean ONLY as a data: URI (served from a URL it taints the canvas
+  // even same-origin, and a tainted frame cannot be uploaded as a WebGL
+  // texture, so every layer vanishes at once), and an SVG loaded through
+  // <img> may fetch nothing of its own, so a @font-face naming a URL is
+  // silently ignored. So the faces are fetched here by ordinary fetch,
+  // inlined, and what lands in the cache is an inline, vector picture under
+  // the clip's content-addressed key.
+  //
+  // Per-clip state on the namespace: htmlWant (the key a clip wants NOW, so a
+  // build a keystroke made stale is dropped before it decodes), htmlLast (the
+  // last picture built for a clip, drawn while the next rasterizes so an edit
+  // never blinks the layer out), htmlKeys (the key in the cache for a clip,
+  // evicted when a new one lands), htmlErrors (why a clip did not decode).
+  // faceData caches a face's bytes by URL across every layer on the page.
+  const htmlSvg = ${HTML_LAYER_SVG_CODE}
+  ns.htmlWant = ns.htmlWant || {}
+  ns.htmlLast = ns.htmlLast || {}
+  ns.htmlKeys = ns.htmlKeys || {}
+  ns.htmlErrors = ns.htmlErrors || {}
+  const faceData = ns.faceData || (ns.faceData = new Map())
+  const faceOf = (f) => {
+    let p = faceData.get(f.url)
+    if (p) return p
+    p = fetch(f.url).then(async (r) => {
+      if (!r.ok) throw new Error('HTTP ' + r.status)
+      const buf = new Uint8Array(await r.arrayBuffer())
+      // Chunked: String.fromCharCode.apply throws on a large spread.
+      let str = ''
+      for (let i = 0; i < buf.length; i += 0x8000) str += String.fromCharCode.apply(null, buf.subarray(i, i + 0x8000))
+      return 'data:font/woff2;base64,' + btoa(str)
+    }).catch((e) => {
+      // Fail open per face, and NOT sticky: the layer paints in the fallback
+      // stack now and the next build asks again.
+      faceData.delete(f.url)
+      console.warn('[voila] html layer face failed to load', f.url, e)
+      return ''
+    })
+    faceData.set(f.url, p)
+    return p
+  }
+  const buildHtmlLayer = async (oc) => {
+    const want = () => ns.htmlWant[oc.id] === oc.key
+    ns.htmlWant[oc.id] = oc.key
+    const h = oc.html
+    const uris = await Promise.all((h.faces || []).map(faceOf))
+    if (!want()) return
+    const faces = []
+    for (let i = 0; i < uris.length; i++) {
+      if (uris[i]) faces.push({ family: h.faces[i].family, weight: h.faces[i].weight, style: h.faces[i].style, dataUri: uris[i] })
+    }
+    const svg = htmlSvg({ html: h.markup, css: h.css, box: h.box, bleed: h.bleed }, faces)
+    const uri = 'data:image/svg+xml;base64,' + btoa(unescape(encodeURIComponent(svg)))
+    const img = await new Promise((res, rej) => {
+      const i = new Image()
+      i.onload = () => res(i)
+      // foreignObject is XML: malformed markup fails to DECODE, silently, and
+      // the layer would simply never appear. Say so instead.
+      i.onerror = () => rej(new Error('did not decode: is the markup well-formed XML?'))
+      i.src = uri
+    })
+    if (!want()) return
+    // A browser that taints a canvas drawing a foreignObject SVG (WebKit's
+    // history) would lose EVERY layer to one SecurityError at the texture
+    // upload. Probe once on a scratch canvas and, failing, drop the HTML
+    // layers and nothing else.
+    if (ns.htmlSafe === undefined) {
+      try {
+        const pc = document.createElement('canvas')
+        pc.width = pc.height = 1
+        const px = pc.getContext('2d')
+        px.drawImage(img, 0, 0, 1, 1)
+        px.getImageData(0, 0, 1, 1)
+        ns.htmlSafe = true
+      } catch (e) {
+        ns.htmlSafe = false
+        console.error('[voila] html layers are off: this browser taints a canvas that draws a foreignObject SVG', e)
+      }
+    }
+    const prev = ns.htmlKeys[oc.id]
+    if (prev && prev !== oc.key) cache.delete(prev)
+    cache.set(oc.key, img)
+    ns.htmlKeys[oc.id] = oc.key
+    ns.htmlLast[oc.id] = img
+    delete ns.htmlErrors[oc.id]
+  }
+  // ON_FRAME is its own function string, so the builder is handed over for a
+  // layer that arrives by live edit after setup has run. A failure is
+  // recorded on the clip and said at the level a render page forwards.
+  ns.buildHtmlLayer = (oc) => buildHtmlLayer(oc).catch((e) => {
+    ns.htmlErrors[oc.id] = String((e && e.message) || e)
+    console.error('[voila] html layer ' + oc.id + ' ' + ns.htmlErrors[oc.id])
+  })
   // Media overlays (V1b): warm-load through the shared cache so the first
   // frame draws complete. Fail-open per clip (a bad key just doesn't draw).
   for (const oc of (ctx.data.overlays || [])) {
+    if (oc.html) { await ns.buildHtmlLayer(oc); continue }
     if (oc.kind !== 'image' && oc.kind !== 'video') continue
     try {
       if (oc.kind === 'image') await loadImage(oc.key)
@@ -2862,6 +3297,8 @@ var STUDIO_FRAME = `(ctx, content, dt) => {
   for (var oi = 0; oi < ols.length; oi++) {
     var ol0 = ols[oi]
     if (t < ol0.start || t > ol0.start + ol0.dur) continue
+    // A page that taints on foreignObject draws no HTML layer (setup's probe).
+    if (ol0.html && ns.htmlSafe === false) continue
     olVisSig += ol0.id + ':' + (ol0.text || ol0.key) + ':' + ol0.x + ',' + ol0.y + ',' + ol0.scale + ',' + ol0.rot + ',' + (ol0.fs || ol0.w) + ',' + (ol0.color || ol0.radius) + ',' + (ol0.opacity == null ? 1 : ol0.opacity) + (ol0.fx ? ',' + ol0.fx.k + ol0.fx.u + ol0.fx.d + ol0.fx.st : '') + (ol0.mw ? ',w' + ol0.mw : '') + ';'
     // fx widens the entrance window to the whole staggered span (tt);
     // without fx it is the legacy enter transition window.
@@ -2873,6 +3310,10 @@ var STUDIO_FRAME = `(ctx, content, dt) => {
     if (ol0.track) olAnim = true
     // A layer CARD is painted on its own plane every frame it is visible.
     if (ol0.card) olAnim = true
+    // An HTML layer whose source just changed is rasterizing: keep repainting
+    // until its picture lands, or the edit would not appear until something
+    // else happened to dirty the canvas.
+    if (ol0.html && !(ns.videoCache && ns.videoCache.get(ol0.key))) olAnim = true
     // Video overlays advance every frame; images redraw until decoded.
     if (ol0.kind === 'video') olAnim = true
     else if (ol0.kind === 'image') {
@@ -2880,6 +3321,20 @@ var STUDIO_FRAME = `(ctx, content, dt) => {
       if (!(olEl0 && olEl0.complete && olEl0.naturalWidth)) olAnim = true
     }
   }
+  // A clip that left the document takes its picture with it: the cache
+  // holds decoded images, and a session's edits would otherwise pile up.
+  if (ns.htmlLast) {
+    for (var hlK in ns.htmlLast) {
+      var hlSeen = false
+      for (var hlI = 0; hlI < ols.length; hlI++) if (ols[hlI].id === hlK) { hlSeen = true; break }
+      if (hlSeen) continue
+      if (ns.htmlKeys && ns.htmlKeys[hlK] && ns.videoCache) ns.videoCache.delete(ns.htmlKeys[hlK])
+      delete ns.htmlLast[hlK]
+      if (ns.htmlKeys) delete ns.htmlKeys[hlK]
+      if (ns.htmlWant) delete ns.htmlWant[hlK]
+      if (ns.htmlErrors) delete ns.htmlErrors[hlK]
+    }
+  }
   var ovSig = W + 'x' + H + '|' + olVisSig
   var ovDirty = ov.sig !== ovSig || ov.active || olAnim
   // The layer cards visible this frame, with their pose, for the card
@@ -2891,6 +3346,18 @@ var STUDIO_FRAME = `(ctx, content, dt) => {
   // picture and the layer card.
   function olAcquire(ol, olT) {
     var olEl = ns.videoCache ? ns.videoCache.get(ol.key) : null
+    // An HTML layer's key is a CACHE HANDLE, not a URL: never hand it to an
+    // <img>. A miss means setup has not built it (a live edit), so ask once
+    // per key and let a later frame pick it up; a build that failed stays
+    // asked, and the next source edit is a new key.
+    if (ol.html) {
+      if (!olEl && ns.buildHtmlLayer) {
+        var hlB = ns.htmlBuilding || (ns.htmlBuilding = {})
+        if (!hlB[ol.key]) { hlB[ol.key] = 1; ns.buildHtmlLayer(ol) }
+      }
+      // While the edited source rasterizes, keep the clip's previous picture.
+      return olEl || (ns.htmlLast && ns.htmlLast[ol.id]) || null
+    }
     if (!olEl && ns.videoCache) {
       if (ol.kind === 'image') {
         olEl = new Image()
@@ -2967,6 +3434,7 @@ var STUDIO_FRAME = `(ctx, content, dt) => {
     var ol = ols[oj]
     var olT = t - ol.start
     if (olT < 0 || olT > ol.dur) continue
+    if (ol.html && ns.htmlSafe === false) continue
     var olA = 1, olYof = 0, olScl = 1, olBlur = 0
     if (ol.fx && ol.fx.u === 'block') {
       // fx owns the entrance; block unit = the legacy presets generalized
@@ -5793,6 +6261,19 @@ function studioLayerData(layers, duration) {
             return track.keyframes.length ? { track } : {};
           })()
         };
+        if (o.kind === "html") {
+          const hl = htmlLayerPayload(o);
+          return {
+            ...base,
+            kind: "image",
+            key: hl.key,
+            w: round6(hl.width),
+            radius: 0,
+            shadow: "none",
+            opacity: round6(o.opacity ?? 1),
+            html: hl.html
+          };
+        }
         if (o.kind !== "text") {
           const lm = rec ? layerMedia(rec, o.key) : null;
           const lmImage = lm ? lm.sourceKind === "image" : o.kind === "image";
@@ -6704,9 +7185,10 @@ function copyLayout(from, to, opts = {}) {
     next.duration = Math.max(0.3, Math.round(outDur * 1e3) / 1e3);
     if (next.kind === "text") {
       if (mine?.kind === "text") next.text = mine.text;
+    } else if (next.kind === "html") {
     } else if (opts.keys?.[clip.id]) {
       next.key = opts.keys[clip.id];
-    } else if (mine && mine.kind !== "text") {
+    } else if (mine && mine.kind !== "text" && mine.kind !== "html") {
       next.key = mine.key;
     } else {
       skippedMarks.push(clip.id);
@@ -6767,7 +7249,7 @@ function copyLayout(from, to, opts = {}) {
   return { doc, notes };
 }
 function trailingFreeze(doc) {
-  const last = doc.segments.at(-1);
+  const last = doc.segments?.at(-1);
   if (!last) return null;
   return docFreezes(doc).find((f) => Math.abs(f.at - last.out) < 1e-9) ?? null;
 }
@@ -6833,9 +7315,10 @@ function applyTemplate(template, take, opts) {
       const word = opts.words?.[clip.id];
       if (word !== void 0) next.text = word;
       else if (mine?.kind === "text") next.text = mine.text;
+    } else if (next.kind === "html") {
     } else if (opts.keys?.[clip.id]) {
       next.key = opts.keys[clip.id];
-    } else if (mine && mine.kind !== "text") {
+    } else if (mine && mine.kind !== "text" && mine.kind !== "html") {
       next.key = mine.key;
     } else if (!/^(https?:|\/\/)/.test(next.key)) {
       skipped.push(clip.id);
@@ -6860,16 +7343,16 @@ function applyTemplate(template, take, opts) {
   }
   if (objects.length || doc.objects) doc.objects = objects;
   const audio = doc.audio.filter(
-    (a) => !template.audio.some((t) => t.id === a.id)
+    (a) => !(template.audio ?? []).some((t) => t.id === a.id)
   );
-  for (const clip of template.audio) {
+  for (const clip of template.audio ?? []) {
     const next = structuredClone(clip);
     next.start = Math.max(0, round34(clip.start + shift));
     next.from = from;
     audio.push(next);
   }
   doc.audio = audio;
-  if (template.frame.anim) {
+  if (template.frame?.anim) {
     doc.frame = {
       ...doc.frame,
       anim: { ...doc.frame.anim ?? {}, ...template.frame.anim }
@@ -7581,6 +8064,60 @@ function destinationsForChannel(channel) {
   return DESTINATIONS.filter((d) => d.channel === channel);
 }
 
+// src/htmlStarters.ts
+var WORDS = "font-family:'Inter',-apple-system,system-ui,sans-serif;color:#fafafa;-webkit-font-smoothing:antialiased;";
+var MONO = "font-family:'JetBrains Mono',ui-monospace,monospace;";
+var CARD = "background:#0b0b0d;border:1px solid rgba(255,255,255,.08);border-radius:16px;box-shadow:0 24px 60px rgba(0,0,0,.45);";
+var HTML_STARTERS = [
+  {
+    id: "callout",
+    name: "Callout",
+    box: { width: 420, height: 132 },
+    html: '<div class="callout"><div class="head"><span class="dot"></span><span class="title">Title</span></div><div class="body">One line that says what this is.</div></div>',
+    css: `.callout{${WORDS}${CARD}box-sizing:border-box;width:420px;height:132px;padding:22px 24px}.head{display:flex;align-items:center;gap:10px}.dot{width:8px;height:8px;border-radius:99px;background:#4ade80;box-shadow:0 0 10px rgba(74,222,128,.9)}.title{font-size:20px;font-weight:600;letter-spacing:-0.01em}.body{margin-top:12px;font-size:15px;line-height:1.5;color:#8b8b94}`
+  },
+  {
+    id: "code",
+    name: "Code",
+    box: { width: 460, height: 168 },
+    html: '<div class="code"><span class="mut">// button.tsx</span>\n<span class="kw">export function</span> <span class="fn">Button</span>({ variant }) {\n  <span class="kw">return</span> <span class="tag">&lt;button</span> className={<span class="fn">cn</span>(variant)} <span class="tag">/&gt;</span>\n}</div>',
+    css: `.code{${MONO}${CARD}color:#e8e8ec;box-sizing:border-box;width:460px;height:168px;padding:22px 24px;font-size:14px;line-height:1.8;white-space:pre;letter-spacing:-0.01em}.kw{color:#c4b5fd}.fn{color:#7dd3fc}.tag{color:#f0abfc}.mut{color:#5b5b66}`
+  },
+  {
+    id: "terminal",
+    name: "Terminal",
+    box: { width: 460, height: 152 },
+    html: '<div class="term"><span class="prompt">$</span> <span class="cmd">npx vos record https://your.app</span>\n<span class="mut">recording 1920x1080 at 30 fps</span>\n<span class="mut">saved take/</span></div>',
+    css: `.term{${MONO}${CARD}background:#08080a;color:#e8e8ec;box-sizing:border-box;width:460px;height:152px;padding:22px 24px;font-size:14px;line-height:1.8;white-space:pre}.prompt{color:#4ade80}.mut{color:#5b5b66}`
+  },
+  {
+    id: "keys",
+    name: "Keys",
+    box: { width: 220, height: 64 },
+    html: '<div class="keys"><kbd>&#8984;</kbd><span class="plus">+</span><kbd>K</kbd></div>',
+    css: `.keys{${WORDS}display:flex;align-items:center;justify-content:center;gap:10px;width:220px;height:64px}kbd{display:inline-flex;align-items:center;justify-content:center;min-width:48px;height:48px;padding:0 14px;border-radius:10px;background:#1a1a1f;border:1px solid rgba(255,255,255,.14);border-bottom-width:3px;box-shadow:0 10px 24px rgba(0,0,0,.4);font-size:22px;font-weight:600}.plus{color:#8b8b94;font-size:18px}`
+  },
+  {
+    id: "badge",
+    name: "Badge",
+    box: { width: 200, height: 52 },
+    html: '<div class="badge"><span class="dot"></span>New in 2.0</div>',
+    css: `.badge{${WORDS}display:inline-flex;align-items:center;gap:10px;height:44px;padding:0 20px;border-radius:99px;background:#1a1a1f;border:1px solid rgba(255,255,255,.12);box-shadow:0 12px 30px rgba(0,0,0,.4);font-size:16px;font-weight:600;letter-spacing:-0.01em}.dot{width:8px;height:8px;border-radius:99px;background:#3b82f6;box-shadow:0 0 10px rgba(59,130,246,.9)}`
+  }
+];
+function htmlStarterClip(starter, id, start, duration) {
+  return {
+    id,
+    kind: "html",
+    html: starter.html,
+    css: starter.css,
+    box: { ...starter.box },
+    start,
+    duration,
+    transform: { x: 0.5, y: 0.5, scale: 1, rotation: 0 }
+  };
+}
+
 // src/lower/audioPlan.ts
 var AUDIO_PLAN_STEP = 1 / 240;
 function envelopeAt(env, t, def) {
@@ -8738,7 +9275,7 @@ var overlaysLane = {
         kind: "clip",
         t: round11(o.start),
         duration: round11(o.duration),
-        label: o.kind === "text" ? o.text.split("\n")[0].slice(0, 24) || "Text" : o.kind === "image" ? "Image" : "Video"
+        label: o.kind === "text" ? o.text.split("\n")[0].slice(0, 24) || "Text" : o.kind === "html" ? htmlLayerLabel(o) : o.kind === "image" ? "Image" : "Video"
       },
       // Pose diamonds render after the clips, so they sit on top.
       ...poseItems(o.id, o.start, o.duration, o.motion)
@@ -9134,6 +9671,7 @@ export {
   DEFAULT_TILT_POSE,
   DEFAULT_ZOOM_LEVEL,
   DEFAULT_ZOOM_STYLE,
+  DESIGN_FRAME_WIDTH,
   DESTINATIONS,
   DIGEST_CROP_MAX,
   DIGEST_FULL_MAX,
@@ -9155,6 +9693,11 @@ export {
   FREEZE_SECONDS_MAX,
   FREEZE_SECONDS_MIN,
   HOUSE_GRADIENT,
+  HTML_LAYER_FOREIGN_FIELDS,
+  HTML_LAYER_MAX_BYTES,
+  HTML_LAYER_SVG_CODE,
+  HTML_LAYER_WARN_BYTES,
+  HTML_STARTERS,
   IDLE_KINDS,
   LAYER_CARD_SHADOW,
   LAYOUT_FRAME_FIELDS,
@@ -9268,6 +9811,8 @@ export {
   copyLayout,
   copyStyle,
   cropBox,
+  cssFamilies,
+  cssWeights,
   cursorIdleFade,
   deriveViewportCrop,
   destinationById,
@@ -9304,8 +9849,22 @@ export {
   freezeOutputExtents,
   hexToRgbTriplet,
   houseLook,
+  htmlLayerBleed,
+  htmlLayerBleedFor,
+  htmlLayerFaces,
+  htmlLayerKey,
+  htmlLayerLabel,
+  htmlLayerPayload,
+  htmlLayerPictureBox,
+  htmlLayerProblems,
+  htmlLayerSvg,
+  htmlLayerText,
+  htmlLayerUnhostedFamilies,
+  htmlLayerWidth,
+  htmlStarterClip,
   idleGaps,
   idleKey,
+  isKeyedOverlay,
   isLookKind,
   isMusicBed,
   isPlayback,
@@ -9401,6 +9960,7 @@ export {
   transitionSeconds,
   videoLane,
   voiceKey,
+  wellFormedXml,
   withBackdrop,
   withFreezes,
   withHolds,