Skip to content

The VS Code of video editing, built for agents.

TypeScript

Add animation support in JSX and runtime

konstantin-paulus64ab858182f3
diff --git a/packages/jsx/src/index.ts b/packages/jsx/src/index.ts
index ef2fe729..b94d3272 100644
--- a/packages/jsx/src/index.ts
+++ b/packages/jsx/src/index.ts
@@ -39,6 +39,7 @@ export type { Ticker } from "./hooks";
export type {
Animatable,
AnimatableProperty,
+ AnimationProps,
AnimationSpec,
AnimationType,
AudioProps,
diff --git a/packages/jsx/src/jsx-runtime.ts b/packages/jsx/src/jsx-runtime.ts
index 3067b004..eae4ebac 100644
--- a/packages/jsx/src/jsx-runtime.ts
+++ b/packages/jsx/src/jsx-runtime.ts
@@ -21,6 +21,7 @@
import type { JSX as SolidJSX } from "solid-js";
import type { AssetInput } from "./generate";
import type {
+ AnimationProps,
AudioProps,
CaptionsProps,
ColorStopProps,
@@ -90,6 +91,7 @@ export declare namespace JSX {
stroke: StrokeProps & SourceProps;
shadow: ShadowProps & SourceProps;
effect: EffectProps & SourceProps;
+ animation: AnimationProps & SourceProps;
keyframeTrack: KeyframeTrackProps & SourceProps;
keyframe: KeyframeProps & SourceProps;
htmlPaint: HtmlPaintProps & SourceProps;
diff --git a/packages/jsx/src/source.ts b/packages/jsx/src/source.ts
index 4f117bb7..9708c928 100644
--- a/packages/jsx/src/source.ts
+++ b/packages/jsx/src/source.ts
@@ -106,6 +106,7 @@ export const COMPOSITION_TAGS = [
"stroke",
"shadow",
"effect",
+ "animation",
"keyframeTrack",
"keyframe",
"htmlPaint",
diff --git a/packages/jsx/src/types.ts b/packages/jsx/src/types.ts
index 9485baab..bcb627ab 100644
--- a/packages/jsx/src/types.ts
+++ b/packages/jsx/src/types.ts
@@ -208,8 +208,8 @@ export type PatchProps = {
cap?: StrokeCap;
/** Miter length limit of a `<stroke>`, as a ratio of its width. Default 10. */
miterLimit?: number;
- /** Which filter an `<effect>` applies. */
- type?: EffectType;
+ /** 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
@@ -222,6 +222,15 @@ export type PatchProps = {
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.
+ */
+ delay?: Time;
/** Parent-timeline time at which the node begins. Default 0. */
start?: Time;
/** Parent-timeline time at which the node ends. Alternative to `sourceOut`. */
@@ -407,12 +416,21 @@ export type ShadowProps = Required<Pick<PatchProps, "color">> &
* and children together), a sub-entity like a paint. Several stack in
* document order.
*/
-export type EffectProps = Required<Pick<PatchProps, "type">> & {
+export type EffectProps = {
+ type: EffectType;
value: Animatable<number>;
/** `<KeyframeTrack>` children. */
children?: SolidJSX.Element;
};
+/**
+ * `<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.
+ */
+export type AnimationProps = { type: AnimationType } & Pick<PatchProps, "phase" | "duration" | "delay">;
+
/**
* `<keyframeTrack>` — the keyframes of one prop of the element holding it,
* as elements: the addressable form of an `Animatable` prop's keyframe list,
diff --git a/packages/reconciler/src/document.ts b/packages/reconciler/src/document.ts
index 19af9d05..47fd9ebe 100644
--- a/packages/reconciler/src/document.ts
+++ b/packages/reconciler/src/document.ts
@@ -5,6 +5,9 @@
import {
Active,
+ Animation,
+ AnimationPhase,
+ AnimationType,
appendChild,
AssetId,
Assets,
@@ -244,6 +247,23 @@ const EASINGS: Record<string, string> = {
strong: 'spring(0.65,400)',
};
+const ANIMATION_TYPES: Record<string, AnimationType> = {
+ fade: AnimationType.FADE,
+ gain: AnimationType.GAIN,
+ grow: AnimationType.GROW,
+ shrink: AnimationType.SHRINK,
+ blur: AnimationType.BLUR,
+ slideLeft: AnimationType.SLIDE_LEFT,
+ slideRight: AnimationType.SLIDE_RIGHT,
+ slideUp: AnimationType.SLIDE_UP,
+ slideDown: AnimationType.SLIDE_DOWN,
+ spin: AnimationType.SPIN,
+ twist: AnimationType.TWIST,
+ appearWord: AnimationType.APPEAR_WORD,
+ appearChar: AnimationType.APPEAR_CHAR,
+ scramble: AnimationType.SCRAMBLE,
+};
+
const EFFECT_TYPES: Record<string, EffectType> = {
blur: EffectType.LAYER_BLUR,
brightness: EffectType.BRIGHTNESS,
@@ -449,6 +469,12 @@ export class RuntimeDocument implements ProjectDocument<HostNode> {
entity.set(Effect, { type: EffectType.LAYER_BLUR, value: 0 });
break;
}
+ case 'animation': {
+ entity = createEntity(this.world);
+ entity.add(Animation);
+ entity.set(Animation, { duration: this.toFrames(1) });
+ break;
+ }
case 'keyframeTrack': {
// `property` names the prop; the path it resolves to depends on the
// holder, so it is (re)resolved when the track is inserted.
@@ -464,7 +490,7 @@ export class RuntimeDocument implements ProjectDocument<HostNode> {
}
default:
throw new Error(
- `<${tag}> is not supported yet (only <stage>, <scene>, <group>, <sequence>, <rect>, <text>, <video>, <image>, <audio>, <solidPaint>, <linearGradientPaint>, <radialGradientPaint>, <colorStop>, <stroke>, <shadow>, <effect>, <keyframeTrack> and <keyframe>).`,
+ `<${tag}> is not supported yet (only <stage>, <scene>, <group>, <sequence>, <rect>, <text>, <video>, <image>, <audio>, <solidPaint>, <linearGradientPaint>, <radialGradientPaint>, <colorStop>, <stroke>, <shadow>, <effect>, <animation>, <keyframeTrack> and <keyframe>).`,
);
}
@@ -602,11 +628,28 @@ export class RuntimeDocument implements ProjectDocument<HostNode> {
return;
}
case 'type': {
+ if (entity.has(Animation)) {
+ const type = typeof value === 'string' ? ANIMATION_TYPES[value] : undefined;
+ entity.set(Animation, { type: type ?? AnimationType.FADE });
+ return;
+ }
if (!entity.has(Effect)) return;
const type = typeof value === 'string' ? EFFECT_TYPES[value] : undefined;
entity.set(Effect, { type: type ?? EffectType.LAYER_BLUR });
return;
}
+ case 'phase': {
+ if (!entity.has(Animation)) return;
+ entity.set(Animation, { phase: value === 'out' ? AnimationPhase.OUT : AnimationPhase.IN });
+ return;
+ }
+ case 'duration':
+ case 'delay': {
+ if (!entity.has(Animation)) return;
+ const seconds = toSeconds(value);
+ entity.set(Animation, { [name]: this.toFrames(seconds ?? (name === 'duration' ? 1 : 0)) });
+ return;
+ }
case 'value': {
if (entity.has(Keyframe)) {
// A number, or a color on a color track; either is a number to the trait.
@@ -625,8 +668,7 @@ export class RuntimeDocument implements ProjectDocument<HostNode> {
case 'time': {
if (!entity.has(Keyframe)) return;
const seconds = toSeconds(value);
- const fps = this.world.get(FrameRate)?.value ?? 30;
- entity.set(Keyframe, { time: seconds === undefined ? 0 : secondsToFrames(seconds, fps) });
+ entity.set(Keyframe, { time: this.toFrames(seconds ?? 0) });
return;
}
case 'easing': {
@@ -658,9 +700,8 @@ export class RuntimeDocument implements ProjectDocument<HostNode> {
return;
}
- const fps = this.world.get(FrameRate)?.value ?? 30;
entity.add(trait);
- entity.set(trait, { value: secondsToFrames(seconds, fps) });
+ entity.set(trait, { value: this.toFrames(seconds) });
return;
}
case 'src': {
@@ -790,6 +831,11 @@ export class RuntimeDocument implements ProjectDocument<HostNode> {
}
}
+ /** Seconds as frames of this project. */
+ private toFrames(seconds: number): number {
+ return secondsToFrames(seconds, this.world.get(FrameRate)?.value ?? 30);
+ }
+
/**
* Writes a track's runtime property path from its authored `property`,
* against the entity holding it (a `width` track under a stroke drives the
diff --git a/packages/reconciler/src/elements.ts b/packages/reconciler/src/elements.ts
index 1643c8b9..e06bf983 100644
--- a/packages/reconciler/src/elements.ts
+++ b/packages/reconciler/src/elements.ts
@@ -19,6 +19,7 @@ import { createElement, createTextNode, insertNode, setProp, spread, use } from
import type { JSX as SolidJSX } from "solid-js";
import type { AuthoredTree } from "./document";
import type {
+ AnimationProps,
AudioProps,
CaptionsProps,
ColorStopProps,
@@ -96,6 +97,7 @@ export const ColorStop = hostElement<ColorStopProps>("ColorStop");
export const Stroke = hostElement<StrokeProps>("Stroke");
export const Shadow = hostElement<ShadowProps>("Shadow");
export const Effect = hostElement<EffectProps>("Effect");
+export const Animation = hostElement<AnimationProps>("Animation");
export const KeyframeTrack = hostElement<KeyframeTrackProps>("KeyframeTrack");
export const Keyframe = hostElement<KeyframeProps>("Keyframe");
export const HtmlPaint = hostElement<HtmlPaintProps>("HtmlPaint");
diff --git a/packages/reconciler/src/patch.ts b/packages/reconciler/src/patch.ts
index 7befec7c..fa0555b8 100644
--- a/packages/reconciler/src/patch.ts
+++ b/packages/reconciler/src/patch.ts
@@ -32,6 +32,9 @@ export const PATCH_PROP_KEYS = Object.keys({
property: true,
time: true,
easing: true,
+ phase: true,
+ duration: true,
+ delay: true,
start: true,
end: true,
sourceIn: true,
diff --git a/packages/runtime/MIGRATION.md b/packages/runtime/MIGRATION.md
index d05e71af..3e2c6f86 100644
--- a/packages/runtime/MIGRATION.md
+++ b/packages/runtime/MIGRATION.md
@@ -151,6 +151,8 @@ apps/web now depends on `@diffusionstudio/runtime` and `@diffusionstudio/koota-s
**`<keyframeTrack>` and `<keyframe>` are hosted** (`KeyframeTrackProps`/`KeyframeProps` and `AnimatableProperty` in `@diffusionstudio/jsx`, both tags in `IntrinsicElements` and `COMPOSITION_TAGS`, `KeyframeTrack`/`Keyframe` components in the reconciler): the addressable form of an `Animatable` prop's keyframe list, so an editor moving a keyframe has an element (and id) to write it to. `<keyframeTrack property="x">` sits under the element whose prop it drives (any node, paint, color stop, stroke, shadow or effect: the runtime's `KeyframeTrack` is `ChildOf` its target) and holds `<keyframe time value easing />` children in any order (`Cache.keyframes` sorts by frame). `property` is the prop's JSX name and resolves through `TRACK_PROPERTIES` to the runtime's `PropertyPath` (`x` -> `position.x`, `cornerRadius` -> `vertexRadius`, `offset` -> `stop.offset`, `value` -> `effect.value`, ...); `width` under a `Stroke` is `stroke.width`, so the path is (re)resolved on insertion, since Solid sets props before the track has a parent (`resolveTrackProperty`). `time` is node-local and goes through `parseTime` + `secondsToFrames` like the timing props; `value` is a number, or a CSS color on a color track (`parseColor`); `easing` maps the named presets to the descriptors the runtime's `resolveEasing` and the interpolation inspector speak (`easeIn` -> `cubicBezier(0.42,0,1,1)`, `gentle` -> `spring(0.5,628)`, ..., `linear` -> `""`; descriptors pass through with whitespace dropped). `PatchProps` gained `property`, `time`, `easing`, and `value` widened to `Animatable<number> | string` (`EffectProps` narrows it back). One runtime fix came with it (`actions/cache.ts`): `rebuildCaches` re-aggregates a node's `Cache.keyframeTracks` not only when a track is attached but also when a non-node sub-entity carrying tracks is (`carriesKeyframeTrack`), because JSX builds bottom-up: a paint's tracks are attached to the paint before the paint meets its rect, and the old (bitecs) code only ever saw tracks attached to already-placed targets. Not decided yet: whether the inline `Animatable<T>` keyframe arrays stay (the host does not expand them; a static value is what `setProperty` handles) or the tags become the only spelling.
+ **`<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.
+
**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)