reframe-video 0.1.0

package/dist/renderer-canvas.js

@@ -0,0 +1,89 @@
+// ../renderer-canvas/src/index.ts
+import { evaluate } from "@reframe/core";
+function renderFrame(ctx, compiled, t) {
+  const { size, background } = compiled.ir;
+  ctx.setTransform(1, 0, 0, 1, 0, 0);
+  ctx.clearRect(0, 0, size.width, size.height);
+  if (background) {
+    ctx.fillStyle = background;
+    ctx.fillRect(0, 0, size.width, size.height);
+  }
+  drawDisplayList(ctx, evaluate(compiled, t));
+}
+function drawDisplayList(ctx, ops) {
+  for (const op of ops) {
+    ctx.save();
+    ctx.setTransform(...op.transform);
+    ctx.globalAlpha = Math.max(0, Math.min(1, op.opacity));
+    switch (op.type) {
+      case "rect": {
+        ctx.beginPath();
+        if (op.radius && op.radius > 0) {
+          ctx.roundRect(op.offsetX, op.offsetY, op.width, op.height, op.radius);
+        } else {
+          ctx.rect(op.offsetX, op.offsetY, op.width, op.height);
+        }
+        if (op.fill) {
+          ctx.fillStyle = op.fill;
+          ctx.fill();
+        }
+        if (op.stroke) {
+          ctx.strokeStyle = op.stroke;
+          ctx.lineWidth = op.strokeWidth ?? 1;
+          ctx.stroke();
+        }
+        break;
+      }
+      case "ellipse": {
+        ctx.beginPath();
+        ctx.ellipse(
+          op.offsetX + op.width / 2,
+          op.offsetY + op.height / 2,
+          Math.abs(op.width / 2),
+          Math.abs(op.height / 2),
+          0,
+          0,
+          Math.PI * 2
+        );
+        if (op.fill) {
+          ctx.fillStyle = op.fill;
+          ctx.fill();
+        }
+        if (op.stroke) {
+          ctx.strokeStyle = op.stroke;
+          ctx.lineWidth = op.strokeWidth ?? 1;
+          ctx.stroke();
+        }
+        break;
+      }
+      case "line": {
+        ctx.beginPath();
+        ctx.moveTo(op.x1, op.y1);
+        ctx.lineTo(op.x2, op.y2);
+        ctx.strokeStyle = op.stroke;
+        ctx.lineWidth = op.strokeWidth;
+        ctx.lineCap = "round";
+        ctx.stroke();
+        break;
+      }
+      case "text": {
+        ctx.font = `${op.fontWeight} ${op.fontSize}px ${quoteFamily(op.fontFamily)}`;
+        if (op.letterSpacing) ctx.letterSpacing = `${op.letterSpacing}px`;
+        ctx.textAlign = op.align;
+        ctx.textBaseline = op.baseline;
+        ctx.fillStyle = op.fill;
+        ctx.fillText(op.content, 0, 0);
+        if (op.letterSpacing) ctx.letterSpacing = "0px";
+        break;
+      }
+    }
+    ctx.restore();
+  }
+}
+function quoteFamily(family) {
+  return family.includes(" ") && !family.includes('"') ? `"${family}"` : family;
+}
+export {
+  drawDisplayList,
+  renderFrame
+};

package/dist/types/audio.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Audio cue resolution: turn label-anchored cues into an absolute-time plan.
+ * Pure data in, pure data out — the renderer only executes the plan, so the
+ * plan itself is golden-testable and reusable (e.g. preview cue markers).
+ *
+ * Anchoring to labels is the point: retime a step via an overlay, or let an
+ * AI regenerate the scene, and the sound design follows.
+ */
+import type { CompiledScene } from "./compile.js";
+import type { SfxName } from "./ir.js";
+/** Nominal cue lengths (s) for duck-window math; file cues use a default. */
+export declare const SFX_DURATION: Record<SfxName, number>;
+export interface ResolvedCue {
+    t: number;
+    gain: number;
+    duration: number;
+    source: {
+        kind: "sfx";
+        name: SfxName;
+        params: Record<string, number>;
+    } | {
+        kind: "file";
+        path: string;
+    };
+}
+export interface AudioPlan {
+    duration: number;
+    bgm: {
+        source: {
+            kind: "file";
+            path: string;
+        } | {
+            kind: "synth";
+            name: "ambient-pad";
+        };
+        gain: number;
+        fadeIn: number;
+        fadeOut: number;
+        duck: {
+            depth: number;
+            attack: number;
+            release: number;
+        } | null;
+    } | null;
+    cues: ResolvedCue[];
+    /** Merged [t0, t1] cue windows the bed should duck under. */
+    duckWindows: {
+        t0: number;
+        t1: number;
+    }[];
+    warnings: string[];
+}
+export declare function resolveAudioPlan(compiled: CompiledScene): AudioPlan | null;

