reframe-video 0.4.0 → 0.6.0

package/dist/bin.js

@@ -153,6 +153,14 @@ function compileScene(ir) {
       }
     }
   }
+  const cameraIsNode = nodeById.has("camera");
+  if (!cameraIsNode) {
+    const cam = ir.camera ?? {};
+    initialValues.set(key("camera", "x"), cam.x ?? ir.size.width / 2);
+    initialValues.set(key("camera", "y"), cam.y ?? ir.size.height / 2);
+    initialValues.set(key("camera", "zoom"), cam.zoom ?? 1);
+    initialValues.set(key("camera", "rotation"), cam.rotation ?? 0);
+  }
   const segments = /* @__PURE__ */ new Map();
   const motionPaths = /* @__PURE__ */ new Map();
   const current = new Map(initialValues);
@@ -313,6 +321,7 @@ function compileScene(ir) {
   const inferredEnd = ir.timeline ? walk(ir.timeline, 0) : 0;
   for (const list of segments.values()) list.sort((a, b) => a.t0 - b.t0);
   for (const list of motionPaths.values()) list.sort((a, b) => a.t0 - b.t0);
+  const hasCamera = !cameraIsNode && (ir.camera !== void 0 || motionPaths.has("camera") || [...segments.keys()].some((k) => k.startsWith("camera.")));
   return {
     ir,
     duration: ir.duration ?? inferredEnd,
@@ -322,7 +331,8 @@ function compileScene(ir) {
     nodeById,
     nodeOrder,
     labelTimes,
-    beatTimes
+    beatTimes,
+    hasCamera
   };
 }
 var key;
@@ -361,6 +371,14 @@ function validateScene(ir) {
   };
   collect(ir.nodes);
   const checkProps = (where, nodeId, props) => {
+    if (nodeId === "camera" && !nodeById.has("camera")) {
+      for (const key2 of Object.keys(props)) {
+        if (!CAMERA_PROPS.includes(key2)) {
+          problems.push(`${where}: "${key2}" is not a camera prop \u2014 valid props: ${CAMERA_PROPS.join(", ")}`);
+        }
+      }
+      return;
+    }
     const node = nodeById.get(nodeId);
     if (!node) {
       problems.push(
@@ -428,12 +446,15 @@ function validateScene(ir) {
         break;
       case "motionPath": {
         const node = nodeById.get(tl.target);
-        if (!node) {
-          problems.push(
-            `${path2}: motionPath targets unknown node "${tl.target}" \u2014 known ids: ${[...nodeById.keys()].join(", ")}`
-          );
-        } else if (node.type === "line") {
-          problems.push(`${path2}: motionPath cannot target a line (no x/y) \u2014 "${tl.target}"`);
+        const isSceneCamera = tl.target === "camera" && !node;
+        if (!isSceneCamera) {
+          if (!node) {
+            problems.push(
+              `${path2}: motionPath targets unknown node "${tl.target}" \u2014 known ids: ${[...nodeById.keys()].join(", ")}`
+            );
+          } else if (node.type === "line") {
+            problems.push(`${path2}: motionPath cannot target a line (no x/y) \u2014 "${tl.target}"`);
+          }
         }
         if (tl.points.length < 1) problems.push(`${path2}: motionPath "${tl.target}" needs at least 1 point`);
         if (tl.duration !== void 0 && tl.duration <= 0) {
@@ -478,6 +499,18 @@ function validateScene(ir) {
   if (ir.duration !== void 0 && ir.duration <= 0) {
     problems.push("scene duration must be > 0");
   }
+  if (ir.camera) {
+    if (nodeById.has("camera")) {
+      problems.push(`camera: a node is already named "camera" \u2014 rename that node or drop the scene camera (the id "camera" can't be both)`);
+    }
+    for (const [key2, value] of Object.entries(ir.camera)) {
+      if (!CAMERA_PROPS.includes(key2)) {
+        problems.push(`camera: "${key2}" is not a camera prop \u2014 valid props: ${CAMERA_PROPS.join(", ")}`);
+      } else if (typeof value !== "number") {
+        problems.push(`camera.${key2} must be a number`);
+      }
+    }
+  }
   const SFX_NAMES = ["whoosh", "pop", "tick", "rise", "shimmer", "thud"];
   for (const [i, cue] of (ir.audio?.cues ?? []).entries()) {
     if (typeof cue.at === "string" && !labels.has(cue.at)) {
@@ -536,16 +569,17 @@ function validateComposition(comp) {
   }
   if (problems.length > 0) throw new SceneValidationError(problems);
 }
-var COMMON_PROPS, PROPS_BY_TYPE, SceneValidationError, TRANSITIONS;
+var COMMON_PROPS, CAMERA_PROPS, PROPS_BY_TYPE, SceneValidationError, TRANSITIONS;
 var init_validate = __esm({
   "../core/src/validate.ts"() {
     "use strict";
-    COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "anchor"];
+    COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "anchor", "fixed"];
+    CAMERA_PROPS = ["x", "y", "zoom", "rotation"];
     PROPS_BY_TYPE = {
       rect: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth", "radius"],
       ellipse: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth"],
       line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress"],
-      text: [...COMMON_PROPS, "content", "contentDecimals", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
+      text: [...COMMON_PROPS, "content", "contentDecimals", "contentThousands", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
       image: [...COMMON_PROPS, "src", "width", "height"],
       path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
       group: COMMON_PROPS
@@ -857,6 +891,14 @@ var init_compose = __esm({
   }
 });
 
+// ../core/src/camera.ts
+var init_camera = __esm({
+  "../core/src/camera.ts"() {
+    "use strict";
+    init_dsl();
+  }
+});
+
 // ../core/src/presets.ts
 function makeRng(seed) {
   let a = seed >>> 0 || 2654435769;
@@ -1044,6 +1086,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"() {
@@ -1241,6 +1291,7 @@ var init_evaluate = __esm({
   "../core/src/evaluate.ts"() {
     "use strict";
     init_behaviors();
+    init_camera();
     init_interpolate();
     init_path();
   }
@@ -1302,8 +1353,10 @@ var init_src = __esm({
     init_compose();
     init_compile();
     init_path();
+    init_camera();
     init_presets();
     init_devicePreset();
+    init_cursor();
     init_rig();
     init_characterPreset();
     init_figure();
@@ -2325,6 +2378,7 @@ var ROOT2 = PACKAGED ? resolve4(HERE2, "..") : resolve4(HERE2, "..", "..", "..")
 var USER_CWD = process.env.INIT_CWD ?? process.cwd();
 var RENDER_CLI = PACKAGED ? join6(ROOT2, "dist", "cli.js") : join6(ROOT2, "packages", "render-cli", "src", "cli.ts");
 var LABELS = PACKAGED ? join6(ROOT2, "dist", "labels.js") : join6(ROOT2, "packages", "render-cli", "src", "labels.ts");
+var PLAYER = PACKAGED ? join6(ROOT2, "dist", "player.js") : join6(ROOT2, "packages", "render-cli", "src", "player.ts");
 var ANALYZE = PACKAGED ? join6(ROOT2, "dist", "analyze.js") : join6(ROOT2, "benchmark", "harness", "motion", "analyze.ts");
 var TRACE = PACKAGED ? join6(ROOT2, "dist", "trace-cli.js") : join6(ROOT2, "benchmark", "harness", "motion", "trace-cli.ts");
 var CMD = PACKAGED ? "reframe" : "pnpm reframe";
@@ -2336,6 +2390,8 @@ usage:
   ${CMD} logo <logo.svg|brand-slug> ["Name"] [--motion <preset>] [--energy 0..1] [--seed N] [-o out.mp4]
                                  animate a logo into a sting (presets: draw-bloom, punch-in,
                                  rise-settle, slide-bank, reveal-orbit, spin-forge)
+  ${CMD} player <scene.ts|.json> [-o out.html]  bundle a scene into one self-contained HTML
+                                 player (plays live in any browser or a Claude.ai artifact; visual only)
   ${CMD} preview                 open the scrub/edit UI (lists scenes in your directory)
   ${CMD} new <scene-name>        scaffold <scene-name>.ts in your directory
   ${CMD} labels <scene.ts|.json>  print the event clock (label \u2192 exact seconds; for sound design / timing)
@@ -2480,6 +2536,21 @@ ${USAGE}`);
         await (PACKAGED ? run(process.execPath, [LABELS, inputPath]) : run("npx", ["tsx", LABELS, inputPath]))
       );
     }
+    case "player": {
+      const input = rest[0];
+      if (!input || input.startsWith("-")) fail(`player needs a scene file
+
+${USAGE}`);
+      const inputPath = userPath(input);
+      if (!existsSync4(inputPath)) fail(`no such file: ${inputPath}`);
+      const oIdx = rest.indexOf("-o");
+      const outBase = PACKAGED ? join6(USER_CWD, "out") : join6(ROOT2, "out");
+      const outPath = oIdx >= 0 && rest[oIdx + 1] ? userPath(rest[oIdx + 1]) : join6(outBase, `${basename(input).replace(/\.[^.]+$/, "")}.html`);
+      await mkdir4(dirname7(outPath), { recursive: true });
+      process.exit(
+        await (PACKAGED ? run(process.execPath, [PLAYER, inputPath, outPath]) : run("npx", ["tsx", PLAYER, inputPath, outPath]))
+      );
+    }
     case "logo": {
       const positional = [];
       const flags = {};

package/dist/browserEntry.js

@@ -134,6 +134,14 @@
         }
       }
     }
+    const cameraIsNode = nodeById.has("camera");
+    if (!cameraIsNode) {
+      const cam = ir.camera ?? {};
+      initialValues.set(key("camera", "x"), cam.x ?? ir.size.width / 2);
+      initialValues.set(key("camera", "y"), cam.y ?? ir.size.height / 2);
+      initialValues.set(key("camera", "zoom"), cam.zoom ?? 1);
+      initialValues.set(key("camera", "rotation"), cam.rotation ?? 0);
+    }
     const segments = /* @__PURE__ */ new Map();
     const motionPaths = /* @__PURE__ */ new Map();
     const current = new Map(initialValues);
@@ -294,6 +302,7 @@
     const inferredEnd = ir.timeline ? walk(ir.timeline, 0) : 0;
     for (const list of segments.values()) list.sort((a, b) => a.t0 - b.t0);
     for (const list of motionPaths.values()) list.sort((a, b) => a.t0 - b.t0);
+    const hasCamera = !cameraIsNode && (ir.camera !== void 0 || motionPaths.has("camera") || [...segments.keys()].some((k) => k.startsWith("camera.")));
     return {
       ir,
       duration: ir.duration ?? inferredEnd,
@@ -303,22 +312,38 @@
       nodeById,
       nodeOrder,
       labelTimes,
-      beatTimes
+      beatTimes,
+      hasCamera
     };
   }
 
   // ../core/src/validate.ts
-  var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "anchor"];
+  var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "anchor", "fixed"];
   var PROPS_BY_TYPE = {
     rect: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth", "radius"],
     ellipse: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth"],
     line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress"],
-    text: [...COMMON_PROPS, "content", "contentDecimals", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
+    text: [...COMMON_PROPS, "content", "contentDecimals", "contentThousands", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
     image: [...COMMON_PROPS, "src", "width", "height"],
     path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
     group: COMMON_PROPS
   };
 
+  // ../core/src/camera.ts
+  function cameraMatrix(cam, size) {
+    const W = size.width;
+    const H = size.height;
+    const x = cam.x ?? W / 2;
+    const y = cam.y ?? H / 2;
+    const zoom = cam.zoom ?? 1;
+    const r = (cam.rotation ?? 0) * Math.PI / 180;
+    const a = Math.cos(r) * zoom;
+    const b = Math.sin(r) * zoom;
+    const c = b === 0 ? 0 : -b;
+    const d = Math.cos(r) * zoom;
+    return [a, b, c, d, W / 2 - a * x - c * y, H / 2 - b * x - d * y];
+  }
+
   // ../core/src/presets.ts
   var SET = 1 / 120;
 
@@ -552,6 +577,17 @@
   };
   var TEXT_ALIGN = { 0: "left", 0.5: "center", 1: "right" };
   var TEXT_BASELINE = { 0: "top", 0.5: "middle", 1: "bottom" };
+  function formatNumber(value, decimals, thousands) {
+    const fixed = value.toFixed(decimals);
+    if (!thousands) return fixed;
+    const neg = fixed.startsWith("-");
+    const body = neg ? fixed.slice(1) : fixed;
+    const dot = body.indexOf(".");
+    const intPart = dot === -1 ? body : body.slice(0, dot);
+    const frac = dot === -1 ? "" : body.slice(dot);
+    const grouped = intPart.replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+    return (neg ? "-" : "") + grouped + frac;
+  }
   function behaviorEnvelope(b, t) {
     const from = b.from ?? Number.NEGATIVE_INFINITY;
     const until = b.until ?? Number.POSITIVE_INFINITY;
@@ -739,7 +775,7 @@
             id,
             transform: matrix,
             opacity,
-            content: typeof raw === "number" ? raw.toFixed(decimals) : raw,
+            content: typeof raw === "number" ? formatNumber(raw, decimals, node.props.contentThousands === true) : raw,
             fontFamily: str(id, "fontFamily", node.props.fontFamily),
             fontSize: num(id, "fontSize", node.props.fontSize),
             fontWeight: num(id, "fontWeight", node.props.fontWeight ?? 400),
@@ -753,7 +789,19 @@
         }
       }
     };
-    for (const node of compiled2.ir.nodes) walk(node, IDENTITY, 1, []);
+    const cameraRoot = compiled2.hasCamera ? cameraMatrix(
+      {
+        x: num("camera", "x", compiled2.ir.size.width / 2),
+        y: num("camera", "y", compiled2.ir.size.height / 2),
+        zoom: num("camera", "zoom", 1),
+        rotation: num("camera", "rotation", 0)
+      },
+      compiled2.ir.size
+    ) : IDENTITY;
+    for (const node of compiled2.ir.nodes) {
+      const root = compiled2.hasCamera && node.props.fixed ? IDENTITY : cameraRoot;
+      walk(node, root, 1, []);
+    }
     return ops;
   }
 

package/dist/cli.js

@@ -140,6 +140,14 @@ function compileScene(ir) {
       }
     }
   }
+  const cameraIsNode = nodeById.has("camera");
+  if (!cameraIsNode) {
+    const cam = ir.camera ?? {};
+    initialValues.set(key("camera", "x"), cam.x ?? ir.size.width / 2);
+    initialValues.set(key("camera", "y"), cam.y ?? ir.size.height / 2);
+    initialValues.set(key("camera", "zoom"), cam.zoom ?? 1);
+    initialValues.set(key("camera", "rotation"), cam.rotation ?? 0);
+  }
   const segments = /* @__PURE__ */ new Map();
   const motionPaths = /* @__PURE__ */ new Map();
   const current = new Map(initialValues);
@@ -300,6 +308,7 @@ function compileScene(ir) {
   const inferredEnd = ir.timeline ? walk(ir.timeline, 0) : 0;
   for (const list of segments.values()) list.sort((a, b) => a.t0 - b.t0);
   for (const list of motionPaths.values()) list.sort((a, b) => a.t0 - b.t0);
+  const hasCamera = !cameraIsNode && (ir.camera !== void 0 || motionPaths.has("camera") || [...segments.keys()].some((k) => k.startsWith("camera.")));
   return {
     ir,
     duration: ir.duration ?? inferredEnd,
@@ -309,17 +318,19 @@ function compileScene(ir) {
     nodeById,
     nodeOrder,
     labelTimes,
-    beatTimes
+    beatTimes,
+    hasCamera
   };
 }
 
 // ../core/src/validate.ts
-var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "anchor"];
+var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "anchor", "fixed"];
+var CAMERA_PROPS = ["x", "y", "zoom", "rotation"];
 var PROPS_BY_TYPE = {
   rect: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth", "radius"],
   ellipse: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth"],
   line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress"],
-  text: [...COMMON_PROPS, "content", "contentDecimals", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
+  text: [...COMMON_PROPS, "content", "contentDecimals", "contentThousands", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
   image: [...COMMON_PROPS, "src", "width", "height"],
   path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
   group: COMMON_PROPS
@@ -358,6 +369,14 @@ function validateScene(ir) {
   };
   collect(ir.nodes);
   const checkProps = (where, nodeId, props) => {
+    if (nodeId === "camera" && !nodeById.has("camera")) {
+      for (const key2 of Object.keys(props)) {
+        if (!CAMERA_PROPS.includes(key2)) {
+          problems.push(`${where}: "${key2}" is not a camera prop \u2014 valid props: ${CAMERA_PROPS.join(", ")}`);
+        }
+      }
+      return;
+    }
     const node = nodeById.get(nodeId);
     if (!node) {
       problems.push(
@@ -425,12 +444,15 @@ function validateScene(ir) {
         break;
       case "motionPath": {
         const node = nodeById.get(tl.target);
-        if (!node) {
-          problems.push(
-            `${path2}: motionPath targets unknown node "${tl.target}" \u2014 known ids: ${[...nodeById.keys()].join(", ")}`
-          );
-        } else if (node.type === "line") {
-          problems.push(`${path2}: motionPath cannot target a line (no x/y) \u2014 "${tl.target}"`);
+        const isSceneCamera = tl.target === "camera" && !node;
+        if (!isSceneCamera) {
+          if (!node) {
+            problems.push(
+              `${path2}: motionPath targets unknown node "${tl.target}" \u2014 known ids: ${[...nodeById.keys()].join(", ")}`
+            );
+          } else if (node.type === "line") {
+            problems.push(`${path2}: motionPath cannot target a line (no x/y) \u2014 "${tl.target}"`);
+          }
         }
         if (tl.points.length < 1) problems.push(`${path2}: motionPath "${tl.target}" needs at least 1 point`);
         if (tl.duration !== void 0 && tl.duration <= 0) {
@@ -475,6 +497,18 @@ function validateScene(ir) {
   if (ir.duration !== void 0 && ir.duration <= 0) {
     problems.push("scene duration must be > 0");
   }
+  if (ir.camera) {
+    if (nodeById.has("camera")) {
+      problems.push(`camera: a node is already named "camera" \u2014 rename that node or drop the scene camera (the id "camera" can't be both)`);
+    }
+    for (const [key2, value] of Object.entries(ir.camera)) {
+      if (!CAMERA_PROPS.includes(key2)) {
+        problems.push(`camera: "${key2}" is not a camera prop \u2014 valid props: ${CAMERA_PROPS.join(", ")}`);
+      } else if (typeof value !== "number") {
+        problems.push(`camera.${key2} must be a number`);
+      }
+    }
+  }
   const SFX_NAMES = ["whoosh", "pop", "tick", "rise", "shimmer", "thud"];
   for (const [i, cue] of (ir.audio?.cues ?? []).entries()) {
     if (typeof cue.at === "string" && !labels.has(cue.at)) {

package/dist/index.js

@@ -134,6 +134,14 @@ function compileScene(ir) {
       }
     }
   }
+  const cameraIsNode = nodeById.has("camera");
+  if (!cameraIsNode) {
+    const cam = ir.camera ?? {};
+    initialValues.set(key("camera", "x"), cam.x ?? ir.size.width / 2);
+    initialValues.set(key("camera", "y"), cam.y ?? ir.size.height / 2);
+    initialValues.set(key("camera", "zoom"), cam.zoom ?? 1);
+    initialValues.set(key("camera", "rotation"), cam.rotation ?? 0);
+  }
   const segments = /* @__PURE__ */ new Map();
   const motionPaths = /* @__PURE__ */ new Map();
   const current = new Map(initialValues);
@@ -294,6 +302,7 @@ function compileScene(ir) {
   const inferredEnd = ir.timeline ? walk(ir.timeline, 0) : 0;
   for (const list of segments.values()) list.sort((a, b) => a.t0 - b.t0);
   for (const list of motionPaths.values()) list.sort((a, b) => a.t0 - b.t0);
+  const hasCamera = !cameraIsNode && (ir.camera !== void 0 || motionPaths.has("camera") || [...segments.keys()].some((k) => k.startsWith("camera.")));
   return {
     ir,
     duration: ir.duration ?? inferredEnd,
@@ -303,17 +312,19 @@ function compileScene(ir) {
     nodeById,
     nodeOrder,
     labelTimes,
-    beatTimes
+    beatTimes,
+    hasCamera
   };
 }
 
 // ../core/src/validate.ts
-var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "anchor"];
+var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "anchor", "fixed"];
+var CAMERA_PROPS = ["x", "y", "zoom", "rotation"];
 var PROPS_BY_TYPE = {
   rect: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth", "radius"],
   ellipse: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth"],
   line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress"],
-  text: [...COMMON_PROPS, "content", "contentDecimals", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
+  text: [...COMMON_PROPS, "content", "contentDecimals", "contentThousands", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
   image: [...COMMON_PROPS, "src", "width", "height"],
   path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
   group: COMMON_PROPS
@@ -352,6 +363,14 @@ function validateScene(ir) {
   };
   collect(ir.nodes);
   const checkProps = (where, nodeId, props) => {
+    if (nodeId === "camera" && !nodeById.has("camera")) {
+      for (const key2 of Object.keys(props)) {
+        if (!CAMERA_PROPS.includes(key2)) {
+          problems.push(`${where}: "${key2}" is not a camera prop \u2014 valid props: ${CAMERA_PROPS.join(", ")}`);
+        }
+      }
+      return;
+    }
     const node = nodeById.get(nodeId);
     if (!node) {
       problems.push(
@@ -419,12 +438,15 @@ function validateScene(ir) {
         break;
       case "motionPath": {
         const node = nodeById.get(tl.target);
-        if (!node) {
-          problems.push(
-            `${path2}: motionPath targets unknown node "${tl.target}" \u2014 known ids: ${[...nodeById.keys()].join(", ")}`
-          );
-        } else if (node.type === "line") {
-          problems.push(`${path2}: motionPath cannot target a line (no x/y) \u2014 "${tl.target}"`);
+        const isSceneCamera = tl.target === "camera" && !node;
+        if (!isSceneCamera) {
+          if (!node) {
+            problems.push(
+              `${path2}: motionPath targets unknown node "${tl.target}" \u2014 known ids: ${[...nodeById.keys()].join(", ")}`
+            );
+          } else if (node.type === "line") {
+            problems.push(`${path2}: motionPath cannot target a line (no x/y) \u2014 "${tl.target}"`);
+          }
         }
         if (tl.points.length < 1) problems.push(`${path2}: motionPath "${tl.target}" needs at least 1 point`);
         if (tl.duration !== void 0 && tl.duration <= 0) {
@@ -469,6 +491,18 @@ function validateScene(ir) {
   if (ir.duration !== void 0 && ir.duration <= 0) {
     problems.push("scene duration must be > 0");
   }
+  if (ir.camera) {
+    if (nodeById.has("camera")) {
+      problems.push(`camera: a node is already named "camera" \u2014 rename that node or drop the scene camera (the id "camera" can't be both)`);
+    }
+    for (const [key2, value] of Object.entries(ir.camera)) {
+      if (!CAMERA_PROPS.includes(key2)) {
+        problems.push(`camera: "${key2}" is not a camera prop \u2014 valid props: ${CAMERA_PROPS.join(", ")}`);
+      } else if (typeof value !== "number") {
+        problems.push(`camera.${key2} must be a number`);
+      }
+    }
+  }
   const SFX_NAMES = ["whoosh", "pop", "tick", "rise", "shimmer", "thud"];
   for (const [i, cue] of (ir.audio?.cues ?? []).entries()) {
     if (typeof cue.at === "string" && !labels.has(cue.at)) {
@@ -863,6 +897,26 @@ function formatComposeReport(report) {
   return lines.join("\n");
 }
 
+// ../core/src/camera.ts
+var CAMERA_ID = "camera";
+var CAMERA_PROPS2 = ["x", "y", "zoom", "rotation"];
+function cameraMatrix(cam, size) {
+  const W = size.width;
+  const H = size.height;
+  const x = cam.x ?? W / 2;
+  const y = cam.y ?? H / 2;
+  const zoom = cam.zoom ?? 1;
+  const r = (cam.rotation ?? 0) * Math.PI / 180;
+  const a = Math.cos(r) * zoom;
+  const b = Math.sin(r) * zoom;
+  const c = b === 0 ? 0 : -b;
+  const d = Math.cos(r) * zoom;
+  return [a, b, c, d, W / 2 - a * x - c * y, H / 2 - b * x - d * y];
+}
+function cameraTo(props, opts = {}) {
+  return tween(CAMERA_ID, props, opts);
+}
+
 // ../core/src/presets.ts
 var PRESET_NAMES = [
   "draw-bloom",
@@ -1089,6 +1143,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 +1322,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 +2134,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 +2160,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 +2174,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 };
@@ -2629,6 +2755,17 @@ var ANCHOR_FACTORS = {
 };
 var TEXT_ALIGN = { 0: "left", 0.5: "center", 1: "right" };
 var TEXT_BASELINE = { 0: "top", 0.5: "middle", 1: "bottom" };
+function formatNumber(value, decimals, thousands) {
+  const fixed = value.toFixed(decimals);
+  if (!thousands) return fixed;
+  const neg = fixed.startsWith("-");
+  const body = neg ? fixed.slice(1) : fixed;
+  const dot = body.indexOf(".");
+  const intPart = dot === -1 ? body : body.slice(0, dot);
+  const frac = dot === -1 ? "" : body.slice(dot);
+  const grouped = intPart.replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+  return (neg ? "-" : "") + grouped + frac;
+}
 function behaviorEnvelope(b, t) {
   const from = b.from ?? Number.NEGATIVE_INFINITY;
   const until = b.until ?? Number.POSITIVE_INFINITY;
@@ -2848,7 +2985,7 @@ function evaluate(compiled, t) {
           id,
           transform: matrix,
           opacity,
-          content: typeof raw === "number" ? raw.toFixed(decimals) : raw,
+          content: typeof raw === "number" ? formatNumber(raw, decimals, node.props.contentThousands === true) : raw,
           fontFamily: str(id, "fontFamily", node.props.fontFamily),
           fontSize: num(id, "fontSize", node.props.fontSize),
           fontWeight: num(id, "fontWeight", node.props.fontWeight ?? 400),
@@ -2862,7 +2999,19 @@ function evaluate(compiled, t) {
       }
     }
   };
-  for (const node of compiled.ir.nodes) walk(node, IDENTITY, 1, []);
+  const cameraRoot = compiled.hasCamera ? cameraMatrix(
+    {
+      x: num("camera", "x", compiled.ir.size.width / 2),
+      y: num("camera", "y", compiled.ir.size.height / 2),
+      zoom: num("camera", "zoom", 1),
+      rotation: num("camera", "rotation", 0)
+    },
+    compiled.ir.size
+  ) : IDENTITY;
+  for (const node of compiled.ir.nodes) {
+    const root = compiled.hasCamera && node.props.fixed ? IDENTITY : cameraRoot;
+    walk(node, root, 1, []);
+  }
   return ops;
 }
 
@@ -2943,6 +3092,8 @@ function sketchToTimeline(sketch, nodeIds) {
   return par(...steps);
 }
 export {
+  CAMERA_ID,
+  CAMERA_PROPS2 as CAMERA_PROPS,
   CHARACTER_PRESET_NAMES,
   DEFAULT_CROSSFADE,
   DEFAULT_FPS,
@@ -2957,16 +3108,24 @@ export {
   SFX_DURATION,
   SceneValidationError,
   beat,
+  cameraMatrix,
+  cameraTo,
   characterPreset,
   collectImageSrcs,
   compileComposition,
   compileScene,
   composeScene,
   composition,
+  cursor,
+  cursorClick,
+  cursorDouble,
+  cursorPath,
+  cursorTo,
   deviceBounds,
   devicePreset,
   deviceScreen,
   deviceScreenCenter,
+  deviceScreenPoint,
   ellipse,
   evaluate,
   figure,

package/dist/labels.js

@@ -134,6 +134,14 @@ function compileScene(ir) {
       }
     }
   }
+  const cameraIsNode = nodeById.has("camera");
+  if (!cameraIsNode) {
+    const cam = ir.camera ?? {};
+    initialValues.set(key("camera", "x"), cam.x ?? ir.size.width / 2);
+    initialValues.set(key("camera", "y"), cam.y ?? ir.size.height / 2);
+    initialValues.set(key("camera", "zoom"), cam.zoom ?? 1);
+    initialValues.set(key("camera", "rotation"), cam.rotation ?? 0);
+  }
   const segments = /* @__PURE__ */ new Map();
   const motionPaths = /* @__PURE__ */ new Map();
   const current = new Map(initialValues);
@@ -294,6 +302,7 @@ function compileScene(ir) {
   const inferredEnd = ir.timeline ? walk(ir.timeline, 0) : 0;
   for (const list of segments.values()) list.sort((a, b) => a.t0 - b.t0);
   for (const list of motionPaths.values()) list.sort((a, b) => a.t0 - b.t0);
+  const hasCamera = !cameraIsNode && (ir.camera !== void 0 || motionPaths.has("camera") || [...segments.keys()].some((k) => k.startsWith("camera.")));
   return {
     ir,
     duration: ir.duration ?? inferredEnd,
@@ -303,17 +312,19 @@ function compileScene(ir) {
     nodeById,
     nodeOrder,
     labelTimes,
-    beatTimes
+    beatTimes,
+    hasCamera
   };
 }
 
 // ../core/src/validate.ts
-var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "anchor"];
+var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "anchor", "fixed"];
+var CAMERA_PROPS = ["x", "y", "zoom", "rotation"];
 var PROPS_BY_TYPE = {
   rect: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth", "radius"],
   ellipse: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth"],
   line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress"],
-  text: [...COMMON_PROPS, "content", "contentDecimals", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
+  text: [...COMMON_PROPS, "content", "contentDecimals", "contentThousands", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
   image: [...COMMON_PROPS, "src", "width", "height"],
   path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
   group: COMMON_PROPS
@@ -352,6 +363,14 @@ function validateScene(ir) {
   };
   collect(ir.nodes);
   const checkProps = (where, nodeId, props) => {
+    if (nodeId === "camera" && !nodeById.has("camera")) {
+      for (const key2 of Object.keys(props)) {
+        if (!CAMERA_PROPS.includes(key2)) {
+          problems.push(`${where}: "${key2}" is not a camera prop \u2014 valid props: ${CAMERA_PROPS.join(", ")}`);
+        }
+      }
+      return;
+    }
     const node = nodeById.get(nodeId);
     if (!node) {
       problems.push(
@@ -419,12 +438,15 @@ function validateScene(ir) {
         break;
       case "motionPath": {
         const node = nodeById.get(tl.target);
-        if (!node) {
-          problems.push(
-            `${path3}: motionPath targets unknown node "${tl.target}" \u2014 known ids: ${[...nodeById.keys()].join(", ")}`
-          );
-        } else if (node.type === "line") {
-          problems.push(`${path3}: motionPath cannot target a line (no x/y) \u2014 "${tl.target}"`);
+        const isSceneCamera = tl.target === "camera" && !node;
+        if (!isSceneCamera) {
+          if (!node) {
+            problems.push(
+              `${path3}: motionPath targets unknown node "${tl.target}" \u2014 known ids: ${[...nodeById.keys()].join(", ")}`
+            );
+          } else if (node.type === "line") {
+            problems.push(`${path3}: motionPath cannot target a line (no x/y) \u2014 "${tl.target}"`);
+          }
         }
         if (tl.points.length < 1) problems.push(`${path3}: motionPath "${tl.target}" needs at least 1 point`);
         if (tl.duration !== void 0 && tl.duration <= 0) {
@@ -469,6 +491,18 @@ function validateScene(ir) {
   if (ir.duration !== void 0 && ir.duration <= 0) {
     problems.push("scene duration must be > 0");
   }
+  if (ir.camera) {
+    if (nodeById.has("camera")) {
+      problems.push(`camera: a node is already named "camera" \u2014 rename that node or drop the scene camera (the id "camera" can't be both)`);
+    }
+    for (const [key2, value] of Object.entries(ir.camera)) {
+      if (!CAMERA_PROPS.includes(key2)) {
+        problems.push(`camera: "${key2}" is not a camera prop \u2014 valid props: ${CAMERA_PROPS.join(", ")}`);
+      } else if (typeof value !== "number") {
+        problems.push(`camera.${key2} must be a number`);
+      }
+    }
+  }
   const SFX_NAMES = ["whoosh", "pop", "tick", "rise", "shimmer", "thud"];
   for (const [i, cue] of (ir.audio?.cues ?? []).entries()) {
     if (typeof cue.at === "string" && !labels.has(cue.at)) {

package/dist/player.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env tsx
+
+// ../render-cli/src/player.ts
+import { build } from "esbuild";
+import { mkdir, writeFile, readFile } from "node:fs/promises";
+import { basename, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+var PACKAGED = true;
+var HERE = dirname(fileURLToPath(import.meta.url));
+var CORE = PACKAGED ? resolve(HERE, "index.js") : resolve(HERE, "..", "..", "core", "src", "index.ts");
+var RENDERER = PACKAGED ? resolve(HERE, "renderer-canvas.js") : resolve(HERE, "..", "..", "renderer-canvas", "src", "index.ts");
+var FONTS = PACKAGED ? resolve(HERE, "..", "assets", "fonts") : resolve(HERE, "..", "..", "..", "assets", "fonts");
+async function fontFace(weight) {
+  try {
+    const b64 = (await readFile(resolve(FONTS, `inter-${weight}.woff2`))).toString("base64");
+    return `@font-face{font-family:Inter;font-style:normal;font-weight:${weight};font-display:block;src:url(data:font/woff2;base64,${b64}) format('woff2')}`;
+  } catch {
+    return "";
+  }
+}
+async function main() {
+  const [scenePath, outPath] = process.argv.slice(2);
+  if (!scenePath || !outPath) {
+    console.error("usage: player <scene.ts|.json> <out.html>");
+    process.exit(2);
+  }
+  const entry = `
+import { compileScene } from "@reframe/core";
+import { renderFrame } from "@reframe/renderer-canvas";
+import sceneIR from ${JSON.stringify(scenePath)};
+const compiled = compileScene(sceneIR);
+const canvas = document.getElementById("c");
+const ctx = canvas.getContext("2d");
+canvas.width = sceneIR.size.width;
+canvas.height = sceneIR.size.height;
+const dur = compiled.duration || 1;
+function frame(now){ renderFrame(ctx, compiled, (now / 1000) % dur); requestAnimationFrame(frame); }
+const ff = document.fonts;
+if (ff && ff.ready) ff.ready.then(() => requestAnimationFrame(frame));
+else requestAnimationFrame(frame);
+`;
+  let bundle;
+  try {
+    bundle = await build({
+      stdin: { contents: entry, resolveDir: dirname(scenePath), loader: "ts" },
+      bundle: true,
+      format: "iife",
+      platform: "browser",
+      target: "es2022",
+      write: false,
+      logLevel: "silent",
+      alias: { "@reframe/core": CORE, "@reframe/renderer-canvas": RENDERER, "reframe-video": CORE }
+    });
+  } catch (err) {
+    console.error(`failed to bundle ${scenePath}:
+${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+  const js = bundle.outputFiles[0].text;
+  const faces = (await Promise.all([400, 700, 800].map(fontFace))).join("");
+  const html = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>${basename(scenePath)} \xB7 reframe</title>
+<style>${faces}
+html,body{margin:0;height:100%;background:#06070b;display:grid;place-items:center;font-family:Inter,system-ui}
+canvas{max-width:94vw;max-height:94vh;border-radius:16px;box-shadow:0 24px 90px rgba(0,0,0,.55)}</style></head>
+<body><canvas id="c"></canvas><script>${js}</script></body></html>`;
+  await mkdir(dirname(outPath), { recursive: true });
+  await writeFile(outPath, html);
+  console.log(outPath);
+}
+void main();

package/dist/trace-cli.js

@@ -6,12 +6,12 @@ import { resolve as resolve2 } from "node:path";
 import { pathToFileURL } from "node:url";
 
 // ../core/src/validate.ts
-var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "anchor"];
+var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "anchor", "fixed"];
 var PROPS_BY_TYPE = {
   rect: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth", "radius"],
   ellipse: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth"],
   line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress"],
-  text: [...COMMON_PROPS, "content", "contentDecimals", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
+  text: [...COMMON_PROPS, "content", "contentDecimals", "contentThousands", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
   image: [...COMMON_PROPS, "src", "width", "height"],
   path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
   group: COMMON_PROPS

package/dist/types/camera.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The scene camera — a single affine viewport applied to the whole scene.
+ *
+ * Semantics (look-at): `camera.{x,y}` is the scene point centered in frame,
+ * `zoom` scales about it, `rotation` (degrees) turns about it. Defaults
+ * (`x=W/2, y=H/2, zoom=1, rotation=0`) are the identity, so a scene without a
+ * camera renders byte-identically.
+ *
+ * The camera is animated through the SAME machinery as nodes: tween / motionPath /
+ * behaviors targeting the reserved id `"camera"` with props x/y/zoom/rotation.
+ * `cameraTo` is a thin readable wrapper. Because those are ordinary labeled
+ * timeline steps, camera keyframes are overlay-addressable for free, so human
+ * edits survive AI regeneration.
+ */
+import type { CameraIR, Ease, Size, TimelineIR } from "./ir.js";
+import type { Mat2D } from "./evaluate.js";
+/** Reserved timeline/behavior target id for the camera. */
+export declare const CAMERA_ID = "camera";
+/** The animatable camera props (look-at point + zoom + rotation). */
+export declare const CAMERA_PROPS: readonly ["x", "y", "zoom", "rotation"];
+/**
+ * The camera's affine matrix: `T(W/2,H/2) · R(rotation) · S(zoom) · T(-x,-y)`,
+ * i.e. center the focal point, then zoom/rotate about the frame centre. Defaults
+ * collapse to the identity.
+ */
+export declare function cameraMatrix(cam: CameraIR, size: Size): Mat2D;
+/** Keyframe the camera: a `tween` on the reserved "camera" target. */
+export declare function cameraTo(props: CameraIR, opts?: {
+    duration?: number;
+    ease?: Ease;
+    label?: string;
+}): TimelineIR;

package/dist/types/compile.d.ts

@@ -49,5 +49,7 @@ export interface CompiledScene {
     labelTimes: Map<string, LabelSpan>;
     /** The subset of label spans that come from beat nodes — keyed by beat name. */
     beatTimes: Map<string, LabelSpan>;
+    /** True iff the scene declares or animates a `camera` (gates the camera matrix). */
+    hasCamera: boolean;
 }
 export declare function compileScene(ir: SceneIR): CompiledScene;

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/dsl.d.ts

@@ -2,7 +2,7 @@
  * The eDSL surface: thin factories that build plain IR objects.
  * `scene()` validates and returns the IR — the return value is the document.
  */
-import type { AudioIR, BehaviorIR, CompositionIR, CompositionSceneEntry, Ease, EllipseProps, GroupProps, ImageProps, LineProps, NodeIR, PathProps, PropValue, RectProps, SceneIR, Size, StateOverride, TextProps, TimelineIR } from "./ir.js";
+import type { AudioIR, BehaviorIR, CameraIR, CompositionIR, CompositionSceneEntry, Ease, EllipseProps, GroupProps, ImageProps, LineProps, NodeIR, PathProps, PropValue, RectProps, SceneIR, Size, StateOverride, TextProps, TimelineIR } from "./ir.js";
 export interface SceneInput {
     id: string;
     size: Size;
@@ -10,6 +10,7 @@ export interface SceneInput {
     duration?: number;
     background?: string;
     nodes: NodeIR[];
+    camera?: CameraIR;
     states?: Record<string, StateOverride>;
     initial?: string;
     timeline?: TimelineIR;

package/dist/types/index.d.ts

@@ -5,8 +5,10 @@ export { compileComposition, type CompiledComposition, type ScenePlacement, } fr
 export { composeScene, formatComposeReport, type OverlayDoc, type ComposeReport, } from "./compose.js";
 export { compileScene, type CompiledScene, type PropertySegment, type LabelSpan, type MotionDriver } from "./compile.js";
 export { pathPoint, pathTangentAngle, type Pt } from "./path.js";
+export { cameraTo, cameraMatrix, CAMERA_ID, CAMERA_PROPS } from "./camera.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/dist/types/ir.d.ts

@@ -31,6 +31,11 @@ export interface BaseProps {
     skewX?: number;
     skewY?: number;
     anchor?: Anchor;
+    /**
+     * Pin a TOP-LEVEL node to the screen so the scene `camera` does not move it —
+     * for HUD / titles / watermark layers. No-op when the scene has no camera.
+     */
+    fixed?: boolean;
 }
 export interface RectProps extends BaseProps {
     width: number;
@@ -57,12 +62,16 @@ export interface LineProps {
     opacity?: number;
     /** 0..1 — how much of the line is drawn (for draw-on effects). */
     progress?: number;
+    /** Pin to the screen so the scene `camera` does not move it (top-level only). */
+    fixed?: boolean;
 }
 export interface TextProps extends BaseProps {
     /** Numbers interpolate (count-up) and render via toFixed(contentDecimals). */
     content: string | number;
     /** Decimal places when content is numeric (default 0). */
     contentDecimals?: number;
+    /** Group the integer part with thousands separators (e.g. 35,786). */
+    contentThousands?: boolean;
     fontFamily: string;
     fontSize: number;
     fontWeight?: number;
@@ -302,6 +311,19 @@ export interface AudioIR {
     };
     cues?: AudioCueIR[];
 }
+/**
+ * The scene camera: a viewport over the whole scene. `(x,y)` is the scene point
+ * centered in frame (defaults to the frame centre), `zoom` scales about it,
+ * `rotation` (degrees) turns about it. Defaults (`x=W/2, y=H/2, zoom=1, rotation=0`)
+ * are the identity. Animate it by tweening the reserved target `"camera"`
+ * (or the `cameraTo` helper); pin layers out of it with a node's `fixed` flag.
+ */
+export interface CameraIR {
+    x?: number;
+    y?: number;
+    zoom?: number;
+    rotation?: number;
+}
 export interface SceneIR {
     version: 1;
     id: string;
@@ -312,6 +334,8 @@ export interface SceneIR {
     duration?: number;
     background?: string;
     nodes: NodeIR[];
+    /** A viewport over the scene, keyframable via the reserved target "camera". */
+    camera?: CameraIR;
     states?: Record<string, StateOverride>;
     /** State applied at t=0. */
     initial?: string;

package/guides/edsl-guide.md

@@ -121,6 +121,35 @@ bound — e.g. a pulse only during the hold:
 `oscillate("title", "scale", { amplitude: 0.04, frequency: 1.2 }, { from: 1.5, until: 3.5 })`.
 Omit the window to run for the whole scene.
 
+## Camera (one keyframable viewport)
+
+A scene-level camera moves the whole scene at once: a look-at point + zoom +
+rotation, animated over the timeline. Add it as a top-level `camera` field and
+keyframe it with `cameraTo` (or by tweening the reserved target `"camera"`):
+
+```ts
+scene({
+  // ...
+  camera: { x: W/2, y: H/2, zoom: 1, rotation: 0 }, // (x,y) = scene point centred in frame; defaults = frame centre, zoom 1, rot 0 (= no camera)
+  timeline: seq(
+    cameraTo({ x: 300, y: 400, zoom: 4 }, { duration: 1.5, ease: "easeInOutCubic", label: "push-in" }), // zoom into a detail
+    cameraTo({ x: 800, y: 200, zoom: 2, rotation: -5 }, { duration: 1.2 }),                              // pan + slight bank
+    cameraTo({ x: W/2, y: H/2, zoom: 1, rotation: 0 }, { duration: 1.6 }),                               // pull back
+  ),
+})
+```
+
+- `cameraTo(props, { duration?, ease?, label? })` keyframes the camera; it is a
+  `tween` on the `"camera"` target, so `motionPath("camera", pts, …)` (pan along
+  a curve) and `oscillate/wiggle("camera", "rotation"|"x"|…)` (handheld drift)
+  also work.
+- **Pin HUD/titles to the screen** with `fixed: true` on a TOP-LEVEL node — the
+  camera won't move it (for overlays, watermarks, captions).
+- Defaults are the identity, so a scene without a camera is unchanged. Don't name
+  a node `"camera"` if you use the scene camera (the id can't be both).
+
+See `examples/scenes/camera-demo.ts`.
+
 ## Character rig (skeleton, poses, IK)
 
 A first-class, declarative character rig that **compiles to plain IR** (nested
@@ -199,6 +228,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.6.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",