reframe-video 0.1.3 → 0.3.0

package/dist/types/characterPreset.d.ts

@@ -0,0 +1,39 @@
+/**
+ * characterPreset — a SEEDED motion generator for the humanoid rig. The
+ * character analog of `motionPreset`: `characterPreset(name, opts)` returns a
+ * `beat` (a TimelineIR) that drives a `humanoid()` rig's joints through a named
+ * performance (walk/run/jump/dance/wave/cheer). Same `(name, knobs, seed)` →
+ * identical IR; a different `seed` varies it within the family.
+ *
+ *   seq(characterPreset("walk", { target: "hero", at: [CX, BASE_Y], cycles: 4 }))
+ *
+ * Pure keyframe timeline (a beat can't hold behaviors): secondary motion is
+ * baked into poses; continuous idle stays the author's `oscillate`. Legs use the
+ * 2-bone `ikReach` solver (foot targets relative to the hip → natural knee bend);
+ * arms swing via FK. Assumes the `humanoid()` joint names.
+ */
+import type { TimelineIR } from "./ir.js";
+export declare const CHARACTER_PRESET_NAMES: readonly ["walk", "run", "jump", "dance", "wave", "cheer"];
+export type CharacterPresetName = (typeof CHARACTER_PRESET_NAMES)[number];
+export interface CharacterPresetOpts {
+    /** humanoid rig id — joints are `${target}-${name}`, outer group = `${target}`. */
+    target: string;
+    /** 0..1 — stride / swing / bounce / jump-height amplitude (default 0.5). */
+    energy?: number;
+    /** >0 — tempo; durations divide by it (default 1, min 0.25). */
+    speed?: number;
+    /** Deterministic within-family variation (default 0). */
+    seed?: number;
+    /** Repeats for cyclic motions walk/run/dance (default 4). */
+    cycles?: number;
+    /** 1 = faces/moves right (default 1). */
+    facing?: 1 | -1;
+    /** The rig's scene position — needed to translate the body (walk travel, jump lift). Default [0,0]. */
+    at?: [number, number];
+    /** px travelled per cycle for walk/run (default ~stride·2; 0 = walk in place). */
+    travel?: number;
+    /** Override the beat name (overlay address) — set this when the same preset is
+     * used more than once in a scene so the beat labels stay unique. */
+    label?: string;
+}
+export declare function characterPreset(name: CharacterPresetName, opts: CharacterPresetOpts): TimelineIR;

package/dist/types/compile.d.ts

@@ -25,6 +25,7 @@ export interface MotionDriver {
     ease?: Ease;
     points: [number, number][];
     closed: boolean;
+    curviness: number;
     autoRotate: boolean;
     rotateOffset: number;
 }

package/dist/types/compose.d.ts

@@ -8,7 +8,7 @@
  * validation errors on the composed result. Silent failure is the one
  * behavior this module must never have.
  */
