reframe-video 0.5.0 → 0.6.1

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

@@ -4,7 +4,7 @@
  * always. Renderers only draw; they never compute animation.
  */
 import type { CompiledScene } from "./compile.js";
-import type { ClipShape, PropValue } from "./ir.js";
+import type { ClipShape, Paint, PropValue } from "./ir.js";
 /** Canvas-style 2D affine matrix [a, b, c, d, e, f]. */
 export type Mat2D = [number, number, number, number, number, number];
 /** A clip from an ancestor group: its shape in the group's coordinate space,
@@ -31,8 +31,8 @@ export type DisplayOp = (OpBase & {
     height: number;
     offsetX: number;
     offsetY: number;
-    fill?: string;
-    stroke?: string;
+    fill?: Paint;
+    stroke?: Paint;
     strokeWidth?: number;
     radius?: number;
 }) | (OpBase & {
@@ -41,8 +41,8 @@ export type DisplayOp = (OpBase & {
     height: number;
     offsetX: number;
     offsetY: number;
-    fill?: string;
-    stroke?: string;
+    fill?: Paint;
+    stroke?: Paint;
     strokeWidth?: number;
 }) | (OpBase & {
     type: "line";
@@ -76,9 +76,11 @@ export type DisplayOp = (OpBase & {
     d: string;
     /** 0..1 fraction of the stroke outline drawn (draw-on). */
     progress: number;
-    fill?: string;
-    stroke?: string;
+    fill?: Paint;
+    stroke?: Paint;
     strokeWidth?: number;
+    /** Local-space bbox [x,y,w,h] for mapping a gradient paint (set only when one is used). */
+    bbox?: [number, number, number, number];
 });
 export type DisplayList = DisplayOp[];
 /**

package/dist/types/gradient.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Gradient paints — the structured alternative to a solid color `fill`/`stroke`.
+ *
+ * Coordinates are normalized to the node's bounding box (0..1), so a gradient is
+ * just an angle + color stops, independent of the node's size. The renderer maps
+ * 0..1 → the node's local box and the paint is applied in node-local space, so
+ * rotating/scaling the NODE moves the gradient with it (the "animated gradient"
+ * idiom — gradients themselves are static this version). Pure + deterministic.
+ */
+import type { ColorStop, Gradient, Paint } from "./ir.js";
+/** True when a paint is a gradient object (vs a plain color string). */
+export declare function isGradient(p: Paint | undefined): p is Gradient;
+/** A linear gradient. `angle` in degrees: 0 = left→right, 90 = top→bottom. */
+export declare function linearGradient(stops: (string | ColorStop)[], opts?: {
+    angle?: number;
+}): Gradient;
+/** A radial gradient. `cx/cy` centre (0..1 of the box, default 0.5), `r` radius (0..1, default 0.5). */
+export declare function radialGradient(stops: (string | ColorStop)[], opts?: {
+    cx?: number;
+    cy?: number;
+    r?: number;
+}): Gradient;
+/** A conic (angular sweep) gradient. `angle` start in degrees, `cx/cy` centre (0..1). */
+export declare function conicGradient(stops: (string | ColorStop)[], opts?: {
+    angle?: number;
+    cx?: number;
+    cy?: number;
+}): Gradient;

package/dist/types/index.d.ts

@@ -5,6 +5,8 @@ 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 { linearGradient, radialGradient, conicGradient, isGradient } from "./gradient.js";
 export { motionPreset, PRESET_NAMES, type PresetName, type PresetRig, type PresetOpts } from "./presets.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";

package/dist/types/ir.d.ts

@@ -31,20 +31,54 @@ 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;
+}
+/**
+ * A paint is a solid color string OR a gradient. Coordinates are normalized to the
+ * node's bounding box (0..1, SVG `objectBoundingBox` style) so a gradient is just an
+ * angle + stops, size-independent. Applied in node-local space, so animating the
+ * node's transform (rotation/scale) moves the gradient with it. Build with
+ * `linearGradient`/`radialGradient`/`conicGradient` (`gradient.ts`).
+ */
+export interface ColorStop {
+    offset: number;
+    color: string;
 }
