reframe-video 0.2.0 → 0.4.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/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

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

package/dist/types/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/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/textFx.d.ts

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

package/dist/types/textMetrics.d.ts

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

package/guides/edsl-guide.md

@@ -41,6 +41,12 @@ Factories return plain data. Every node needs a unique `id`.
   the art's centre (e.g. the viewBox centre) so `scale`/`rotation` happen about the
   middle. `d` is drawn in its own coords; `x`/`y` place that pivot. Classic logo
   reveal: a stroke path drawing on, then a fill path fading in over it.
+  **`d` is animatable (shape morph):** `tween(id, { d: otherShape }, …)` morphs
+  the path vertex-by-vertex (the Lottie-style shape tween) when both `d` strings
+  share the same command sequence and arg counts — author the two poses with the
+  same structure (e.g. both 4-cubic ovals). Arcs (`A`) can't morph (their 0/1
+  flags aren't interpolable) and incompatible shapes snap at the midpoint; build
+  morph targets from `M/L/C/Q/Z` only.
 - `image({ id, src, x, y, width, height, opacity?, rotation?, scale?, anchor? })` —
   `src` is a file path, absolute or relative to the scene file; drawn stretched
   to `width`×`height` (png/jpg/webp). `src` switches discretely (no crossfade) —
@@ -115,6 +121,84 @@ 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.
 