package/dist/types/behaviors.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Named parametric behaviors (Fran-style continuous-time functions).
+ * Composed additively on top of the timeline value. All deterministic:
+ * randomness comes from an explicit seed, never Math.random.
+ */
+import type { BehaviorIR } from "./ir.js";
+export declare function sampleBehavior(b: BehaviorIR["behavior"], t: number): number;

package/dist/types/compile.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Compile the authored structure (states + timeline tree) into a flat list of
+ * property segments with absolute times and baked `from` values.
+ *
+ * The tree is the canonical IR; segments are a derived runtime artifact.
+ * Baking `from` at compile time is what makes `to("state")` synthesize
+ * "current value -> target" transitions deterministically (Gemini-style
+ * start/end synthesis): everything is data, so "current value" is computable
+ * without running anything.
+ */
+import type { NodeIR, PropValue, SceneIR, Ease } from "./ir.js";
+export interface PropertySegment {
+    target: string;
+    prop: string;
+    t0: number;
+    t1: number;
+    from: PropValue;
+    to: PropValue;
+    ease?: Ease;
+}
+export interface LabelSpan {
+    t0: number;
+    t1: number;
+}
+export interface CompiledScene {
+    ir: SceneIR;
+    duration: number;
+    /** Keyed by `${target}.${prop}`, sorted by t0. */
+    segments: Map<string, PropertySegment[]>;
+    /** 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. */
+    labelTimes: Map<string, LabelSpan>;
+}
+export declare function compileScene(ir: SceneIR): CompiledScene;

package/dist/types/compose.d.ts

@@ -0,0 +1,64 @@
+/**
+ * USD-style non-destructive layer composition: human edits live in overlay
+ * documents that re-apply on top of a regenerated base scene.
+ *
+ * Contract: composeScene never throws because the base drifted (a renamed or
+ * retyped node) — those edits are skipped and reported as orphans, loudly.
+ * Defects in the overlay itself (duplicate ids, invalid values) surface as
+ * 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";
+export interface OverlayDoc {
+    reframeOverlay: 1;
+    /** Shown in reports; falls back to "overlay-<index>". */
+    name?: string;
+    /** Scene id this overlay was authored against — mismatch is a warning. */
+    target?: string;
+    scene?: {
+        background?: string;
+        duration?: number;
+        fps?: number;
+    };
+    /** nodeId -> prop -> value; null deletes the prop key (USD "block"). */
+    nodes?: Record<string, Record<string, PropValue | null>>;
+    /** stateName -> nodeId -> prop -> value/null. */
+    states?: Record<string, Record<string, Record<string, PropValue | null>>>;
+    behaviors?: {
+        /** Upsert keyed by (target, prop): replaces a matching behavior or appends. */
+        set?: BehaviorIR[];
+        remove?: {
+            target: string;
+            prop: string;
+        }[];
+    };
+    /** 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.
+     */
+    timeline?: Record<string, {
+        duration?: number;
+        ease?: Ease;
+        stagger?: number;
+    }>;
+}
+export interface ComposeReport {
+    applied: {
+        layer: string;
+        address: string;
+        action: "set" | "unset" | "add-node" | "behavior-set" | "behavior-remove";
+    }[];
+    orphans: {
+        layer: string;
+        address: string;
+        reason: string;
+    }[];
+    warnings: string[];
+}
+export declare function composeScene(base: SceneIR, ...overlays: OverlayDoc[]): {
+    ir: SceneIR;
+    report: ComposeReport;
+};
+export declare function formatComposeReport(report: ComposeReport): string;

