reframe-video 0.3.0 → 0.5.0

package/dist/bin.js

@@ -1044,6 +1044,14 @@ var init_devicePreset = __esm({
   }
 });
 
+// ../core/src/cursor.ts
+var init_cursor = __esm({
+  "../core/src/cursor.ts"() {
+    "use strict";
+    init_dsl();
+  }
+});
+
 // ../core/src/rig.ts
 var init_rig = __esm({
   "../core/src/rig.ts"() {
@@ -1070,6 +1078,22 @@ var init_figure = __esm({
   }
 });
 
+// ../core/src/textMetrics.ts
+var init_textMetrics = __esm({
+  "../core/src/textMetrics.ts"() {
+    "use strict";
+  }
+});
+
+// ../core/src/textFx.ts
+var init_textFx = __esm({
+  "../core/src/textFx.ts"() {
+    "use strict";
+    init_dsl();
+    init_textMetrics();
+  }
+});
+
 // ../core/src/motionOps.ts
 var init_motionOps = __esm({
   "../core/src/motionOps.ts"() {
@@ -1288,9 +1312,11 @@ var init_src = __esm({
     init_path();
     init_presets();
     init_devicePreset();
+    init_cursor();
     init_rig();
     init_characterPreset();
     init_figure();
+    init_textFx();
     init_motionOps();
     init_audio();
     init_evaluate();

package/dist/index.js

@@ -884,14 +884,14 @@ function makeRng(seed) {
 var clamp01 = (x) => Math.max(0, Math.min(1, x));
 var SET = 1 / 120;
 function ctx(o) {
-  const rand = makeRng((o.seed ?? 0) + 1);
+  const rand2 = makeRng((o.seed ?? 0) + 1);
   return {
     e: clamp01(o.energy ?? 0.5),
     sp: Math.max(0.25, o.speed ?? 1),
     it: clamp01(o.intensity ?? 0.5),
     from: o.from,
-    rand,
-    jit: (amp) => (rand() - 0.5) * 2 * amp,
+    rand: rand2,
+    jit: (amp) => (rand2() - 0.5) * 2 * amp,
     g: o.target.group,
     cx: o.target.center[0],
     cy: o.target.center[1],
@@ -1089,6 +1089,11 @@ function deviceBounds(name, opts = {}) {
   const b = BOUNDS[name];
   return isLandscape(name, opts) ? { width: b.height, height: b.width } : { ...b };
 }
+function deviceScreenPoint(name, opts, local) {
+  const c = deviceScreenCenter(name, opts);
+  const s = opts.scale ?? 1;
+  return [(opts.x ?? 0) + s * (c.x + local[0]), (opts.y ?? 0) + s * (c.y + local[1])];
+}
 function screenGroup(id, p, o, cx, cy, dims, content) {
   return group({ id: `${id}-screen`, x: cx, y: cy, clip: { kind: "rect", x: -dims.width / 2, y: -dims.height / 2, width: dims.width, height: dims.height, radius: dims.radius } }, [
     rect({ id: `${id}-screenbg`, x: 0, y: 0, anchor: "center", width: dims.width, height: dims.height, fill: o.screen ?? p.screen }),
@@ -1263,6 +1268,73 @@ function devicePreset(name, opts = {}) {
   );
 }
 
+// ../core/src/cursor.ts
+var ARROW_D = "M0 0 L0 30 L8 23 L12.6 33 L17 31 L12.4 21.4 L21 21.4 Z";
+function cursor(opts = {}) {
+  const id = opts.id ?? "cursor";
+  const style = opts.style ?? "arrow";
+  const fill = opts.fill ?? "#FFFFFF";
+  const accent = opts.accent ?? "#FF5A1F";
+  const art = style === "arrow" ? [path({ id: `${id}-arrow`, d: ARROW_D, x: 0, y: 0, fill, stroke: "#15171E", strokeWidth: 2 })] : style === "dot" ? [ellipse({ id: `${id}-dot`, x: 0, y: 0, width: 18, height: 18, fill: accent, anchor: "center" })] : [ellipse({ id: `${id}-ring`, x: 0, y: 0, width: 22, height: 22, fill: "none", stroke: accent, strokeWidth: 3, anchor: "center" })];
+  return group(
+    { id, x: opts.x ?? 0, y: opts.y ?? 0, scale: opts.scale ?? 1, opacity: opts.opacity ?? 1 },
+    [
+      // ripple ring (behind the pointer), emanates from the hotspot on click
+      ellipse({ id: `${id}-ripple`, x: 0, y: 0, width: 30, height: 30, fill: "none", stroke: accent, strokeWidth: 3, opacity: 0, scale: 0, anchor: "center" }),
+      // the pointer art lives in its own group so a click "tap" can scale it
+      // independently of the cursor's resting scale
+      group({ id: `${id}-art`, x: 0, y: 0 }, art)
+    ]
+  );
+}
+var clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));
+function cursorTo(id, from, to2, opts = {}) {
+  const dx = to2[0] - from[0], dy = to2[1] - from[1];
+  const dist = Math.hypot(dx, dy) || 1;
+  const arc = opts.arc ?? 0.12;
+  const mid = [(from[0] + to2[0]) / 2 + -dy / dist * arc * dist, (from[1] + to2[1]) / 2 + dx / dist * arc * dist];
+  const duration = opts.duration ?? clamp(dist / 1400, 0.4, 0.9);
+  return motionPath(id, [from, mid, to2], { duration, ease: opts.ease ?? "easeInOutCubic", curviness: 1, ...opts.label && { label: opts.label } });
+}
+function cursorPath(id, points, opts = {}) {
+  return motionPath(id, points, {
+    duration: opts.duration ?? clamp(points.length * 0.5, 0.5, 4),
+    ease: opts.ease ?? "easeInOutCubic",
+    curviness: opts.curviness ?? 1,
+    ...opts.label && { label: opts.label }
+  });
+}
+function clickBody(id, o) {
+  const sp = Math.max(0.25, o.speed ?? 1);
+  const d = (b) => b / sp;
+  const out = [
+    // the pointer taps
+    seq(tween(`${id}-art`, { scale: 0.82 }, { duration: d(0.08), ease: "easeOutQuad" }), tween(`${id}-art`, { scale: 1 }, { duration: d(0.1), ease: "easeOutBack" }))
+  ];
+  if (o.ripple !== false) {
+    out.push(seq(
+      tween(`${id}-ripple`, { scale: 0.2, opacity: 0.55 }, { duration: 1e-3 }),
+      par(
+        tween(`${id}-ripple`, { scale: 5 }, { duration: d(0.5), ease: "easeOutCubic" }),
+        tween(`${id}-ripple`, { opacity: 0 }, { duration: d(0.5), ease: "easeOutQuad" })
+      )
+    ));
+  }
+  if (o.press) {
+    out.push(seq(tween(o.press, { scale: 0.94 }, { duration: d(0.08), ease: "easeOutQuad" }), tween(o.press, { scale: 1 }, { duration: d(0.14), ease: "easeOutBack" })));
+  }
+  return out;
+}
+function cursorClick(id, opts = {}) {
+  return beat(opts.label ?? "cursor-click", {}, [par(...clickBody(id, opts))]);
+}
+function cursorDouble(id, opts = {}) {
+  const sp = Math.max(0.25, opts.speed ?? 1);
+  return beat(opts.label ?? "cursor-double", {}, [
+    seq(par(...clickBody(id, { ...opts, ripple: false })), wait(0.12 / sp), par(...clickBody(id, opts)))
+  ]);
+}
+
 // ../core/src/rig.ts
 var DEFAULT_LINE = "#FFE3D2";
 var DEFAULT_FILL = "#0E1424";
@@ -1378,7 +1450,7 @@ function makeRng2(seed) {
 }
 var dur2 = (base, sp) => base / sp;
 function ctx2(o) {
-  const rand = makeRng2((o.seed ?? 0) + 1);
+  const rand2 = makeRng2((o.seed ?? 0) + 1);
   return {
     g: o.target,
     label: o.label,
@@ -1388,8 +1460,8 @@ function ctx2(o) {
     facing: o.facing ?? 1,
     at: o.at ?? [0, 0],
     travel: o.travel,
-    rand,
-    jit: (amp) => (rand() - 0.5) * 2 * amp
+    rand: rand2,
+    jit: (amp) => (rand2() - 0.5) * 2 * amp
   };
 }
 var round = (v) => Math.round(v * 1e3) / 1e3;
@@ -1688,9 +1760,511 @@ function figure(opts = {}) {
   return rig(buildSkeleton(id, parts), rigOpts);
 }
 
+// ../core/src/textMetrics.ts
+var INTER_ADVANCE = {
+  "400": {
+    "0": 63.09,
+    "1": 40.67,
+    "2": 60.99,
+    "3": 61.77,
+    "4": 64.6,
+    "5": 59.33,
+    "6": 62.01,
+    "7": 56.59,
+    "8": 61.87,
+    "9": 62.01,
+    " ": 28.13,
+    "!": 28.76,
+    '"': 46.58,
+    "#": 63.33,
+    "$": 64.16,
+    "%": 98.19,
+    "&": 64.4,
+    "'": 29.98,
+    "(": 36.47,
+    ")": 36.47,
+    "*": 50.1,
+    "+": 66.16,
+    ",": 28.81,
+    "-": 46,
+    ".": 28.81,
+    "/": 36.04,
+    ":": 28.81,
+    ";": 30.18,
+    "<": 66.16,
+    "=": 66.16,
+    ">": 66.16,
+    "?": 51.12,
+    "@": 96.58,
+    "A": 68.99,
+    "B": 65.43,
+    "C": 73.05,
+    "D": 72.17,
+    "E": 60.11,
+    "F": 59.03,
+    "G": 74.61,
+    "H": 74.32,
+    "I": 26.86,
+    "J": 57.08,
+    "K": 67.19,
+    "L": 56.54,
+    "M": 90.33,
+    "N": 75.34,
+    "O": 76.46,
+    "P": 63.87,
+    "Q": 76.46,
+    "R": 64.36,
+    "S": 64.16,
+    "T": 64.55,
+    "U": 74.41,
+    "V": 68.99,
+    "W": 98.54,
+    "X": 68.21,
+    "Y": 67.87,
+    "Z": 62.89,
+    "[": 36.47,
+    "\\": 36.04,
+    "]": 36.47,
+    "^": 47.12,
+    "_": 45.61,
+    "`": 32.28,
+    "a": 56.15,
+    "b": 61.23,
+    "c": 57.13,
+    "d": 61.23,
+    "e": 58.3,
+    "f": 37.01,
+    "g": 61.33,
+    "h": 59.13,
+    "i": 24.22,
+    "j": 24.22,
+    "k": 54.88,
+    "l": 24.22,
+    "m": 87.6,
+    "n": 59.08,
+    "o": 59.96,
+    "p": 61.23,
+    "q": 61.23,
+    "r": 37.65,
+    "s": 52.78,
+    "t": 32.71,
+    "u": 59.13,
+    "v": 56.2,
+    "w": 81.84,
+    "x": 54.59,
+    "y": 56.2,
+    "z": 55.22,
+    "{": 42.63,
+    "|": 33.25,
+    "}": 42.63,
+    "~": 66.16
+  },
+  "700": {
+    "0": 67.43,
+    "1": 43.12,
+    "2": 62.94,
+    "3": 64.55,
+    "4": 67.63,
+    "5": 62.21,
+    "6": 64.94,
+    "7": 58.15,
+    "8": 65.09,
+    "9": 64.94,
+    " ": 23.68,
+    "!": 33.79,
+    '"': 55.13,
+    "#": 64.89,
+    "$": 65.48,
+    "%": 101.56,
+    "&": 67.19,
+    "'": 33.89,
+    "(": 37.7,
+    ")": 37.7,
+    "*": 55.91,
+    "+": 67.87,
+    ",": 33.4,
+    "-": 46.78,
+    ".": 33.4,
+    "/": 38.82,
+    ":": 33.4,
+    ";": 34.28,
+    "<": 67.87,
+    "=": 67.87,
+    ">": 67.87,
+    "?": 55.96,
+    "@": 101.61,
+    "A": 74.66,
+    "B": 66.16,
+    "C": 73.97,
+    "D": 72.22,
+    "E": 60.74,
+    "F": 58.69,
+    "G": 75.05,
+    "H": 74.71,
+    "I": 28.08,
+    "J": 58.45,
+    "K": 71.92,
+    "L": 56.54,
+    "M": 93.16,
+    "N": 76.22,
+    "O": 77.05,
+    "P": 64.79,
+    "Q": 77.69,
+    "R": 65.67,
+    "S": 65.48,
+    "T": 66.75,
+    "U": 73.19,
+    "V": 74.66,
+    "W": 103.76,
+    "X": 73.83,
+    "Y": 73.1,
+    "Z": 66.41,
+    "[": 37.7,
+    "\\": 38.82,
+    "]": 37.7,
+    "^": 48.68,
+    "_": 47.61,
+    "`": 36.52,
+    "a": 58.06,
+    "b": 63.04,
+    "c": 58.84,
+    "d": 63.04,
+    "e": 59.57,
+    "f": 39.79,
+    "g": 63.18,
+    "h": 62.26,
+    "i": 27.1,
+    "j": 27.1,
+    "k": 58.01,
+    "l": 27.1,
+    "m": 91.26,
+    "n": 62.26,
+    "o": 61.33,
+    "p": 63.04,
+    "q": 63.04,
+    "r": 40.72,
+    "s": 56.01,
+    "t": 36.62,
+    "u": 62.26,
+    "v": 59.96,
+    "w": 85.01,
+    "x": 58.01,
+    "y": 60.21,
+    "z": 57.28,
+    "{": 46.88,
+    "|": 37.16,
+    "}": 46.88,
+    "~": 67.87
+  },
+  "800": {
+    "0": 69.19,
+    "1": 44.14,
+    "2": 63.77,
+    "3": 65.67,
+    "4": 68.85,
+    "5": 63.38,
+    "6": 66.16,
+    "7": 58.79,
+    "8": 66.41,
+    "9": 66.16,
+    " ": 21.88,
+    "!": 35.84,
+    '"': 58.64,
+    "#": 65.53,
+    "$": 66.02,
+    "%": 102.93,
+    "&": 68.31,
+    "'": 35.45,
+    "(": 38.23,
+    ")": 38.23,
+    "*": 58.25,
+    "+": 68.55,
+    ",": 35.25,
+    "-": 47.12,
+    ".": 35.25,
+    "/": 39.99,
+    ":": 35.25,
+    ";": 35.99,
+    "<": 68.55,
+    "=": 68.55,
+    ">": 68.55,
+    "?": 57.91,
+    "@": 103.61,
+    "A": 76.95,
+    "B": 66.46,
+    "C": 74.37,
+    "D": 72.27,
+    "E": 60.99,
+    "F": 58.54,
+    "G": 75.24,
+    "H": 74.85,
+    "I": 28.56,
+    "J": 58.98,
+    "K": 73.83,
+    "L": 56.54,
+    "M": 94.34,
+    "N": 76.56,
+    "O": 77.29,
+    "P": 65.19,
+    "Q": 78.17,
+    "R": 66.21,
+    "S": 66.02,
+    "T": 67.68,
+    "U": 72.71,
+    "V": 76.95,
+    "W": 105.86,
+    "X": 76.12,
+    "Y": 75.2,
+    "Z": 67.87,
+    "[": 38.23,
+    "\\": 39.99,
+    "]": 38.23,
+    "^": 49.32,
+    "_": 48.44,
+    "`": 38.23,
+    "a": 58.84,
+    "b": 63.77,
+    "c": 59.52,
+    "d": 63.77,
+    "e": 60.06,
+    "f": 40.97,
+    "g": 63.92,
+    "h": 63.53,
+    "i": 28.32,
+    "j": 28.32,
+    "k": 59.28,
+    "l": 28.32,
+    "m": 92.72,
+    "n": 63.53,
+    "o": 61.91,
+    "p": 63.77,
+    "q": 63.77,
+    "r": 41.99,
+    "s": 57.32,
+    "t": 38.18,
+    "u": 63.53,
+    "v": 61.52,
+    "w": 86.28,
+    "x": 59.42,
+    "y": 61.82,
+    "z": 58.11,
+    "{": 48.63,
+    "|": 38.77,
+    "}": 48.63,
+    "~": 68.55
+  }
+};
+var INTER_FALLBACK = {
+  "400": 56.16,
+  "700": 58.74,
+  "800": 59.79
+};
+
+// ../core/src/textFx.ts
+var clamp013 = (v) => Math.max(0, Math.min(1, v));
+var fract = (v) => v - Math.floor(v);
+var rand = (i, salt) => fract(Math.sin(i * 127.1 + salt * 311.7) * 43758.5453);
+var dur3 = (base, sp) => base / sp;
+var SCRAMBLE = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789#%&@";
+var advance = (ch, weight, fontSize) => (INTER_ADVANCE[weight]?.[ch] ?? INTER_FALLBACK[weight]) * (fontSize / 100);
+function splitText(textStr, opts) {
+  const { id, x, y, fontSize } = opts;
+  const weight = opts.fontWeight ?? 800;
+  const fill = opts.fill ?? "#FFFFFF";
+  const ls = opts.letterSpacing ?? 0;
+  const align = opts.align ?? "center";
+  const unit = opts.unit ?? "glyph";
+  const opacity = opts.opacity ?? 0;
+  const chars = [...textStr];
+  let total = 0;
+  chars.forEach((ch, i) => {
+    total += advance(ch, weight, fontSize) + (i < chars.length - 1 ? ls : 0);
+  });
+  let cursor2 = align === "center" ? x - total / 2 : x;
+  const glyphs = [];
+  const nodes = [];
+  const mk = (ch, cx, adv, lsProp) => {
+    const g = { id: `${id}-${glyphs.length}`, ch, x: cx, y, advance: adv, i: glyphs.length };
+    glyphs.push(g);
+    nodes.push(
+      text({
+        id: g.id,
+        x: cx,
+        y,
+        content: ch,
+        fontFamily: "Inter",
+        fontSize,
+        fontWeight: weight,
+        fill,
+        anchor: "center",
+        opacity,
+        ...lsProp ? { letterSpacing: lsProp } : {}
+      })
+    );
+  };
+  if (unit === "word") {
+    let i = 0;
+    while (i < chars.length) {
+      if (chars[i] === " ") {
+        cursor2 += advance(" ", weight, fontSize) + ls;
+        i++;
+        continue;
+      }
+      let word = "";
+      let w = 0;
+      const startCursor = cursor2;
+      while (i < chars.length && chars[i] !== " ") {
+        const a = advance(chars[i], weight, fontSize);
+        word += chars[i];
+        w += a + (chars[i + 1] && chars[i + 1] !== " " ? ls : 0);
+        i++;
+      }
+      mk(word, startCursor + w / 2, w, ls);
+      cursor2 = startCursor + w + ls;
+    }
+  } else {
+    chars.forEach((ch) => {
+      const a = advance(ch, weight, fontSize);
+      if (ch !== " ") mk(ch, cursor2 + a / 2, a);
+      cursor2 += a + ls;
+    });
+  }
+  return { nodes, glyphs, ids: glyphs.map((g) => g.id), width: total, x, y, fontSize };
+}
+var ctx3 = (o) => ({
+  sp: Math.max(0.25, o.speed ?? 1),
+  e: clamp013(o.energy ?? 0.5),
+  seed: o.seed ?? 0,
+  fs: 0,
+  stag: o.stagger
+});
+var IN_STAGGER = { typewriter: 0.065, cascade: 0.04, rise: 0.03, bounce: 0.045, assemble: 0.05, decode: 0.05 };
+function glyphIn(name, g, c) {
+  const set = (props) => tween(g.id, props, { duration: 1e-3 });
+  const rs = (salt) => rand(g.i, salt + c.seed);
+  switch (name) {
+    case "typewriter":
+      return tween(g.id, { opacity: 1 }, { duration: dur3(0.04, c.sp), ease: "linear" });
+    case "cascade":
+      return seq(
+        set({ y: g.y + 56, opacity: 0 }),
+        par(
+          tween(g.id, { opacity: 1 }, { duration: dur3(0.22, c.sp), ease: "easeOutQuad" }),
+          tween(g.id, { y: g.y }, { duration: dur3(0.34, c.sp), ease: "easeOutCubic" })
+        )
+      );
+    case "rise":
+      return seq(
+        set({ y: g.y + 36, opacity: 0 }),
+        par(
+          tween(g.id, { opacity: 1 }, { duration: dur3(0.3, c.sp), ease: "easeOutQuad" }),
+          tween(g.id, { y: g.y }, { duration: dur3(0.4, c.sp), ease: "easeOutQuad" })
+        )
+      );
+    case "bounce":
+      return seq(
+        set({ y: g.y - 80 * (0.6 + c.e), opacity: 0, scale: 0.7 }),
+        par(
+          tween(g.id, { opacity: 1 }, { duration: dur3(0.2, c.sp), ease: "easeOutQuad" }),
+          tween(g.id, { y: g.y, scale: 1 }, { duration: dur3(0.7, c.sp), ease: "easeOutBounce" })
+        )
+      );
+    case "assemble":
+      return seq(
+        set({ x: g.x + (rs(11) - 0.5) * 1e3 * (0.5 + c.e), y: g.y + (rs(12) - 0.5) * 640, rotation: (rs(13) - 0.5) * 200, scale: 0.4, opacity: 0 }),
+        par(
+          tween(g.id, { opacity: 1 }, { duration: dur3(0.4, c.sp), ease: "easeOutQuad" }),
+          tween(g.id, { x: g.x, y: g.y, rotation: 0, scale: 1 }, { duration: dur3(0.8, c.sp), ease: "easeOutExpo" })
+        )
+      );
+    case "decode": {
+      const steps = 4 + Math.floor(rs(7) * 3);
+      const flicker = [set({ opacity: 1 })];
+      for (let k = 0; k < steps; k++) {
+        flicker.push(tween(g.id, { content: SCRAMBLE[Math.floor(rand(g.i, 20 + k + c.seed) * SCRAMBLE.length)] }, { duration: dur3(0.05, c.sp), ease: "linear" }));
+      }
+      flicker.push(tween(g.id, { content: g.ch }, { duration: dur3(0.05, c.sp), ease: "linear" }));
+      return seq(...flicker);
+    }
+  }
+}
+function textIn(name, block, opts = {}) {
+  const c = { ...ctx3(opts), fs: block.fontSize };
+  const interval = (c.stag ?? IN_STAGGER[name]) / c.sp;
+  return beat(opts.label ?? `text-in-${name}`, {}, [stagger(interval, ...block.glyphs.map((g) => glyphIn(name, g, c)))]);
+}
+function textLoop(name, block, opts = {}) {
+  const win = { ...opts.from !== void 0 && { from: opts.from }, ...opts.until !== void 0 && { until: opts.until }, ...opts.ramp !== void 0 && { ramp: opts.ramp } };
+  const f = opts.frequency ?? (name === "wave" ? 0.9 : name === "shimmer" ? 1.4 : 0.7);
+  const ps = opts.phaseStep ?? 0.55;
+  return block.glyphs.map((g, i) => {
+    switch (name) {
+      case "wave":
+        return oscillate(g.id, "y", { amplitude: opts.amplitude ?? 9, frequency: f, phase: i * ps }, win);
+      case "shimmer":
+        return oscillate(g.id, "opacity", { amplitude: opts.amplitude ?? 0.25, frequency: f, phase: i * ps }, win);
+      case "wobble":
+        return oscillate(g.id, "rotation", { amplitude: opts.amplitude ?? 6, frequency: f, phase: i * ps }, win);
+      case "float":
+        return oscillate(g.id, "y", { amplitude: opts.amplitude ?? 5, frequency: f, phase: i * ps }, win);
+    }
+  });
+}
+var OUT_STAGGER = { shatter: 0.02, fly: 0.012, dissolve: 0, fall: 0.02, collapse: 0.02 };
+function glyphOut(name, g, c, block, dir) {
+  const rs = (salt) => rand(g.i, salt + c.seed);
+  switch (name) {
+    case "shatter":
+      return par(
+        tween(g.id, { x: g.x + (rs(21) - 0.5) * 1100 * (0.6 + c.e), y: g.y + (rs(22) - 0.5) * 760 }, { duration: dur3(0.7, c.sp), ease: "easeInCubic" }),
+        tween(g.id, { rotation: (rs(23) - 0.5) * 300, opacity: 0 }, { duration: dur3(0.7, c.sp), ease: "easeInQuad" })
+      );
+    case "fly":
+      return par(
+        tween(g.id, { x: g.x + dir[0] * 1200, y: g.y + dir[1] * 1200 }, { duration: dur3(0.6, c.sp), ease: "easeInCubic" }),
+        tween(g.id, { opacity: 0 }, { duration: dur3(0.5, c.sp), ease: "easeInQuad" })
+      );
+    case "dissolve":
+      return seq(wait(rs(31) * 0.5), par(
+        tween(g.id, { opacity: 0 }, { duration: dur3(0.4, c.sp), ease: "easeInQuad" }),
+        tween(g.id, { scale: 1.4 }, { duration: dur3(0.4, c.sp), ease: "easeOutQuad" })
+      ));
+    case "fall":
+      return par(
+        tween(g.id, { y: g.y + 700 + rs(41) * 200 }, { duration: dur3(0.8, c.sp), ease: "easeInQuad" }),
+        tween(g.id, { rotation: (rs(42) - 0.5) * 120, opacity: 0 }, { duration: dur3(0.8, c.sp), ease: "easeInQuad" })
+      );
+    case "collapse":
+      return par(
+        tween(g.id, { x: block.x, y: block.y, scale: 0.2 }, { duration: dur3(0.5, c.sp), ease: "easeInBack" }),
+        tween(g.id, { opacity: 0 }, { duration: dur3(0.5, c.sp), ease: "easeInQuad" })
+      );
+  }
+}
+function textOut(name, block, opts = {}) {
+  const c = { ...ctx3(opts), fs: block.fontSize };
+  const dir = opts.dir ?? [0, -1];
+  const steps = block.glyphs.map((g) => glyphOut(name, g, c, block, dir));
+  const interval = (c.stag ?? OUT_STAGGER[name]) / c.sp;
+  const body = interval > 0 ? stagger(interval, ...steps) : par(...steps);
+  return beat(opts.label ?? `text-out-${name}`, {}, [body]);
+}
+function textTypeCues(block, opts) {
+  const interval = opts.interval ?? 0.065;
+  const gain = opts.gain ?? 0.4;
+  const off = opts.offset ?? 0;
+  const KEYS = ["001", "004", "007", "010", "014"];
+  return block.glyphs.map((g, i) => ({
+    at: opts.at,
+    offset: off + i * interval,
+    file: `keypress-${KEYS[i % KEYS.length]}.wav`,
+    gain: gain + 0.2 * rand(i, 31)
+  }));
+}
+
 // ../core/src/motionOps.ts
 var MOTION_OPS = ["rotate", "zoom", "ken-burns", "slide-in", "fade", "draw-on", "pulse"];
-var clamp013 = (n3) => Math.max(0, Math.min(1, n3));
+var clamp014 = (n3) => Math.max(0, Math.min(1, n3));
 function settleEase2(e) {
   return e < 0.34 ? "easeOutCubic" : e < 0.67 ? "easeOutBack" : "easeOutElastic";
 }
@@ -1708,7 +2282,7 @@ function fromVec2(from, dist) {
 }
 var motionOpLabel = (name, target) => `op-${name}-${target}`;
 function motionOp(name, target, opts = {}) {
-  const e = clamp013(opts.energy ?? 0.5);
+  const e = clamp014(opts.energy ?? 0.5);
   const sp = Math.max(0.25, opts.speed ?? 1);
   const amt = opts.amount ?? 1;
   const b = { scale: 1, x: 0, y: 0, rotation: 0, ...opts.base };
@@ -2411,29 +2985,29 @@ function sketchToTimeline(sketch, nodeIds) {
   const steps = [];
   events.forEach((ev, i) => {
     const node = nodeIds[i % nodeIds.length];
-    const dur3 = Math.max(0.05, ev.t1 - ev.t0);
+    const dur4 = Math.max(0.05, ev.t1 - ev.t0);
     const ease = easeFor(ev.easing);
     let motion;
     switch (ev.kind) {
       case "enter":
-        motion = tween(node, { opacity: 1 }, { duration: dur3, ease });
+        motion = tween(node, { opacity: 1 }, { duration: dur4, ease });
         break;
       case "exit":
-        motion = tween(node, { opacity: 0 }, { duration: dur3, ease });
+        motion = tween(node, { opacity: 0 }, { duration: dur4, ease });
         break;
       case "emphasis": {
         const peak = 1 + Math.max(0.08, Math.min(0.5, ev.magnitude));
         motion = seq(
-          tween(node, { scale: peak }, { duration: dur3 / 2, ease: "easeOutCubic" }),
-          tween(node, { scale: 1 }, { duration: dur3 / 2, ease: "easeInOutQuad" })
+          tween(node, { scale: peak }, { duration: dur4 / 2, ease: "easeOutCubic" }),
+          tween(node, { scale: 1 }, { duration: dur4 / 2, ease: "easeInOutQuad" })
         );
         break;
       }
       case "scale":
-        motion = tween(node, { scale: 1 + Math.max(-0.5, Math.min(0.5, ev.magnitude)) }, { duration: dur3, ease });
+        motion = tween(node, { scale: 1 + Math.max(-0.5, Math.min(0.5, ev.magnitude)) }, { duration: dur4, ease });
         break;
       case "move":
-        motion = tween(node, { opacity: 1 }, { duration: dur3, ease });
+        motion = tween(node, { opacity: 1 }, { duration: dur4, ease });
         break;
     }
     steps.push(ev.t0 > 0 ? seq(wait(ev.t0), motion) : motion);
@@ -2461,10 +3035,16 @@ export {
   compileScene,
   composeScene,
   composition,
+  cursor,
+  cursorClick,
+  cursorDouble,
+  cursorPath,
+  cursorTo,
   deviceBounds,
   devicePreset,
   deviceScreen,
   deviceScreenCenter,
+  deviceScreenPoint,
   ellipse,
   evaluate,
   figure,
@@ -2499,8 +3079,13 @@ export {
   scene,
   seq,
   sketchToTimeline,
+  splitText,
   stagger,
   text,
+  textIn,
+  textLoop,
+  textOut,
+  textTypeCues,
   to,
   tween,
   validateComposition,

package/dist/types/cursor.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Cursor / pointer motion — a vector mouse pointer that glides across the scene
+ * and clicks things (the UI-demo staple). `cursor()` returns a NodeIR (like
+ * `devicePreset`); `cursorTo` / `cursorPath` / `cursorClick` return TimelineIR
+ * (like `characterPreset`). The pointer's HOTSPOT is the group origin (0,0), so a
+ * move lands the tip exactly on a target. Pairs with `deviceScreenPoint` to click
+ * UI inside a `devicePreset` screen.
+ *
+ *   nodes:     [devicePreset("browser", { id: "d", x, y, scale, content }), cursor({ id: "cur" })]
+ *   timeline:  seq(cursorTo("cur", [start], deviceScreenPoint("browser", dOpts, [lx, ly])),
+ *                  cursorClick("cur", { press: "d-ui-cta" }))
+ */
+import type { Ease, NodeIR, TimelineIR } from "./ir.js";
+export type CursorStyle = "arrow" | "dot" | "ring";
+export interface CursorOpts {
+    id?: string;
+    x?: number;
+    y?: number;
+    scale?: number;
+    opacity?: number;
+    style?: CursorStyle;
+    /** Pointer body colour (default white for arrow). */
+    fill?: string;
+    /** Accent for dot/ring body and the click ripple. */
+    accent?: string;
+}
+export declare function cursor(opts?: CursorOpts): NodeIR;
+export interface CursorToOpts {
+    duration?: number;
+    ease?: Ease;
+    /** perpendicular bow as a fraction of distance (default 0.12; 0 = straight). */
+    arc?: number;
+    label?: string;
+}
+/** Glide the cursor from `from` to `to` along a gentle human arc. */
+export declare function cursorTo(id: string, from: [number, number], to: [number, number], opts?: CursorToOpts): TimelineIR;
+export interface CursorPathOpts {
+    duration?: number;
+    ease?: Ease;
+    curviness?: number;
+    label?: string;
+}
+/** Move the cursor through a tour of waypoints (one smooth path). */
+export declare function cursorPath(id: string, points: [number, number][], opts?: CursorPathOpts): TimelineIR;
+export interface CursorClickOpts {
+    /** overall click duration scale (default 1). */
+    speed?: number;
+    /** node id to "press" (a quick scale dip) when the cursor clicks it. */
+    press?: string;
+    /** show the expanding ripple ring (default true). */
+    ripple?: boolean;
+    label?: string;
+}
+/** A click: the pointer taps, a ripple ring expands, and an optional target presses. */
+export declare function cursorClick(id: string, opts?: CursorClickOpts): TimelineIR;
+/** Two quick clicks. */
+export declare function cursorDouble(id: string, opts?: CursorClickOpts): TimelineIR;

package/dist/types/devicePreset.d.ts

@@ -61,5 +61,9 @@ export declare function deviceBounds(name: DevicePresetName, opts?: DevicePreset
     width: number;
     height: number;
 };
+/** Map a SCREEN-LOCAL point (origin = screen centre, the coords `content` is
+ *  authored in) to absolute SCENE coords, given the same `opts` passed to
+ *  `devicePreset`. For aiming a `cursor` at on-screen UI. */
+export declare function deviceScreenPoint(name: DevicePresetName, opts: DevicePresetOpts, local: [number, number]): [number, number];
 /** Build a device-mockup frame (a group) with a clipped screen content slot. */
 export declare function devicePreset(name: DevicePresetName, opts?: DevicePresetOpts): NodeIR;

package/dist/types/index.d.ts

@@ -6,10 +6,12 @@ export { composeScene, formatComposeReport, type OverlayDoc, type ComposeReport,
 export { compileScene, type CompiledScene, type PropertySegment, type LabelSpan, type MotionDriver } from "./compile.js";
 export { pathPoint, pathTangentAngle, type Pt } from "./path.js";
 export { motionPreset, PRESET_NAMES, type PresetName, type PresetRig, type PresetOpts } from "./presets.js";
-export { devicePreset, deviceScreen, deviceScreenCenter, deviceBounds, DEVICE_PRESET_NAMES, type DevicePresetName, type DevicePresetOpts } from "./devicePreset.js";
+export { devicePreset, deviceScreen, deviceScreenCenter, deviceBounds, deviceScreenPoint, DEVICE_PRESET_NAMES, type DevicePresetName, type DevicePresetOpts } from "./devicePreset.js";
+export { cursor, cursorTo, cursorPath, cursorClick, cursorDouble, type CursorStyle, type CursorOpts, type CursorToOpts, type CursorPathOpts, type CursorClickOpts } from "./cursor.js";
 export { rig, rigPose, poseTo, ikReach, humanoid, ovalPath, type Bone, type RigOpts, type Pose, type HumanoidOpts } from "./rig.js";
 export { characterPreset, CHARACTER_PRESET_NAMES, type CharacterPresetName, type CharacterPresetOpts } from "./characterPreset.js";
 export { figure, type FigureStyle, type FigureOpts, type FigurePalette } from "./figure.js";
+export { splitText, textIn, textLoop, textOut, textTypeCues, type SplitOpts, type Glyph, type TextBlock, type FontWeight, type TextInName, type TextLoopName, type TextOutName, type TextLoopOpts, type TextOutOpts, type TypeCueOpts, } from "./textFx.js";
 export { motionOp, motionOpLabel, MOTION_OPS, type MotionOpName, type MotionOpOpts, type MotionOpResult } from "./motionOps.js";
 export { resolveAudioPlan, resolveCompositionAudioPlan, SFX_DURATION, type AudioPlan, type ResolvedCue, } from "./audio.js";
 export { evaluate, sampleProp, nodeParentMatrix, type DisplayList, type DisplayOp, type Mat2D, type ClipRegion, type TextAlign, type TextBaseline, } from "./evaluate.js";

package/dist/types/textFx.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Kinetic text — a deterministic per-glyph text splitter plus a library of
+ * seeded effect generators (entrance / sustained / exit). The text analog of
+ * `motionPreset` / `characterPreset`: `splitText()` lays a phrase out as
+ * center-anchored `text` nodes (advances measured from the real font, so layout
+ * matches the render), then `textIn` / `textLoop` / `textOut` animate the glyphs.
+ *
+ *   const T = splitText("MOTION IS DATA", { id: "t", x: 960, y: 470, fontSize: 130 });
+ *   // nodes:     [...T.nodes]
+ *   // timeline:  seq(textIn("typewriter", T), wait(2), textOut("shatter", T, { seed: 3 }))
+ *   // behaviors: textLoop("wave", T, { from: 1.6, until: 3.6 })
+ */
+import { type BehaviorWindow } from "./dsl.js";
+import type { AudioCueIR, BehaviorIR, NodeIR, TimelineIR } from "./ir.js";
+export type FontWeight = 400 | 700 | 800;
+export interface SplitOpts {
+    /** Id PREFIX → glyph ids `${id}-${i}`. */
+    id: string;
+    /** Anchor point of the line. */
+    x: number;
+    y: number;
+    fontSize: number;
+    fontWeight?: FontWeight;
+    fill?: string;
+    /** Extra px between glyphs (tracking). */
+    letterSpacing?: number;
+    /** Horizontal alignment about `x` (default "center"). */
+    align?: "left" | "center";
+    /** Animate per glyph or per word (default "glyph"). */
+    unit?: "glyph" | "word";
+    /** Starting opacity of the nodes (default 0, for entrances). */
+    opacity?: number;
+}
+export interface Glyph {
+    id: string;
+    /** The character (glyph unit) or word (word unit). */
+    ch: string;
+    /** Home centre (the laid-out resting position). */
+    x: number;
+    y: number;
+    /** This unit's advance width in px. */
+    advance: number;
+    /** Index in declaration order. */
+    i: number;
+}
+export interface TextBlock {
+    nodes: NodeIR[];
+    glyphs: Glyph[];
+    ids: string[];
+    /** Total laid-out width in px. */
+    width: number;
+    x: number;
+    y: number;
+    fontSize: number;
+}
+export declare function splitText(textStr: string, opts: SplitOpts): TextBlock;
+interface FxOpts {
+    speed?: number;
+    energy?: number;
+    seed?: number;
+    stagger?: number;
+    label?: string;
+}
+export type TextInName = "typewriter" | "cascade" | "rise" | "bounce" | "assemble" | "decode";
+export declare function textIn(name: TextInName, block: TextBlock, opts?: FxOpts): TimelineIR;
+export type TextLoopName = "wave" | "shimmer" | "wobble" | "float";
+export interface TextLoopOpts extends BehaviorWindow {
+    amplitude?: number;
+    frequency?: number;
+    /** phase offset per glyph (the travelling-wave speed). */
+    phaseStep?: number;
+}
+export declare function textLoop(name: TextLoopName, block: TextBlock, opts?: TextLoopOpts): BehaviorIR[];
+export type TextOutName = "shatter" | "fly" | "dissolve" | "fall" | "collapse";
+export interface TextOutOpts extends FxOpts {
+    /** direction for "fly" (default up). */
+    dir?: [number, number];
+}
+export declare function textOut(name: TextOutName, block: TextBlock, opts?: TextOutOpts): TimelineIR;
+export interface TypeCueOpts {
+    /** the timeline label the typewriter `textIn` starts at. */
+    at: string | number;
+    /** seconds between keystrokes (match the textIn stagger / speed). */
+    interval?: number;
+    gain?: number;
+    /** offset of the first key from `at`. */
+    offset?: number;
+}
+/** Per-glyph CC0 keypress for `textIn("typewriter", …)`. */
+export declare function textTypeCues(block: TextBlock, opts: TypeCueOpts): AudioCueIR[];
+export {};

package/dist/types/textMetrics.d.ts

@@ -0,0 +1,3 @@
+export declare const INTER_ADVANCE: Record<number, Record<string, number>>;
+/** Average advance per weight — the fallback for glyphs outside the table. */
+export declare const INTER_FALLBACK: Record<number, number>;

package/guides/edsl-guide.md

@@ -167,6 +167,65 @@ no new renderer concept, so overlays/preview/determinism all apply.
   set it when the same preset is used more than once in a scene). Legs use
   `ikReach`, arms FK; pure keyframes, so add continuous idle yourself with `oscillate`.
 
+## Kinetic text (split + effect presets)
+
+reframe's `text` node renders a whole string as one node, so per-glyph effects
+need the string split into per-character nodes. `splitText` does that once;
+seeded effect generators animate the glyphs (the text analog of `motionPreset`).
+
+- `splitText(text, { id, x, y, fontSize, fontWeight?, fill?, letterSpacing?,
+  align?, unit?, opacity? }) → TextBlock` — lays the phrase out as center-anchored
+  `text` nodes using **real Inter advance widths** (so layout matches the render).
+  Returns `{ nodes, glyphs, ids, width, ... }`; put `...block.nodes` in `nodes`.
+  Glyph ids are `${id}-${i}` (stable regen addresses). `unit: "word"` animates
+  whole words instead of letters; `opacity: 0` (default) starts hidden for entrances.
+- `textIn(name, block, { speed?, energy?, seed?, stagger?, label? }) → TimelineIR`
+  (a `beat`) — entrance: `typewriter`, `cascade`, `rise`, `bounce`, `assemble`
+  (fly in from a seeded scatter), `decode` (scramble through random glyphs then lock).
+- `textLoop(name, block, { from?, until?, ramp?, amplitude?, frequency?, phaseStep? })
+  → BehaviorIR[]` — sustained: `wave` (standing sine), `shimmer`, `wobble`, `float`.
+  Spread it into `behaviors`.
+- `textOut(name, block, { …, dir? }) → TimelineIR` — exit: `shatter` (random
+  direction + spin + fade), `fly` (directional), `dissolve`, `fall`, `collapse`.
+- `textTypeCues(block, { at, interval?, gain? }) → AudioCueIR[]` — per-glyph CC0
+  keypress for a typewriter entrance; spread into `audio.cues`.
+
+```ts
+const T = splitText("MOTION IS DATA", { id: "t", x: 960, y: 470, fontSize: 130 });
+// nodes:     [...T.nodes]
+// timeline:  seq(textIn("cascade", T), wait(2), textOut("shatter", T, { seed: 3 }))
+// behaviors: textLoop("wave", T, { from: 1.6, until: 3.6 })
+```
+Every effect is seeded (same `seed` → identical) and pure keyframes. To time a
+`textLoop` window, add up the `textIn` beat length (≈ `(n-1)·stagger + glyphDur`).
+
+## Cursor (UI demos)
+
+A vector mouse pointer that glides across the scene and clicks things — for app
+walkthroughs. `cursor()` returns a node; the moves/clicks return timeline steps.
+The pointer's **hotspot is the group origin**, so a move lands the tip on a target.
+
+- `cursor({ id, x, y, scale?, opacity?, style?, accent? }) → NodeIR` — styles
+  `arrow` (default), `dot`, `ring`. Draw it LAST so it sits on top. Carries a
+  hidden `${id}-ripple` ring for clicks.
+- `cursorTo(id, from, to, { duration?, ease?, arc? }) → TimelineIR` — glide along
+  a gentle human arc (`arc` is the bow, default 0.12). Thread the position: start
+  = the node's `x/y`, each `to` becomes the next `from`.
+- `cursorPath(id, points, opts)` — a multi-stop tour through waypoints.
+- `cursorClick(id, { press?, ripple?, label? })` / `cursorDouble(...)` — the
+  pointer taps, a ripple ring expands, and the `press` node (a button) dips. Pass
+  a unique `label` when you click more than once in a scene.
+- `deviceScreenPoint(name, deviceOpts, [lx, ly]) → [x, y]` — map a UI element's
+  screen-local coords (the coords `devicePreset` `content` is authored in) to
+  scene coords, so the cursor clicks on-screen UI precisely (account for the
+  device's `scale` at click time and any `slot` offset).
+
+```ts
+// nodes:    devicePreset("browser", { id:"d", x, y, scale:0.88, content }), cursor({ id:"cur" })
+const cta = deviceScreenPoint("browser", { x, y, scale: 0.88 }, [lx, ly]);
+seq(cursorTo("cur", [sx, sy], cta), cursorClick("cur", { press: "browser-ui-cta" }))
+```
+
 ## Audio (optional)
 
 Label-anchored sound design — cues follow retiming and regeneration:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reframe-video",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Declarative motion graphics that AI can write and humans can tweak — human edits survive AI regeneration. Deterministic mp4 renders from a plain-data scene format.",
   "keywords": [
     "motion-graphics",