-import type { BehaviorIR, Ease, NodeIR, PropValue, SceneIR } from "./ir.js";
+import type { BehaviorIR, Ease, NodeIR, PropValue, SceneIR, TimelineIR } from "./ir.js";
 export interface OverlayDoc {
     reframeOverlay: 1;
     /** Shown in reports; falls back to "overlay-<index>". */
@@ -34,6 +34,20 @@ export interface OverlayDoc {
     };
     /** Complete nodes appended at the scene root, owned by this overlay. */
     addNodes?: NodeIR[];
+    /**
+     * Remove nodes by id. Only nodes added by an overlay (via `addNodes`) can be
+     * removed — a node owned by the BASE scene is refused and reported as an
+     * orphan (hide it with `opacity: 0` instead, so the regenerated design is
+     * never silently dropped). An unknown id is likewise an orphan.
+     */
+    removeNodes?: string[];
+    /**
+     * Motion fragments (e.g. `motionOp(...)` beats) APPENDED to the scene
+     * timeline — composed in `par` with the base under their own beat labels, so
+     * the editor can ADD motion to a node, not just patch existing motion. A
+     * fragment whose target id is gone is skipped and reported as an orphan.
+     */
+    addTimeline?: TimelineIR[];
     /**
      * Parameter patches on labeled timeline steps (or beats by name). Patchable
      * per kind: to -> duration/ease/stagger, tween -> duration/ease,
@@ -52,13 +66,15 @@ export interface OverlayDoc {
         scale?: number;
         order?: number;
         points?: [number, number][];
+        curviness?: number;
+        autoRotate?: boolean;
     }>;
 }
 export interface ComposeReport {
     applied: {
         layer: string;
         address: string;
-        action: "set" | "unset" | "add-node" | "behavior-set" | "behavior-remove";
+        action: "set" | "unset" | "add-node" | "remove-node" | "behavior-set" | "behavior-remove" | "add-timeline";
     }[];
     orphans: {
         layer: string;

package/dist/types/composeComposition.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Composition layout: place each scene on a single timeline and report the
+ * total duration. Pure data in, pure data out — like compileScene, this never
+ * renders. Each scene is compiled independently (compileScene), so a scene's
+ * frames inside a composition equal rendering it alone, offset by its `start`.
+ */
+import { type CompiledScene } from "./compile.js";
+import { type CompositionIR, type SceneIR, type SceneTransition } from "./ir.js";
+export interface ScenePlacement {
+    id: string;
+    scene: SceneIR;
+    compiled: CompiledScene;
+    /** Absolute start on the composition timeline (s). */
+    start: number;
+    /** The scene's own duration (s). */
+    duration: number;
+    transition: SceneTransition;
+    /** Overlap with the previous scene (s); 0 for a cut. */
+    overlap: number;
+}
+export interface CompiledComposition {
+    ir: CompositionIR;
+    scenes: ScenePlacement[];
+    /** Total composition duration (s) — the end of the last scene. */
+    duration: number;
+}
+export declare function compileComposition(comp: CompositionIR): CompiledComposition;

package/dist/types/devicePreset.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Device-mockup presets: a parametric vector frame (phone/laptop/browser/…) with
+ * a CLIPPED screen "content slot". The sibling of motionPreset — that generates
+ * a TimelineIR, this generates a NodeIR subtree. Pure primitives + clip, so no
+ * assets and fully deterministic (plain JSON, no Date/random). A 2.5D vector
+ * tier — no true perspective.
+ *
+ *   devicePreset("phone", { id: "hero", content: [ ...your UI nodes ] })
+ *
+ * Each instance needs a distinct `id` (it prefixes every generated node id);
+ * two with the same prefix collide via the scene's duplicate-id validation.
+ *
+ * Layout/teardown helpers: `deviceScreen` (content-local screen bounds),
+ * `deviceScreenCenter` (device-local screen origin — slide `${id}-screen` against
+ * it to eject the panel for an exploded view), `deviceBounds` (full frame
+ * footprint — for laying many devices on a grid).
+ */
+import type { NodeIR } from "./ir.js";
+export declare const DEVICE_PRESET_NAMES: readonly ["phone", "tablet", "laptop", "browser", "watch", "monitor", "tv", "foldable", "terminal", "car"];
+export type DevicePresetName = (typeof DEVICE_PRESET_NAMES)[number];
+export interface DevicePresetOpts {
+    /** Id PREFIX for every generated node (default "device"). Make it unique per instance. */
+    id?: string;
+    /** Device-center placement (default 0,0). */
+    x?: number;
+    y?: number;
+    /** Uniform scale (default 1). */
+    scale?: number;
+    /** Outer-group opacity (default 1) — handy to start hidden for an entrance. */
+    opacity?: number;
+    /** Body palette (default "dark"). */
+    color?: "dark" | "light";
+    /** Screen background fill override (default per palette). */
+    screen?: string;
+    /** Portrait/landscape — phone & tablet only (default "portrait"). */
+    orientation?: "portrait" | "landscape";
+    /** Nodes placed inside the screen (authored in screen-LOCAL centre coords), clipped. */
+    content?: NodeIR[];
+    /** Browser/terminal address-bar text. */
+    url?: string;
+}
+/** The screen's content area (content-local coords: origin 0,0 = screen centre,
+ *  pre-scale). Author/scroll `content` against these bounds. */
+export declare function deviceScreen(name: DevicePresetName, opts?: DevicePresetOpts): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    radius: number;
+};
+/** The screen group's centre in device-LOCAL coords. Slide `${id}-screen` against
+ *  this (e.g. `y: deviceScreenCenter(name).y + 160`) to eject the panel from the
+ *  frame for an exploded / teardown view. */
+export declare function deviceScreenCenter(name: DevicePresetName, opts?: DevicePresetOpts): {
+    x: number;
+    y: number;
+};
+/** Full frame footprint (width/height incl. chrome & stands) in device-local
+ *  units — use it to scale many devices onto a shared grid. */
+export declare function deviceBounds(name: DevicePresetName, opts?: DevicePresetOpts): {
+    width: number;
+    height: 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, Ease, EllipseProps, GroupProps, ImageProps, LineProps, NodeIR, PathProps, PropValue, RectProps, SceneIR, Size, StateOverride, TextProps, TimelineIR } from "./ir.js";
+import type { AudioIR, BehaviorIR, 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;
@@ -18,6 +18,14 @@ export interface SceneInput {
     meta?: Record<string, unknown>;
 }
 export declare function scene(input: SceneInput): SceneIR;
+export interface CompositionInput {
+    id: string;
+    scenes: CompositionSceneEntry[];
+    audio?: AudioIR;
+    meta?: Record<string, unknown>;
+}
+/** Build a composition: an ordered list of independent scenes + transitions. */
+export declare function composition(input: CompositionInput): CompositionIR;
 export declare function rect(props: {
     id: string;
 } & RectProps): NodeIR;
@@ -43,6 +51,8 @@ export declare function seq(...children: TimelineIR[]): TimelineIR;
 export declare function par(...children: TimelineIR[]): TimelineIR;
 export declare function stagger(interval: number, ...children: TimelineIR[]): TimelineIR;
 export interface BeatOpts {
+    /** Node ids this beat owns (the intent graph) — additive metadata only. */
+    nodes?: string[];
     /** Group children in parallel instead of sequence. */
     parallel?: boolean;
     /** Absolute start (rigid placement). */
@@ -74,6 +84,7 @@ export declare function motionPath(target: string, points: [number, number][], o
     duration?: number;
     ease?: Ease;
     closed?: boolean;
+    curviness?: number;
     autoRotate?: boolean;
     rotateOffset?: number;
     label?: string;

package/dist/types/evaluate.d.ts

@@ -4,8 +4,15 @@
  * always. Renderers only draw; they never compute animation.
  */
 import type { CompiledScene } from "./compile.js";
+import type { ClipShape, 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,
+ *  plus the matrix mapping that space to the scene. The renderer intersects it. */
+export interface ClipRegion {
+    transform: Mat2D;
+    shape: ClipShape;
+}
 export type TextAlign = "left" | "center" | "right";
 export type TextBaseline = "top" | "middle" | "bottom";
 interface OpBase {
@@ -15,6 +22,8 @@ interface OpBase {
     transform: Mat2D;
     /** Cumulative opacity, parent-multiplied. */
     opacity: number;
+    /** Clip regions from ancestor groups (intersected by the renderer). */
+    clips?: ClipRegion[];
 }
 export type DisplayOp = (OpBase & {
     type: "rect";
@@ -72,5 +81,28 @@ export type DisplayOp = (OpBase & {
     strokeWidth?: number;
 });
 export type DisplayList = DisplayOp[];
+/**
+ * The node's local affine matrix: Translate(x,y) ∘ Rotate ∘ Skew ∘ Scale, around
+ * the anchor. `scaleX/scaleY` are per-axis multipliers on `scale`; `skewX/skewY`
+ * are shear angles in degrees (a 2.5D "tilt" — no true perspective). The fast
+ * path returns the exact uniform formula at defaults, so existing scenes stay
+ * byte-identical (the determinism/golden contract).
+ */
+export declare function localMatrix(x: number, y: number, rotationDeg: number, scale: number, scaleX?: number, scaleY?: number, skewXDeg?: number, skewYDeg?: number): Mat2D;
+/**
+ * Sample one node prop at time t — the single source of animated values shared
+ * by `evaluate` (rendering) and `nodeParentMatrix` (editor hit/drag math), so
+ * both agree to the last bit. Pure; the determinism contract rests on it.
+ */
+export declare function sampleProp(compiled: CompiledScene, t: number, target: string, prop: string, fallback: PropValue): PropValue;
+/**
+ * The accumulated transform of a node's ANCESTORS at time t — the coordinate
+ * space its `x/y` live in (identity for a top-level node). The editor inverts
+ * this to convert a scene-space drag delta into the node's parent space, so a
+ * nested child can be dragged and the overlay still writes `nodes.<id>.x/y`.
+ * Walks groups exactly as `evaluate` does (same sampler, no opacity culling so
+ * an invisible-at-t node is still positionable). Returns null if id is unknown.
+ */
+export declare function nodeParentMatrix(compiled: CompiledScene, id: string, t: number): Mat2D | null;
 export declare function evaluate(compiled: CompiledScene, t: number): DisplayList;
 export {};

package/dist/types/figure.d.ts

@@ -0,0 +1,32 @@
+/**
+ * figure() — a parametric DRESSED character, the sibling of `humanoid()`. Same
+ * skeleton geometry (so `characterPreset` / `ikReach` / overlays apply unchanged),
+ * but each bone carries a coloured, designed flat shape instead of a neon capsule.
+ * Two styles — `clean` (corporate-flat, undraw register: one accent + neutrals,
+ * minimal face, slim adult proportions) and `cute` (mascot: big head, full face).
+ * Palette knobs re-skin it in one line; shadows are derived so a single `accent`
+ * recolours the whole figure.
+ *
+ *   figure({ id: "fig", style: "clean", palette: { accent: "#3B82F6" } })
+ *   characterPreset("walk", { target: "fig", at: [x, y] })   // drives it
+ */
+import type { NodeIR } from "./ir.js";
+import { type RigOpts } from "./rig.js";
+export type FigureStyle = "clean" | "cute";
+export interface FigurePalette {
+    skin?: string;
+    hair?: string;
+    top?: string;
+    pants?: string;
+    shoe?: string;
+    accent?: string;
+}
+export interface FigureOpts extends RigOpts {
+    /** "clean" (corporate-flat, default) | "cute" (mascot). */
+    style?: FigureStyle;
+    /** Colour overrides merged onto the per-style defaults. */
+    palette?: FigurePalette;
+    /** Draw minimal facial features (default true). `false` = faceless (pure undraw). */
+    face?: boolean;
+}
+export declare function figure(opts?: FigureOpts): NodeIR;

package/dist/types/index.d.ts

@@ -1,12 +1,18 @@
 export * from "./ir.js";
 export * from "./dsl.js";
-export { validateScene, SceneValidationError, PROPS_BY_TYPE } from "./validate.js";
+export { validateScene, validateComposition, SceneValidationError, PROPS_BY_TYPE } from "./validate.js";
+export { compileComposition, type CompiledComposition, type ScenePlacement, } from "./composeComposition.js";
 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 { motionPreset, PRESET_NAMES, type PresetName, type PresetRig, type PresetOpts } from "./presets.js";
-export { resolveAudioPlan, SFX_DURATION, type AudioPlan, type ResolvedCue, } from "./audio.js";
-export { evaluate, type DisplayList, type DisplayOp, type Mat2D, type TextAlign, type TextBaseline, } from "./evaluate.js";
+export { devicePreset, deviceScreen, deviceScreenCenter, deviceBounds, DEVICE_PRESET_NAMES, type DevicePresetName, type DevicePresetOpts } from "./devicePreset.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 { 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";
 export { resolveEase, lerpValue, isColor, EASE_NAMES } from "./interpolate.js";
 export { sampleBehavior } from "./behaviors.js";
 export { collectImageSrcs } from "./assets.js";

package/dist/types/interpolate.d.ts

@@ -5,8 +5,9 @@ export declare function resolveEase(ease: Ease | undefined): EaseFn;
 export declare function isColor(v: PropValue): v is string;
 /**
  * Interpolate two prop values at progress u (already eased).
- * number↔number lerps, color↔color lerps in RGB, anything else switches
- * discretely at the start of the segment.
+ * number↔number lerps, color↔color lerps in RGB, two *compatible* SVG path
+ * `d` strings morph vertex-by-vertex (the Lottie-style shape tween), anything
+ * else switches discretely.
  */
 export declare function lerpValue(from: PropValue, to: PropValue, u: number): PropValue;
 export {};

package/dist/types/ir.d.ts

@@ -24,6 +24,12 @@ export interface BaseProps {
     opacity?: number;
     rotation?: number;
     scale?: number;
+    /** Per-axis scale multipliers on `scale` (default 1) — a 2.5D squash/tilt. */
+    scaleX?: number;
+    scaleY?: number;
+    /** Shear angles in degrees (default 0) — a 2.5D lean. No true perspective. */
+    skewX?: number;
+    skewY?: number;
     anchor?: Anchor;
 }
 export interface RectProps extends BaseProps {
@@ -63,7 +69,28 @@ export interface TextProps extends BaseProps {
     fill?: string;
     letterSpacing?: number;
 }
+/**
+ * A clip region (in a group's local coordinate space) that masks its children —
+ * e.g. a rounded-rect phone screen so content inside stays within it. A rect
+ * with `radius` covers most cases; ellipse is a bonus.
+ */
+export type ClipShape = {
+    kind: "rect";
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    radius?: number;
+} | {
+    kind: "ellipse";
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
 export interface GroupProps extends BaseProps {
+    /** Clip the group's children to this shape (group-local coords). */
+    clip?: ClipShape;
 }
 export interface PathProps extends BaseProps {
     /** SVG path data (the `d` attribute). Drawn as a true vector — crisp at any zoom. */
@@ -179,6 +206,8 @@ export type TimelineIR = {
     closed?: boolean;
     duration?: number;
     ease?: Ease;
+    /** Tangent scale: 1 = smooth (default), 0 = sharp corners, >1 = loopier. */
+    curviness?: number;
     autoRotate?: boolean;
     /** Degrees added to the tangent angle (e.g. 90 if the art faces "up"). */
     rotateOffset?: number;
@@ -194,6 +223,13 @@ export type TimelineIR = {
      */
     kind: "beat";
     name: string;
+    /**
+     * Node ids this beat semantically OWNS (the intent graph). Purely additive
+     * metadata — compile/evaluate ignore it, so `beat(name, { nodes }, …)` is
+     * byte-identical to `beat(name, {}, …)`. The preview groups these nodes'
+     * lanes under the beat; overlay/regen address the beat by its stable name.
+     */
+    nodes?: string[];
     parallel?: boolean;
     /** Absolute start (rigid placement). Overrides sequential flow. */
     at?: number;
@@ -288,6 +324,38 @@ export interface SceneIR {
     /** Editor-only data (Theatre.js state.json pattern). */
     meta?: Record<string, unknown>;
 }
+/**
+ * Composition — the layer ABOVE a scene: an ordered list of independent scenes
+ * with transitions, rendered to one deterministic mp4. Each `scene` stays a
+ * normal SceneIR (renders/previews/overlays standalone, unchanged); the
+ * composition only lays out their start times and concatenates. No single-scene
+ * compile/evaluate path is touched.
+ */
+export type SceneTransition = "cut" | "crossfade";
+export interface CompositionSceneEntry {
+    scene: SceneIR;
+    /** How this scene enters from the previous one. Default "cut". A crossfade
+     *  overlaps the previous scene by `at` (or a default) and blends. */
+    transition?: SceneTransition;
+    /**
+     * Placement relative to the sequential append point (the previous scene's
+     * end): a number is an ABSOLUTE start (seconds); a string "-0.5"/"+0.5" shifts
+     * the sequential point (overlap / gap). Omitted = sequential (or, for a
+     * crossfade, overlap by the default crossfade duration).
+     */
+    at?: number | string;
+}
+export interface CompositionIR {
+    version: 1;
+    id: string;
+    scenes: CompositionSceneEntry[];
+    /** Composition-level sound: a bed spanning scenes (e.g. kokoro narration) +
+     *  absolute-time cues, layered over each scene's own offset cues. */
+    audio?: AudioIR;
+    meta?: Record<string, unknown>;
+}
+/** Default crossfade/overlap length (s) when a crossfade gives no explicit `at`. */
+export declare const DEFAULT_CROSSFADE = 0.5;
 export declare const DEFAULT_TO_DURATION = 0.5;
 export declare const DEFAULT_TWEEN_DURATION = 0.5;
 export declare const DEFAULT_MOTIONPATH_DURATION = 1;

package/dist/types/motionOps.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Motion ops — a small GSAP-style library of everyday motions that apply to ANY
+ * node (text, logo paths, shapes), composed from the existing primitives
+ * (tween / motionPath / beat). `motionOp(name, target, opts)` returns a labeled
+ * beat (+ optional `setup` base-prop overrides for entrances) you can author in
+ * code or ADD to a scene from the editor via the `addTimeline` overlay verb.
+ *
+ * Ops compute absolute targets from `opts.base` (the node's current transform),
+ * so they're correct on nodes that aren't at scale 1 / origin 0.
+ */
+import type { PropValue, TimelineIR } from "./ir.js";
+export type MotionOpName = "rotate" | "zoom" | "ken-burns" | "slide-in" | "fade" | "draw-on" | "pulse";
+export declare const MOTION_OPS: MotionOpName[];
+export interface MotionOpOpts {
+    energy?: number;
+    speed?: number;
+    amount?: number;
+    from?: "left" | "right" | "top" | "bottom";
+    /** The target node's current transform — lets scale/position ops be correct
+     *  on nodes that aren't at scale 1 / origin 0. */
+    base?: {
+        scale?: number;
+        x?: number;
+        y?: number;
+        rotation?: number;
+    };
+}
+export interface MotionOpResult {
+    /** Base-prop overrides the op needs (e.g. start hidden for a fade). */
+    setup?: Record<string, Record<string, PropValue>>;
+    /** The op's animation, a labeled beat. */
+    timeline: TimelineIR;
+}
+/** A stable beat label for an op on a node (so it's patchable + foldable). */
+export declare const motionOpLabel: (name: MotionOpName, target: string) => string;
+export declare function motionOp(name: MotionOpName, target: string, opts?: MotionOpOpts): MotionOpResult;

package/dist/types/path.d.ts

@@ -9,7 +9,11 @@
  * spacing ever overshoots.
  */
 export type Pt = [number, number];
-/** Position on the spline at progress u in [0,1]. */
-export declare function pathPoint(points: Pt[], closed: boolean, u: number): Pt;
+/**
+ * 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
+ * byte-exact original), 0 = straight lines / sharp corners, >1 = looser/loopier.
+ */
+export declare function pathPoint(points: Pt[], closed: boolean, u: number, curviness?: number): Pt;
 /** Tangent angle (degrees) at progress u — the direction of travel along the path. */
-export declare function pathTangentAngle(points: Pt[], closed: boolean, u: number): number;
+export declare function pathTangentAngle(points: Pt[], closed: boolean, u: number, curviness?: number): number;

package/dist/types/rig.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Character rig: a first-class, declarative skeleton that COMPILES to plain IR.
+ * The character analog of `devicePreset` (generates a NodeIR subtree) and
+ * `motionPreset` (motion vocabulary). A `Bone` tree → nested `group` joints with
+ * stable ids, each holding the bone's vector art; posing is forward-kinematics
+ * (tween a joint group's `rotation`). Because it lowers to groups + paths, it
+ * inherits the renderer, evaluate, overlay editing, preview, validation and the
+ * determinism/golden contract for free — purely additive.
+ *
+ *   const body = humanoid({ id: "hero" });          // one-call skeleton
+ *   poseTo("hero", { armUpperR: -150 }, { duration: 0.4 });   // wave
+ *
+ * Bone convention: the joint sits at the group origin (0,0); the bone extends
+ * along +Y at rotation 0. A child joint's `at` pivot is in the PARENT bone's
+ * local space (e.g. an elbow at [0, upperLength]). Joint names are the STABLE
+ * regen addresses — id `${id}-${name}`; never rename them across a regen. Each
+ * rig instance needs a distinct `id` (duplicate joints collide via the scene's
+ * duplicate-id validation, exactly like `devicePreset`).
+ */
+import type { Ease, NodeIR, TimelineIR } from "./ir.js";
+export interface Bone {
+    /** Stable joint name → group id `${id}-${name}`. */
+    name: string;
+    /** Joint pivot, in the PARENT bone's local space (root: usually [0,0]). */
+    at: [number, number];
+    /** Bone length along +Y — drives the default capsule shape and IK. */
+    length?: number;
+    /** Default-capsule width (default 20). */
+    width?: number;
+    /** Rest-pose angle (deg); 0 = points down (+Y). */
+    rotation?: number;
+    /** Custom bone art (joint at origin, extends +Y) — overrides the default capsule. */
+    shape?: NodeIR[];
+    children?: Bone[];
+}
+export interface RigOpts {
+    /** Id PREFIX for the outer group and every joint (default "rig"); unique per instance. */
+    id?: string;
+    /** Root placement (default 0,0). */
+    x?: number;
+    y?: number;
+    /** Uniform scale (default 1). */
+    scale?: number;
+    /** Outer-group opacity (default 1) — start hidden for an entrance. */
+    opacity?: number;
+    /** Bone line colour (default warm). */
+    color?: string;
+    /** Bone fill (default near-bg, so overlapping joints occlude cleanly). */
+    fill?: string;
+    /** Glow accent for the double-path look on default bones (default off). */
+    glow?: string | false;
+}
+/** jointName → angle (deg). */
+export type Pose = Record<string, number>;
+/** A 4-cubic oval (morphable) centred at (cx,cy). Handy for heads/torsos/hands. */
+export declare function ovalPath(a: number, b: number, cx?: number, cy?: number): string;
+/** Compile a skeleton to a NodeIR group tree. Outer group id = `${id}`; each
+ * joint = `${id}-${name}` (the stable pose/overlay address). */
+export declare function rig(root: Bone, opts?: RigOpts): NodeIR;
+/** A pose as a `states` fragment: `{ "${id}-${joint}": { rotation } }`. Merge
+ * into scene `states` and transition with the existing `to(state, …)`. */
+export declare function rigPose(id: string, pose: Pose): Record<string, {
+    rotation: number;
+}>;
+/** Pose-to-pose on the timeline: a `par` (or `stagger`) of rotation tweens. */
+export declare function poseTo(id: string, pose: Pose, opts?: {
+    duration?: number;
+    ease?: Ease;
+    stagger?: number;
+}): TimelineIR;
+/**
+ * 2-bone inverse kinematics. Returns `[shoulderDeg, elbowDeg]` (the +Y-down bone
+ * convention) that place the chain's tip at `(dx,dy)` relative to the root joint.
+ * Exact for in-reach targets; clamps gracefully (no NaN) when out of reach.
+ * `flip` chooses the elbow-up vs elbow-down solution.
+ *
+ * Derivation: with R(θ) the canvas rotation, the tip is
+ * R(θ1)·[ (0,upper) + R(θ2)·(0,lower) ]. The bracket has length D=hypot(dx,dy),
+ * giving cosθ2 = (D²−u²−l²)/(2ul); then θ1 rotates that bracket onto the target.
+ */
+export declare function ikReach(upper: number, lower: number, dx: number, dy: number, flip?: boolean): [number, number];
+export interface HumanoidOpts extends Omit<RigOpts, never> {
+}
+/** A ready upright humanoid skeleton — the one-call body. Joints:
+ * chest, head, armUpper/LowerL, armUpper/LowerR, legUpper/LowerL, legUpper/LowerR.
+ * Rooted at the chest so every limb extends naturally along +Y. */
+export declare function humanoid(opts?: HumanoidOpts): NodeIR;

package/dist/types/validate.d.ts

@@ -3,10 +3,13 @@
  * feedback loop for LLM-generated scenes, so they name the exact location
  * and suggest what valid input looks like.
  */
-import type { NodeIR, SceneIR } from "./ir.js";
+import type { CompositionIR, NodeIR, SceneIR } from "./ir.js";
 export declare const PROPS_BY_TYPE: Record<NodeIR["type"], string[]>;
 export declare class SceneValidationError extends Error {
     problems: string[];
     constructor(problems: string[]);
 }
 export declare function validateScene(ir: SceneIR): void;
+/** Validate a composition: each scene is valid, scene ids are unique, transitions
+ *  are known, and `at` strings parse. Throws SceneValidationError on any problem. */
+export declare function validateComposition(comp: CompositionIR): void;