reframe-video 0.1.1 → 0.1.2

package/dist/types/compile.d.ts

@@ -18,6 +18,16 @@ export interface PropertySegment {
     to: PropValue;
     ease?: Ease;
 }
+/** A path driver overrides a node's x/y (and rotation, if autoRotate) over [t0, t1], holding the end. */
+export interface MotionDriver {
+    t0: number;
+    t1: number;
+    ease?: Ease;
+    points: [number, number][];
+    closed: boolean;
+    autoRotate: boolean;
+    rotateOffset: number;
+}
 export interface LabelSpan {
     t0: number;
     t1: number;
@@ -27,12 +37,16 @@ export interface CompiledScene {
     duration: number;
     /** Keyed by `${target}.${prop}`, sorted by t0. */
     segments: Map<string, PropertySegment[]>;
+    /** Path drivers per target node, sorted by t0 — override x/y/rotation. */
+    motionPaths: Map<string, MotionDriver[]>;
     /** Base props merged with the initial state, keyed by `${target}.${prop}`. */
     initialValues: Map<string, PropValue>;
     nodeById: Map<string, NodeIR>;
     /** Declaration order — defines stagger order. */
     nodeOrder: string[];
-    /** Absolute [start, end] of every labeled timeline step. */
+    /** Absolute [start, end] of every labeled timeline step (beat names included). */
     labelTimes: Map<string, LabelSpan>;
+    /** The subset of label spans that come from beat nodes — keyed by beat name. */
+    beatTimes: Map<string, LabelSpan>;
 }
 export declare function compileScene(ir: SceneIR): CompiledScene;

package/dist/types/compose.d.ts

@@ -35,13 +35,23 @@ export interface OverlayDoc {
     /** Complete nodes appended at the scene root, owned by this overlay. */
     addNodes?: NodeIR[];
     /**
-     * Parameter patches on labeled timeline steps. Patchable per kind:
-     * to -> duration/ease/stagger, tween -> duration/ease, wait -> duration.
+     * Parameter patches on labeled timeline steps (or beats by name). Patchable
+     * per kind: to -> duration/ease/stagger, tween -> duration/ease,
+     * wait -> duration, motionPath -> points/duration/ease, beat ->
+     * at/gap/scale/duration/order. A beat move is rigid, so child labels inside
+     * it keep their relative timing and any overlay edits on those children
+     * survive. A dragged motionPath waypoint is a `points` patch — it survives a
+     * knob-driven base regen because the step label is stable.
      */
     timeline?: Record<string, {
         duration?: number;
         ease?: Ease;
         stagger?: number;
+        at?: number;
+        gap?: number;
+        scale?: number;
+        order?: number;
+        points?: [number, number][];
     }>;
 }
 export interface ComposeReport {

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, PropValue, RectProps, SceneIR, Size, StateOverride, TextProps, TimelineIR } from "./ir.js";
+import type { AudioIR, BehaviorIR, Ease, EllipseProps, GroupProps, ImageProps, LineProps, NodeIR, PathProps, PropValue, RectProps, SceneIR, Size, StateOverride, TextProps, TimelineIR } from "./ir.js";
 export interface SceneInput {
     id: string;
     size: Size;
@@ -33,12 +33,30 @@ export declare function text(props: {
 export declare function image(props: {
     id: string;
 } & ImageProps): NodeIR;
+export declare function path(props: {
+    id: string;
+} & PathProps): NodeIR;
 export declare function group(props: {
     id: string;
 } & GroupProps, children: NodeIR[]): NodeIR;
 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 {
+    /** Group children in parallel instead of sequence. */
+    parallel?: boolean;
+    /** Absolute start (rigid placement). */
+    at?: number;
+    /** Relative shift before the beat. */
+    gap?: number;
+    /** Interior time-stretch factor. */
+    scale?: number;
+    /** Target total duration (→ scale). */
+    duration?: number;
+    /** Sort key within a parent seq (reorder). */
+    order?: number;
+}
+export declare function beat(name: string, opts: BeatOpts, children: TimelineIR[]): TimelineIR;
 export declare function to(state: string, opts?: {
     duration?: number;
     ease?: Ease;
@@ -52,6 +70,14 @@ export declare function tween(target: string, props: Record<string, PropValue>,
     label?: string;
 }): TimelineIR;
 export declare function wait(duration: number, label?: string): TimelineIR;
+export declare function motionPath(target: string, points: [number, number][], opts?: {
+    duration?: number;
+    ease?: Ease;
+    closed?: boolean;
+    autoRotate?: boolean;
+    rotateOffset?: number;
+    label?: string;
+}): TimelineIR;
 export interface BehaviorWindow {
     from?: number;
     until?: number;

package/dist/types/evaluate.d.ts

@@ -61,6 +61,15 @@ export type DisplayOp = (OpBase & {
     height: number;
     offsetX: number;
     offsetY: number;
+}) | (OpBase & {
+    type: "path";
+    /** SVG path data, drawn via Path2D. */
+    d: string;
+    /** 0..1 fraction of the stroke outline drawn (draw-on). */
+    progress: number;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
 });
 export type DisplayList = DisplayOp[];
 export declare function evaluate(compiled: CompiledScene, t: number): DisplayList;

package/dist/types/index.d.ts

@@ -2,9 +2,12 @@ export * from "./ir.js";
 export * from "./dsl.js";
 export { validateScene, SceneValidationError, PROPS_BY_TYPE } from "./validate.js";
 export { composeScene, formatComposeReport, type OverlayDoc, type ComposeReport, } from "./compose.js";
-export { compileScene, type CompiledScene, type PropertySegment, type LabelSpan } from "./compile.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 { resolveEase, lerpValue, isColor, EASE_NAMES } from "./interpolate.js";
 export { sampleBehavior } from "./behaviors.js";
 export { collectImageSrcs } from "./assets.js";
+export { sketchToTimeline, type MotionSketch, type MotionEvent, type MotionEventKind, type MotionRegion, } from "./motion.js";

package/dist/types/ir.d.ts

@@ -8,7 +8,7 @@
  * Semantics: a scene is evaluated as a pure function of continuous time
  * `evaluate(scene, tSeconds) -> DisplayList`. `fps` is a render hint only.
  */
-export type EaseName = "linear" | "easeInQuad" | "easeOutQuad" | "easeInOutQuad" | "easeInCubic" | "easeOutCubic" | "easeInOutCubic" | "easeInQuart" | "easeOutQuart" | "easeInOutQuart" | "easeInExpo" | "easeOutExpo" | "easeInOutExpo";
+export type EaseName = "linear" | "easeInQuad" | "easeOutQuad" | "easeInOutQuad" | "easeInCubic" | "easeOutCubic" | "easeInOutCubic" | "easeInQuart" | "easeOutQuart" | "easeInOutQuart" | "easeInExpo" | "easeOutExpo" | "easeInOutExpo" | "easeInBack" | "easeOutBack" | "easeInOutBack" | "easeInElastic" | "easeOutElastic" | "easeInOutElastic" | "easeInBounce" | "easeOutBounce" | "easeInOutBounce";
 export type Ease = EaseName | {
     cubicBezier: [number, number, number, number];
 };
@@ -65,6 +65,26 @@ export interface TextProps extends BaseProps {
 }
 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;
+    strokeWidth?: number;
+    /**
+     * 0..1 — fraction of the OUTLINE drawn, for a self-drawing "draw-on" effect
+     * (animate 0→1). Applies to the stroke; pair a stroke path (draw-on) with a
+     * separate fill path (fade-in) for the classic logo reveal. Default 1.
+     */
+    progress?: number;
+    /**
+     * Local pivot in the path's own coordinate space — scale/rotation happen
+     * around this point. Set it to the art's centre (e.g. the viewBox centre) so
+     * a logo zooms/spins about its middle. Default (0,0).
+     */
+    originX?: number;
+    originY?: number;
+}
 export interface ImageProps extends BaseProps {
     /**
      * Image file path: absolute, or relative to the scene file. Drawn
@@ -96,6 +116,10 @@ export type NodeIR = {
     type: "image";
     id: string;
     props: ImageProps;
+} | {
+    type: "path";
+    id: string;
+    props: PathProps;
 } | {
     type: "group";
     id: string;
@@ -141,6 +165,47 @@ export type TimelineIR = {
     kind: "wait";
     duration: number;
     label?: string;
+} | {
+    /**
+     * Drive a node's x/y along a Catmull-Rom spline through `points`
+     * (absolute coords in the node's parent space). With `autoRotate`, the
+     * node's rotation tracks the path tangent (plus `rotateOffset`). The
+     * position HOLDS at the final point after the path completes, so a swoop
+     * is a positioning move, not a one-shot that snaps back.
+     */
+    kind: "motionPath";
+    target: string;
+    points: [number, number][];
+    closed?: boolean;
+    duration?: number;
+    ease?: Ease;
+    autoRotate?: boolean;
+    /** Degrees added to the tangent angle (e.g. 90 if the art faces "up"). */
+    rotateOffset?: number;
+    label?: string;
+} | {
+    /**
+     * A named, retimable, reorderable span wrapping timeline steps — the
+     * semantic unit ("brand-reveal", "feature-cascade") humans and AI revise.
+     * Lowers to its grouping (seq, or par if `parallel`) before timing, so
+     * `beat(name, {}, children)` is byte-identical to `seq(children)`.
+     * Ops are RIGID: they translate/stretch the whole span, preserving the
+     * interior's relative timing (so sub-beat overlay edits survive a move).
+     */
+    kind: "beat";
+    name: string;
+    parallel?: boolean;
+    /** Absolute start (rigid placement). Overrides sequential flow. */
+    at?: number;
+    /** Relative shift: a leading delay before the beat (and everything after). */
+    gap?: number;
+    /** Interior time-stretch factor (every child offset and duration ×scale). */
+    scale?: number;
+    /** Target total duration → scale = duration / natural duration. */
+    duration?: number;
+    /** Sort key within a parent seq (reorder); default = declaration index. */
+    order?: number;
+    children: TimelineIR[];
 };
 export interface BehaviorIR {
     target: string;
@@ -225,4 +290,5 @@ export interface SceneIR {
 }
 export declare const DEFAULT_TO_DURATION = 0.5;
 export declare const DEFAULT_TWEEN_DURATION = 0.5;
+export declare const DEFAULT_MOTIONPATH_DURATION = 1;
 export declare const DEFAULT_FPS = 30;

package/dist/types/motion.d.ts

@@ -0,0 +1,54 @@
+/**
+ * MotionSketch — the intermediate representation between a video's pixel
+ * motion signal and a reframe timeline. Extraction (pixels → sketch) lives in
+ * the motion harness (it needs the profiler); this module owns the sketch
+ * *vocabulary* and the *emission* (sketch → TimelineIR), both of which are
+ * pure and dependency-free so core can host them.
+ *
+ * Reconstruction is deliberately geometry-free: events emit opacity/scale
+ * tweens whose targets are absolute (1, or 1+magnitude), so a sketch re-applies
+ * to nodes without knowing their rest positions — which is what makes the
+ * round-trip verifier independent of node layout.
+ */
+import type { TimelineIR } from "./ir.js";
+export type MotionEventKind = "enter" | "exit" | "move" | "scale" | "emphasis";
+/** Normalized 0..1 activity bounding box — a coarse region, NOT a tracked object. */
+export interface MotionRegion {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface MotionEvent {
+    /** Onset / settle, seconds. */
+    t0: number;
+    t1: number;
+    kind: MotionEventKind;
+    region: MotionRegion;
+    /** Displacement or scale delta, normalized to the frame. */
+    magnitude: number;
+    easing: {
+        class: string;
+        thirdsRatio: number | null;
+        reliable: boolean;
+    };
+}
+export interface MotionSketch {
+    duration: number;
+    fps: number;
+    events: MotionEvent[];
+    /** Global cadence; periodicityHz null when no clear oscillation. */
+    rhythm: {
+        periodicityHz: number | null;
+        beatCount: number;
+    };
+}
+/**
+ * Emit a reframe timeline reproducing a sketch's timing, applied to `nodeIds`.
+ * Events are assigned to nodes in onset order (v1: region→node mapping is
+ * goal-2's concern; here ids are given). Geometry-free: enter/exit drive
+ * opacity, emphasis/scale drive scale, so the emitted timeline needs no node
+ * coordinates. For an `enter` to read as an entrance the target node should
+ * start hidden (opacity 0) — idiomatic reframe `initial` state.
+ */
+export declare function sketchToTimeline(sketch: MotionSketch, nodeIds: string[]): TimelineIR;

package/dist/types/path.d.ts

@@ -0,0 +1,15 @@
+/**
+ * MotionPath geometry — a Catmull-Rom spline through waypoints, evaluated as a
+ * pure function of progress u in [0,1]. Used by evaluate() to drive a node's
+ * x/y (and, with autoRotate, rotation along the tangent) along a curve.
+ *
+ * Pure math, no DOM: same result in Node (tests/golden) and the browser
+ * renderer. Uniform parameterisation — each segment owns an equal slice of u.
+ * Good for hand-authored sting waypoints; centripetal can come later if uneven
+ * 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;
+/** Tangent angle (degrees) at progress u — the direction of travel along the path. */
+export declare function pathTangentAngle(points: Pt[], closed: boolean, u: number): number;

package/dist/types/presets.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Motion presets — a small NAMED vocabulary of logo-sting motions, each a
+ * SEEDED GENERATOR (not a frozen template). `motionPreset(name, opts)` returns
+ * a `beat` (goal-2's addressable, retimable unit) composed from the existing
+ * primitives (motionPath, tween, stagger, path draw-on, expressive eases).
+ *
+ * Two-determinisms: same (name, knobs, seed) → identical IR (reproducible);
+ * a different `seed` perturbs waypoints / timing / accents WITHIN BOUNDED
+ * ranges → a measurably different motion that is still the same family. The
+ * seed feeds a deterministic PRNG — no Math.random, ever.
+ *
+ * Universal knobs (every preset): `energy` 0..1 (settle ↔ springy overshoot),
+ * `speed` (duration multiplier, >1 faster). Plus a signature knob `intensity`
+ * 0..1 (the preset's amplitude) and, where spatial, `from`.
+ */
+import type { TimelineIR } from "./ir.js";
+export type PresetName = "draw-bloom" | "punch-in" | "rise-settle" | "slide-bank" | "reveal-orbit" | "spin-forge";
+export declare const PRESET_NAMES: PresetName[];
+/** The rig a preset drives: a group at `center` scaled to `baseScale`, with
+ *  fill layers (bloom) and ink layers (draw-on outline). */
+export interface PresetRig {
+    group: string;
+    center: [number, number];
+    baseScale: number;
+    fills: string[];
+    inks: string[];
+}
+export interface PresetOpts {
+    target: PresetRig;
+    /** 0..1 — clean settle ↔ springy overshoot. Default 0.5. */
+    energy?: number;
+    /** Duration multiplier; >1 faster, <1 slower. Default 1. */
+    speed?: number;
+    /** 0..1 — the signature amplitude (orbit radius / rise distance / spins). Default 0.5. */
+    intensity?: number;
+    /** Entry direction for spatial presets. Default per preset. */
+    from?: "left" | "right" | "top" | "bottom";
+    /** Deterministic variation. Same seed → identical; different seed → same family. Default 0. */
+    seed?: number;
+}
+export declare function motionPreset(name: PresetName, opts: PresetOpts): TimelineIR;

package/guides/edsl-guide.md

@@ -34,6 +34,13 @@ Factories return plain data. Every node needs a unique `id`.
   `content` may be a number; numeric content interpolates (count-up) and renders
   via `toFixed(contentDecimals ?? 0)`. For a "8.2"-style label, set
   `contentDecimals: 1`.
+- `path({ id, d, x, y, fill?, stroke?, strokeWidth?, progress?, originX?, originY?, opacity?, rotation?, scale?, anchor? })` —
+  a true vector shape from an SVG path `d` string (crisp at any zoom; recolour by
+  animating `fill`/`stroke`). `progress` 0..1 draws the stroke OUTLINE on (animate
+  0→1 for a self-drawing logo). `originX`/`originY` is the local pivot — set it to
+  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.
 - `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) —
@@ -75,11 +82,23 @@ them with normal TS (`Object.fromEntries`, `.map`) for data-driven scenes.
 - `to(stateName, opts)` — transition into a named state (see above).
 - `tween(nodeId, { prop: value, ... }, { duration, ease })` — low-level escape hatch
   for one node. Colors (`"#rrggbb"`) interpolate; numbers interpolate.
+- `motionPath(nodeId, [[x,y], ...], { duration, ease, autoRotate?, rotateOffset?, closed? })`
+  — drive a node's `x`/`y` along a smooth Catmull-Rom curve through the waypoints
+  (parent-space coords). `autoRotate: true` banks the node along the path tangent
+  (`rotateOffset` degrees if the art faces "up", e.g. `-90`). The node HOLDS at the
+  final point after the path finishes (a positioning move, not a one-shot), so a
+  later `tween` can chain from there. Use it for swoops/arcs/orbits — straight
+  `tween`s on x and y can't curve. `closed: true` loops the waypoints (orbit).
 - `wait(seconds)` — hold.
 
 Eases: `linear`, `easeIn/Out/InOutQuad`, `easeIn/Out/InOutCubic`,
 `easeIn/Out/InOutQuart`, `easeIn/Out/InOutExpo`, or `{ cubicBezier: [x1,y1,x2,y2] }`.
 Decelerating entrances = `easeOut*`, accelerating exits = `easeIn*`.
+Expressive eases for a premium feel: `easeIn/Out/InOutBack` (overshoots past the
+target then settles — a pop/snap), `easeIn/Out/InOutElastic` (rings around the
+target — a playful spring), `easeIn/Out/InOutBounce` (drops and bounces to rest).
+A logo or card "popping" in usually wants `easeOutBack`; a stamp landing,
+`easeOutBounce`.
 Scene duration is inferred from the timeline.
 
 ## Behaviors: continuous motion during holds

package/package.json

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

package/preview/src/main.ts

@@ -134,6 +134,9 @@ function opCorners(op: DisplayOp): [number, number][] {
         applyMat(op.transform, px!, py!),
       );
     }
+    case "path":
+      // No cheap bbox for an arbitrary `d`; mark the origin for selection.
+      return [applyMat(op.transform, 0, 0)];
   }
 }
 
@@ -158,11 +161,70 @@ function draw() {
     ctx.restore();
   }
 
+  // motionPath waypoint handles — drag to reshape the curve (writes a
+  // timeline.<label>.points overlay patch that survives base regeneration).
+  // Points are in the target's parent space; correct for top-level targets.
+  ctx.save();
+  ctx.setTransform(1, 0, 0, 1, 0, 0);
+  for (const mp of store.motionPaths()) {
+    ctx.strokeStyle = "rgba(125,154,255,0.4)";
+    ctx.lineWidth = 1.5;
+    ctx.setLineDash([4, 4]);
+    ctx.beginPath();
+    mp.points.forEach(([x, y], i) => (i === 0 ? ctx.moveTo(x, y) : ctx.lineTo(x, y)));
+    ctx.stroke();
+    ctx.setLineDash([]);
+    for (const [x, y] of mp.points) {
+      ctx.beginPath();
+      ctx.arc(x, y, HANDLE_R, 0, Math.PI * 2);
+      ctx.fillStyle = "#7d9aff";
+      ctx.fill();
+      ctx.strokeStyle = "#0b0b12";
+      ctx.lineWidth = 2;
+      ctx.stroke();
+    }
+  }
+  ctx.restore();
+
   const duration = store.compiled.duration;
   scrub.value = String(duration ? t / duration : 0);
   timeLabel.textContent = `${t.toFixed(3)} / ${duration.toFixed(3)}`;
 }
 
+const HANDLE_R = 9;
+
+/** Map a mouse event to scene coordinates (canvas is rendered at scene size, displayed scaled). */
+function clientToScene(ev: MouseEvent): [number, number] {
+  const r = canvas.getBoundingClientRect();
+  return [((ev.clientX - r.left) * canvas.width) / r.width, ((ev.clientY - r.top) * canvas.height) / r.height];
+}
+
+let drag: { label: string; index: number; points: [number, number][] } | null = null;
+canvas.addEventListener("mousedown", (ev) => {
+  if (!store) return;
+  const [x, y] = clientToScene(ev);
+  for (const mp of store.motionPaths()) {
+    const i = mp.points.findIndex(([px, py]) => Math.hypot(px - x, py - y) <= HANDLE_R + 4);
+    if (i >= 0) {
+      drag = { label: mp.label, index: i, points: mp.points.map((p) => [...p] as [number, number]) };
+      playing = false;
+      playBtn.textContent = "play";
+      ev.preventDefault();
+      return;
+    }
+  }
+});
+window.addEventListener("mousemove", (ev) => {
+  if (!drag || !store) return;
+  const [x, y] = clientToScene(ev);
+  drag.points[drag.index] = [Math.round(x), Math.round(y)];
+  store.setMotionPathPoints(drag.label, drag.points);
+  draw();
+});
+window.addEventListener("mouseup", () => {
+  drag = null;
+});
+
 function tick(now: number) {
   if (playing && store) {
     t += (now - lastTick) / 1000;

package/preview/src/panel.ts

@@ -200,6 +200,39 @@ export function buildPanel(store: EditorStore, root: HTMLElement) {
       }
     }
 
+    // --- beats (semantic groups) ---
+    const beats: Extract<TimelineIR, { kind: "beat" }>[] = [];
+    const beatOf = new Map<string, string>();
+    const walkBeats = (tl: TimelineIR, owner?: string) => {
+      if (tl.kind === "beat") {
+        beats.push(tl);
+        tl.children.forEach((c) => walkBeats(c, tl.name));
+        return;
+      }
+      if ("label" in tl && tl.label !== undefined && owner) beatOf.set(tl.label, owner);
+      if ("children" in tl) tl.children.forEach((c) => walkBeats(c, owner));
+    };
+    if (ir.timeline) walkBeats(ir.timeline);
+    if (beats.length > 0) {
+      root.append(el("h3", {}, "Beats"));
+      for (const b of beats) {
+        const card = el("div", { class: "step-card beat-card" },
+          el("div", {}, `${b.name} `, el("span", { class: "kind" }, "(beat)")),
+        );
+        const gapRow = makeControl("gap", b.gap ?? 0, store.hasTimelineEdit(b.name, "gap"),
+          (v) => store.setTimelineParam(b.name, "gap", Number(v)),
+          () => store.unsetTimelineParam(b.name, "gap"));
+        gapRow.prepend(el("label", {}, "gap"));
+        card.append(gapRow);
+        const scaleRow = makeControl("scale", b.scale ?? 1, store.hasTimelineEdit(b.name, "scale"),
+          (v) => store.setTimelineParam(b.name, "scale", Number(v)),
+          () => store.unsetTimelineParam(b.name, "scale"));
+        scaleRow.prepend(el("label", {}, "scale"));
+        card.append(scaleRow);
+        root.append(card);
+      }
+    }
+
     // --- labeled timeline steps ---
     const steps: Extract<TimelineIR, { label?: string }>[] = [];
     const walkTl = (tl: TimelineIR) => {
@@ -211,9 +244,10 @@ export function buildPanel(store: EditorStore, root: HTMLElement) {
       root.append(el("h3", {}, "Timeline"));
       for (const step of steps) {
         const label = step.label!;
-        const card = el("div", { class: "step-card" },
-          el("div", {}, `${label} `, el("span", { class: "kind" }, `(${step.kind})`)),
-        );
+        const beatName = beatOf.get(label);
+        const head = el("div", {}, `${label} `, el("span", { class: "kind" }, `(${step.kind})`));
+        if (beatName) head.append(el("span", { class: "badge" }, ` ↳ ${beatName}`));
+        const card = el("div", { class: "step-card" }, head);
         const durRow = makeControl(
           "duration",
           "duration" in step ? (step.duration ?? 0.5) : 0.5,

package/preview/src/store.ts

@@ -15,6 +15,7 @@ import {
   type OverlayDoc,
   type PropValue,
   type SceneIR,
+  type TimelineIR,
 } from "@reframe/core";
 
 export type ChangeKind = "value" | "structure";
@@ -91,12 +92,37 @@ export class EditorStore {
     this.recompose("structure");
   }
 
-  setTimelineParam(label: string, key: "duration" | "ease" | "stagger", value: number | string) {
+  setTimelineParam(
+    label: string,
+    key: "duration" | "ease" | "stagger" | "at" | "gap" | "scale" | "order",
+    value: number | string,
+  ) {
     ((this.draft.timeline ??= {})[label] ??= {})[key] = value as never;
     this.recompose("value");
   }
 
-  unsetTimelineParam(label: string, key: "duration" | "ease" | "stagger") {
+  /** Labeled motionPath steps with their (possibly overlay-edited) waypoints —
+   *  drives the preview's draggable handles and is exposed on window.__store. */
+  motionPaths(): { label: string; points: [number, number][] }[] {
+    const out: { label: string; points: [number, number][] }[] = [];
+    const walk = (tl: TimelineIR) => {
+      if (tl.kind === "motionPath" && tl.label) out.push({ label: tl.label, points: tl.points });
+      if ("children" in tl) tl.children.forEach(walk);
+    };
+    if (this.compiled.ir.timeline) walk(this.compiled.ir.timeline);
+    return out;
+  }
+
+  /** A dragged waypoint writes the whole points array as a timeline patch. */
+  setMotionPathPoints(label: string, points: [number, number][]) {
+    ((this.draft.timeline ??= {})[label] ??= {}).points = points;
+    this.recompose("value");
+  }
+
+  unsetTimelineParam(
+    label: string,
+    key: "duration" | "ease" | "stagger" | "at" | "gap" | "scale" | "order",
+  ) {
     delete this.draft.timeline?.[label]?.[key];
     this.prune();
     this.recompose("structure");