@vosjs/studio-core 0.24.0 → 0.25.0

package/dist/index.js

@@ -236,6 +236,210 @@ var MEDIA_FRAME_KEYS = [
   "focusFollow"
 ];
 
+// src/callout.ts
+var CALLOUT_SHAPES = ["tag", "note", "code"];
+var CALLOUT_TYPE_RATIO = 1.35;
+var CALLOUT_DEFAULT_BODY_PX = 14;
+var HOUSE_REGISTER = {
+  ground: "#ffffff",
+  accent: "#7c3aed"
+};
+var DEFAULT_FACE = "'Inter',-apple-system,system-ui,sans-serif";
+var DEFAULT_MONO = "'JetBrains Mono',ui-monospace,monospace";
+function calloutLook(register, scale = 1) {
+  const ground = hexToRgb(register.ground) ?? [255, 255, 255];
+  const accent = hexToRgb(register.accent) ?? [124, 58, 237];
+  const light = relativeLuminance(ground) > 0.4;
+  const [h, s] = rgbToHsl(accent);
+  const cardGround = light ? hslToHex(h, Math.min(0.35, s * 0.6), 0.07) : hslToHex(h, Math.min(0.25, s * 0.35), 0.97);
+  const bodyPx = register.body ?? CALLOUT_DEFAULT_BODY_PX;
+  const titlePx = Math.max(20, Math.round(CALLOUT_TYPE_RATIO * bodyPx * scale));
+  return {
+    light,
+    cardGround,
+    cardInk: light ? "#fafafa" : "#101012",
+    cardMuted: light ? "rgba(255,255,255,0.64)" : "rgba(16,16,18,0.6)",
+    hairline: light ? "rgba(255,255,255,0.12)" : "rgba(0,0,0,0.1)",
+    accent: rgbToHex(accent),
+    shadow: "0 24px 60px rgba(0,0,0,0.35), 0 2px 6px rgba(0,0,0,0.16)",
+    face: register.face ? quoteFamily(register.face) : DEFAULT_FACE,
+    mono: register.mono ? quoteFamily(register.mono) : DEFAULT_MONO,
+    kickerPx: Math.max(11, Math.round(titlePx * 0.55)),
+    titlePx,
+    bodyPx: Math.max(15, Math.round(titlePx * 0.75)),
+    codePx: Math.max(14, Math.round(titlePx * 0.68)),
+    radius: 16,
+    padX: 24,
+    padY: 20
+  };
+}
+function calloutBox(shape, look, words) {
+  const em = (px, chars, adv) => Math.ceil(px * adv * chars);
+  if (shape === "tag") {
+    const text = words.kicker ?? words.title ?? "";
+    const w = em(look.kickerPx * 1.1, text.length, 0.62) + 14 + 18 * 2;
+    return {
+      width: clamp(w, 120, 720),
+      height: Math.max(36, Math.round(look.kickerPx * 1.1 * 2.6))
+    };
+  }
+  if (shape === "code") {
+    const lines = (words.code ?? "").split("\n");
+    const longest = Math.max(1, ...lines.map((l) => l.length));
+    const lineH = Math.round(look.codePx * 1.7);
+    const w = em(look.codePx, longest, 0.62) + look.padX * 2;
+    const h = lines.length * lineH + look.padY * 2 + (words.kicker ? look.kickerPx * 2 : 0);
+    return { width: clamp(w, 360, 820), height: clamp(h, 72, 640) };
+  }
+  const title = words.title ?? "";
+  const body = words.body ?? "";
+  const titleW = em(look.titlePx, title.length, 0.56);
+  const width = clamp(Math.max(titleW, 320) + look.padX * 2, 360, 640);
+  const inner = width - look.padX * 2;
+  const bodyLines = body ? Math.max(1, Math.ceil(em(look.bodyPx, body.length, 0.54) / inner)) : 0;
+  const titleLines = Math.max(1, Math.ceil(titleW / inner));
+  const height = look.padY * 2 + (words.kicker ? Math.round(look.kickerPx * 1.6) : 0) + titleLines * Math.round(look.titlePx * 1.25) + (bodyLines ? 8 + bodyLines * Math.round(look.bodyPx * 1.5) : 0);
+  return { width, height: clamp(height, 64, 480) };
+}
+function calloutSource(shape, look, words, box) {
+  const base = `box-sizing:border-box;width:${box.width}px;height:${box.height}px;background:${look.cardGround};color:${look.cardInk};border:1px solid ${look.hairline};border-radius:${look.radius}px;box-shadow:${look.shadow};-webkit-font-smoothing:antialiased;`;
+  if (shape === "tag") {
+    const text = esc(words.kicker ?? words.title ?? "");
+    return {
+      html: `<div class="tag"><span class="dot"></span><span class="t">${text}</span></div>`,
+      css: `.tag{font-family:${look.face};display:flex;align-items:center;gap:10px;${base}border-radius:999px;padding:0 18px;background:${look.accent};color:#fff;border-color:rgba(255,255,255,0.18);font-size:${Math.round(look.kickerPx * 1.1)}px;font-weight:600;letter-spacing:0.02em;text-transform:uppercase;white-space:nowrap}.dot{width:8px;height:8px;border-radius:99px;background:#fff;opacity:0.9;flex:none}`
+    };
+  }
+  if (shape === "code") {
+    const lines = (words.code ?? "").split("\n").map(
+      (l) => /^\s*(\/\/|#|\$)/.test(l) ? `<span class="mut">${esc(l)}</span>` : esc(l)
+    ).join("\n");
+    const kicker2 = words.kicker ? `<div class="k">${esc(words.kicker)}</div>` : "";
+    return {
+      html: `<div class="code">${kicker2}<pre class="p">${lines}</pre></div>`,
+      css: `.code{font-family:${look.mono};${base}padding:${look.padY}px ${look.padX}px;font-size:${look.codePx}px;line-height:1.7;letter-spacing:-0.01em}.k{font-family:${look.face};font-size:${look.kickerPx}px;font-weight:600;letter-spacing:0.08em;text-transform:uppercase;color:${look.accent};margin:0 0 ${Math.round(look.kickerPx * 0.9)}px}.p{margin:0;white-space:pre;font:inherit}.mut{color:${look.cardMuted}}`
+    };
+  }
+  const kicker = words.kicker ? `<div class="k"><span class="dot"></span>${esc(words.kicker)}</div>` : "";
+  const body = words.body ? `<div class="b">${esc(words.body)}</div>` : "";
+  return {
+    html: `<div class="note">${kicker}<div class="t">${esc(words.title ?? "")}</div>${body}</div>`,
+    css: `.note{font-family:${look.face};${base}padding:${look.padY}px ${look.padX}px;display:flex;flex-direction:column;justify-content:center}.k{display:flex;align-items:center;gap:8px;font-size:${look.kickerPx}px;font-weight:600;letter-spacing:0.08em;text-transform:uppercase;color:${look.accent};margin-bottom:${Math.round(look.kickerPx * 0.6)}px}.dot{width:7px;height:7px;border-radius:99px;background:${look.accent};box-shadow:0 0 10px ${look.accent}}.t{font-size:${look.titlePx}px;font-weight:600;line-height:1.25;letter-spacing:-0.01em}.b{margin-top:8px;font-size:${look.bodyPx}px;line-height:1.5;color:${look.cardMuted}}`
+  };
+}
+function calloutClip(shape, register, words, opts) {
+  const look = calloutLook(register, opts.scale ?? 1);
+  const box = calloutBox(shape, look, words);
+  const { html, css } = calloutSource(shape, look, words, box);
+  return {
+    id: opts.id,
+    kind: "html",
+    start: opts.start,
+    duration: opts.duration,
+    html,
+    css,
+    box,
+    transform: {
+      x: opts.at?.x ?? 0.5,
+      y: opts.at?.y ?? 0.5,
+      scale: 1,
+      rotation: 0
+    },
+    anim: { enter: "rise", exit: "fade" },
+    ...opts.pin ? { pin: opts.pin } : {}
+  };
+}
+function calloutGroundOf(css) {
+  const m = /background(?:-color)?\s*:\s*(#[0-9a-fA-F]{3,8}|rgba?\([^)]*\))/.exec(css);
+  if (!m) return null;
+  const rgb = parseCssColour(m[1]);
+  return rgb ? rgbToHex(rgb) : null;
+}
+function hexToRgb(hex) {
+  const m = /^#?([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i.exec(hex.trim());
+  if (!m) return null;
+  let h = m[1];
+  if (h.length === 3)
+    h = h.split("").map((c) => c + c).join("");
+  return [
+    parseInt(h.slice(0, 2), 16),
+    parseInt(h.slice(2, 4), 16),
+    parseInt(h.slice(4, 6), 16)
+  ];
+}
+function rgbToHex([r, g, b]) {
+  const c = (v) => Math.round(clamp(v, 0, 255)).toString(16).padStart(2, "0");
+  return `#${c(r)}${c(g)}${c(b)}`;
+}
+function parseCssColour(s) {
+  const hex = hexToRgb(s);
+  if (hex) return hex;
+  const m = /rgba?\(\s*([\d.]+)[,\s]+([\d.]+)[,\s]+([\d.]+)/.exec(s);
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+function relativeLuminance([r, g, b]) {
+  const lin = (v) => {
+    const c = v / 255;
+    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+}
+function rgbToHsl([r, g, b]) {
+  const rr = r / 255;
+  const gg = g / 255;
+  const bb = b / 255;
+  const max = Math.max(rr, gg, bb);
+  const min = Math.min(rr, gg, bb);
+  const l = (max + min) / 2;
+  if (max === min) return [0, 0, l];
+  const d = max - min;
+  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+  let h = 0;
+  if (max === rr) h = (gg - bb) / d + (gg < bb ? 6 : 0);
+  else if (max === gg) h = (bb - rr) / d + 2;
+  else h = (rr - gg) / d + 4;
+  return [h / 6, s, l];
+}
+function hslToHex(h, s, l) {
+  const f = (n) => {
+    const k = (n + h * 12) % 12;
+    const a = s * Math.min(l, 1 - l);
+    return l - a * Math.max(-1, Math.min(k - 3, 9 - k, 1));
+  };
+  return rgbToHex([f(0) * 255, f(8) * 255, f(4) * 255]);
+}
+function deltaE(a, b) {
+  const la = rgbToLab(a);
+  const lb = rgbToLab(b);
+  return Math.hypot(la[0] - lb[0], la[1] - lb[1], la[2] - lb[2]);
+}
+function rgbToLab([r, g, b]) {
+  const lin = (v) => {
+    const c = v / 255;
+    return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  };
+  const R = lin(r);
+  const G = lin(g);
+  const B = lin(b);
+  const x = (R * 0.4124 + G * 0.3576 + B * 0.1805) / 0.95047;
+  const y = R * 0.2126 + G * 0.7152 + B * 0.0722;
+  const z = (R * 0.0193 + G * 0.1192 + B * 0.9505) / 1.08883;
+  const f = (t) => t > 8856e-6 ? Math.cbrt(t) : 7.787 * t + 16 / 116;
+  return [116 * f(y) - 16, 500 * (f(x) - f(y)), 200 * (f(y) - f(z))];
+}
+function quoteFamily(family) {
+  const first = family.split(",")[0].trim().replace(/^['"]|['"]$/g, "");
+  const rest = family.includes(",") ? family.slice(family.indexOf(",") + 1).trim() : /mono/i.test(first) ? "ui-monospace,monospace" : "-apple-system,system-ui,sans-serif";
+  return /^[a-z-]+$/i.test(first) && /^(ui-|system-ui|sans-serif|serif|monospace)/.test(first) ? `${first},${rest}` : `'${first}',${rest}`;
+}
+function esc(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function clamp(v, lo, hi) {
+  return Math.max(lo, Math.min(hi, v));
+}
+
 // src/capture.ts
 var CHROME_TOP_MIN = 20;
 var CHROME_TOP_MAX = 220;
@@ -1102,7 +1306,7 @@ function sampleAt(points, t) {
   return { x: last.x, y: last.y };
 }
 function smoothCursor(track, options = {}) {
-  const factor = clamp(options.factor ?? 0.15, 0.01, 1);
+  const factor = clamp2(options.factor ?? 0.15, 0.01, 1);
   const fps = options.fps ?? 60;
   const raw = track.filter((e) => e.type === "move" || e.type === "down" || e.type === "up").map((e) => ({ t: e.t / 1e3, x: e.x, y: e.y }));
   if (raw.length === 0) return [];
@@ -1121,7 +1325,7 @@ function smoothCursor(track, options = {}) {
     if (clicks.length) {
       while (ci < clicks.length - 1 && t > clicks[ci].t + SNAP_AFTER) ci++;
       const ck = clicks[ci];
-      const u = clamp(
+      const u = clamp2(
         (t - (ck.t - SNAP_BEFORE)) / SNAP_BEFORE,
         0,
         t <= ck.t + SNAP_AFTER ? 1 : 0
@@ -1136,7 +1340,7 @@ function smoothCursor(track, options = {}) {
   }
   return out;
 }
-function clamp(v, lo, hi) {
+function clamp2(v, lo, hi) {
   return Math.max(lo, Math.min(hi, v));
 }
 
@@ -1782,7 +1986,7 @@ function focusFor(cluster, width, height, targetFill, minLevel, maxLevel) {
   const cx = clamp012(sx / n / width);
   const cy = clamp012(sy / n / height);
   const level = fitLevel({ x: 0, y: 0, w: maxW, h: maxH }, width, height, targetFill) ?? maxLevel;
-  return { cx, cy, level: clamp2(level, minLevel, maxLevel) };
+  return { cx, cy, level: clamp3(level, minLevel, maxLevel) };
 }
 function clusterFocus(events, width, height) {
   let sx = 0;
@@ -1815,11 +2019,11 @@ function clusterFocus(events, width, height) {
   } : null;
   return { cx: clamp012(sx / n / width), cy: clamp012(sy / n / height), rect };
 }
-function clamp2(v, lo, hi) {
+function clamp3(v, lo, hi) {
   return Math.max(lo, Math.min(hi, v));
 }
 function clamp012(v) {
-  return clamp2(v, 0, 1);
+  return clamp3(v, 0, 1);
 }
 function round(v) {
   return Math.round(v * 1e3) / 1e3;
@@ -3058,7 +3262,7 @@ function round2(v) {
 }
 
 // src/lower/pin.ts
-import { lerpArray, sample } from "@vosjs/timeline";
+import { lerpArray, mapTime, sample } from "@vosjs/timeline";
 var PIN_GAP = 24;
 var PIN_MARGIN = 24;
 var PIN_SAMPLE_HZ = 30;
@@ -3077,19 +3281,27 @@ function pinReferent(doc, pin) {
   if (pin.step !== void 0) {
     const step = findStep(meta.steps ?? [], pin.step);
     if (!step || step.skipped) return null;
+    const carry = dragCarry(doc, step.tStart - 0.05, step.tEnd + 0.05);
     if (step.rect && validRect(step.rect) && w > 0 && h > 0) {
       return {
         rect: normRect(step.rect, w, h),
         by: "step",
         step,
-        at: step.tStart
+        at: step.tStart,
+        ...carry ? { carry } : {}
       };
     }
     const union = unionRects(
       pressRects(doc, step.tStart - 0.05, step.tEnd + 0.05)
     );
     if (!union || w <= 0 || h <= 0) return null;
-    return { rect: normRect(union, w, h), by: "step", step, at: step.tStart };
+    return {
+      rect: normRect(union, w, h),
+      by: "step",
+      step,
+      at: step.tStart,
+      ...carry ? { carry } : {}
+    };
   }
   if (pin.press !== void 0 && Number.isFinite(pin.press)) {
     let best = null;
@@ -3101,10 +3313,42 @@ function pinReferent(doc, pin) {
       if (!best || d < Math.abs(best.t - pin.press)) best = { t, rect: e.rect };
     }
     if (!best || w <= 0 || h <= 0) return null;
-    return { rect: normRect(best.rect, w, h), by: "press", at: best.t };
+    const carry = dragCarry(doc, best.t - 0.01, best.t + 0.01);
+    return {
+      rect: normRect(best.rect, w, h),
+      by: "press",
+      at: best.t,
+      ...carry ? { carry } : {}
+    };
   }
   return null;
 }
+function dragCarry(doc, from, to) {
+  const meta = doc.source.meta;
+  if (!(meta.width > 0) || !(meta.height > 0)) return null;
+  const d = dragsFromTrack(doc.source.cursor, meta.width, meta.height).find(
+    (g) => g.t0 >= from && g.t0 <= to
+  );
+  if (!d) return null;
+  return { t0: d.t0, t1: d.t1, x0: d.nx, y0: d.ny };
+}
+function cursorAt(cursor, t, space) {
+  let prev = null;
+  for (const e of cursor) {
+    if (e.type !== "move" && e.type !== "down" && e.type !== "up") continue;
+    const cur = { t: e.t / 1e3, nx: e.x / space.w, ny: e.y / space.h };
+    if (cur.t >= t) {
+      if (!prev) return { nx: cur.nx, ny: cur.ny };
+      const k = cur.t > prev.t ? (t - prev.t) / (cur.t - prev.t) : 1;
+      return {
+        nx: prev.nx + (cur.nx - prev.nx) * k,
+        ny: prev.ny + (cur.ny - prev.ny) * k
+      };
+    }
+    prev = cur;
+  }
+  return prev ? { nx: prev.nx, ny: prev.ny } : null;
+}
 function findStep(steps, ref) {
   const byId = steps.find((s) => s.id !== void 0 && s.id === ref);
   if (byId) return byId;
@@ -3188,6 +3432,20 @@ function pinRectOnScreen(rect, t, layout, camera, zoomTrack) {
   const b = map(rect.x + rect.w, rect.y + rect.h);
   return { x: a.x, y: a.y, w: b.x - a.x, h: b.y - a.y };
 }
+function pinReferentAt(referent, t, input) {
+  const { carry, cursor, space, rated } = input;
+  if (!carry || !cursor || !space || !rated) return referent;
+  const s = mapTime(rated, t);
+  const sc = Math.max(carry.t0, Math.min(carry.t1, s));
+  const p = cursorAt(cursor, sc, space);
+  if (!p) return referent;
+  return {
+    x: referent.x + (p.nx - carry.x0),
+    y: referent.y + (p.ny - carry.y0),
+    w: referent.w,
+    h: referent.h
+  };
+}
 function pinPlacement(input) {
   const { clip, referent, layout, camera, zoomTrack, base, motion } = input;
   const dur = Math.max(1e-3, clip.duration);
@@ -3195,7 +3453,13 @@ function pinPlacement(input) {
   const box = pinBox(clip, layout);
   const W = layout.W;
   const H = layout.H;
-  const refAt = (local) => pinRectOnScreen(referent, clip.start + local, layout, camera, zoomTrack);
+  const refAt = (local) => pinRectOnScreen(
+    pinReferentAt(referent, clip.start + local, input),
+    clip.start + local,
+    layout,
+    camera,
+    zoomTrack
+  );
   const centreFor = (r, side2) => {
     switch (side2) {
       case "right":
@@ -6670,6 +6934,15 @@ var ON_FRAME = `(ctx, content, dt) => {
       if (pn.dur - pnT < 0.35) { var pnV = (pn.dur - pnT) / 0.35; pnA = Math.min(pnA, 1 - Math.pow(1 - pnV, 3)) }
       if (pnA <= 0.004) continue
       var pnX = dx + pn.x * dw, pnY = dy + pn.y * dh, pnW = pn.w * dw, pnH = pn.h * dh
+      // a carried referent (a drag): moved by where the pointer has taken
+      // it at the on-screen source moment, held at the release
+      if (pn.carry) {
+        var pcC = (actM ? actM.cursor : d.cursor) || []
+        var pcT = Math.max(pn.carry.t0, Math.min(pn.carry.t1, srcT))
+        var pcx = -1, pcy = -1
+        for (var pk = 0; pk < pcC.length; pk++) { if (pcC[pk].t <= pcT) { pcx = pcC[pk].x; pcy = pcC[pk].y } }
+        if (pcx >= 0) { pnX += (pcx / (space.w || vw) - pn.carry.x0) * dw; pnY += (pcy / (space.h || vh) - pn.carry.y0) * dh }
+      }
       var pnLw = 2 * s2 / ceZs, pnPad = 6 * s2 / ceZs
       var pnCol = pn.color || 'rgba(255,255,255,0.95)'
       c.save()
@@ -6839,6 +7112,15 @@ var ON_FRAME = `(ctx, content, dt) => {
       // the referent's corners in frame space under the live camera
       var pqAx = dx + pq.x * dw, pqAy = dy + pq.y * dh
       var pqBx = dx + (pq.x + pq.w) * dw, pqBy = dy + (pq.y + pq.h) * dh
+      if (pq.carry) {
+        var pqcT = Math.max(pq.carry.t0, Math.min(pq.carry.t1, srcT))
+        var pqcx = -1, pqcy = -1
+        for (var pqk = 0; pqk < cur.length; pqk++) { if (cur[pqk].t <= pqcT) { pqcx = cur[pqk].x; pqcy = cur[pqk].y } }
+        if (pqcx >= 0) {
+          var pqOx = (pqcx / (space.w || vw) - pq.carry.x0) * dw, pqOy = (pqcy / (space.h || vh) - pq.carry.y0) * dh
+          pqAx += pqOx; pqBx += pqOx; pqAy += pqOy; pqBy += pqOy
+        }
+      }
       if (lvl > 1.001 && !d.zoomSuppressed) {
         if (camStage) {
           pqAx = W / 2 + (pqAx - wcx) * lvl; pqAy = H / 2 + (pqAy - wcy) * lvl
@@ -7423,6 +7705,8 @@ function docZoomTrack(input) {
 }
 function resolvePins(doc, layout, camera, zoomTrack) {
   const out = /* @__PURE__ */ new Map();
+  const rated = ratedSegments(doc);
+  const space = { w: doc.source.meta.width, h: doc.source.meta.height };
   for (const o of doc.overlays ?? []) {
     if (!o.pin) continue;
     const ref = pinReferent(doc, o.pin);
@@ -7442,12 +7726,39 @@ function resolvePins(doc, layout, camera, zoomTrack) {
         camera,
         zoomTrack,
         base,
-        motion
+        motion,
+        carry: ref.carry ?? null,
+        cursor: doc.source.cursor,
+        space,
+        rated
       })
     );
   }
   return out;
 }
+function pinCandidates(doc, clip) {
+  const rated = ratedSegments(doc);
+  const out = [];
+  const a0 = clip.start;
+  const a1 = clip.start + clip.duration;
+  for (const s of doc.source.meta.steps ?? []) {
+    if (s.skipped) continue;
+    const ref = pinReferent(doc, { step: s.id ?? s.step });
+    if (!ref) continue;
+    const ext = spanOutputExtent(rated, s.tStart, s.tEnd);
+    if (!ext) continue;
+    const overlap = Math.min(a1, ext.end) - Math.max(a0, ext.start);
+    if (overlap <= 0) continue;
+    out.push({
+      step: s.id ?? s.step,
+      do: s.do,
+      ...s.selector ? { selector: s.selector } : {},
+      output: { start: round7(ext.start), end: round7(ext.end) },
+      overlap: round7(overlap)
+    });
+  }
+  return out.sort((x, y) => y.overlap - x.overlap);
+}
 function overlayPinPoseAt(doc, o, t) {
   if (!o.pin) return null;
   const layout = docCardLayout(doc);
@@ -7484,6 +7795,16 @@ function pinsDataOf(doc, pins) {
       mark,
       leader: !!p.leader,
       ...p.color ? { color: p.color } : {},
+      // A carried referent (a drag): ON_FRAME moves the mark and the
+      // leader's end with the pointer through [t0, t1], source seconds.
+      ...ref.carry ? {
+        carry: {
+          t0: round7(ref.carry.t0),
+          t1: round7(ref.carry.t1),
+          x0: round43(ref.carry.x0),
+          y0: round43(ref.carry.y0)
+        }
+      } : {},
       enter: enterKey(o),
       tip: placed.tip
     });
@@ -8439,12 +8760,12 @@ function round10(v) {
 }
 
 // src/timeline/rangeActions.ts
-import { mapTime } from "@vosjs/timeline";
+import { mapTime as mapTime2 } from "@vosjs/timeline";
 function outputRangeToSource(doc, t0, t1) {
   const rated = ratedSegments(doc);
   return {
-    srcIn: mapTime(rated, Math.max(0, t0)),
-    srcOut: mapTime(rated, Math.max(0, t1))
+    srcIn: mapTime2(rated, Math.max(0, t0)),
+    srcOut: mapTime2(rated, Math.max(0, t1))
   };
 }
 var EPS = 1e-6;
@@ -8985,24 +9306,31 @@ function destinationsForChannel(channel) {
 }
 
 // src/htmlStarters.ts
+function grammarStarter(id, name, words) {
+  const clip = calloutClip(id, HOUSE_REGISTER, words, {
+    id,
+    start: 0,
+    duration: 1,
+    scale: 1.4
+  });
+  return { id, name, html: clip.html, css: clip.css ?? "", box: clip.box };
+}
 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}`
-  },
+  // The callout grammar (three shapes a viewer learns once), in the house
+  // register: a dark card in the house hue over a light app.
+  grammarStarter("note", "Note", {
+    kicker: "Presets",
+    title: "One of 43, picked here.",
+    body: "One line that says what this is about."
+  }),
+  grammarStarter("tag", "Tag", { kicker: "New in 2.0" }),
+  grammarStarter("code", "Code", {
+    kicker: "index.css",
+    code: ":root {\n  --primary: oklch(0.63 0.06 4.6);\n  --radius: 2.25rem;\n}"
+  }),
   {
     id: "terminal",
     name: "Terminal",
@@ -9209,7 +9537,7 @@ function applyLook(frame, look, size, video, placement) {
 
 // src/timeline/lanes.ts
 import {
-  mapTime as mapTime2,
+  mapTime as mapTime3,
   removeSegment,
   segmentRate as segmentRate3,
   sourceToTimeline as sourceToTimeline2,
@@ -9277,7 +9605,7 @@ var videoLane = {
           index === 0 || !contiguous(segments, index)
         );
         const anchorOut = sourceToTimeline2(fullMap, Math.min(edgeSrc, sourceDuration)) ?? edgeSrc;
-        const sourceT = mapTime2(fullMap, anchorOut + (g.t - edgeOutNow));
+        const sourceT = mapTime3(fullMap, anchorOut + (g.t - edgeOutNow));
         const next = trimSegment(
           segments,
           index,
@@ -9313,7 +9641,7 @@ var videoLane = {
             return null;
         }
         const sourceT = round12(
-          mapTime2(segmentPieces(s, speeds, freezes, leading), local)
+          mapTime3(segmentPieces(s, speeds, freezes, leading), local)
         );
         if (sourceT - s.in < 0.05 || s.out - sourceT < 0.05) return null;
         const next = [
@@ -9403,7 +9731,7 @@ var freezeLane = {
         if (g.t >= m.t - 1e-9 && g.t <= m.t + m.duration + 1e-9) return null;
       }
       if (g.t > totalDuration7(rated) + 1e-9) return null;
-      const srcT = round12(mapTime2(rated, Math.max(0, g.t)));
+      const srcT = round12(mapTime3(rated, Math.max(0, g.t)));
       if (!kept(srcT) || !clear(srcT)) return null;
       const id = nextFreezeId(doc);
       const mediaHere = mediaAtOutput(rated, Math.max(0, g.t));
@@ -9446,7 +9774,7 @@ var freezeLane = {
       const mine = marks.get(f.id);
       const endOut = mine ? mine.t + mine.duration : null;
       const srcT = round12(
-        Math.min(sourceDuration, mapTime2(base, Math.max(0, g.t)))
+        Math.min(sourceDuration, mapTime3(base, Math.max(0, g.t)))
       );
       if (!kept(srcT) || !clear(srcT, f.id)) return null;
       return (d) => {
@@ -9517,7 +9845,7 @@ var zoomLane = {
     const rated = ratedSegments(doc);
     const sourceDuration = anchorSourceDuration(doc);
     if (g.type === "create") {
-      const srcT = mapTime2(rated, Math.max(0, g.t));
+      const srcT = mapTime3(rated, Math.max(0, g.t));
       const mediaHere = mediaAtOutput(rated, Math.max(0, g.t));
       const here = spans.filter((z) => (z.media ?? "") === mediaHere);
       const mediaLen = mediaDuration(mediaSource(doc, mediaHere) ?? doc.source);
@@ -9551,7 +9879,7 @@ var zoomLane = {
       const len = sp.out - sp.in;
       let newIn = clampToKept(
         effectiveSegments(doc),
-        mapTime2(rated, Math.max(0, g.t)),
+        mapTime3(rated, Math.max(0, g.t)),
         len
       );
       for (const o of others) {
@@ -9581,7 +9909,7 @@ var zoomLane = {
         sourceDuration,
         ...others.filter((o) => o.in >= sp.out).map((o) => o.in)
       );
-      const sourceT = mapTime2(rated, Math.max(0, g.t));
+      const sourceT = mapTime3(rated, Math.max(0, g.t));
       const minSrc = Math.min(
         ZOOM_SPAN_MIN * rateAt(rated, sp.in),
         sp.out - sp.in
@@ -9646,7 +9974,7 @@ var tiltLane = {
     const rated = ratedSegments(doc);
     const sourceDuration = anchorSourceDuration(doc);
     if (g.type === "create") {
-      const srcT = mapTime2(rated, Math.max(0, g.t));
+      const srcT = mapTime3(rated, Math.max(0, g.t));
       const mediaHere = mediaAtOutput(rated, Math.max(0, g.t));
       const here = spans.filter((z) => (z.media ?? "") === mediaHere);
       const mediaLen = mediaDuration(mediaSource(doc, mediaHere) ?? doc.source);
@@ -9678,7 +10006,7 @@ var tiltLane = {
       const len = sp.out - sp.in;
       let newIn = clampToKept(
         effectiveSegments(doc),
-        mapTime2(rated, Math.max(0, g.t)),
+        mapTime3(rated, Math.max(0, g.t)),
         len
       );
       for (const o of others) {
@@ -9708,7 +10036,7 @@ var tiltLane = {
         sourceDuration,
         ...others.filter((o) => o.in >= sp.out).map((o) => o.in)
       );
-      const sourceT = mapTime2(rated, Math.max(0, g.t));
+      const sourceT = mapTime3(rated, Math.max(0, g.t));
       const minSrc = Math.min(
         TILT_SPAN_MIN * rateAt(rated, sp.in),
         sp.out - sp.in
@@ -9764,7 +10092,7 @@ var camMoveLane = {
     const sourceDuration = anchorSourceDuration(doc);
     if (g.type === "create") {
       if (!doc.source.camKey) return null;
-      const srcT = mapTime2(rated, Math.max(0, g.t));
+      const srcT = mapTime3(rated, Math.max(0, g.t));
       if (spans.some((z) => srcT >= z.in && srcT < z.out)) return null;
       const next = spans.filter((z) => z.in > srcT).sort((a, b) => a.in - b.in).at(0);
       const limit = Math.min(sourceDuration, next ? next.in : sourceDuration);
@@ -9791,7 +10119,7 @@ var camMoveLane = {
       const len = sp.out - sp.in;
       let newIn = clampToKept(
         effectiveSegments(doc),
-        mapTime2(rated, Math.max(0, g.t)),
+        mapTime3(rated, Math.max(0, g.t)),
         len
       );
       for (const o of others) {
@@ -9821,7 +10149,7 @@ var camMoveLane = {
         sourceDuration,
         ...others.filter((o) => o.in >= sp.out).map((o) => o.in)
       );
-      const sourceT = mapTime2(rated, Math.max(0, g.t));
+      const sourceT = mapTime3(rated, Math.max(0, g.t));
       const minSrc = Math.min(
         CAM_SPAN_MIN * rateAt(rated, sp.in),
         sp.out - sp.in
@@ -9895,7 +10223,7 @@ var camLane = {
       if (!seg) return null;
       const clipSrcStart = Math.max(seg.in, Math.max(current.in, first.in));
       const span = Math.max(0.05, current.out - current.in);
-      const delta = mapTime2(rated, Math.max(0, g.t)) - clipSrcStart;
+      const delta = mapTime3(rated, Math.max(0, g.t)) - clipSrcStart;
       const base = Math.max(first.in, current.in);
       const newIn = Math.min(
         Math.max(first.in, base + delta),
@@ -9911,7 +10239,7 @@ var camLane = {
     })).filter((x) => x.len > 1e-6);
     const edgeIdx = g.edge === "start" ? overlapping.at(0)?.i : overlapping.at(-1)?.i;
     if (edgeIdx === void 0 || g.id !== `cam-${edgeIdx}`) return null;
-    const sourceT = Math.min(Math.max(mapTime2(rated, g.t), 0), sourceDuration);
+    const sourceT = Math.min(Math.max(mapTime3(rated, g.t), 0), sourceDuration);
     const next = g.edge === "start" ? { in: Math.min(sourceT, current.out - 0.05), out: current.out } : { in: current.in, out: Math.max(sourceT, current.in + 0.05) };
     return (d) => {
       d.cam.window = {
@@ -10005,7 +10333,7 @@ var speedLane = {
     const rated = ratedSegments(doc);
     const sourceDuration = anchorSourceDuration(doc);
     if (g.type === "create") {
-      const srcT = mapTime2(rated, Math.max(0, g.t));
+      const srcT = mapTime3(rated, Math.max(0, g.t));
       if (spans.some((s) => srcT >= s.in && srcT < s.out)) return null;
       const next = spans.filter((s) => s.in > srcT).sort((a, b) => a.in - b.in).at(0);
       const limit = Math.min(sourceDuration, next ? next.in : sourceDuration);
@@ -10035,7 +10363,7 @@ var speedLane = {
       const len = sp.out - sp.in;
       let newIn = clampToKept(
         effectiveSegments(doc),
-        mapTime2(base, Math.max(0, g.t)),
+        mapTime3(base, Math.max(0, g.t)),
         len
       );
       for (const o of others) {
@@ -10064,7 +10392,7 @@ var speedLane = {
       const minSrc = Math.min(SPEED_SPAN_MIN * sp.rate, sp.out - sp.in);
       let next;
       if (g.edge === "start") {
-        const sourceT = mapTime2(base, Math.max(0, g.t));
+        const sourceT = mapTime3(base, Math.max(0, g.t));
         next = {
           in: Math.min(Math.max(lo, sourceT), sp.out - minSrc),
           out: sp.out
@@ -10432,7 +10760,7 @@ function computePeaks(channels, buckets) {
 }
 
 // src/lower/duckCurve.ts
-import { mapTime as mapTime3 } from "@vosjs/timeline";
+import { mapTime as mapTime4 } from "@vosjs/timeline";
 var DEFAULT_DUCK = {
   threshold: 0.02,
   duckTo: 0.25,
@@ -10468,7 +10796,7 @@ function duckCurve(rms, segments, durationSec2, opts = DEFAULT_DUCK) {
   const steps = Math.ceil(durationSec2 * opts.gridHz);
   for (let i = 0; i <= steps; i++) {
     const t = Math.min(durationSec2, i * dt);
-    const srcT = mapTime3(segments, t);
+    const srcT = mapTime4(segments, t);
     const w = Math.min(
       rms.values.length - 1,
       Math.max(0, Math.floor(srcT * rms.rate))
@@ -10543,6 +10871,9 @@ export {
   AUDIO_PLAN_STEP,
   BACKGROUND_Z,
   BASE_FRAME_STYLE,
+  CALLOUT_DEFAULT_BODY_PX,
+  CALLOUT_SHAPES,
+  CALLOUT_TYPE_RATIO,
   CAMERA_CENTRE_RAMP,
   CAMERA_COVER_MIN,
   CAMERA_FAR,
@@ -10617,6 +10948,7 @@ export {
   FREEZE_SECONDS_MAX,
   FREEZE_SECONDS_MIN,
   HOUSE_GRADIENT,
+  HOUSE_REGISTER,
   HTML_LAYER_FOREIGN_FIELDS,
   HTML_LAYER_MAX_BYTES,
   HTML_LAYER_SVG_CODE,
@@ -10708,6 +11040,11 @@ export {
   audioLane,
   backdropMedia,
   buildDigest,
+  calloutBox,
+  calloutClip,
+  calloutGroundOf,
+  calloutLook,
+  calloutSource,
   camBubbleRect,
   camBubbleRectAt,
   camLane,
@@ -10742,6 +11079,7 @@ export {
   cssFamilies,
   cssWeights,
   cursorIdleFade,
+  deltaE,
   deriveViewportCrop,
   destinationById,
   destinationsForChannel,
@@ -10779,6 +11117,7 @@ export {
   frameGeometry,
   freezeLane,
   freezeOutputExtents,
+  hexToRgb,
   hexToRgbTriplet,
   houseLook,
   htmlLayerBleed,
@@ -10849,12 +11188,15 @@ export {
   overlaysLane,
   ownFreezes,
   pageDisplayUrl,
+  parseCssColour,
   parsePoseId,
   pickStyle,
   pinBox,
+  pinCandidates,
   pinPlacement,
   pinRectOnScreen,
   pinReferent,
+  pinReferentAt,
   placeFreezes,
   planAutoSpeed,
   planAutoTilt,
@@ -10868,6 +11210,7 @@ export {
   recommendedExportResolution,
   refillAudioBeds,
   rejectSpan,
+  relativeLuminance,
   removeSourceRange,
   removeSpeedInRange,
   resolveExportSize,
@@ -10878,6 +11221,7 @@ export {
   resolveZoomStyle,
   restLeanOf,
   restSpansThroughTransitions,
+  rgbToHex,
   sameMedia,
   sceneChanges,
   scrollRuns,