The VS Code of video editing, built for agents.
TypeScript
Add animations prop to various components and documentation
konstantin-paulus5a8b56d29bf9
diff --git a/apps/cli/reference/jsx/README.md b/apps/cli/reference/jsx/README.mdindex 99316488..0a0b562c 100644--- a/apps/cli/reference/jsx/README.md+++ b/apps/cli/reference/jsx/README.md@@ -20,6 +20,7 @@ The pipeline is driven by two commands: [`dapi mount`](../mount.md) renders the| [media.md](./media.md) | `src` resolution (paths, URLs, asset ids, `AssetRef`) || [timing.md](./timing.md) | `start` / `end` / `sourceIn` / `sourceOut`, time formats || [keyframes.md](./keyframes.md) | Keyframe animation and easing |+| [animations.md](./animations.md) | The `animations` prop: preset in/out animations || [transitions.md](./transitions.md) | The `transition` prop on sequence clips || [sequences.md](./sequences.md) | `<sequence>` sequential placement || [audio-sync.md](./audio-sync.md) | `syncTo` audio alignment |diff --git a/apps/cli/reference/jsx/animations.md b/apps/cli/reference/jsx/animations.mdnew file mode 100644index 00000000..97fdd000--- /dev/null+++ b/apps/cli/reference/jsx/animations.md@@ -0,0 +1,50 @@+# 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.++```tsx+<video+ src="/Movies/intro.mp4"+ start={0} end={8}+ animations={[+ { type: "fade", duration: "15f" },+ { type: "slideUp", phase: "out", duration: 0.5, delay: 0.2 },+ ]}+/>+```++```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+};+```++## Types++The editor's animations inspector options:++| `type` | Effect |+| ------ | ------ |+| `"fade"` | Opacity ramp. |+| `"slideLeft"`, `"slideRight"`, `"slideUp"`, `"slideDown"` | Slide in from (or out toward) the named direction, fading. |+| `"grow"` | Scales up from 50%. |+| `"shrink"` | Scales down from 150%. |+| `"spin"` | Scale plus rotation. |+| `"twist"` | Overscale plus rotation and offset. |+| `"blur"` | 24px blur ramp. |+| `"appearWord"` | Text only: reveals the text word by word. |+| `"appearChar"` | Text only: reveals the text character by character. |+| `"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.++## 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.+- Animations land as regular editor animations, editable in the inspector. Part of the shared property table: [`dapi node patch`](../node/patch.md) accepts `animations` with identical semantics, e.g. `--json '[{ "id": 42, "animations": [{ "type": "fade" }] }]'`, and they list under `animations` in [`dapi node tree`](../node/tree.md).diff --git a/apps/cli/reference/jsx/audio.md b/apps/cli/reference/jsx/audio.mdindex d738fa5d..f9146c55 100644--- a/apps/cli/reference/jsx/audio.md+++ b/apps/cli/reference/jsx/audio.md@@ -16,3 +16,4 @@ An audio clip: no visual output, no spatial props; carries volume. When timing i| `volume` | `Animatable<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/apps/cli/reference/jsx/elements.md b/apps/cli/reference/jsx/elements.mdindex 6cb0b874..8c77a60c 100644--- a/apps/cli/reference/jsx/elements.md+++ b/apps/cli/reference/jsx/elements.md@@ -40,6 +40,7 @@ All visual elements accept:| `cornerRadius` | `Animatable<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).diff --git a/apps/cli/reference/jsx/keyframes.md b/apps/cli/reference/jsx/keyframes.mdindex d6852394..e7e2904f 100644--- a/apps/cli/reference/jsx/keyframes.md+++ b/apps/cli/reference/jsx/keyframes.md@@ -19,7 +19,7 @@ type Keyframe<T> = { time: Time; value: T; easing?: Easing };type Animatable<T> = T | Keyframe<T>[];```-Animatable props: `x`, `y`, `width`, `height`, `rotation`, `opacity`, `cornerRadius`, `volume`, `color`, `offset`. As part of the shared property table this applies to [`dapi node patch`](../node/patch.md) identically, and to [paints and color stops](./paints.md) (`color`, `opacity`, `offset` animate gradients).+Animatable props: `x`, `y`, `width`, `height`, `rotation`, `opacity`, `cornerRadius`, `volume`, `color`, `offset`. As part of the shared property table this applies to [`dapi node patch`](../node/patch.md) 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.## Semanticsdiff --git a/apps/cli/reference/jsx/text.md b/apps/cli/reference/jsx/text.mdindex 158e0ad8..6803248c 100644--- a/apps/cli/reference/jsx/text.md+++ b/apps/cli/reference/jsx/text.md@@ -22,3 +22,5 @@ All [common props](./elements.md#common-props), plus:| `fill` | `string` | white | The glyph color; any CSS color, alpha ignored (use `opacity`). Shorthand for a solid paint child (see [paints.md](./paints.md)); animate it by declaring the paint explicitly. || `textAlign` | `"left" \| "center" \| "right"` | `"left"` | Horizontal alignment of glyphs within the box. || `textBaseline` | `"top" \| "middle" \| "bottom"` | `"top"` | Vertical alignment within the box. |++The text-only [animation types](./animations.md) (`"appearWord"`, `"appearChar"`, `"scramble"`) animate the glyphs themselves.diff --git a/apps/cli/reference/node/patch.md b/apps/cli/reference/node/patch.mdindex 20b7becb..40a692ad 100644--- a/apps/cli/reference/node/patch.md+++ b/apps/cli/reference/node/patch.md@@ -23,6 +23,7 @@ All props are optional; a patch may set any subset. An unsupported property or a- `src` takes a path, URL, or asset id (`generate.*` declarations are JSX-only). The source resolves asynchronously after the other props land; if resolution fails, the command fails at that entity even though its other props were applied. Patch `src` on its own to avoid ambiguity.- `syncTo` re-runs audio alignment against the document node carrying the given key and writes the entity's `start` from the measured offset (see [jsx/audio-sync.md](../jsx/audio-sync.md)). The command blocks until alignment settles; a failed alignment rejects the entity.- `transition` sets, merges into, or (with `null`) removes the clip's transition into the next clip (see [jsx/transitions.md](../jsx/transitions.md)).+- `animations` replaces the entity's preset in/out animations with the given list; `[]` removes them all (see [jsx/animations.md](../jsx/animations.md)).- Keyframe lists are accepted wherever the property is animatable, with the same semantics as mount (see [jsx/keyframes.md](../jsx/keyframes.md)); a static value replaces any existing keyframes.- Element applicability is not checked: props are applied wherever `mount` would apply them (e.g. `fontSize` only makes sense on a text node).diff --git a/apps/web/src/components/sidebar-left/assets.tsx b/apps/web/src/components/sidebar-left/assets.tsxindex 858e94be..c6da7118 100644--- a/apps/web/src/components/sidebar-left/assets.tsx+++ b/apps/web/src/components/sidebar-left/assets.tsx@@ -43,6 +43,7 @@ import { LazyAssetItem } from "./asset-item";import { FolderItem, handleFolderDrop, ASSET_DRAG_TYPE, FOLDER_DRAG_TYPE } from "./folder-item";import type { EngineWorld } from "@/components/engine";+import type { ElectronFileHandle } from "@/lib/electron-file-handle";export function Assets() {let root: HTMLDivElement | undefined;@@ -122,7 +123,7 @@ export function Assets() {}});- const importAssets = async (handles: ReadonlyArray<File | FileSystemFileHandle | DataTransferItem>) => {+ const importAssets = async (handles: ReadonlyArray<File | FileSystemFileHandle | ElectronFileHandle | DataTransferItem>) => {if (handles.length === 0) return;try {diff --git a/apps/web/src/context/editor-api/node.ts b/apps/web/src/context/editor-api/node.tsindex a3e57a4b..c2215bd2 100644--- a/apps/web/src/context/editor-api/node.ts+++ b/apps/web/src/context/editor-api/node.ts@@ -9,6 +9,7 @@ import { createImageEncoder } from "@/components/engine/encode/image-encoder";import { ElectronWritableFileHandle } from "@/lib/electron-file-writable";import {+ AnimationPhase,deleteEntity,isText,isScene,@@ -17,7 +18,7 @@ import {serializeEntity,} from "@/components/engine";import { ChildOf } from "@/components/engine/components";-import { WorldDocument } from "@/utils/jsx";+import { ANIMATION_TYPE_MAP, WorldDocument } from "@/utils/jsx";import { entityType } from "./selection";import type { EngineWorld, Engine } from "@/components/engine";@@ -38,6 +39,11 @@ import type {import type { EncoderConfig } from "@/components/engine/encode/interfaces";import type { Accessor } from "solid-js";+// The JSX animation names, keyed by engine preset.+const ANIMATION_TYPE_NAMES: Record<number, string> = Object.fromEntries(+ Object.entries(ANIMATION_TYPE_MAP).map(([name, type]) => [type, name]),+);+// Scenes are nodes too, so node ops accept them alongside geometry, groups,// and adjustment layers.export function isNode(world: EngineWorld, eid: number): boolean {@@ -153,6 +159,14 @@ function describeEntity(world: EngineWorld, eid: number): string {parts.push(`time: ${fmtTime(c.Keyframe.time[eid] ?? 0)}`, `value: ${c.Keyframe.value[eid]}`);if (c.Keyframe.easing[eid]) parts.push(`easing: ${c.Keyframe.easing[eid]}`);}+ if (hasComponent(world, eid, c.Animation)) {+ parts.push(+ `type: ${ANIMATION_TYPE_NAMES[c.Animation.type[eid] ?? 0] ?? c.Animation.type[eid]}`,+ `phase: ${c.Animation.phase[eid] === AnimationPhase.OUT ? "out" : "in"}`,+ `duration: ${fmtTime(c.Animation.duration[eid] ?? 0)}`,+ );+ if (c.Animation.delay[eid]) parts.push(`delay: ${fmtTime(c.Animation.delay[eid])}`);+ }if (hasComponent(world, eid, c.TextRange)) {parts.push(`range: ${c.TextRange.start[eid] ?? 0}–${c.TextRange.end[eid] ?? "end"}`);}diff --git a/apps/web/src/utils/jsx.ts b/apps/web/src/utils/jsx.tsindex 0a85cfc4..c4e3f5c5 100644--- a/apps/web/src/utils/jsx.ts+++ b/apps/web/src/utils/jsx.ts@@ -8,6 +8,8 @@ import * as solid from "solid-js";import * as solidStore from "solid-js/store";import * as diffusionJsx from "@diffusionstudio/jsx";import {+ AnimationPhase,+ AnimationType,CaptionType,FontStyle,GeometryType,@@ -180,6 +182,77 @@ function parseTransitionDuration(value: unknown): number {return frames;}+// JSX animation names, mapped to the presets the animations inspector writes.+// Exported for `node tree`'s entity descriptions.+export const ANIMATION_TYPE_MAP = {+ 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,+} as const;++const TEXT_ANIMATION_TYPES: ReadonlySet<AnimationType> = new Set([+ AnimationType.APPEAR_WORD,+ AnimationType.APPEAR_CHAR,+ AnimationType.SCRAMBLE,+]);++// 1 second at the canonical 30 fps — the animations inspector's default.+const ANIMATION_DEFAULT_DURATION = 30;++function parseAnimationSpec(+ entry: unknown,+ isTextNode: boolean,+): { type: AnimationType; phase: AnimationPhase; duration: number; delay: number } {+ assert(+ typeof entry === "object" && entry !== null && !Array.isArray(entry),+ "`animations` entries must be { type, phase?, duration?, delay? } objects" + `, value: ${entry}`,+ );+ const { type, phase, duration, delay } = entry as Record<string, unknown>;++ assert(typeof type === "string", "animation `type` must be a string" + `, value: ${type}`);+ const parsedType = ANIMATION_TYPE_MAP[type as keyof typeof ANIMATION_TYPE_MAP];+ assert(parsedType !== undefined, `invalid animation type: "${type}"`);+ assert(+ isTextNode || !TEXT_ANIMATION_TYPES.has(parsedType),+ `animation type "${type}" only applies to text elements`,+ );++ let parsedPhase = AnimationPhase.IN;+ if (phase !== undefined) {+ assert(phase === "in" || phase === "out", 'animation `phase` must be "in" or "out"' + `, value: ${phase}`);+ if (phase === "out") parsedPhase = AnimationPhase.OUT;+ }++ let parsedDuration = ANIMATION_DEFAULT_DURATION;+ if (duration !== undefined) {+ const frames = parseFrames(String(duration), 30);+ assert(typeof frames === "number", "animation `duration` must be a time value" + `, value: ${duration}`);+ assert(frames > 0, "animation `duration` must be > 0");+ parsedDuration = frames;+ }++ let parsedDelay = 0;+ if (delay !== undefined) {+ const frames = parseFrames(String(delay), 30);+ assert(typeof frames === "number", "animation `delay` must be a time value" + `, value: ${delay}`);+ assert(frames >= 0, "animation `delay` must be >= 0");+ parsedDelay = frames;+ }++ return { type: parsedType, phase: parsedPhase, duration: parsedDuration, delay: parsedDelay };+}+const CAPTION_PRESET_MAP = {classic: CaptionType.CLASSIC,cascade: CaptionType.CASCADE,@@ -684,6 +757,25 @@ export class WorldDocument implements ProjectDocument<DocumentNode> {}setComponent(world, eid, c.Transition, spec);break;+ } case "animations": {+ assert(+ Array.isArray(value),+ "`animations` must be an array of { type, phase?, duration?, delay? } objects" + `, value: ${value}`,+ );+ const isTextNode = c.Geometry[eid] === GeometryType.TEXT;+ const specs = value.map((entry) => parseAnimationSpec(entry, isTextNode));++ // The list replaces the node's existing animations; [] clears them.+ // Materialized before deleting — removal mutates the live query.+ for (const aid of [...query(world, [c.Animation, ChildOf(eid), Not(c.Deleted)])]) {+ deleteEntity(world, aid);+ }+ for (const spec of specs) {+ const aid = createEntity(world);+ setComponent(world, aid, c.Animation, spec);+ appendChild(world, aid, eid);+ }+ break;} case "src": {if (isAssetRef(value)) {world.history.untrack(() => addComponent(world, eid, c.Generating));diff --git a/packages/jsx/src/index.ts b/packages/jsx/src/index.tsindex a8f35940..804b62b5 100644--- a/packages/jsx/src/index.ts+++ b/packages/jsx/src/index.ts@@ -17,6 +17,8 @@ export { PATCH_PROP_KEYS } from "./types";export { parseTime, TIME_FPS } from "./time";export type {Animatable,+ AnimationSpec,+ AnimationType,AudioProps,CaptionPreset,CaptionsProps,diff --git a/packages/jsx/src/types.ts b/packages/jsx/src/types.tsindex a1159526..34fac85b 100644--- a/packages/jsx/src/types.ts+++ b/packages/jsx/src/types.ts@@ -63,6 +63,42 @@ export type TransitionSpec = {duration?: Time;};+/**+ * Preset animation styles — the editor's animations inspector options.+ * "appearWord" / "appearChar" / "scramble" apply only to text elements;+ * "gain" ramps audio and has no visual effect.+ */+export type AnimationType =+ | "fade"+ | "gain"+ | "grow"+ | "shrink"+ | "blur"+ | "slideLeft"+ | "slideRight"+ | "slideUp"+ | "slideDown"+ | "spin"+ | "twist"+ | "appearWord"+ | "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"@@ -120,6 +156,11 @@ export type PatchProps = {* 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[];/** Any CSS color, applied to the node's solid fill (created if absent); alpha is ignored — use `opacity`. */fill?: string;/**@@ -172,6 +213,7 @@ export const PATCH_PROP_KEYS = Object.keys({sourceOut: true,syncTo: true,transition: true,+ animations: true,fill: true,src: true,objectFit: true,@@ -195,7 +237,7 @@ type CommonProps = TimingProps &Pick<PatchProps,| "key" | "name" | "x" | "y" | "width" | "height" | "rotation" | "opacity" | "cornerRadius"- | "transition"+ | "transition" | "animations">;export type SceneProps = {@@ -246,7 +288,7 @@ export type ImageProps = CommonProps &export type AudioProps = TimingProps &Required<Pick<PatchProps, "src">> &- Pick<PatchProps, "name" | "volume" | "muted" | "syncTo">;+ Pick<PatchProps, "name" | "volume" | "muted" | "syncTo" | "animations">;export type TextProps = CommonProps &Pick<@@ -261,4 +303,4 @@ export type SequenceProps = Pick<PatchProps, "name"> & {children?: SolidJSX.Element;};-export type CaptionsProps = Pick<PatchProps, "preset" | "colors" | "src" | "start">;+export type CaptionsProps = Pick<PatchProps, "preset" | "colors" | "src" | "start" | "animations">;