package/dist/types/dsl.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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";
+export interface SceneInput {
+    id: string;
+    size: Size;
+    fps?: number;
+    duration?: number;
+    background?: string;
+    nodes: NodeIR[];
+    states?: Record<string, StateOverride>;
+    initial?: string;
+    timeline?: TimelineIR;
+    behaviors?: BehaviorIR[];
+    audio?: AudioIR;
+    meta?: Record<string, unknown>;
+}
+export declare function scene(input: SceneInput): SceneIR;
+export declare function rect(props: {
+    id: string;
+} & RectProps): NodeIR;
+export declare function ellipse(props: {
+    id: string;
+} & EllipseProps): NodeIR;
+export declare function line(props: {
+    id: string;
+} & LineProps): NodeIR;
+export declare function text(props: {
+    id: string;
+} & TextProps): 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 declare function to(state: string, opts?: {
+    duration?: number;
+    ease?: Ease;
+    stagger?: number;
+    filter?: string[];
+    label?: string;
+}): TimelineIR;
+export declare function tween(target: string, props: Record<string, PropValue>, opts?: {
+    duration?: number;
+    ease?: Ease;
+    label?: string;
+}): TimelineIR;
+export declare function wait(duration: number, label?: string): TimelineIR;
+export interface BehaviorWindow {
+    from?: number;
+    until?: number;
+    ramp?: number;
+}
+export declare function oscillate(target: string, prop: string, params: {
+    amplitude: number;
+    frequency: number;
+    phase?: number;
+}, window?: BehaviorWindow): BehaviorIR;
+export declare function wiggle(target: string, prop: string, params: {
+    amplitude: number;
+    frequency: number;
+    seed: number;
+}, window?: BehaviorWindow): BehaviorIR;

package/dist/types/evaluate.d.ts

