Skip to content

The VS Code of video editing, built for agents.

TypeScript

Refactor animation and keyframe handling in JSX and runtime

konstantin-paulusce04be1ddc70
diff --git a/apps/web/src/engine/editor.ts b/apps/web/src/engine/editor.ts
index da2191c1..fa860ab9 100644
--- a/apps/web/src/engine/editor.ts
+++ b/apps/web/src/engine/editor.ts
@@ -184,8 +184,8 @@ export class DocumentEditor {
/**
* Selects `entities`, replacing the current selection unless `extend` is
- * set. Selection is a document property (`selected` on the element, see
- * `PatchProps`), so it goes the way every editor change goes: the trait for
+ * set. Selection is a document property (`selected` on the element), so it
+ * goes the way every editor change goes: the trait for
* the canvas, an edit for the file. Deselection reports `false`, which the
* writer spells as the attribute's absence. Entities without a source
* (nothing mounted yet) only get the trait; the stage is not selectable.
diff --git a/packages/jsx/src/index.ts b/packages/jsx/src/index.ts
index b94d3272..0870e119 100644
--- a/packages/jsx/src/index.ts
+++ b/packages/jsx/src/index.ts
@@ -37,10 +37,8 @@ export type { CompositionTag, PropValue } from "./source";
export { useTicker, useFile } from "./hooks";
export type { Ticker } from "./hooks";
export type {
- Animatable,
AnimatableProperty,
AnimationProps,
- AnimationSpec,
AnimationType,
AudioProps,
CameraMatrix,
@@ -56,10 +54,8 @@ export type {
HtmlPaintProps,
HtmlProps,
ImageProps,
- Keyframe,
KeyframeProps,
KeyframeTrackProps,
- PatchProps,
RectProps,
SceneProps,
SequenceProps,
diff --git a/packages/jsx/src/types.ts b/packages/jsx/src/types.ts
index bcb627ab..be6b8b63 100644
--- a/packages/jsx/src/types.ts
+++ b/packages/jsx/src/types.ts
@@ -54,25 +54,11 @@ export type Easing =
| `spring(${string})`
| `steps(${string})`;
-export type Keyframe<T> = {
- /** Node-local time: 0 is where the clip begins (its `start`). Any `Time` format. */
- time: Time;
- value: T;
- /** Shapes the segment to the next keyframe; ignored on the last. Default "linear". */
- easing?: Easing;
-};
-
/**
- * A static value, or keyframes animating it over the node's local time.
- * Setting a static value removes any existing keyframe track on the property.
- */
-export type Animatable<T> = T | Keyframe<T>[];
-
-/**
- * The props a `<keyframeTrack>` can drive, by name: every `Animatable` prop.
- * Which entity's prop is the track's parent's (`width` under a `<stroke>` is
- * the line width, `value` under an `<effect>` its amount, `color`/`opacity`
- * under a paint the paint's).
+ * The props a `<keyframeTrack>` can drive, by name. Whose prop is the
+ * track's holder's: `x` under a `<rect>` is the rect's, `width` under a
+ * `<stroke>` the line width, `value` under an `<effect>` its amount,
+ * `color`/`opacity` under a paint the paint's.
*/
export type AnimatableProperty =
| "x"
@@ -98,7 +84,7 @@ export type TransitionType =
| "fadeToBlack"
| "fadeToWhite";
-/** The `transition` prop's value — see `PatchProps["transition"]`. */
+/** The `transition` prop's value — see `SequenceItemProps["transition"]`. */
export type TransitionSpec = {
/** Transition style. Default "dissolve". */
type?: TransitionType;
@@ -127,21 +113,6 @@ export type AnimationType =
| "appearChar"
| "scramble";
-/** One entry of the `animations` prop's list — see `PatchProps["animations"]`. */
-export type AnimationSpec = {
- /** Animation style. */
- type: AnimationType;
- /** "in" plays from the clip's head, "out" into its tail. Default "in". */
- phase?: "in" | "out";
- /** Length of the animation. Any `Time` format. Default 1 second. */
- duration?: Time;
- /**
- * Gap between the clip edge and the animation: after the head for "in",
- * before the tail for "out". Any `Time` format. Default 0.
- */
- delay?: Time;
-};
-
/** Caption style presets — the editor's caption inspector presets. */
export type CaptionPreset =
| "classic"
@@ -152,13 +123,15 @@ export type CaptionPreset =
| "guinea"
| "stark";
-/**
- * Every property assignable through the renderer's property-write path. This
- * is the single property table: element props pick from it, and a patch-style
- * command takes any subset per patch entry with identical value requirements,
- * so JSX and any patch API can't drift.
- */
-export type PatchProps = {
+// ── Shared prop groups ──────────────────────────────────────────────────────
+//
+// Props several elements share, each defined once so its type and doc are the
+// same wherever it appears. Element prop types compose these and add what is
+// theirs alone. Any prop can be animated by a `<keyframeTrack>` child naming
+// it (see `AnimatableProperty`); none takes keyframes inline.
+
+/** What every element the editor can point at carries. */
+type IdentityProps = {
/** Human-readable node name. */
name?: string;
/**
@@ -170,67 +143,40 @@ export type PatchProps = {
* selected; the editor writes the bare attribute and removes it again.
*/
selected?: boolean;
- /**
- * Whether this element is the one the playhead, timeline, and capture
- * operate on. Editor state carried by the source like `selected`, with two
- * rules the runtime holds: at most one element is active, and only a root
- * (a direct child of `<stage>`) can be; a nested `active` is dropped. When
- * a file names more than one, the last one rendered wins.
- */
- active?: boolean;
- /** Position relative to the parent, px. Defaults to 0. Animatable. */
- x?: Animatable<number>;
- y?: Animatable<number>;
+};
+
+type PositionProps = {
+ /** Position relative to the parent, px. Defaults to 0. */
+ x?: number;
+ y?: number;
+};
+
+type OffsetProps = {
/**
* Render-time translation on top of `x`/`y`, px — moves the drawn content
* without changing the layout box (the property slide animations drive).
- * Subpixel values are kept. Defaults to 0. Animatable.
- */
- offsetX?: Animatable<number>;
- offsetY?: Animatable<number>;
- /**
- * Box size, px. Defaults to the parent's size. Animatable. On a `<stroke>`
- * `width` is the line width instead, px (default 1).
- */
- width?: Animatable<number>;
- height?: Animatable<number>;
- /** Rotation in degrees. Animatable. */
- rotation?: Animatable<number>;
- /** Opacity, 0–1 (out-of-range values clamp, like CSS). Animatable. */
- opacity?: Animatable<number>;
- /** Uniform corner radius, px. Animatable. */
- cornerRadius?: Animatable<number>;
- /** Blur radius of a `<shadow>`, px. Default 0. Animatable. */
- blur?: Animatable<number>;
- /** How a `<stroke>` turns corners. Default "miter". */
- join?: StrokeJoin;
- /** How a `<stroke>` ends open paths (text glyphs). Default "butt". */
- cap?: StrokeCap;
- /** Miter length limit of a `<stroke>`, as a ratio of its width. Default 10. */
- miterLimit?: number;
- /** Which filter an `<effect>` applies, or which preset an `<animation>` plays. */
- type?: EffectType | AnimationType;
- /**
- * An `<effect>`'s amount: px for "blur", degrees for "hueRotate", 0–1
- * otherwise (animatable). On a `<keyframe>`, the value at its `time`: a
- * number, or any CSS color on a `color` track.
- */
- value?: Animatable<number> | string;
- /** Which prop a `<keyframeTrack>` animates, on the element holding the track. */
- property?: AnimatableProperty;
- /** A `<keyframe>`'s time, node-local: 0 is where the clip begins (its `start`). Any `Time` format. */
- time?: Time;
- /** Shapes the segment from a `<keyframe>` to the next one; ignored on the last. Default "linear". */
- easing?: Easing;
- /** Whether an `<animation>` plays from the clip's head ("in") or into its tail ("out"). Default "in". */
- phase?: "in" | "out";
- /** Length of an `<animation>`. Any `Time` format. Default 1 second. */
- duration?: Time;
- /**
- * Gap between the clip edge and an `<animation>`: after the head for "in",
- * before the tail for "out". Any `Time` format. Default 0.
+ * Subpixel values are kept. Defaults to 0.
*/
- delay?: Time;
+ offsetX?: number;
+ offsetY?: number;
+};
+
+type SizeProps = {
+ /** Box size, px. Defaults to the parent's size. */
+ width?: number;
+ height?: number;
+};
+
+type TransformProps = PositionProps & OffsetProps & SizeProps & {
+ /** Rotation in degrees. */
+ rotation?: number;
+ /** Opacity, 0–1 (out-of-range values clamp, like CSS). */
+ opacity?: number;
+ /** Uniform corner radius, px. */
+ cornerRadius?: number;
+};
+
+type TimingProps = {
/** Parent-timeline time at which the node begins. Default 0. */
start?: Time;
/** Parent-timeline time at which the node ends. Alternative to `sourceOut`. */
@@ -239,97 +185,72 @@ export type PatchProps = {
sourceIn?: Time;
/** Source out point: where playback ends within the source. Defaults to the natural end. Alternative to `end`. */
sourceOut?: Time;
- /**
- * `id` of another element carrying an audio track. Derives the timeline
- * placement (`start`) by cross-correlating the two audio signals so the
- * recordings coincide on the timeline. Mutually exclusive with `start`.
- */
- syncTo?: string;
+};
+
+type SequenceItemProps = {
/**
* Transition into the next clip, rendered centered on the cut, set on the
* outgoing clip. Only on direct children of `<Sequence>`; a partial value
* merges into the clip's existing transition, `null` removes it.
*/
transition?: TransitionSpec | null;
- /**
- * Preset in/out animations, played over the clip's head and tail. The list
- * replaces the node's existing animations; `[]` removes them all.
- */
- animations?: AnimationSpec[];
+};
+
+type FillProps = {
/** Any CSS color, the node's intrinsic solid fill (drawn beneath any paint children); alpha is ignored — use `opacity`. */
fill?: string;
+};
+
+type MediaProps = {
/**
* Path, URL, asset id, or a `generate.*` declaration. On `<Captions>` a
* transcript source (.srt, .vtt, or transcript .json) mounted instead of
* transcribing the scene; `generate.*` is not accepted there.
*/
- src?: string | AssetRef;
+ src: string | AssetRef;
+};
+
+type FitProps = {
/** How the source maps into the box. Default "cover" on `<Video>`, "contain" on `<Image>`. */
objectFit?: Fit;
- /**
- * Fragment-stage WGSL of a `<ShaderPaint>`, applied to the video/image
- * paint directly below it in the paint stack, or run procedurally (over a
- * transparent source) when there is none. Entry point
- * `@fragment fn main(@location(0) uv: vec2f) -> @location(0) vec4f`;
- * sample the media with `sampleSource(uv)`.
- */
- wgsl?: string;
- /**
- * Values for the shader's `@group(1)` uniform declarations, matched by
- * name: numbers bind to `f32`, arrays of 2-4 to `vec2f`-`vec4f`, CSS
- * color strings to `vec3f`/`vec4f`.
- */
- uniforms?: Record<string, number | number[] | string>;
- /** Decibels: 0 = unity gain, negative attenuates (-6 ≈ half as loud), -Infinity = silence. Use `muted` to silence. Animatable. */
- volume?: Animatable<number>;
+};
+
+type AudioTrackProps = {
+ /** Decibels: 0 = unity gain, negative attenuates (-6 ≈ half as loud), -Infinity = silence. Use `muted` to silence. */
+ volume?: number;
/** Excludes the node's audio from the mix; independent of `volume`. */
muted?: boolean;
- /** A family available on the machine (`dapi fonts`). */
- fontFamily?: string;
- /** Font size, px. */
- fontSize?: number;
- /** CSS weights 100–900, or "normal" / "bold". */
- fontWeight?: number | "normal" | "bold";
- fontStyle?: "normal" | "italic";
- /** Any CSS color: the glyph color on `<Text>`, the paint color on paints, strokes, shadows and color stops. Animatable. */
- color?: Animatable<string>;
- /** Horizontal alignment of glyphs within the box. Default "left". */
- textAlign?: "left" | "center" | "right";
- /** Vertical alignment within the box. Default "top". */
- textBaseline?: "top" | "middle" | "bottom";
- /** Position along the gradient, 0–1. Animatable. */
- offset?: Animatable<number>;
- /** Caption style preset — `<Captions>` only. Default "classic". */
- preset?: CaptionPreset;
- /** Fills the caption preset's color slots in order; any CSS color, alpha is ignored. */
- colors?: string[];
- /**
- * Vertical placement of the caption block — `<Captions>` only: anchored to
- * the top or bottom safe margin, or centered. The preset keeps owning the
- * horizontal placement. Defaults to the preset's own alignment.
- */
- verticalAlign?: "top" | "center" | "bottom";
/**
- * Transcription seed — `<Captions>` only. Part of the transcript cache key,
- * so a new value bypasses the cached transcript and transcribes the scene
- * again; reusing a value replays that take from cache.
+ * `id` of another element carrying an audio track. Derives the timeline
+ * placement (`start`) by cross-correlating the two audio signals so the
+ * recordings coincide on the timeline. Mutually exclusive with `start`.
*/
- seed?: number;
+ syncTo?: string;
+};
+
+type OpacityProps = {
+ /** Opacity, 0–1 (out-of-range values clamp, like CSS). */
+ opacity?: number;
};
-type TimingProps = Pick<PatchProps, "start" | "end" | "sourceIn" | "sourceOut">;
+type ColorProps = {
+ /** Any CSS color: the glyph color on `<Text>`, the paint color on paints, strokes, shadows and color stops. */
+ color: string;
+};
-type CommonProps = TimingProps &
- Pick<
- PatchProps,
- | "name" | "selected" | "x" | "y" | "offsetX" | "offsetY" | "width" | "height" | "rotation"
- | "opacity" | "cornerRadius" | "transition" | "animations"
- >;
+/** What every visual node accepts on top of its own props. */
+type CommonProps = IdentityProps & TransformProps & TimingProps & SequenceItemProps;
+
+/** Sub-entity children (`<KeyframeTrack>`) an element that is itself a style takes. */
+type TrackChildren = {
+ /** `<KeyframeTrack>` children. */
+ children?: SolidJSX.Element;
+};
/**
* What every composition element accepts on top of its own props. Read by the
- * compile step and never seen by a host, so it is not part of `PatchProps`:
- * nothing patches an id, because an id is not a property of the composition.
+ * compile step and never seen by a host: an id is not a property of the
+ * composition, it is how the source addresses the element.
*/
export type SourceProps = {
id?: string;
@@ -372,20 +293,28 @@ export type StageProps = {
* `camera` does: the source is the document, so a scene dragged or clicked on
* the canvas has nowhere else to be written back to.
*/
-export type SceneProps = Required<Pick<PatchProps, "width" | "height">> &
- Pick<PatchProps, "name" | "selected" | "active" | "x" | "y" | "fill"> & {
- children?: SolidJSX.Element;
- };
+export type SceneProps = IdentityProps & PositionProps & Required<SizeProps> & FillProps & {
+ /**
+ * Whether this element is the one the playhead, timeline, and capture
+ * operate on. Editor state carried by the source like `selected`, with two
+ * rules the runtime holds: at most one element is active, and only a root
+ * (a direct child of `<stage>`) can be; a nested `active` is dropped. When
+ * a file names more than one, the last one rendered wins.
+ */
+ active?: boolean;
+ children?: SolidJSX.Element;
+};
-export type GroupProps = CommonProps & Pick<PatchProps, "fill"> & {
- /** Element children, and `<Effect>` children filtering the group as a whole. */
+export type GroupProps = CommonProps & FillProps & {
+ /** Element children, plus `<Effect>` (filtering the group as a whole), `<Animation>` and `<KeyframeTrack>` children. */
children?: SolidJSX.Element;
};
-export type RectProps = CommonProps & Pick<PatchProps, "fill"> & {
+export type RectProps = CommonProps & FillProps & {
/**
* Paint children (`<SolidPaint>`, `<LinearGradientPaint>`,
- * `<RadialGradientPaint>`), plus `<Stroke>`, `<Shadow>` and `<Effect>` children.
+ * `<RadialGradientPaint>`), plus `<Stroke>`, `<Shadow>`, `<Effect>`,
+ * `<Animation>` and `<KeyframeTrack>` children.
*/
children?: SolidJSX.Element;
};
@@ -395,89 +324,110 @@ export type RectProps = CommonProps & Pick<PatchProps, "fill"> & {
* paint: `color`/`opacity` are its paint, `width`/`join`/`cap`/`miterLimit`
* its line style. Several stack in document order, later ones on top.
*/
-export type StrokeProps = Required<Pick<PatchProps, "color">> &
- Pick<PatchProps, "opacity" | "width" | "join" | "cap" | "miterLimit"> & {
- /** `<KeyframeTrack>` children. */
- children?: SolidJSX.Element;
- };
+export type StrokeProps = ColorProps & OpacityProps & TrackChildren & {
+ /** Line width, px. Default 1. */
+ width?: number;
+ /** How the stroke turns corners. Default "miter". */
+ join?: StrokeJoin;
+ /** How the stroke ends open paths (text glyphs). Default "butt". */
+ cap?: StrokeCap;
+ /** Miter length limit, as a ratio of the width. Default 10. */
+ miterLimit?: number;
+};
/**
* `<shadow>` — a drop shadow beneath the parent's box (or glyphs): a blurred,
* offset copy of its silhouette in `color`. Several stack in document order.
*/
-export type ShadowProps = Required<Pick<PatchProps, "color">> &
- Pick<PatchProps, "opacity" | "blur" | "offsetX" | "offsetY"> & {
- /** `<KeyframeTrack>` children. */
- children?: SolidJSX.Element;
- };
+export type ShadowProps = ColorProps & OpacityProps & TrackChildren & {
+ /** Blur radius, px. Default 0. */
+ blur?: number;
+ /** Where the shadow sits relative to the silhouette, px. Default 0. */
+ offsetX?: number;
+ offsetY?: number;
+};
/**
* `<effect>` — a filter over the parent's rendered pixels (its fills, strokes
* and children together), a sub-entity like a paint. Several stack in
* document order.
*/
-export type EffectProps = {
+export type EffectProps = TrackChildren & {
+ /** Which filter to apply. */
type: EffectType;
- value: Animatable<number>;
- /** `<KeyframeTrack>` children. */
- children?: SolidJSX.Element;
+ /** The amount: px for "blur", degrees for "hueRotate", 0–1 otherwise. */
+ value: number;
};
/**
* `<animation>` — one preset in/out animation of the node holding it, played
- * over the clip's head or tail: the element form of an `animations` entry, so
- * an editor has something to write to. Several stack in document order,
- * later ones writing over earlier ones on the properties they share.
+ * over the clip's head or tail. Several stack in document order, later ones
+ * writing over earlier ones on the properties they share; a `<keyframeTrack>`
+ * on the same property overrides the preset while it has keyframes.
*/
-export type AnimationProps = { type: AnimationType } & Pick<PatchProps, "phase" | "duration" | "delay">;
+export type AnimationProps = {
+ /** Which preset plays. */
+ type: AnimationType;
+ /** "in" plays from the clip's head, "out" into its tail. Default "in". */
+ phase?: "in" | "out";
+ /** Length of the animation. Any `Time` format. Default 1 second. */
+ duration?: Time;
+ /**
+ * Gap between the clip edge and the animation: after the head for "in",
+ * before the tail for "out". Any `Time` format. Default 0.
+ */
+ delay?: Time;
+};
/**
* `<keyframeTrack>` — the keyframes of one prop of the element holding it,
- * as elements: the addressable form of an `Animatable` prop's keyframe list,
- * so an editor moving a keyframe has an element to write it to. One track
- * per prop; a static value of that prop is what holds outside the keyframes.
+ * as elements, so an editor moving a keyframe has an element to write it to.
+ * One track per prop; the prop's static value is what holds when the track
+ * is empty. Outside the keyframed range the value holds at the first/last
+ * keyframe.
*/
-export type KeyframeTrackProps = Required<Pick<PatchProps, "property">> & {
+export type KeyframeTrackProps = {
+ /** Which prop of the holding element the track animates. */
+ property: AnimatableProperty;
/** `<Keyframe>` children, in any order; they sort by `time`. */
children?: SolidJSX.Element;
};
/** `<keyframe>` — one keyframe of the `<keyframeTrack>` holding it. */
-export type KeyframeProps = Required<Pick<PatchProps, "time" | "value">> & Pick<PatchProps, "easing">;
-
-export type SolidPaintProps = Required<Pick<PatchProps, "color">> & Pick<PatchProps, "opacity"> & {
- /** `<KeyframeTrack>` children. */
- children?: SolidJSX.Element;
+export type KeyframeProps = {
+ /** Node-local time: 0 is where the clip begins (its `start`). Any `Time` format. */
+ time: Time;
+ /** The value at `time`: a number, or any CSS color on a `color` track. */
+ value: number | string;
+ /** Shapes the segment to the next keyframe; ignored on the last. Default "linear". */
+ easing?: Easing;
};
-export type GradientPaintProps = Pick<PatchProps, "opacity"> & {
+export type SolidPaintProps = ColorProps & OpacityProps & TrackChildren;
+
+export type GradientPaintProps = OpacityProps & {
/** Gradient rotation in degrees. Defaults to 0 (left to right). */
rotation?: number;
/** `<ColorStop>` children — the gradient's color stops. */
children?: SolidJSX.Element;
};
-export type ColorStopProps = Required<Pick<PatchProps, "offset" | "color">> &
- Pick<PatchProps, "opacity"> & {
- /** `<KeyframeTrack>` children. */
- children?: SolidJSX.Element;
- };
+export type ColorStopProps = ColorProps & OpacityProps & TrackChildren & {
+ /** Position along the gradient, 0–1. */
+ offset: number;
+};
-export type VideoProps = CommonProps &
- Required<Pick<PatchProps, "src">> &
- Pick<PatchProps, "objectFit" | "volume" | "muted" | "syncTo"> & {
- /** Paint children, stacked over the media paint created by `src`; `<Stroke>`, `<Shadow>` and `<Effect>` children. */
+export type VideoProps = CommonProps & MediaProps & FitProps & AudioTrackProps & {
+ /** Paint children, stacked over the media paint created by `src`; `<Stroke>`, `<Shadow>`, `<Effect>`, `<Animation>` and `<KeyframeTrack>` children. */
children?: SolidJSX.Element;
};
-export type ImageProps = CommonProps &
- Required<Pick<PatchProps, "src">> &
- Pick<PatchProps, "objectFit"> & {
- /** Paint children, stacked over the media paint created by `src`; `<Stroke>`, `<Shadow>` and `<Effect>` children. */
+export type ImageProps = CommonProps & MediaProps & FitProps & {
+ /** Paint children, stacked over the media paint created by `src`; `<Stroke>`, `<Shadow>`, `<Effect>`, `<Animation>` and `<KeyframeTrack>` children. */
children?: SolidJSX.Element;
};
-export type HtmlPaintProps = Pick<PatchProps, "opacity"> & {
+export type HtmlPaintProps = OpacityProps & {
/**
* HTML children — real DOM elements laid out by the browser at the parent
* geometry's box size and drawn into it (html-in-canvas). Fully reactive:
@@ -496,10 +446,24 @@ type HostCanvas = typeof globalThis extends { HTMLCanvasElement: new () => infer
: { width: number; height: number; getContext(contextId: string, options?: unknown): unknown };
/** `<ShaderPaint>` — transforms the media paint directly below it. Takes no children. */
-export type ShaderPaintProps = Required<Pick<PatchProps, "wgsl">> &
- Pick<PatchProps, "uniforms" | "opacity">;
+export type ShaderPaintProps = OpacityProps & {
+ /**
+ * Fragment-stage WGSL, applied to the video/image paint directly below it
+ * in the paint stack, or run procedurally (over a transparent source) when
+ * there is none. Entry point
+ * `@fragment fn main(@location(0) uv: vec2f) -> @location(0) vec4f`;
+ * sample the media with `sampleSource(uv)`.
+ */
+ wgsl: string;
+ /**
+ * Values for the shader's `@group(1)` uniform declarations, matched by
+ * name: numbers bind to `f32`, arrays of 2-4 to `vec2f`-`vec4f`, CSS
+ * color strings to `vec3f`/`vec4f`.
+ */
+ uniforms?: Record<string, number | number[] | string>;
+};
-export type SurfacePaintProps = Pick<PatchProps, "opacity"> & {
+export type SurfacePaintProps = OpacityProps & {
/**
* Receives the surface's backing canvas once the paint materializes. Draw to
* any context type (2d, webgl, webgpu); the engine samples the bitmap every
@@ -512,31 +476,51 @@ export type SurfacePaintProps = Pick<PatchProps, "opacity"> & {
/** `<Surface>` — a rectangle carrying a `<SurfacePaint>` with the given ref. */
export type SurfaceProps = CommonProps & Pick<SurfacePaintProps, "ref">;
-export type AudioProps = TimingProps &
- Required<Pick<PatchProps, "src">> &
- Pick<PatchProps, "name" | "volume" | "muted" | "syncTo" | "animations"> & {
- /** `<KeyframeTrack>` children (a `volume` track). */
- children?: SolidJSX.Element;
- };
+export type AudioProps = IdentityProps & TimingProps & MediaProps & AudioTrackProps & {
+ /** `<KeyframeTrack>` (a `volume` track) and `<Animation>` children. */
+ children?: SolidJSX.Element;
+};
-export type TextProps = CommonProps &
- Pick<
- PatchProps,
- "fontFamily" | "fontSize" | "fontWeight" | "fontStyle" | "color" | "textAlign" | "textBaseline"
- > & {
+export type TextProps = CommonProps & Partial<ColorProps> & {
+ /** A family available on the machine (`dapi fonts`). */
+ fontFamily?: string;
+ /** Font size, px. */
+ fontSize?: number;
+ /** CSS weights 100–900, or "normal" / "bold". */
+ fontWeight?: number | "normal" | "bold";
+ fontStyle?: "normal" | "italic";
+ /** Horizontal alignment of glyphs within the box. Default "left". */
+ textAlign?: "left" | "center" | "right";
+ /** Vertical alignment within the box. Default "top". */
+ textBaseline?: "top" | "middle" | "bottom";
/**
- * The text content, required; alongside it, paint, `<Stroke>`, `<Shadow>`
- * and `<Effect>` children styling the glyphs.
+ * The text content, required; alongside it, paint, `<Stroke>`, `<Shadow>`,
+ * `<Effect>`, `<Animation>` and `<KeyframeTrack>` children.
*/
children: SolidJSX.Element;
};
-export type SequenceProps = Pick<PatchProps, "name"> & {
+export type SequenceProps = Pick<IdentityProps, "name"> & {
children?: SolidJSX.Element;
};
-export type CaptionsProps = Pick<
- PatchProps,
- | "preset" | "colors" | "verticalAlign" | "offsetX" | "offsetY" | "src"
- | "start" | "end" | "sourceIn" | "sourceOut" | "animations" | "seed"
->;
+export type CaptionsProps = TimingProps & OffsetProps & Partial<MediaProps> & {
+ /** Caption style preset. Default "classic". */
+ preset?: CaptionPreset;
+ /** Fills the caption preset's color slots in order; any CSS color, alpha is ignored. */
+ colors?: string[];
+ /**
+ * Vertical placement of the caption block: anchored to the top or bottom
+ * safe margin, or centered. The preset keeps owning the horizontal
+ * placement. Defaults to the preset's own alignment.
+ */
+ verticalAlign?: "top" | "center" | "bottom";
+ /**
+ * Transcription seed. Part of the transcript cache key, so a new value
+ * bypasses the cached transcript and transcribes the scene again; reusing
+ * a value replays that take from cache.
+ */
+ seed?: number;
+ /** `<Animation>` children. */
+ children?: SolidJSX.Element;
+};
diff --git a/packages/reconciler/src/index.ts b/packages/reconciler/src/index.ts
index cb44365a..23df2d40 100644
--- a/packages/reconciler/src/index.ts
+++ b/packages/reconciler/src/index.ts
@@ -6,7 +6,6 @@ export * from './document';
export * from './elements';
export { evaluate } from './evaluate';
export { mount, type Mount } from './mount';
-export { PATCH_PROP_KEYS } from './patch';
export { insert, renderProject, withDocument } from './renderer';
export { JSX_RUNTIME } from './runtime';
export type { ProjectDocument, ProjectTick } from './host';
diff --git a/packages/reconciler/src/patch.ts b/packages/reconciler/src/patch.ts
deleted file mode 100644
index fa0555b8..00000000
--- a/packages/reconciler/src/patch.ts
+++ /dev/null
@@ -1,64 +0,0 @@
-/* This Source Code Form is subject to the terms of the Mozilla Public
- * License, v. 2.0. If a copy of the MPL was not distributed with this
- * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
-
-import type { PatchProps } from '@diffusionstudio/jsx';
-
-/**
- * Every `PatchProps` key, at runtime — the patch-command allowlist. Host-side:
- * a project never enumerates its own props, but anything applying a patch has
- * to reject unknown keys. The `satisfies` guard keeps the list exhaustive as
- * `PatchProps` grows.
- */
-export const PATCH_PROP_KEYS = Object.keys({
- name: true,
- selected: true,
- active: true,
- x: true,
- y: true,
- offsetX: true,
- offsetY: true,
- width: true,
- height: true,
- rotation: true,
- opacity: true,
- cornerRadius: true,
- blur: true,
- join: true,
- cap: true,
- miterLimit: true,
- type: true,
- value: true,
- property: true,
- time: true,
- easing: true,
- phase: true,
- duration: true,
- delay: true,
- start: true,
- end: true,
- sourceIn: true,
- sourceOut: true,
- syncTo: true,
- transition: true,
- animations: true,
- fill: true,
- src: true,
- objectFit: true,
- wgsl: true,
- uniforms: true,
- volume: true,
- muted: true,
- fontFamily: true,
- fontSize: true,
- fontWeight: true,
- fontStyle: true,
- color: true,
- textAlign: true,
- textBaseline: true,
- offset: true,
- preset: true,
- colors: true,
- verticalAlign: true,
- seed: true,
-} satisfies Record<keyof PatchProps, true>) as ReadonlyArray<keyof PatchProps>;
diff --git a/packages/runtime/MIGRATION.md b/packages/runtime/MIGRATION.md
index 3e2c6f86..b6c2bf77 100644
--- a/packages/runtime/MIGRATION.md
+++ b/packages/runtime/MIGRATION.md
@@ -153,6 +153,8 @@ apps/web now depends on `@diffusionstudio/runtime` and `@diffusionstudio/koota-s
**`<animation>` is hosted** (`AnimationProps` in `@diffusionstudio/jsx`, `animation` in `IntrinsicElements` and `COMPOSITION_TAGS`, `Animation` component in the reconciler): the element form of one `animations` entry, `<animation type="fade" phase="out" duration={1} delay="15f" />`, a sub-entity child of a node (`Animation` trait, `ChildOf` its target; `Cache.animations` already collects it, the motion system already plays it). `type` reuses the `AnimationType` names (`fade`/`gain`/`grow`/`shrink`/`blur`/`slideLeft`/.../`scramble`, mapped onto the runtime enum), `phase` is `in`/`out`, `duration`/`delay` are `Time` and go to frames like the timing props (defaults 1s / 0, restored when the prop is unset). `PatchProps.type` widened to `EffectType | AnimationType` (`EffectProps`/`AnimationProps` narrow it), and gained `phase`, `duration`, `delay`. `RuntimeDocument.toFrames` now centralises the seconds-to-project-frames conversion the timing props, keyframes and animations share. As with `Animatable`, the `animations?: AnimationSpec[]` list prop is left in the types but not expanded by the host; the tags are what the document builds.
+ **`PatchProps` and `PATCH_PROP_KEYS` are gone.** They were the property table of the old `dapi node patch` command (any subset of props per patch entry, allowlisted at runtime); with the source as the document nothing patches by prop name (edits go through `editProperty`/`insertElement` and the desktop writer), and `PATCH_PROP_KEYS` had no consumer left. `packages/jsx/src/types.ts` now defines small internal prop groups (`IdentityProps`, `PositionProps`, `OffsetProps`, `SizeProps`, `TransformProps`, `TimingProps`, `SequenceItemProps`, `FillProps`, `MediaProps`, `FitProps`, `AudioTrackProps`, `OpacityProps`, `ColorProps`, `CommonProps`, `TrackChildren`) that the element prop types compose, and props one element owns (`type`, `value`, `property`, `time`, `easing`, `phase`, `duration`, `delay`, `join`, `cap`, `miterLimit`, `blur`, the text style, the caption props, `wgsl`/`uniforms`) live on that element's type, so the shared-name unions the table forced (`type?: EffectType | AnimationType`, `value?: Animatable<number> | string`) are gone. Gone with it: the inline `Animatable<T>`/`Keyframe<T>` keyframe arrays and the `animations?: AnimationSpec[]` list (`<keyframeTrack>`/`<animation>` are the only spelling; every prop is a plain value), and `packages/reconciler/src/patch.ts`. `reference/jsx/{keyframes,animations}.md` were rewritten for the tags and the `Animatable`/`animations` rows dropped from `elements.md`/`audio.md`/`captions.md`/`html.md`/`paints.md`; the rest of `reference/jsx` stays stale as noted below.
+
**Left stale on purpose** (deferred to a docs/examples pass): all eight `examples/*.tsx` still open with `<rect scene="...">` and no `<stage>`, so `tsc -p examples --noEmit` fails on them; `reference/jsx/{scene,roots}.md` still describes the pre-`<stage>` model where a mount grafts roots into an existing document; and `reference/jsx/{audio-sync,video,audio,elements}.md` still document `key` as the `syncTo` target. Deliberately not half-migrated: `reference/jsx` is stale as a whole, and patching the `key` rows alone would hide that.
## Remaining work (suggested order)
diff --git a/reference/jsx/animations.md b/reference/jsx/animations.md
index d2faca93..db5f5e25 100644
--- a/reference/jsx/animations.md
+++ b/reference/jsx/animations.md
@@ -1,27 +1,22 @@
# Animations
-`animations` declares **preset in/out animations** on a clip: each entry plays over the clip's head (`"in"`) or tail (`"out"`), between the node's static state and the preset's start/end state. For hand-authored motion on individual props, use [keyframes](./keyframes.md); the two compose on distinct properties.
+`<animation>` declares one **preset in/out animation** on the clip holding it: it plays over the clip's head (`"in"`) or tail (`"out"`), between the node's static state and the preset's start/end state. For hand-authored motion on individual props, use [keyframes](./keyframes.md); the two compose on distinct properties.
```tsx
-<video
- src="/Movies/intro.mp4"
- width={1920} height={1080}
- start={0} end={8}
- animations={[
- { type: "fade", duration: "15f" },
- { type: "slideUp", phase: "out", duration: 0.5, delay: 0.2 },
- ]}
-/>
+<video src="/Movies/intro.mp4" width={1920} height={1080} start={0} end={8}>
+ <animation type="fade" duration="15f" />
+ <animation type="slideUp" phase="out" duration={0.5} delay={0.2} />
+</video>
```
-```ts
-type AnimationSpec = {
- type: AnimationType; // preset, see below
- phase?: "in" | "out"; // default "in"
- duration?: Time; // default 1 second
- delay?: Time; // gap between the clip edge and the animation; default 0
-};
-```
+| Prop | Type | Default | Meaning |
+| ---- | ---- | ------- | ------- |
+| `type` | `AnimationType` (**required**) | | Preset, see below. |
+| `phase` | `"in" \| "out"` | `"in"` | Plays from the clip's head or into its tail. |
+| `duration` | `Time` | 1 second | Length of the animation. |
+| `delay` | `Time` | `0` | Gap between the clip edge and the animation: after the head for `"in"`, before the tail for `"out"`. |
+
+Valid under any node (`<rect>`, `<text>`, `<video>`, `<image>`, `<audio>`, `<group>`, `<captions>`). An `<animation>` is an element like any other: it has an `id`, the editor writes changes back to it, and it is copied with its node.
## Types
@@ -41,10 +36,9 @@ The editor's animations inspector options:
| `"scramble"` | Text only: resolves scrambled characters into the text. |
| `"gain"` | Audio only: volume ramp (fade-in/fade-out of the mix). No visual effect. |
-Text types apply only to [`<text>`](./text.md) and [`<captions>`](./captions.md); a mount that puts them elsewhere fails validation.
+Text types apply only to [`<text>`](./text.md) and [`<captions>`](./captions.md).
## Semantics
- `duration` and `delay` take any [time format](./timing.md#time-formats). An `"in"` animation plays over `[delay, delay + duration]` from the clip's in point; an `"out"` animation ends `delay` before the clip's out point. Both track the clip when it is retimed.
-- A node takes **any number of animations**; overlapping entries apply in list order, later ones writing over earlier ones on the properties they share. A [keyframe](./keyframes.md) track on the same property (say, keyframed `opacity` next to `"fade"`) overrides the preset while it has effect; presets and keyframes on distinct properties compose freely.
-- The list is **mount-shaped**: setting `animations` replaces the node's existing animations, `[]` removes them all, and an omitted prop leaves hand-added ones untouched.
+- A node takes **any number of animations**; overlapping ones apply in document order, later ones writing over earlier ones on the properties they share. A [keyframe track](./keyframes.md) on the same property (say, a keyframed `opacity` next to `"fade"`) overrides the preset while it has keyframes; presets and keyframes on distinct properties compose freely.
diff --git a/reference/jsx/audio.md b/reference/jsx/audio.md
index f9146c55..01fb20c1 100644
--- a/reference/jsx/audio.md
+++ b/reference/jsx/audio.md
@@ -13,7 +13,7 @@ An audio clip: no visual output, no spatial props; carries volume. When timing i
| `src` | `string \| AssetRef` | **required** | See [media.md](./media.md). |
| `name` | `string` | none | Human-readable node name. |
| `start`, `end`, `sourceIn`, `sourceOut` | `Time` | see [timing.md](./timing.md) | Temporal placement. |
-| `volume` | `Animatable<number>` | `0` | Decibels: `0` = unity, negative attenuates (`-6` ≈ half as loud), `-Infinity` = silence. Not linear. |
+| `volume` | `number` | `0` | Decibels: `0` = unity, negative attenuates (`-6` ≈ half as loud), `-Infinity` = silence. Not linear. |
| `muted` | `boolean` | `false` | Excludes the node's audio from the mix; independent of `volume`. |
| `syncTo` | `string` | none | Key of another element carrying audio; derives `start` by audio alignment (see [audio-sync.md](./audio-sync.md)). Mutually exclusive with `start`. |
| `animations` | `AnimationSpec[]` | none | Preset in/out animations (see [animations.md](./animations.md)); only `"gain"` is audible. |
diff --git a/reference/jsx/captions.md b/reference/jsx/captions.md
index e114618d..343c096a 100644
--- a/reference/jsx/captions.md
+++ b/reference/jsx/captions.md
@@ -18,7 +18,7 @@ Transcripts are **cached**: every transcript asset records a fingerprint of the
| `colors` | `string[]` | preset defaults | Fills the preset's color slots in order; any CSS color, alpha ignored. Ignored by presets without slots. |
| `verticalAlign` | `"top" \| "center" \| "bottom"` | preset default | Vertical placement of the caption block: anchored to the top or bottom safe margin (100 px), or centered. Horizontal placement stays with the preset. |
| `seed` | `number` | none | Joins the transcript cache key: a value unused for this audio transcribes the scene again instead of reusing the cached transcript (it costs credits). Reusing a value replays that take from cache. |
-| `offsetX`, `offsetY` | `Animatable<number>` | `0` | Render-time nudge in px on top of the preset placement; subpixel values are kept. A slide animation drives the same channel and wins while it plays. |
+| `offsetX`, `offsetY` | `number` | `0` | Render-time nudge in px on top of the preset placement; subpixel values are kept. A slide animation drives the same channel and wins while it plays. |
| `start`, `end`, `sourceIn`, `sourceOut` | `Time` | full transcript | Trim which stretch of the transcript is captioned, using the same [timing](./timing.md) semantics as media nodes. Set the source window (`sourceIn`/`sourceOut`) and timeline placement (`start`/`end`) together — see [Trimming](#trimming). |
The preset positions the caption block; `verticalAlign` overrides only its vertical anchor (`whisper` and `cascade` default to `bottom`, all other presets to `center`), and `offsetX`/`offsetY` nudge the drawn result from there.
diff --git a/reference/jsx/elements.md b/reference/jsx/elements.md
index bdad0516..a32bf4ab 100644
--- a/reference/jsx/elements.md
+++ b/reference/jsx/elements.md
@@ -37,15 +37,14 @@ All visual elements accept:
| `key` | `string` | none | A within-render label so another node can reference this one (e.g. [`syncTo`](./audio-sync.md)); |
| `scene` | `string` | none | Promotes a `<rect>` to a scene, the only mountable root, and is its identity across mounts (see [scene.md](./scene.md)). |
| `name` | `string` | none | Human-readable node name. |
-| `x`, `y` | `Animatable<number>` | `0` | Position relative to the parent, px. |
-| `offsetX`, `offsetY` | `Animatable<number>` | `0` | Render-time translation on top of `x`/`y`, px; moves the drawn content without changing the layout box. Subpixel values are kept. |
-| `width`, `height` | `Animatable<number>` | parent size | Box size, px. |
-| `rotation` | `Animatable<number>` | `0` | Rotation in degrees. |
-| `opacity` | `Animatable<number>` | `1` | `0`-`1`. |
-| `cornerRadius` | `Animatable<number>` | `0` | Uniform corner radius, px. |
+| `x`, `y` | `number` | `0` | Position relative to the parent, px. |
+| `offsetX`, `offsetY` | `number` | `0` | Render-time translation on top of `x`/`y`, px; moves the drawn content without changing the layout box. Subpixel values are kept. |
+| `width`, `height` | `number` | parent size | Box size, px. |
+| `rotation` | `number` | `0` | Rotation in degrees. |
+| `opacity` | `number` | `1` | `0`-`1`. |
+| `cornerRadius` | `number` | `0` | Uniform corner radius, px. |
| `start`, `end`, `sourceIn`, `sourceOut` | `Time` | see [timing.md](./timing.md) | Temporal placement. |
| `transition` | `TransitionSpec \| null` | none | Transition into the next clip; direct children of `<sequence>` only (see [transitions.md](./transitions.md)). |
-| `animations` | `AnimationSpec[]` | none | Preset in/out animations over the clip's head and tail (see [animations.md](./animations.md)). |
-`Animatable` props also take a keyframe list; see [keyframes.md](./keyframes.md).
+Numeric props are animated by `<keyframeTrack>` children (see [keyframes.md](./keyframes.md)); preset in/out effects are `<animation>` children (see [animations.md](./animations.md)).
diff --git a/reference/jsx/html.md b/reference/jsx/html.md
index bed3f10a..60cd9d84 100644
--- a/reference/jsx/html.md
+++ b/reference/jsx/html.md
@@ -66,7 +66,7 @@ setInterval(() => setCount((c) => c + 1), 1000);
| Prop | Type | Default | Meaning |
| ---- | ---- | ------- | ------- |
-| `opacity` | `Animatable<number>` | `1` | Paint opacity, `0`-`1`. |
+| `opacity` | `number` | `1` | Paint opacity, `0`-`1`. |
Like all paints, `<htmlPaint>` stacks with siblings in document order and clips to the parent's box (including `cornerRadius`).
diff --git a/reference/jsx/keyframes.md b/reference/jsx/keyframes.md
index ce8774c3..963519fb 100644
--- a/reference/jsx/keyframes.md
+++ b/reference/jsx/keyframes.md
@@ -1,32 +1,34 @@
# Keyframes
-Animatable props accept a keyframe list in place of a static value:
+A `<keyframeTrack>` animates one prop of the element holding it over the node's local time; its `<keyframe>` children are the values along the way:
```tsx
-<image
- src="/photo.jpg"
- start={0} end={5}
- x={[
- { time: 0, value: -400 },
- { time: 1, value: 200, easing: "easeOut" },
- ]}
- opacity={[{ time: 0, value: 0 }, { time: "15f", value: 1 }]}
-/>
+<image src="/photo.jpg" start={0} end={5}>
+ <keyframeTrack property="x">
+ <keyframe time={0} value={-400} easing="easeOut" />
+ <keyframe time={1} value={200} />
+ </keyframeTrack>
+ <keyframeTrack property="opacity">
+ <keyframe time={0} value={0} />
+ <keyframe time="15f" value={1} />
+ </keyframeTrack>
+</image>
```
-```ts
-type Keyframe<T> = { time: Time; value: T; easing?: Easing };
-type Animatable<T> = T | Keyframe<T>[];
-```
+| Element | Props | Meaning |
+| ------- | ----- | ------- |
+| `<keyframeTrack>` | `property` (**required**) | The prop of the holding element it drives, by name. One track per prop. |
+| `<keyframe>` | `time` (**required**), `value` (**required**), `easing` | One keyframe: node-local time in any [time format](./timing.md#time-formats), the value at that time (a number, or any CSS color on a `color` track), and the easing into the next keyframe. |
-Animatable props: `x`, `y`, `offsetX`, `offsetY`, `width`, `height`, `rotation`, `opacity`, `cornerRadius`, `volume`, `color`, `offset`. As part of the shared property table this applies to `dapi node patch` identically, and to [paints and color stops](./paints.md) (`color`, `opacity`, `offset` animate gradients). For preset in/out effects (fade, slides, text reveals, ...) use the [`animations` prop](./animations.md) instead.
+Animatable props (`property`): `x`, `y`, `offsetX`, `offsetY`, `width`, `height`, `rotation`, `opacity`, `cornerRadius`, `volume`, `color`, `offset`, `blur`, `value`. Whose prop is the track's holder's: a track under a [paint or color stop](./paints.md) animates the paint (`color`, `opacity`, `offset`), under a `<stroke>` the stroke (`width` is the line width), under a `<shadow>` the shadow (`blur`, `offsetX`, `offsetY`), under an `<effect>` its `value`. For preset in/out effects (fade, slides, text reveals, ...) use [`<animation>`](./animations.md) instead.
## Semantics
-- `time` is **node-local**: `0` is where the clip begins (its `start`), in any [time format](./timing.md#time-formats). Timing props are parent-relative; keyframe times are not, so animation moves with the clip.
-- Outside the keyframed range the value holds at the first/last keyframe.
+- `time` is **node-local**: `0` is where the clip begins (its `start`). Timing props are parent-relative; keyframe times are not, so animation moves with the clip.
+- Keyframes may be written in any order; they sort by `time`. Outside the keyframed range the value holds at the first/last keyframe.
- `easing` shapes the segment from its keyframe to the next; the last keyframe's easing is ignored. Default `"linear"`.
-- A **static value replaces any existing keyframes** on that property; mount and `dapi node patch` own what they set. Keyframes land as regular editor keyframes, editable in the timeline and inspector, and props the render doesn't set keep their hand-made tracks across re-mounts.
+- The prop's static value (`x={10}` on the element) is what holds when the track has no keyframes; while it has any, the track wins.
+- Tracks and keyframes are elements like any other: each has an `id`, the editor writes a moved keyframe back to it, and they are copied with their element.
## Easing
diff --git a/reference/jsx/paints.md b/reference/jsx/paints.md
index 1fc15093..bbbd5b7a 100644
--- a/reference/jsx/paints.md
+++ b/reference/jsx/paints.md
@@ -23,6 +23,4 @@ Paint elements are valid inside any filled visual element (`<rect>`, `<text>`, `
| [`<surfacePaint>`](./surface-paint.md) | `opacity`, `ref` (**required**) | A canvas your `ref` callback draws into (any context type), sampled into the parent's box every frame. `<surface>` is shorthand for a `<rect>` carrying one. |
| [`<shaderPaint>`](./shader-paint.md) | `opacity`, `wgsl` (**required**), `uniforms` | A WGSL fragment shader applied to the video/image paint directly below it (that media renders only through the shader's output), or run procedurally when there is none. |
-Colors accept any CSS color; alpha is ignored (use `opacity`). `color`, `opacity`, and `offset` are animatable (see [keyframes.md](./keyframes.md)), so gradients can animate. Paints have no spatial or timing props and cannot be stage roots.
-
-Paints are live entities like any other: patch them with `dapi node patch`, and add a stop to an existing gradient with `dapi node insert` (`node insert <paintId> '<colorStop offset={0.5} color="#FF0055" />'`).
+Colors accept any CSS color; alpha is ignored (use `opacity`). `color`, `opacity`, and `offset` are animatable with `<keyframeTrack>` children (see [keyframes.md](./keyframes.md)), so gradients can animate. Paints have no spatial or timing props and cannot be stage roots.