+export type Gradient = {
+    kind: "linear";
+    angle?: number;
+    stops: ColorStop[];
+} | {
+    kind: "radial";
+    cx?: number;
+    cy?: number;
+    r?: number;
+    stops: ColorStop[];
+} | {
+    kind: "conic";
+    angle?: number;
+    cx?: number;
+    cy?: number;
+    stops: ColorStop[];
+};
+export type Paint = string | Gradient;
 export interface RectProps extends BaseProps {
     width: number;
     height: number;
-    fill?: string;
-    stroke?: string;
+    fill?: Paint;
+    stroke?: Paint;
     strokeWidth?: number;
     radius?: number;
 }
 export interface EllipseProps extends BaseProps {
     width: number;
     height: number;
-    fill?: string;
-    stroke?: string;
+    fill?: Paint;
+    stroke?: Paint;
     strokeWidth?: number;
 }
 export interface LineProps {
@@ -57,12 +91,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;
@@ -95,8 +133,8 @@ export interface GroupProps extends BaseProps {
 export interface PathProps extends BaseProps {
     /** SVG path data (the `d` attribute). Drawn as a true vector — crisp at any zoom. */
     d: string;
-    fill?: string;
-    stroke?: string;
+    fill?: Paint;
+    stroke?: Paint;
     strokeWidth?: number;
     /**
      * 0..1 — fraction of the OUTLINE drawn, for a self-drawing "draw-on" effect
@@ -302,6 +340,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 +363,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/dist/types/path.d.ts

@@ -9,6 +9,12 @@
  * spacing ever overshoots.
  */
 export type Pt = [number, number];
+/**
+ * A loose bounding box `[x, y, w, h]` from a path `d`'s coordinate extents — used
+ * only to map a gradient across the shape. Exact for M/L/C/Q/S/T paths (every
+ * number is an x/y coord, control points included); loose for the rare H/V/A.
+ */
+export declare function pathBBox(d: string): [number, number, number, number];
 /**
  * Position on the spline at progress u in [0,1]. `curviness` scales the
  * Catmull-Rom tangents (GSAP's idea): 1 = standard smooth (the default and the

package/guides/edsl-guide.md

@@ -121,6 +121,57 @@ 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`.
+
+## Gradients (fill / stroke)
+
+`fill` and `stroke` on **rect / ellipse / path** accept a gradient as well as a
+color string. Coordinates are normalized to the node's bounding box (0..1), so a
+gradient is just an angle + stops:
+
+```ts
+rect({ id: "card", x, y, width: 300, height: 300, anchor: "center",
+  fill: linearGradient(["#FF5C3A", "#FFC24B"], { angle: 60 }) })   // 0=L→R, 90=T→B
+ellipse({ id: "orb", /* … */ fill: radialGradient(["#9B7CFF", "#221A4A"], { cx: 0.4, cy: 0.4, r: 0.6 }) })
+path({ id: "star", d, fill: conicGradient(["#00C2A8", "#3AA0FF", "#7C5CFF", "#00C2A8"], { angle: -90 }) })
+ellipse({ id: "ring", /* … */ fill: "none", stroke: linearGradient(["#3AA0FF", "#46E5A0"]), strokeWidth: 10 })
+```
+
+- `linearGradient(stops, { angle })`, `radialGradient(stops, { cx, cy, r })`,
+  `conicGradient(stops, { angle, cx, cy })`. `stops` is a color array (even offsets)
+  or `[{ offset, color }]`. `cx/cy/r` are 0..1 of the box (centre defaults to 0.5).
+- **Gradients are static** (not keyframed). The gradient lives in the node's local
+  space, so **animate the NODE** (`tween(id, { rotation: 360 })`, scale, move) and the
+  gradient sweeps/stretches with it. Color-string fills still tween as today.
+- text fill and line stroke are color-only for now. See `examples/scenes/gradient-demo.ts`.
+
 ## Character rig (skeleton, poses, IK)
 
 A first-class, declarative character rig that **compiles to plain IR** (nested

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reframe-video",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "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",