@vosjs/studio-core 0.19.1 → 0.21.0

package/dist/index.d.ts

@@ -61,7 +61,13 @@ interface ZoomStyleParams {
     autoZoom: boolean;
     /** clicks within this many seconds merge into one span (session merge). */
     clusterGap: number;
-    /** minimum clicks for a cluster to earn a zoom (Cursorful's ≥2 rule). */
+    /**
+     * Minimum clicks for a cluster to earn a zoom. Every style is 1: the
+     * Cursorful ≥2 rule glide and keynote carried was never in effect on a
+     * recorded take (the recorder counted each press twice, so a lone click
+     * was a pair on most pages and a stray on the rest), and the lone click on
+     * a button is the zoom people miss when it goes.
+     */
     minClusterClicks: number;
     /** zoom so the clicked element fills ~this fraction of the frame. */
     targetFill: number;
@@ -1353,6 +1359,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;
 }
@@ -2011,11 +2029,18 @@ interface SmoothOptions {
 declare function smoothCursor(track: CursorTrack, options?: SmoothOptions): SmoothPoint[];
 
 /**
- * A click cluster whose element FITS the frame at less than this level is
- * not a target: it is a drag (aiming, scrubbing, moving a thing across the
- * canvas) or a frame-sized surface, and a zoom on it says nothing. Five real
- * takes (2026-08-25) each carried 1-4 such clusters, planned at the floor
- * level for 10-25s; every one was dropped by hand. Now they plan nothing.
+ * A press whose element FITS the frame at less than this level is not a
+ * target: it is a drag (aiming, scrubbing, moving a thing across the canvas)
+ * or a frame-sized surface (a canvas, a panel, a modal clicked to focus or
+ * dismiss it), and a zoom on it says nothing. Five real takes (2026-08-25)
+ * each carried 1-4 clusters of these, planned at the floor level for 10-25s;
+ * every one was dropped by hand. Now they plan nothing.
+ *
+ * The rule is PER PRESS, never per cluster: a target cluster's level came
+ * from its LARGEST element, so one press on a panel inside a chain of button
+ * clicks read the whole chain as a drag and threw every zoom away — two real
+ * takes (2026-09-11) lost 5 of 8 and 4 of 4 clicks that way. A surface press
+ * is set aside before clustering; the targets around it keep their zoom.
  */
 declare const DRAG_FIT_LEVEL = 1.15;
 interface PlanOptions {
@@ -2105,6 +2130,12 @@ interface Moment {
     /** Normalized target bounds (element rect union), when the events had one. */
     rect: NormRect | null;
     clicks?: number;
+    /**
+     * A click cluster on a frame-sized element (a canvas, a panel, a drag):
+     * the planner frames nothing on it (DRAG_FIT_LEVEL), so a zoom here is
+     * the agent's call, never a proposal.
+     */
+    surface?: boolean;
     pings?: number;
     /** Motion in the window, 0..1 (fraction of changed pixels), null without frames. */
     activity: number | null;
@@ -3090,7 +3121,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 +3144,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 +3159,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 +3224,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 +3240,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 +3264,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 +3281,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 +3292,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): {