reframe-video 0.4.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"() {
@@ -1304,6 +1312,7 @@ var init_src = __esm({
     init_path();
     init_presets();
     init_devicePreset();
+    init_cursor();
     init_rig();
     init_characterPreset();
     init_figure();

package/dist/index.js

@@ -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";
@@ -2008,7 +2080,7 @@ function splitText(textStr, opts) {
   chars.forEach((ch, i) => {
     total += advance(ch, weight, fontSize) + (i < chars.length - 1 ? ls : 0);
   });
-  let cursor = align === "center" ? x - total / 2 : x;
+  let cursor2 = align === "center" ? x - total / 2 : x;
   const glyphs = [];
   const nodes = [];
   const mk = (ch, cx, adv, lsProp) => {
@@ -2034,13 +2106,13 @@ function splitText(textStr, opts) {
     let i = 0;
     while (i < chars.length) {
       if (chars[i] === " ") {
-        cursor += advance(" ", weight, fontSize) + ls;
+        cursor2 += advance(" ", weight, fontSize) + ls;
         i++;
         continue;
       }
       let word = "";
       let w = 0;
-      const startCursor = cursor;
+      const startCursor = cursor2;
       while (i < chars.length && chars[i] !== " ") {
         const a = advance(chars[i], weight, fontSize);
         word += chars[i];
@@ -2048,13 +2120,13 @@ function splitText(textStr, opts) {
         i++;
       }
       mk(word, startCursor + w / 2, w, ls);
-      cursor = startCursor + w + ls;
+      cursor2 = startCursor + w + ls;
     }
   } else {
     chars.forEach((ch) => {
       const a = advance(ch, weight, fontSize);
-      if (ch !== " ") mk(ch, cursor + a / 2, a);
-      cursor += a + ls;
+      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 };
@@ -2963,10 +3035,16 @@ export {
   compileScene,
   composeScene,
   composition,
+  cursor,
+  cursorClick,
+  cursorDouble,
+  cursorPath,
+  cursorTo,
   deviceBounds,
   devicePreset,
   deviceScreen,
   deviceScreenCenter,
+  deviceScreenPoint,
   ellipse,
   evaluate,
   figure,

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,7 +6,8 @@ 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";

package/guides/edsl-guide.md

@@ -199,6 +199,33 @@ const T = splitText("MOTION IS DATA", { id: "t", x: 960, y: 470, fontSize: 130 }
 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.4.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",