@@ -0,0 +1,59 @@
+/**
+ * evaluate(compiled, t) -> DisplayList. The pure function at the heart of the
+ * determinism contract: same compiled scene + same t = same display list,
+ * always. Renderers only draw; they never compute animation.
+ */
+import type { CompiledScene } from "./compile.js";
+/** Canvas-style 2D affine matrix [a, b, c, d, e, f]. */
+export type Mat2D = [number, number, number, number, number, number];
+export type TextAlign = "left" | "center" | "right";
+export type TextBaseline = "top" | "middle" | "bottom";
+interface OpBase {
+    /** Source node id — lets editors map ops back to the scene graph. */
+    id: string;
+    /** Maps local coords (origin = anchor point) to scene coords. */
+    transform: Mat2D;
+    /** Cumulative opacity, parent-multiplied. */
+    opacity: number;
+}
+export type DisplayOp = (OpBase & {
+    type: "rect";
+    width: number;
+    height: number;
+    offsetX: number;
+    offsetY: number;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    radius?: number;
+}) | (OpBase & {
+    type: "ellipse";
+    width: number;
+    height: number;
+    offsetX: number;
+    offsetY: number;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+}) | (OpBase & {
+    type: "line";
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    stroke: string;
+    strokeWidth: number;
+}) | (OpBase & {
+    type: "text";
+    content: string;
+    fontFamily: string;
+    fontSize: number;
+    fontWeight: number;
+    fill: string;
+    letterSpacing: number;
+    align: TextAlign;
+    baseline: TextBaseline;
+});
+export type DisplayList = DisplayOp[];
+export declare function evaluate(compiled: CompiledScene, t: number): DisplayList;
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,9 @@
+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 { 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";

package/dist/types/interpolate.d.ts

@@ -0,0 +1,12 @@
+import type { Ease, PropValue } from "./ir.js";
+type EaseFn = (u: number) => number;
+export declare const EASE_NAMES: import("./ir.js").EaseName[];
+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.
+ */
+export declare function lerpValue(from: PropValue, to: PropValue, u: number): PropValue;
+export {};

package/dist/types/ir.d.ts

@@ -0,0 +1,213 @@
+/**
+ * reframe IR — the serialized scene graph.
+ *
+ * Invariant: every value in the IR is plain JSON data. No functions, ever.
+ * Easing is a name or bezier params, dynamic motion is a named behavior with
+ * params. `JSON.stringify(scene)` IS the serialization format.
+ *
+ * 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 Ease = EaseName | {
+    cubicBezier: [number, number, number, number];
+};
+export type Anchor = "top-left" | "top-center" | "top-right" | "center-left" | "center" | "center-right" | "bottom-left" | "bottom-center" | "bottom-right";
+export interface Size {
+    width: number;
+    height: number;
+}
+/** Props shared by every node. All numeric props are animatable. */
+export interface BaseProps {
+    x: number;
+    y: number;
+    opacity?: number;
+    rotation?: number;
+    scale?: number;
+    anchor?: Anchor;
+}
+export interface RectProps extends BaseProps {
+    width: number;
+    height: number;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    radius?: number;
+}
+export interface EllipseProps extends BaseProps {
+    width: number;
+    height: number;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+}
+export interface LineProps {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    stroke: string;
+    strokeWidth?: number;
+    opacity?: number;
+    /** 0..1 — how much of the line is drawn (for draw-on effects). */
+    progress?: number;
+}
+export interface TextProps extends BaseProps {
+    /** Numbers interpolate (count-up) and render via toFixed(contentDecimals). */
+    content: string | number;
+    /** Decimal places when content is numeric (default 0). */
+    contentDecimals?: number;
+    fontFamily: string;
+    fontSize: number;
+    fontWeight?: number;
+    fill?: string;
+    letterSpacing?: number;
+}
+export interface GroupProps extends BaseProps {
+}
+export type NodeIR = {
+    type: "rect";
+    id: string;
+    props: RectProps;
+} | {
+    type: "ellipse";
+    id: string;
+    props: EllipseProps;
+} | {
+    type: "line";
+    id: string;
+    props: LineProps;
+} | {
+    type: "text";
+    id: string;
+    props: TextProps;
+} | {
+    type: "group";
+    id: string;
+    props: GroupProps;
+    children: NodeIR[];
+};
+export type PropValue = number | string;
+/**
+ * A state is a sparse override: only the props it mentions differ from base.
+ * This shape is isomorphic to a USD-style override layer — future
+ * human-edit layers compose with the same merge.
+ */
+export type StateOverride = Record<string, Record<string, PropValue>>;
+export type TimelineIR = {
+    kind: "seq";
+    children: TimelineIR[];
+} | {
+    kind: "par";
+    children: TimelineIR[];
+} | {
+    kind: "stagger";
+    interval: number;
+    children: TimelineIR[];
+} | {
+    kind: "to";
+    state: string;
+    duration?: number;
+    ease?: Ease;
+    /** Per-node offset (seconds), in node declaration order. */
+    stagger?: number;
+    /** Restrict the transition to these node ids. */
+    filter?: string[];
+    /** Stable address for overlay timeline patches; must be unique. */
+    label?: string;
+} | {
+    kind: "tween";
+    target: string;
+    props: Record<string, PropValue>;
+    duration?: number;
+    ease?: Ease;
+    label?: string;
+} | {
+    kind: "wait";
+    duration: number;
+    label?: string;
+};
+export interface BehaviorIR {
+    target: string;
+    prop: string;
+    /** Active window in seconds; omit for the whole scene. */
+    from?: number;
+    until?: number;
+    /** Linear fade length (s) at each window boundary, avoiding pops. Default 0.2. */
+    ramp?: number;
+    /** Composed additively on top of the timeline value. */
+    behavior: {
+        kind: "named";
+        name: "oscillate";
+        params: {
+            amplitude: number;
+            frequency: number;
+            phase?: number;
+        };
+    } | {
+        kind: "named";
+        name: "wiggle";
+        params: {
+            amplitude: number;
+            frequency: number;
+            seed: number;
+        };
+    };
+}
+export type SfxName = "whoosh" | "pop" | "tick" | "rise" | "shimmer" | "thud";
+export interface AudioCueIR {
+    /** Anchor: a timeline label (the step's start) or absolute seconds. */
+    at: string | number;
+    /** Seconds relative to the anchor (negative allowed; result clamps to 0). */
+    offset?: number;
+    /** Procedural SFX name — exactly one of sfx | file. */
+    sfx?: SfxName;
+    /** Audio file path (absolute, scene-relative, or assets/sfx-relative). */
+    file?: string;
+    /** Linear gain, default 1. */
+    gain?: number;
+    /** Synth parameter overrides (seed, duration, …) — numbers only. */
+    params?: Record<string, number>;
+}
+export interface AudioIR {
+    bgm?: {
+        file?: string;
+        /** License-free synthesized bed. */
+        synth?: "ambient-pad";
+        gain?: number;
+        fadeIn?: number;
+        fadeOut?: number;
+        /** Dip the bed under cues. false disables. */
+        duck?: {
+            depth?: number;
+            attack?: number;
+            release?: number;
+        } | false;
+    };
+    cues?: AudioCueIR[];
+}
+export interface SceneIR {
+    version: 1;
+    id: string;
+    size: Size;
+    /** Render hint only — semantics are continuous-time. */
+    fps?: number;
+    /** Inferred from the timeline when omitted. */
+    duration?: number;
+    background?: string;
+    nodes: NodeIR[];
+    states?: Record<string, StateOverride>;
+    /** State applied at t=0. */
+    initial?: string;
+    timeline?: TimelineIR;
+    behaviors?: BehaviorIR[];
+    /** Label-anchored sound design — cues survive retiming and regeneration. */
+    audio?: AudioIR;
+    /** Reserved for v2 (Madeus-style temporal constraints). */
+    constraints?: unknown[];
+    /** Editor-only data (Theatre.js state.json pattern). */
+    meta?: Record<string, unknown>;
+}
+export declare const DEFAULT_TO_DURATION = 0.5;
+export declare const DEFAULT_TWEEN_DURATION = 0.5;
+export declare const DEFAULT_FPS = 30;

package/dist/types/validate.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Scene validation with actionable error messages — these errors are the
+ * 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";
+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;