reframe-video 0.1.2 → 0.2.0

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

@@ -1,12 +1,15 @@
 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 { 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/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/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;

package/guides/edsl-guide.md

@@ -82,13 +82,14 @@ 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? })`
+- `motionPath(nodeId, [[x,y], ...], { duration, ease, curviness?, 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).
+  `curviness` shapes the path: `1` smooth (default), `0` sharp corners, `>1` loopier.
 - `wait(seconds)` — hold.
 
 Eases: `linear`, `easeIn/Out/InOutQuad`, `easeIn/Out/InOutCubic`,

package/package.json

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

package/preview/index.html

@@ -11,8 +11,11 @@
   #content { flex: 1; display: flex; min-height: 0; }
   #stage-wrap { flex: 1; display: flex; align-items: center; justify-content: center; min-width: 0; padding: 16px; }
   canvas { max-width: 100%; max-height: 100%; box-shadow: 0 4px 32px rgba(0,0,0,.5); }
-  #bar { display: flex; gap: 12px; align-items: center; padding: 12px 16px; background: #232329; }
-  #scrub { flex: 1; }
+  #bar { display: flex; gap: 8px; align-items: center; padding: 12px 16px; background: #232329; }
+  #scrub-wrap { flex: 1; position: relative; display: flex; align-items: center; }
+  #scrub { width: 100%; }
+  #loop-band { position: absolute; top: 50%; transform: translateY(-50%); height: 6px; background: rgba(125,154,255,.35); border-radius: 3px; pointer-events: none; display: none; }
+  button.on { background: #3a4a86; border-color: #7d9aff; color: #fff; }
   select, button, input[type=text], input[type=number] { background: #2e2e36; color: #ddd; border: 1px solid #444; border-radius: 4px; padding: 3px 8px; font: 12px system-ui; }
   input[type=number] { width: 64px; }
   input[type=color] { width: 40px; height: 22px; padding: 0; border: 1px solid #444; background: none; }
@@ -42,6 +45,42 @@
   #report details { color: #8a8a96; }
   #io { display: flex; gap: 6px; flex-wrap: wrap; margin-top: 8px; }
   #overlay-name { width: 100%; margin-bottom: 6px; box-sizing: border-box; }
+  .beat-group { margin: 4px 0 2px; border-left: 2px solid #3a4a86; padding-left: 6px; }
+  .beat-lane { padding: 1px 4px; border-radius: 3px; cursor: pointer; color: #b9c2da; font-size: 12px; }
+  .beat-lane:hover { background: #2a2a32; }
+  .beat-lane.selected { background: #31313c; color: #fff; }
+  .beat-lane.missing { color: #ff7b72; cursor: default; }
+  .beat-markers { color: #7d9aff; font-size: 11px; margin-top: 3px; opacity: 0.85; }
+  /* bottom timeline: scene bands (composition) or top-level beat bands (one scene) */
+  #comp-timeline { display: none; padding: 8px 16px 10px; background: #1f1f25; border-top: 1px solid #333; }
+  #comp-timeline.on { display: block; }
+  #comp-timeline .ct-title { color: #8a8a96; font-size: 11px; text-transform: uppercase; letter-spacing: 1px; margin-bottom: 6px; }
+  .ct-bandrow { display: flex; align-items: flex-start; }
+  .ct-bandrow .tk-label { padding-top: 4px; }
+  #comp-track { position: relative; flex: 1; min-width: 0; background: #16161b; border-radius: 6px; }
+  .ct-scene { position: absolute; background: #2a2a32; border: 1px solid #3a3a44; border-radius: 5px; cursor: pointer; overflow: hidden; box-sizing: border-box; padding: 4px 8px; white-space: nowrap; }
+  .ct-scene:hover { border-color: #7d9aff; }
+  .ct-scene.active { background: #31313c; border-color: #7d9aff; color: #fff; }
+  .ct-scene.beat { border-style: dashed; }
+  .ct-scene .ct-range { color: #8a8a96; font-size: 10px; margin-left: 6px; font-variant-numeric: tabular-nums; }
+  #ct-playhead { position: absolute; top: -2px; bottom: -2px; width: 2px; background: #ff4d00; pointer-events: none; }
+  /* node tracks (dope sheet): each node a lane, its motion segments as bars */
+  .tk-toggle { background: none; border: 1px solid #3a3a44; color: #8a8a96; font-size: 11px; border-radius: 4px; padding: 2px 8px; cursor: pointer; margin-top: 8px; }
+  .tk-toggle:hover { border-color: #7d9aff; color: #ddd; }
+  #comp-tracks { position: relative; margin-top: 6px; max-height: 150px; overflow-y: auto; display: none; }
+  #comp-tracks.on { display: block; }
+  .tk-row { display: flex; align-items: center; height: 18px; }
+  .tk-label { width: 120px; flex: none; color: #99a; font-size: 11px; padding: 0 6px; cursor: pointer; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; box-sizing: border-box; }
+  .tk-label:hover { color: #fff; }
+  .tk-row.selected .tk-label { color: #fff; font-weight: 600; }
+  .tk-lane { position: relative; flex: 1; height: 12px; background: #16161b; border-radius: 3px; }
+  .tk-bar { position: absolute; top: 1px; height: 10px; background: #3a4a86; border-radius: 2px; cursor: pointer; min-width: 3px; box-sizing: border-box; }
+  .tk-bar:hover { background: #7d9aff; }
+  .tk-bar.path { background: #b06a2a; }
+  .tk-bar.group { background: #4a4a58; }
+  .tk-bar.group:hover { background: #5e5e70; }
+  .tk-row.selected .tk-bar { background: #7d9aff; }
+  #tk-playhead { position: absolute; top: 0; bottom: 0; width: 2px; background: #ff4d00; pointer-events: none; }
 </style>
 </head>
 <body>
@@ -52,9 +91,23 @@
   <div id="bar">
     <select id="scene-select"></select>
     <button id="play">play</button>
-    <input id="scrub" type="range" min="0" max="1" step="0.001" value="0" />
+    <button id="play-all" title="play the whole composition across scenes" style="display:none">play all</button>
+    <button id="mark-in" title="set loop start to current time">[</button>
+    <button id="loop" title="loop the in/out range">loop</button>
+    <button id="mark-out" title="set loop end to current time">]</button>
+    <select id="speed" title="playback speed">
+      <option value="0.25">0.25×</option>
+      <option value="0.5">0.5×</option>
+      <option value="1" selected>1×</option>
+      <option value="2">2×</option>
+    </select>
+    <div id="scrub-wrap">
+      <div id="loop-band"></div>
+      <input id="scrub" type="range" min="0" max="1" step="0.001" value="0" />
+    </div>
     <span id="time">0.000 / 0.000</span>
   </div>
+  <div id="comp-timeline"></div>
   <script type="module" src="/src/main.ts"></script>
 </body>
 </html>