reframe-video 0.1.0 → 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, 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;
@@ -30,12 +30,33 @@ export declare function line(props: {
 export declare function text(props: {
     id: string;
 } & TextProps): NodeIR;
+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;
@@ -49,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

@@ -53,6 +53,23 @@ export type DisplayOp = (OpBase & {
     letterSpacing: number;
     align: TextAlign;
     baseline: TextBaseline;
+}) | (OpBase & {
+    type: "image";
+    /** Raw src string as authored in the IR — consumers resolve it. */
+    src: string;
+    width: number;
+    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,8 +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,37 @@ 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
+     * stretched to width×height. As a string prop it switches discretely at
+     * segment start (no crossfade) — for hard-cut sequences stack image
+     * nodes and step their opacity instead.
+     */
+    src: string;
+    width: number;
+    height: number;
+}
 export type NodeIR = {
     type: "rect";
     id: string;
@@ -81,6 +112,14 @@ export type NodeIR = {
     type: "text";
     id: string;
     props: TextProps;
+} | {
+    type: "image";
+    id: string;
+    props: ImageProps;
+} | {
+    type: "path";
+    id: string;
+    props: PathProps;
 } | {
     type: "group";
     id: string;
@@ -126,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;
@@ -210,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,18 @@ 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) —
+  for hard-cut frame sequences stack image nodes and step their `opacity`; for
+  a dissolve, crossfade two nodes' opacity.
 - `group({ id, x, y, opacity?, rotation?, scale?, anchor? }, children)` — children's
   coordinates are relative to the group; group opacity/transform multiply down.
 
@@ -70,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.0",
+  "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

@@ -5,7 +5,7 @@
  * path never uses wall-clock time.
  */
 
-import { evaluate, type DisplayOp, type SceneIR } from "@reframe/core";
+import { collectImageSrcs, evaluate, type DisplayOp, type SceneIR } from "@reframe/core";
 import { renderFrame } from "@reframe/renderer-canvas";
 import { userScenes } from "virtual:reframe-user-scenes";
 import { buildPanel } from "./panel.js";
@@ -13,17 +13,23 @@ import { EditorStore } from "./store.js";
 
 interface SceneEntry {
   label: string;
+  /** Absolute directory of the scene file — relative image srcs resolve here. */
+  dir: string;
   load: () => Promise<{ default: SceneIR }>;
 }
 
 const exampleModules = ({} as Record<string, () => Promise<{ default: SceneIR }>>);
 const modules: Record<string, SceneEntry> = {};
 for (const path of Object.keys(exampleModules).sort()) {
-  modules[path] = { label: path.split("/").pop()!.replace(".ts", ""), load: exampleModules[path]! };
+  modules[path] = {
+    label: path.split("/").pop()!.replace(".ts", ""),
+    dir: __REFRAME_EXAMPLES_DIR__,
+    load: exampleModules[path]!,
+  };
 }
 // scenes from the directory `reframe preview` was invoked in
-for (const { name, load } of userScenes) {
-  modules[`user:${name}`] ??= { label: `${name} (cwd)`, load };
+for (const { name, dir, load } of userScenes) {
+  modules[`user:${name}`] ??= { label: `${name} (cwd)`, dir, load };
 }
 
 const canvas = document.getElementById("canvas") as HTMLCanvasElement;
@@ -47,9 +53,43 @@ for (const [key, entry] of Object.entries(modules)) {
   select.appendChild(option);
 }
 
+// decoded images keyed by raw src; missing entries render as a placeholder
+const images = new Map<string, CanvasImageSource>();
+const imageLoads = new Map<string, Promise<void>>();
+let sceneDir = "";
+
+/** Load any not-yet-loaded srcs of the current scene via /@fs. */
+function ensureImages(): Promise<void> {
+  if (!store) return Promise.resolve();
+  const pending: Promise<void>[] = [];
+  for (const src of collectImageSrcs(store.compiled.ir)) {
+    if (images.has(src) || imageLoads.has(src)) continue;
+    const url = `/@fs${src.startsWith("/") ? src : `${sceneDir}/${src}`}`;
+    const load = new Promise<void>((done) => {
+      const img = new Image();
+      img.onload = () => {
+        images.set(src, img);
+        done();
+        draw();
+      };
+      img.onerror = () => {
+        console.warn(`image "${src}" failed to load (${url}) — rendering placeholder`);
+        done();
+      };
+      img.src = url;
+    });
+    imageLoads.set(src, load);
+    pending.push(load);
+  }
+  return Promise.all(pending).then(() => undefined);
+}
+
 async function loadScene(path: string) {
   const mod = await modules[path]!.load();
   store = new EditorStore(mod.default);
+  sceneDir = modules[path]!.dir;
+  images.clear();
+  imageLoads.clear();
   (window as unknown as { __store: EditorStore }).__store = store; // debug/testing hook
   panel = buildPanel(store, panelRoot);
   canvas.width = store.compiled.ir.size.width;
@@ -58,9 +98,11 @@ async function loadScene(path: string) {
     t = Math.min(t, store!.compiled.duration);
     if (kind === "structure") panel!.rebuild();
     else panel!.refreshReport();
+    void ensureImages(); // an edited src loads lazily, then redraws
     draw();
   });
   await document.fonts.ready;
+  await ensureImages();
   t = 0;
   panel.rebuild();
   draw();
@@ -73,7 +115,8 @@ function applyMat(m: number[], x: number, y: number): [number, number] {
 function opCorners(op: DisplayOp): [number, number][] {
   switch (op.type) {
     case "rect":
-    case "ellipse": {
+    case "ellipse":
+    case "image": {
       const { offsetX: x, offsetY: y, width: w, height: h } = op;
       return [[x, y], [x + w, y], [x + w, y + h], [x, y + h]].map(([px, py]) =>
         applyMat(op.transform, px!, py!),
@@ -91,12 +134,15 @@ 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)];
   }
 }
 
 function draw() {
   if (!store) return;
-  renderFrame(ctx, store.compiled, t);
+  renderFrame(ctx, store.compiled, t, images);
 
   if (store.selectedId) {
     const ops = evaluate(store.compiled, t).filter((op) => op.id === store!.selectedId);
@@ -115,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;