@vosjs/studio-core 0.19.1 → 0.20.0

package/dist/index.d.ts

@@ -1353,6 +1353,18 @@ interface HtmlOverlayClip extends OverlayClipBase {
      * component designed at 452 px lands at 452 px in a 1080p frame.
      */
     width?: number;
+    /**
+     * A LIVE layer: the picture is a function of clip-local time. CSS
+     * `@keyframes` inside it are scrubbed to t (paused, delayed by -t), and
+     * `{{t}}` / `{{data.<name>}}` placeholders in the markup and CSS fill per
+     * frame, so a counter, a progress bar or a typed line come out on the
+     * timeline's clock in the preview and in every export chunk alike. One
+     * rasterize per frame while on screen. Absent = a still, byte-identical
+     * to before the field existed.
+     */
+    live?: boolean;
+    /** Values for a live layer's `{{data.<name>}}` placeholders. */
+    data?: Record<string, string | number | boolean>;
     /** Opacity 0..1. Absent = 1. */
     opacity?: number;
 }
@@ -3090,7 +3102,7 @@ declare function studioEntry(data: Record<string, unknown>): StudioEntry;
  * import, so the composer is carried twice and `htmlOverlay.test.ts` pins
  * the two byte-for-byte. Change them together.
  */
-declare const HTML_LAYER_SVG_CODE = "(src, faces) => {\n  const bleed = Math.max(0, Math.round(src.bleed || 0))\n  const boxW = src.box.width + bleed * 2\n  const boxH = src.box.height + bleed * 2\n  let fontCss = ''\n  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}\"\n  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}'\n  return '<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"' + boxW + '\" height=\"' + boxH + '\" viewBox=\"0 0 ' + boxW + ' ' + boxH + '\">' +\n    '<foreignObject x=\"0\" y=\"0\" width=\"' + boxW + '\" height=\"' + boxH + '\">' +\n    '<div xmlns=\"http://www.w3.org/1999/xhtml\" class=\"vos-html-layer\">' +\n    '<style>' + fontCss + wrapper + (src.css || '') + '</style>' + src.html +\n    '</div></foreignObject></svg>'\n}";
+declare const HTML_LAYER_SVG_CODE = "(src, faces, assets) => {\n  const bleed = Math.max(0, Math.round(src.bleed || 0))\n  const boxW = src.box.width + bleed * 2\n  const boxH = src.box.height + bleed * 2\n  let fontCss = ''\n  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}\"\n  const t = src.t || 0\n  const fmtT = (n) => String(Math.round(n * 1000) / 1000)\n  const esc = (v) => String(v).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/\"/g, '&quot;')\n  const fill = (text) => {\n    let out = text\n    for (const a of assets || []) out = out.split(a.url).join(a.dataUri)\n    if (src.live) {\n      out = out.replace(/\\{\\{\\s*t\\s*\\}\\}/g, fmtT(t))\n      out = out.replace(/\\{\\{\\s*data\\.([A-Za-z0-9_.-]+)\\s*\\}\\}/g, (m, name) => { const v = src.data ? src.data[name] : undefined; return v == null ? '' : esc(v) })\n    }\n    return out\n  }\n  const scrub = src.live ? '.vos-html-layer{--vos-t:' + fmtT(t) + '}.vos-html-layer,.vos-html-layer *{animation-play-state:paused!important;animation-delay:calc(var(--vos-t) * -1s)!important}' : ''\n  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}'\n  return '<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"' + boxW + '\" height=\"' + boxH + '\" viewBox=\"0 0 ' + boxW + ' ' + boxH + '\">' +\n    '<foreignObject x=\"0\" y=\"0\" width=\"' + boxW + '\" height=\"' + boxH + '\">' +\n    '<div xmlns=\"http://www.w3.org/1999/xhtml\" class=\"vos-html-layer\">' +\n    '<style>' + fontCss + wrapper + fill(src.css || '') + scrub + '</style>' + fill(src.html) +\n    '</div></foreignObject></svg>'\n}";
 
 /** The design frame an HTML layer's `box` is measured against (1080p). */
 declare const DESIGN_FRAME_WIDTH = 1920;
@@ -3113,6 +3125,14 @@ interface HtmlLayerSource {
         height: number;
     };
     bleed?: number;