+## Character rig (skeleton, poses, IK)
+
+A first-class, declarative character rig that **compiles to plain IR** (nested
+`group` joints + bone paths) — the character analog of `devicePreset`. It needs
+no new renderer concept, so overlays/preview/determinism all apply.
+
+- `humanoid({ id, x, y, scale, opacity?, color?, fill?, glow? })` → a NodeIR: a
+  ready upright body. Joints (stable ids `${id}-${name}`): `chest`, `head`,
+  `armUpperL/armLowerL`, `armUpperR/armLowerR`, `legUpperL/legLowerL`,
+  `legUpperR/legLowerR`. Drop it in `nodes`.
+- `rig(boneTree, opts)` → build your own skeleton. A `Bone` is
+  `{ name, at:[x,y], length?, width?, rotation?, shape?, children? }`. The joint
+  sits at the group origin; the bone extends **+Y at rotation 0**; a child's `at`
+  pivot is in the PARENT bone's local space (e.g. an elbow at `[0, upperLength]`).
+  Nested groups give forward kinematics — a child's rotation composes on its
+  parent's. Default bone = a bezier capsule (morphable); pass `shape` for custom art.
+- A **pose** is `{ jointName: angleDeg }` (0 = bone points down). Animate it:
+  - `poseTo(id, pose, { duration, ease, stagger? })` → a timeline step (a `par`
+    of rotation tweens). Sequence poses for wave/jump/run.
+  - `rigPose(id, pose)` → a `states` fragment, to transition with `to(state, …)`.
+- `ikReach(upper, lower, dx, dy, flip?)` → `[shoulderDeg, elbowDeg]` that place a
+  2-bone limb's tip at `(dx,dy)` relative to its shoulder joint (law of cosines;
+  clamps when out of reach). Feed the two angles into a pose.
+- Joint names are the **stable regen addresses** — never rename them across a
+  regen; each rig instance needs a distinct `id` (duplicates collide via scene
+  validation). Squash/stretch and expressions are per-bone `d` morphs (above),
+  composed on top of FK posing. Idle sway/breathing = `oscillate` on a joint.
+- `figure(opts)` — a **dressed** character (the styled sibling of `humanoid`):
+  same skeleton, but coloured flat-design shapes. `style: "clean"` (corporate-flat
+  / undraw register, the default) or `"cute"` (mascot); `palette` knobs
+  (`skin`/`hair`/`top`/`pants`/`shoe`/`accent`) re-skin it — for `clean` the top
+  follows `accent`, so `figure({ palette: { accent: "#3B82F6" } })` recolours the
+  whole figure; `face: false` makes it faceless. It exposes the humanoid joint
+  ids, so `characterPreset` / `ikReach` drive it unchanged. Use it as the
+  supporting actor in a product promo (gesturing at a `devicePreset`), not the hero.
+- `characterPreset(name, opts)` — a **seeded motion generator** for a `humanoid`
+  or `figure` rig (the character analog of `motionPreset`). Returns a composable `beat`;
+  drop it in the timeline: `seq(characterPreset("walk", { target: "hero", at:
+  [cx, cy], cycles: 4 }))`. Names: `walk`, `run`, `jump`, `dance`, `wave`,
+  `cheer`. Knobs: `target` (rig id), `energy` 0..1, `speed` (>0, divides
+  durations), `seed` (varies within the family), `cycles` (walk/run/dance),
+  `facing` (±1), `at: [x,y]` (the rig's scene position — needed for walk travel
+  & jump lift), `travel` (px/cycle, 0 = in place), `label` (unique beat name —
+  set it when the same preset is used more than once in a scene). Legs use
+  `ikReach`, arms FK; pure keyframes, so add continuous idle yourself with `oscillate`.
+
+## Kinetic text (split + effect presets)
+
+reframe's `text` node renders a whole string as one node, so per-glyph effects
+need the string split into per-character nodes. `splitText` does that once;
+seeded effect generators animate the glyphs (the text analog of `motionPreset`).
+
+- `splitText(text, { id, x, y, fontSize, fontWeight?, fill?, letterSpacing?,
+  align?, unit?, opacity? }) → TextBlock` — lays the phrase out as center-anchored
+  `text` nodes using **real Inter advance widths** (so layout matches the render).
+  Returns `{ nodes, glyphs, ids, width, ... }`; put `...block.nodes` in `nodes`.
+  Glyph ids are `${id}-${i}` (stable regen addresses). `unit: "word"` animates
+  whole words instead of letters; `opacity: 0` (default) starts hidden for entrances.
+- `textIn(name, block, { speed?, energy?, seed?, stagger?, label? }) → TimelineIR`
+  (a `beat`) — entrance: `typewriter`, `cascade`, `rise`, `bounce`, `assemble`
+  (fly in from a seeded scatter), `decode` (scramble through random glyphs then lock).
+- `textLoop(name, block, { from?, until?, ramp?, amplitude?, frequency?, phaseStep? })
+  → BehaviorIR[]` — sustained: `wave` (standing sine), `shimmer`, `wobble`, `float`.
+  Spread it into `behaviors`.
+- `textOut(name, block, { …, dir? }) → TimelineIR` — exit: `shatter` (random
+  direction + spin + fade), `fly` (directional), `dissolve`, `fall`, `collapse`.
+- `textTypeCues(block, { at, interval?, gain? }) → AudioCueIR[]` — per-glyph CC0
+  keypress for a typewriter entrance; spread into `audio.cues`.
+
+```ts
+const T = splitText("MOTION IS DATA", { id: "t", x: 960, y: 470, fontSize: 130 });
+// nodes:     [...T.nodes]
+// timeline:  seq(textIn("cascade", T), wait(2), textOut("shatter", T, { seed: 3 }))
+// behaviors: textLoop("wave", T, { from: 1.6, until: 3.6 })
+```
+Every effect is seeded (same `seed` → identical) and pure keyframes. To time a
+`textLoop` window, add up the `textIn` beat length (≈ `(n-1)·stagger + glyphDur`).
+
 ## Audio (optional)
 
 Label-anchored sound design — cues follow retiming and regeneration:

package/guides/regen-contract.md

@@ -16,3 +16,14 @@ source):
 When the contract is broken anyway, `composeScene` skips the affected edits
 and reports them as orphans with the known-ids list — loud, diagnosable,
 never a silent drop and never a render failure.
+
+## Generated subtrees (devicePreset, rig/humanoid)
+
+Generators emit nodes with deterministic ids under an instance prefix, and those
+ids are stable addresses too. For `devicePreset(name,{id})` the screen/content
+parts are `${id}-screen` / `${id}-content`. For `rig(...)` / `humanoid({id})`
+each joint is `${id}-${jointName}` (e.g. `hero-armUpperR`) and its bone art is
+`${id}-${jointName}-shape`. Across a regen, **keep the instance `id` and the
+joint `name`s** for any character/device that survives the redesign — overlay
+edits (a retimed wave, a nudged limb angle) reference those exact ids. Renaming a
+joint orphans the edit, exactly like renaming a hand-authored node id.

package/package.json

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