@vosjs/studio-core 0.19.1 → 0.21.0

package/dist/index.js

@@ -1135,7 +1135,7 @@ var ZOOM_STYLES = {
   glide: {
     autoZoom: true,
     clusterGap: 3,
-    minClusterClicks: 2,
+    minClusterClicks: 1,
     targetFill: 0.42,
     minLevel: 1.3,
     maxLevel: 1.8,
@@ -1308,7 +1308,7 @@ var ZOOM_STYLES = {
   keynote: {
     autoZoom: true,
     clusterGap: 3,
-    minClusterClicks: 2,
+    minClusterClicks: 1,
     targetFill: 0.42,
     minLevel: 1.3,
     maxLevel: 1.8,
@@ -1417,13 +1417,17 @@ var DWELL_MIN = 0.45;
 var DWELL_MAX = 2.6;
 var DWELL_SPACING = 1.8;
 var DRAG_FIT_LEVEL = 1.15;
+var PRESS_ECHO_MS = 4;
+var PRESS_ECHO_PX = 2;
 var TYPING_MIN_PINGS = 2;
 var TYPING_MIN_DUR = 0.5;
 var TYPING_CLICK_ABSORB = 1.5;
 var TYPING_REFOCUS_FRAC = 0.08;
 function groupTrack(track, opts) {
-  const { width, height, clusterGap, typingGap, typingZoom } = opts;
-  const clicks = track.filter((e) => e.type === "down").map((e) => ({ t: e.t / 1e3, rect: e.rect, x: e.x, y: e.y }));
+  const { width, height, clusterGap, typingGap, typingZoom, targetFill } = opts;
+  const clicks = dedupePresses(
+    track.filter((e) => e.type === "down")
+  ).map((e) => ({ t: e.t / 1e3, rect: e.rect, x: e.x, y: e.y }));
   const sessions = typingZoom ? typingSessions(track, width, height, typingGap) : [];
   const absorbed = /* @__PURE__ */ new Set();
   for (const s of sessions) {
@@ -1441,15 +1445,43 @@ function groupTrack(track, opts) {
       s.events = [best, ...s.events];
     }
   }
-  const clusters = [];
+  const targets = [];
+  const surfaces = [];
   for (const c of clicks) {
     if (absorbed.has(c)) continue;
-    const last = clusters.at(-1);
-    const prev = last?.at(-1);
-    if (last && prev && c.t - prev.t <= clusterGap) last.push(c);
-    else clusters.push([c]);
+    if (isSurfacePress(c, width, height, targetFill)) surfaces.push(c);
+    else targets.push(c);
+  }
+  const chain = (list) => {
+    const clusters = [];
+    for (const c of list) {
+      const last = clusters.at(-1);
+      const prev = last?.at(-1);
+      if (last && prev && c.t - prev.t <= clusterGap) last.push(c);
+      else clusters.push([c]);
+    }
+    return clusters;
+  };
+  return { sessions, clusters: chain(targets), surfaces: chain(surfaces) };
+}
+function dedupePresses(downs) {
+  const kept = [];
+  for (const e of downs) {
+    const prev = kept.at(-1);
+    if (prev && e.t - prev.t <= PRESS_ECHO_MS && Math.abs(e.x - prev.x) <= PRESS_ECHO_PX && Math.abs(e.y - prev.y) <= PRESS_ECHO_PX) {
+      continue;
+    }
+    kept.push(e);
   }
-  return { sessions, clusters };
+  return kept;
+}
+function fitLevel(rect, width, height, targetFill) {
+  if (!rect || rect.w <= 0 || rect.h <= 0) return null;
+  return Math.min(width * targetFill / rect.w, height * targetFill / rect.h);
+}
+function isSurfacePress(c, width, height, targetFill) {
+  const fit = fitLevel(c.rect, width, height, targetFill);
+  return fit !== null && fit < DRAG_FIT_LEVEL;
 }
 function planAutoZoom(track, options) {
   const style = resolveZoomStyle(options.style, options.params);
@@ -1470,31 +1502,31 @@ function planAutoZoom(track, options) {
     typingHold = style.typingHold,
     typingMinLevel = style.typingMinLevel
   } = options;
-  const { sessions, clusters } = groupTrack(track, {
+  const { sessions, clusters, surfaces } = groupTrack(track, {
     width,
     height,
     clusterGap,
     typingGap,
-    typingZoom
+    typingZoom,
+    targetFill
   });
   const eligible = clusters.filter((c) => c.length >= minClusterClicks);
   const clickSpans = [];
-  const dragReserved = [];
+  const dragReserved = surfaces.map((cluster, i) => {
+    const f = clusterFocus(cluster, width, height);
+    return {
+      id: `drag${i}`,
+      in: Math.max(0, cluster[0].t - lead),
+      out: cluster[cluster.length - 1].t + hold,
+      level: 1,
+      cx: f.cx,
+      cy: f.cy
+    };
+  });
   for (const cluster of eligible) {
     const first = cluster[0];
     const last = cluster[cluster.length - 1];
     const f = focusFor(cluster, width, height, targetFill, minLevel, maxLevel);
-    if (f.fit !== null && f.fit < DRAG_FIT_LEVEL) {
-      dragReserved.push({
-        id: `drag${dragReserved.length}`,
-        in: Math.max(0, first.t - lead),
-        out: last.t + hold,
-        level: 1,
-        cx: f.cx,
-        cy: f.cy
-      });
-      continue;
-    }
     clickSpans.push({
       in: Math.max(0, first.t - lead),
       out: last.t + hold,
@@ -1668,15 +1700,8 @@ function focusFor(cluster, width, height, targetFill, minLevel, maxLevel) {
   const n = cluster.length;
   const cx = clamp012(sx / n / width);
   const cy = clamp012(sy / n / height);
-  let level = maxLevel;
-  let fit = null;
-  if (maxW > 0 && maxH > 0) {
-    const fitX = width * targetFill / maxW;
-    const fitY = height * targetFill / maxH;
-    level = Math.min(fitX, fitY);
-    fit = level;
-  }
-  return { cx, cy, level: clamp2(level, minLevel, maxLevel), fit };
+  const level = fitLevel({ x: 0, y: 0, w: maxW, h: maxH }, width, height, targetFill) ?? maxLevel;
+  return { cx, cy, level: clamp2(level, minLevel, maxLevel) };
 }
 function clusterFocus(events, width, height) {
   let sx = 0;
@@ -1918,6 +1943,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 +2044,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 +2128,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 +2215,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 ${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 (/\bhref\s*=\s*["']\s*(https?:)?\/\//i.test(html))
     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 a stylesheet or a link by URL. An SVG image fetches no href; inline the styles in the CSS."
     );
-  if (/\b(animation|transition)(-[a-z-]+)?\s*:/i.test(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 +2267,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 +2301,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 +2946,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 +3060,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 +3134,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 +3474,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 +3513,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) }
@@ -6803,14 +6987,15 @@ function momentsFromDoc(doc, plan, opts = {}) {
     rect: null
   });
   if (track.length) {
-    const { sessions, clusters } = groupTrack(track, {
+    const { sessions, clusters, surfaces } = groupTrack(track, {
       width,
       height,
       clusterGap: style.clusterGap,
       typingGap: style.typingGap,
-      typingZoom: style.typingZoom
+      typingZoom: style.typingZoom,
+      targetFill: style.targetFill
     });
-    for (const c of clusters) {
+    const pressed = (c, surface) => {
       const f = clusterFocus(c, width, height);
       drafts.push({
         kind: "click",
@@ -6821,9 +7006,12 @@ function momentsFromDoc(doc, plan, opts = {}) {
         at: c[0].t,
         focus: { cx: f.cx, cy: f.cy },
         rect: f.rect,
-        clicks: c.length
+        clicks: c.length,
+        ...surface ? { surface: true } : {}
       });
-    }
+    };
+    for (const c of clusters) pressed(c, false);
+    for (const c of surfaces) pressed(c, true);
     for (const s of sessions) {
       const f = clusterFocus(s.events, width, height);
       drafts.push({
@@ -6943,6 +7131,7 @@ function momentsFromDoc(doc, plan, opts = {}) {
         h: round8(d.rect.h)
       } : null,
       ...d.clicks !== void 0 ? { clicks: d.clicks } : {},
+      ...d.surface ? { surface: true } : {},
       ...d.pings !== void 0 ? { pings: d.pings } : {},
       activity: activityOf(opts.bins, d),
       proposed,