+    /**
+     * A LIVE layer (§3.13): the picture is a function of clip-local time.
+     * `t` is the moment being drawn, `data` the clip's own values for the
+     * `{{data.<name>}}` placeholders. Absent = a still.
+     */
+    live?: boolean;
+    t?: number;
+    data?: Record<string, string | number | boolean>;
 }
 interface HtmlLayerInlineFace {
     family: string;
@@ -3120,6 +3140,11 @@ interface HtmlLayerInlineFace {
     style: 'normal' | 'italic';
     dataUri: string;
 }
+/** An image the source names by URL, fetched and inlined by the page. */
+interface HtmlLayerInlineAsset {
+    url: string;
+    dataUri: string;
+}
 declare function cssFamilies(css: string | undefined): string[];
 /**
  * The weights the CSS and the markup ask for: `font-weight` numbers and
@@ -3180,7 +3205,7 @@ declare function htmlLayerWidth(clip: Pick<HtmlOverlayClip, 'width' | 'box' | 'c
 declare function htmlLayerText(html: string): string;
 /** The timeline item's label: the first words, else the kind. */
 declare function htmlLayerLabel(clip: Pick<HtmlOverlayClip, 'html'>): string;
-type HtmlLayerProblemCode = 'empty' | 'unclosed-void' | 'bare-ampersand' | 'unquoted-attr' | 'too-large' | 'foreign-field' | 'shadow-clipped' | 'external-resource' | 'wall-clock' | 'unhosted-family';
+type HtmlLayerProblemCode = 'empty' | 'unclosed-void' | 'bare-ampersand' | 'unquoted-attr' | 'too-large' | 'foreign-field' | 'shadow-clipped' | 'external-resource' | 'wall-clock' | 'live-delay' | 'placeholder-still' | 'unhosted-family';
 interface HtmlLayerProblem {
     code: HtmlLayerProblemCode;
     /** A problem stops the layer painting; a warning is a layer that paints wrong. */
@@ -3196,7 +3221,7 @@ declare const HTML_LAYER_FOREIGN_FIELDS: readonly ["key", "radius", "shadow", "b
  * author is told instead, the same answer in the studio, in `vos validate`
  * and in a test.
  */
-declare function htmlLayerProblems(clip: Pick<HtmlOverlayClip, 'html' | 'css' | 'bleed' | 'fonts'>): HtmlLayerProblem[];
+declare function htmlLayerProblems(clip: Pick<HtmlOverlayClip, 'html' | 'css' | 'bleed' | 'fonts' | 'live'>): HtmlLayerProblem[];
 /**
  * The real XML question, asked of a real parser: the studio hands in
  * `DOMParser`, a test hands in a stub. The CLI does not call this (Node
@@ -3220,9 +3245,15 @@ declare function wellFormedXml(svg: string, parseXml: (text: string) => {
  * resets the two properties an SVG document does not inherit sensibly;
  * everything else is the author's.
  *
+ * Assets the source names by URL are swapped for their bytes. A LIVE layer
+ * is composed for one moment: `{{t}}` and `{{data.<name>}}` fill, and a
+ * scrub block after the author's CSS pauses every animation and delays it
+ * by -t, so the browser lays the frame out at exactly that offset (the
+ * standard way to scrub a CSS animation, here applied per picture).
+ *
  * MIRRORED by `HTML_LAYER_SVG_CODE` in `lower/studioEntry.ts`. Change both.
  */
-declare function htmlLayerSvg(src: HtmlLayerSource, faces?: readonly HtmlLayerInlineFace[]): string;
+declare function htmlLayerSvg(src: HtmlLayerSource, faces?: readonly HtmlLayerInlineFace[], assets?: readonly HtmlLayerInlineAsset[]): string;
 /**
  * The layer's CACHE KEY: content-addressed over everything the picture is
  * made of (markup, CSS, box, bleed, the resolved faces), so an edit to the
@@ -3231,7 +3262,7 @@ declare function htmlLayerSvg(src: HtmlLayerSource, faces?: readonly HtmlLayerIn
  * scaling or animating the clip does not re-key it: none of those repaint.
  * The key is a handle, never a URL: nothing may fetch it.
  */
-declare function htmlLayerKey(clip: Pick<HtmlOverlayClip, 'id' | 'html' | 'css' | 'box'>, faces: readonly HtmlLayerFace[], bleed: number): string;
+declare function htmlLayerKey(clip: Pick<HtmlOverlayClip, 'id' | 'html' | 'css' | 'box' | 'live' | 'data'>, faces: readonly HtmlLayerFace[], bleed: number, assets?: readonly string[]): string;
 /** The shape the page is handed for a layer: the source plus resolved faces. */
 interface HtmlLayerPayload {
     markup: string;
@@ -3242,6 +3273,11 @@ interface HtmlLayerPayload {
     };
     bleed: number;
     faces: HtmlLayerFace[];
+    /** Images the source names by URL, for the page to fetch and inline. */
+    assets: string[];
+    /** A live layer: the page composes the picture per frame at clip-local t. */
+    live?: true;
+    data?: Record<string, string | number | boolean>;
 }
 /** Everything the lowering emits for a layer, from the clip alone. */
 declare function htmlLayerPayload(clip: HtmlOverlayClip): {

package/dist/index.js

@@ -1918,6 +1918,8 @@ import { findFontFamily, fontFaceUrl, nearestFontWeight } from "@vosjs/shared";
 var DESIGN_FRAME_WIDTH = 1920;
 var HTML_LAYER_WARN_BYTES = 32e3;
 var HTML_LAYER_MAX_BYTES = 128e3;
+var HTML_LAYER_LIVE_HZ = 60;
+var HTML_LAYER_ASSET_HOST = "https://assets.vos.so/";
 function splitTopLevel(value) {
   const out = [];
   let depth = 0;
@@ -2017,6 +2019,33 @@ function htmlLayerUnhostedFamilies(clip) {
     (f) => !findFontFamily(f) && !explicit.has(f.toLowerCase())
   );
 }
+function htmlLayerAssetUrls(clip) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  const add = (u) => {
+    if (!seen.has(u)) {
+      seen.add(u);
+      out.push(u);
+    }
+  };
+  for (const m of clip.html.matchAll(
+    /\bsrc\s*=\s*["']((?:https?:)?\/\/[^"']+)["']/gi
+  ))
+    add(m[1]);
+  for (const text of [clip.html, clip.css ?? ""])
+    for (const m of text.matchAll(
+      /url\(\s*["']?((?:https?:)?\/\/[^"')\s]+)["']?\s*\)/gi
+    ))
+      add(m[1]);
+  return out;
+}
+function htmlLayerAssets(clip) {
+  const inlinable = [];
+  const foreign = [];
+  for (const u of htmlLayerAssetUrls(clip))
+    (u.replace(/^\/\//, "https://").startsWith(HTML_LAYER_ASSET_HOST) ? inlinable : foreign).push(u);
+  return { inlinable, foreign };
+}
 function htmlLayerBleedFor(css) {
   if (!css) return 0;
   let worst = 0;
@@ -2074,6 +2103,7 @@ function htmlLayerLabel(clip) {
   const words = htmlLayerText(clip.html);
   return words ? words.slice(0, 24) : "HTML";
 }
+var HTML_LAYER_PLACEHOLDER = /\{\{\s*(t|data\.[A-Za-z0-9_.-]+)\s*\}\}/;
 var VOID_TAGS = [
   "br",
   "img",
@@ -2160,18 +2190,36 @@ function htmlLayerProblems(clip) {
       "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)
+  for (const u of htmlLayerAssets({ html, css }).foreign)
     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)."
+      `The source names ${u} by URL. The page inlines only ${HTML_LAYER_ASSET_HOST}\u2026 (the host it may fetch, and the one the fleet reaches), so this will paint blank. Upload it (vos asset upload) or inline it as a data: URI.`
     );
-  if (/\b(animation|transition)(-[a-z-]+)?\s*:/i.test(css ?? ""))
+  if (/\bhref\s*=\s*["']\s*(https?:)?\/\//i.test(html))
+    push2(
+      "external-resource",
+      "warning",
+      "The source names a stylesheet or a link by URL. An SVG image fetches no href; inline the styles in the CSS."
+    );
+  const animated = /\b(animation|transition)(-[a-z-]+)?\s*:/i.test(css ?? "");
+  if (animated && !clip.live)
     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."
+      "CSS animations inside a layer run on the wall clock, not the timeline: the export will not match the preview. Set live: true to scrub them to the clip's time, or animate the layer with motion and anim."
+    );
+  if (clip.live && /\banimation-delay\s*:/i.test(css ?? ""))
+    push2(
+      "live-delay",
+      "warning",
+      "A live layer scrubs its keyframes by setting animation-delay to -t, so the authored animation-delay is overridden. Fold the delay into the keyframes instead."
+    );
+  if (!clip.live && (HTML_LAYER_PLACEHOLDER.test(html) || HTML_LAYER_PLACEHOLDER.test(css ?? "")))
+    push2(
+      "placeholder-still",
+      "warning",
+      "The source carries {{t}} or {{data.\u2026}} placeholders, which fill only on a live layer (live: true); a still layer shows them as written."
     );
   for (const family of htmlLayerUnhostedFamilies(clip))
     push2(
@@ -2194,12 +2242,31 @@ function fontFaceCss(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 = []) {
+var fmtT = (t) => String(Math.round(t * 1e3) / 1e3);
+var escapeXml = (v) => String(v).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+function htmlLayerSvg(src, faces = [], assets = []) {
   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 t = src.t ?? 0;
+  const fill = (text) => {
+    let out = text;
+    for (const a of assets) out = out.split(a.url).join(a.dataUri);
+    if (src.live) {
+      out = out.replace(/\{\{\s*t\s*\}\}/g, fmtT(t));
+      out = out.replace(
+        /\{\{\s*data\.([A-Za-z0-9_.-]+)\s*\}\}/g,
+        (_m, name) => {
+          const v = src.data ? src.data[name] : void 0;
+          return v == null ? "" : escapeXml(v);
+        }
+      );
+    }
+    return out;
+  };
+  const scrub = src.live ? `.vos-html-layer{--vos-t:${fmtT(t)}}.vos-html-layer,.vos-html-layer *{animation-play-state:paused!important;animation-delay:calc(var(--vos-t) * -1s)!important}` : "";
   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>`;
+  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}${fill(src.css ?? "")}${scrub}</style>` + fill(src.html) + `</div></foreignObject></svg>`;
 }
 function fnv1a(s) {
   let h = 2166136261;
@@ -2209,22 +2276,27 @@ function fnv1a(s) {
   }
   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("|");
+function htmlLayerKey(clip, faces, bleed, assets = []) {
+  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("|") + " " + assets.join("|") + // A live layer's picture is also a function of t: ON_FRAME appends the
+  // moment to this key per frame. The data rides here, the moment there.
+  (clip.live ? " live " + JSON.stringify(clip.data ?? null) : "");
   return `html:${clip.id}:${fnv1a(src)}`;
 }
 function htmlLayerPayload(clip) {
   const faces = htmlLayerFaces(clip);
   const bleed = htmlLayerBleed(clip);
+  const assets = htmlLayerAssets(clip).inlinable;
   return {
-    key: htmlLayerKey(clip, faces, bleed),
+    key: htmlLayerKey(clip, faces, bleed, assets),
     width: htmlLayerWidth(clip),
     html: {
       markup: clip.html,
       css: clip.css ?? "",
       box: { width: clip.box.width, height: clip.box.height },
       bleed,
-      faces
+      faces,
+      assets,
+      ...clip.live ? { live: true, ...clip.data ? { data: clip.data } : {} } : {}
     }
   };
 }
@@ -2849,17 +2921,30 @@ function studioEntry(data) {
     onFrame: STUDIO_FRAME
   };
 }
-var HTML_LAYER_SVG_CODE = `(src, faces) => {
+var HTML_LAYER_SVG_CODE = `(src, faces, assets) => {
   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 t = src.t || 0
+  const fmtT = (n) => String(Math.round(n * 1000) / 1000)
+  const esc = (v) => String(v).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
+  const fill = (text) => {
+    let out = text
+    for (const a of assets || []) out = out.split(a.url).join(a.dataUri)
+    if (src.live) {
+      out = out.replace(/\\{\\{\\s*t\\s*\\}\\}/g, fmtT(t))
+      out = out.replace(/\\{\\{\\s*data\\.([A-Za-z0-9_.-]+)\\s*\\}\\}/g, (m, name) => { const v = src.data ? src.data[name] : undefined; return v == null ? '' : esc(v) })
+    }
+    return out
+  }
+  const scrub = src.live ? '.vos-html-layer{--vos-t:' + fmtT(t) + '}.vos-html-layer,.vos-html-layer *{animation-play-state:paused!important;animation-delay:calc(var(--vos-t) * -1s)!important}' : ''
   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 +
+    '<style>' + fontCss + wrapper + fill(src.css || '') + scrub + '</style>' + fill(src.html) +
     '</div></foreignObject></svg>'
 }`;
 var STUDIO_SETUP = `async (ctx) => {
@@ -2950,38 +3035,53 @@ var STUDIO_SETUP = `async (ctx) => {
   ns.htmlLast = ns.htmlLast || {}
   ns.htmlKeys = ns.htmlKeys || {}
   ns.htmlErrors = ns.htmlErrors || {}
+  // One byte cache for faces AND the images a layer names by URL, keyed by
+  // URL: fetched once per page however many layers name it, inlined as a
+  // data: URI (a face is always woff2; an image carries its own type).
   const faceData = ns.faceData || (ns.faceData = new Map())
-  const faceOf = (f) => {
-    let p = faceData.get(f.url)
+  const bytesOf = (url, mime, what) => {
+    let p = faceData.get(url)
     if (p) return p
-    p = fetch(f.url).then(async (r) => {
+    p = fetch(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)
+      const type = mime || ((r.headers.get('content-type') || 'application/octet-stream').split(';')[0])
+      return 'data:' + type + ';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)
+      // Fail open per URL, and NOT sticky: the layer paints without it now
+      // and the next build asks again.
+      faceData.delete(url)
+      console.warn('[voila] html layer ' + what + ' failed to load', url, e)
       return ''
     })
-    faceData.set(f.url, p)
+    faceData.set(url, p)
     return p
   }
-  const buildHtmlLayer = async (oc) => {
-    const want = () => ns.htmlWant[oc.id] === oc.key
-    ns.htmlWant[oc.id] = oc.key
+  const faceOf = (f) => bytesOf(f.url, 'font/woff2', 'face')
+  const assetOf = (url) => bytesOf(url, '', 'asset')
+  // The second argument names the moment a LIVE layer is composed for: its
+  // own key (the clip's key plus the moment) and t. A still builds under
+  // the clip's key.
+  const buildHtmlLayer = async (oc, live) => {
+    const key = live ? live.key : oc.key
+    const want = () => ns.htmlWant[oc.id] === key
+    ns.htmlWant[oc.id] = key
     const h = oc.html
     const uris = await Promise.all((h.faces || []).map(faceOf))
+    const assetUris = await Promise.all((h.assets || []).map(assetOf))
     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 assets = []
+    for (let i = 0; i < assetUris.length; i++) {
+      if (assetUris[i]) assets.push({ url: h.assets[i], dataUri: assetUris[i] })
+    }
+    const svg = htmlSvg({ html: h.markup, css: h.css, box: h.box, bleed: h.bleed, live: !!live, t: live ? live.t : 0, data: h.data }, faces, assets)
     const uri = 'data:image/svg+xml;base64,' + btoa(unescape(encodeURIComponent(svg)))
     const img = await new Promise((res, rej) => {
       const i = new Image()
@@ -3009,24 +3109,59 @@ var STUDIO_SETUP = `async (ctx) => {
         console.error('[voila] html layers are off: this browser taints a canvas that draws a foreignObject SVG', e)
       }
     }
+    // One picture per clip in the cache: the previous key goes when a new
+    // one lands, which for a live layer is every frame.
     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
+    if (prev && prev !== key) cache.delete(prev)
+    cache.set(key, img)
+    ns.htmlKeys[oc.id] = 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.buildHtmlLayer = (oc, live) => buildHtmlLayer(oc, live).catch((e) => {
     ns.htmlErrors[oc.id] = String((e && e.message) || e)
     console.error('[voila] html layer ' + oc.id + ' ' + ns.htmlErrors[oc.id])
   })
+  // The capture contract for a LIVE layer, on ANY anchor. A recording's own
+  // program installs the settle machinery (pendingDecodes, the wait a
+  // capture awaits, a frame-prep hook that requests the frame's footage
+  // before the paint); a program anchor installs none of it, and a live
+  // layer on one would export a frame behind (the last landed picture),
+  // since nothing awaited the build. So the entry installs what is absent
+  // and registers its own hook: the moment every visible live layer needs
+  // at t is asked for BEFORE the paint and put on pendingDecodes, so the
+  // first paint draws the exact picture and a still at t is t. ON_FRAME
+  // asks the same way (one source, inlined in both scopes) for the preview,
+  // where the last landed picture stands in meanwhile.
+  ns.pendingDecodes = ns.pendingDecodes || new Set()
+  if (!ns.waitForVideosReady) ns.waitForVideosReady = async () => {
+    if (ns.pendingDecodes.size) await Promise.all([...ns.pendingDecodes])
+  }
+  ns.framePrep = ns.framePrep || new Map()
+  ns.framePrep.set('vosso.studio', (t) => {
+    if (ns.isPaused === false) return
+    for (const ol of (ctx.data.overlays || [])) {
+      if (!ol.html || !ol.html.live) continue
+      const olT = t - ol.start
+      if (olT < 0 || olT > ol.dur) continue
+      const q = Math.round(olT * ${HTML_LAYER_LIVE_HZ})
+      const key = ol.key + '@' + q
+      if (cache.get(key) || ns.htmlWant[ol.id] === key) continue
+      const p = ns.buildHtmlLayer(ol, { key, t: q / ${HTML_LAYER_LIVE_HZ} })
+      if (p && p.finally) {
+        ns.pendingDecodes.add(p)
+        p.finally(() => ns.pendingDecodes.delete(p))
+      }
+    }
+  })
   // 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).
+  // A live layer warms at its first moment; ON_FRAME re-composes it per frame.
   for (const oc of (ctx.data.overlays || [])) {
-    if (oc.html) { await ns.buildHtmlLayer(oc); continue }
+    if (oc.html) { await ns.buildHtmlLayer(oc, oc.html.live ? { key: oc.key + '@0', t: 0 } : undefined); continue }
     if (oc.kind !== 'image' && oc.kind !== 'video') continue
     try {
       if (oc.kind === 'image') await loadImage(oc.key)
@@ -3314,6 +3449,8 @@ var STUDIO_FRAME = `(ctx, content, dt) => {
     // 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
+    // A LIVE html layer is a new picture every frame it is on screen.
+    if (ol0.html && ol0.html.live) olAnim = true
     // Video overlays advance every frame; images redraw until decoded.
     if (ol0.kind === 'video') olAnim = true
     else if (ol0.kind === 'image') {
@@ -3351,6 +3488,28 @@ var STUDIO_FRAME = `(ctx, content, dt) => {
     // 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 (ol.html.live) {
+        // A live layer's picture is f(t): the key carries clip-local time on
+        // the ${HTML_LAYER_LIVE_HZ} Hz grid, the builder keeps ONE picture per clip
+        // (the previous moment's is evicted as the next lands) and the last
+        // landed picture is drawn while the next composes, so the preview
+        // never blinks. A build in flight for this very moment is not asked
+        // again (htmlWant holds the moment). In capture the build rides
+        // pendingDecodes, so the frame settles and paints again with the
+        // exact picture (the harness's two-phase settle): the export is
+        // deterministic where the preview is merely prompt.
+        var hlQ = Math.round(olT * ${HTML_LAYER_LIVE_HZ})
+        var hlKey = ol.key + '@' + hlQ
+        var hlEl = ns.videoCache ? ns.videoCache.get(hlKey) : null
+        if (!hlEl && ns.buildHtmlLayer && !(ns.htmlWant && ns.htmlWant[ol.id] === hlKey)) {
+          var hlP = ns.buildHtmlLayer(ol, { key: hlKey, t: hlQ / ${HTML_LAYER_LIVE_HZ} })
+          if (ns.pendingDecodes && hlP && hlP.finally) {
+            ns.pendingDecodes.add(hlP)
+            hlP.finally(function () { ns.pendingDecodes.delete(hlP) })
+          }
+        }
+        return hlEl || (ns.htmlLast && ns.htmlLast[ol.id]) || null
+      }
       if (!olEl && ns.buildHtmlLayer) {
         var hlB = ns.htmlBuilding || (ns.htmlBuilding = {})
         if (!hlB[ol.key]) { hlB[ol.key] = 1; ns.buildHtmlLayer(ol) }