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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsdeleted file mode 100644index 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.## Easingdiff --git a/reference/jsx/paints.md b/reference/jsx/paints.mdindex 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.