The VS Code of video editing, built for agents.
TypeScript
/* 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 { Active, AdjustmentLayer, Animation, AnimationPhase, AnimationType, appendChild, AssetId, Audio, Background, bindAsset, BlendMode, BlendModeType, Blur, Caption, CaptionAlign, CAPTION_PRESET_FILLS, CAPTION_PRESET_STYLES, CaptionType, Chars, ClipHeight, ClipsContent, Computed, Constraint, ConstraintCache, ConstraintType, CornerRadius, clampPointCount, createEntity, DEFAULT_BACKGROUND, Color, ColorStop, Delay, Effect, EffectType, EvenOdd, Expanded, FontStyle, FramePromises, FrameRate, getActiveEntity, Loop, LoadRequest, Mask, ClipPath, Geometry, GeometryType, getEntityTree, getParentEntity, getParentNode, Hidden, Host, isText, ItemIndex, KeepAspectRatio, Keyframe, KeyframeTrack, LINEAR_GRADIENT_DEFAULTS, LinearGradient, MixedCornerRadius, Mode, Muted, Name, Offset, Opacity, Pivot, Paint, PaintType, parseColor, parsePath, PathTrim, PendingSource, PendingSync, Playback, PlaybackRate, PointCount, Position, ELLIPTICAL_GRADIENT_DEFAULTS, EllipticalGradient, removeChild, RenderSurface, resizeEntity, Scale, ScaleMode, ScaleModeType, secondsToFrames, getAsset, getEntityChildren, Group, Sequential, Shader, Size, Stage, Root, Rotation, Scene, Selected, Shadow, Source, SourceFrameRate, setCameraMatrix, setPlayhead, setTimelineView, Stroke, StrokeCap, StrokeDash, StrokeJoin, StrokeStyle, SyncRequest, TextAlign, TextBaseline, TextCase, TextRange, TextStyle, Transition, TransitionType, Trim, UniformScale, VectorPath, ViewBox, Volume, Workarea } from '@diffusionstudio/runtime';
import { DEFAULT_MASK_SMOOTHING } from '@diffusionstudio/assets';
import { LOOP_ATTR, parseTime, SOURCE_ATTR } from '@diffusionstudio/jsx';
import { createSignal } from 'solid-js';
import { SVGElements } from 'solid-js/web';
import { IsExcluded } from 'koota';
import type { CameraMatrix, PropertyPath, SceneNode, TimelineView } from '@diffusionstudio/runtime';
import type { AnimatableProperty } from '@diffusionstudio/jsx';
import type { Entity, World } from 'koota';
import type { ProjectDocument, ProjectTick } from './host';
/** Props that address or wire an element rather than describe it. */
const UNAUTHORED_PROPS: ReadonlySet<string> = new Set([SOURCE_ATTR, LOOP_ATTR, 'children', 'ref']);
/**
* How long a single `hold` may keep an offline frame waiting. A project's
* async work is its own, so a promise that never settles is a real
* possibility, and an export that never finishes is worse than one that
* misses a picture.
*/
const HOLD_TIMEOUT_MS = 30_000;
export interface AuthoredElement {
/** The camelCase tag the project used. */
tag: string;
props: Record<string, unknown>;
/** The literal text of a `<text>`, when it holds any. */
text?: string;
}
/**
* The element `entity` was rendered from, as a project would author it, or
* undefined for an entity no document created (the stage included).
*/
export function authoredElement(entity: Entity): AuthoredElement | undefined {
const node = entity.get(Host);
if (!node || !node.native || node.tag === '') return undefined;
const text = isText(entity) ? entity.get(Chars)?.value : undefined;
return { tag: node.tag, props: { ...node.props }, ...(text ? { text } : {}) };
}
/** An authored element with the authored elements under it, in order. */
export interface AuthoredTree extends AuthoredElement {
children: AuthoredTree[];
}
/**
* The subtree `entity` was rendered from, as a project would author it:
* `authoredElement` of it and, recursively, of every child of its that a
* document created. Sub-entities the runtime derives (a recipe's paints) are
* not elements and are left out; they come back with the recipe.
*/
export function authoredTree(world: World, entity: Entity): AuthoredTree | undefined {
const element = authoredElement(entity);
if (element === undefined) return undefined;
const children: AuthoredTree[] = [];
for (const child of getEntityChildren(world, entity)) {
const tree = authoredTree(world, child);
if (tree) children.push(tree);
}
return { ...element, children };
}
export function isSceneNode(node: SceneNode | undefined): node is SceneNode {
return typeof node === 'object' && node !== null && 'entity' in node;
}
function isDomText(node: SceneNode | undefined): node is SceneNode & { readonly element: Text } {
return typeof Text !== 'undefined' && node?.element instanceof Text;
}
/**
* The text nodes among `node`'s children, in order; empty when it holds none.
*/
function textParts(node: SceneNode): (SceneNode & { readonly element: Text })[] {
return node.children.filter(isDomText);
}
/**
* Re-derives `Chars` from the text nodes `node` currently holds. Only a text
* entity has any to read: anywhere else a text node is a placeholder the
* renderer left behind and says nothing (see `insertNode`).
*/
function syncChars(node: SceneNode): void {
const { entity } = node;
if (!entity.isAlive() || !isText(entity)) return;
entity.add(Chars);
entity.set(Chars, { value: textParts(node).map((part) => part.element.data).join('') });
}
/**
* Takes `node` out of the children of whatever parent it has, and refreshes
* that parent's text.
*/
function detach(node: SceneNode): void {
const parent = node.parent;
if (parent === null) return;
const at = parent.children.indexOf(node);
if (at !== -1) parent.children.splice(at, 1);
node.parent = null;
syncChars(parent);
}
const PAINT_TYPES: Record<string, PaintType> = {
solidPaint: PaintType.SOLID,
linearGradientPaint: PaintType.LINEAR_GRADIENT,
radialGradientPaint: PaintType.RADIAL_GRADIENT,
angularGradientPaint: PaintType.ANGULAR_GRADIENT,
shaderPaint: PaintType.SHADER,
surfacePaint: PaintType.SURFACE,
htmlPaint: PaintType.HTML,
imagePaint: PaintType.IMAGE,
videoPaint: PaintType.VIDEO,
};
export const TRANSITION_TYPES: Record<string, TransitionType> = {
dissolve: TransitionType.DISSOLVE,
slideFromRight: TransitionType.SLIDE_FROM_RIGHT,
slideFromLeft: TransitionType.SLIDE_FROM_LEFT,
fadeToBlack: TransitionType.FADE_TO_BLACK,
fadeToWhite: TransitionType.FADE_TO_WHITE,
};
/** The canvas composite operations, spelled camelCase like the other enums. */
export const BLEND_MODES: Record<string, BlendModeType> = {
sourceOver: BlendModeType.SOURCE_OVER,
multiply: BlendModeType.MULTIPLY,
screen: BlendModeType.SCREEN,
overlay: BlendModeType.OVERLAY,
darken: BlendModeType.DARKEN,
lighten: BlendModeType.LIGHTEN,
colorDodge: BlendModeType.COLOR_DODGE,
colorBurn: BlendModeType.COLOR_BURN,
hardLight: BlendModeType.HARD_LIGHT,
softLight: BlendModeType.SOFT_LIGHT,
difference: BlendModeType.DIFFERENCE,
exclusion: BlendModeType.EXCLUSION,
hue: BlendModeType.HUE,
saturation: BlendModeType.SATURATION,
color: BlendModeType.COLOR,
luminosity: BlendModeType.LUMINOSITY,
};
/**
* The `constrainX` values as the runtime's anchors: which edge of the scene's
* frame the element is pinned to, or how it follows the frame instead.
*/
export const HORIZONTAL_CONSTRAINTS: Record<string, ConstraintType> = {
left: ConstraintType.MIN,
right: ConstraintType.MAX,
center: ConstraintType.CENTER,
stretch: ConstraintType.STRETCH,
scale: ConstraintType.SCALE,
};
/** The same for `constrainY`, whose near and far edges are top and bottom. */
export const VERTICAL_CONSTRAINTS: Record<string, ConstraintType> = {
top: ConstraintType.MIN,
bottom: ConstraintType.MAX,
center: ConstraintType.CENTER,
stretch: ConstraintType.STRETCH,
scale: ConstraintType.SCALE,
};
/**
* A `<keyframeTrack>`'s `property` (a prop name) as the runtime's property
* path. `width` depends on the holder: a stroke's is its line width.
*/
const TRACK_PROPERTIES: Record<string, PropertyPath> = {
x: 'position.x',
y: 'position.y',
offsetX: 'offset.x',
offsetY: 'offset.y',
width: 'width',
height: 'height',
rotation: 'rotation',
scale: 'scale',
scaleX: 'scale.x',
scaleY: 'scale.y',
opacity: 'opacity',
cornerRadius: 'vertexRadius',
cornerRadiusTopLeft: 'mixedVertexRadius.topLeft',
cornerRadiusTopRight: 'mixedVertexRadius.topRight',
cornerRadiusBottomRight: 'mixedVertexRadius.bottomRight',
cornerRadiusBottomLeft: 'mixedVertexRadius.bottomLeft',
volume: 'volume',
color: 'color',
offset: 'stop.offset',
x1: 'gradient.x1',
y1: 'gradient.y1',
x2: 'gradient.x2',
y2: 'gradient.y2',
cx: 'gradient.cx',
cy: 'gradient.cy',
rx: 'gradient.rx',
ry: 'gradient.ry',
blur: 'blur',
value: 'effect.value',
d: 'path',
trimStart: 'trim.start',
trimEnd: 'trim.end',
trimOffset: 'trim.offset',
dash: 'stroke.dash',
dashGap: 'stroke.dashGap',
dashOffset: 'stroke.dashOffset',
};
/**
* The runtime property path a `<keyframeTrack property>` under `holder`
* drives, or undefined for a name no track can take. `width` depends on the
* holder: a stroke's is its line width.
*/
export function trackPropertyPath(holder: Entity | null, property: string): PropertyPath | undefined {
const path = TRACK_PROPERTIES[property];
if (path === 'width' && holder?.has(Stroke)) return 'stroke.width';
return path;
}
/**
* The same the other way about: a path as the prop name it was written from.
* `stroke.width` is not a name of its own — on a stroke it is `width`.
*/
const TRACK_PROPERTY_NAMES = {
...Object.fromEntries(Object.entries(TRACK_PROPERTIES).map(([property, path]) => [path, property])),
'stroke.width': 'width',
} as Partial<Record<PropertyPath, AnimatableProperty>>;
/**
* The `<keyframeTrack property>` a track already in the world was written
* from, or undefined for a path no track can be authored for. What a surface
* holding a track (a timeline row, an inspector) needs to speak about it in
* the file's own names.
*/
export function trackProperty(path: string): AnimatableProperty | undefined {
return TRACK_PROPERTY_NAMES[path as PropertyPath];
}
/**
* Whether a keyframe's value is path data rather than a color: it opens with
* a moveto and a coordinate, which no CSS color does ("magenta" has no digit
* after its m).
*/
const PATH_DATA = /^\s*[Mm][\s,]*[-+.\d]/;
/** The `<rect>` props of the per-corner radii, in the trait's (CSS) order. */
const CORNER_PROPS = ['cornerRadiusTopLeft', 'cornerRadiusTopRight', 'cornerRadiusBottomRight', 'cornerRadiusBottomLeft'] as const;
/**
* Named easings as the descriptors the runtime (and the editor's
* interpolation inspector) speak; the descriptor forms pass through with
* their whitespace dropped, linear is the empty string.
*/
export const EASINGS: Record<string, string> = {
linear: '',
easeIn: 'cubicBezier(0.42,0,1,1)',
easeOut: 'cubicBezier(0,0,0.58,1)',
easeInOut: 'cubicBezier(0.42,0,0.58,1)',
gentle: 'spring(0.5,628)',
snappy: 'spring(0.15,300)',
bouncy: 'spring(0.4,500)',
strong: 'spring(0.65,400)',
};
export 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,
};
export const CAPTION_PRESETS: Record<string, CaptionType> = {
classic: CaptionType.CLASSIC,
cascade: CaptionType.CASCADE,
spotlight: CaptionType.SPOTLIGHT,
whisper: CaptionType.WHISPER,
paper: CaptionType.PAPER,
guinea: CaptionType.GUINEA,
stark: CaptionType.STARK,
};
export const CAPTION_ALIGNS: Record<string, CaptionAlign> = {
top: CaptionAlign.TOP,
center: CaptionAlign.CENTER,
bottom: CaptionAlign.BOTTOM,
};
export const EFFECT_TYPES: Record<string, EffectType> = {
blur: EffectType.LAYER_BLUR,
brightness: EffectType.BRIGHTNESS,
contrast: EffectType.CONTRAST,
grayscale: EffectType.GRAYSCALE,
hueRotate: EffectType.HUE_ROTATION,
invert: EffectType.INVERT,
saturate: EffectType.SATURATE,
sepia: EffectType.SEPIA,
opacity: EffectType.OPACITY,
};
const STROKE_JOINS: Record<string, StrokeJoin> = {
miter: StrokeJoin.MITER,
round: StrokeJoin.ROUND,
bevel: StrokeJoin.BEVEL,
};
const STROKE_CAPS: Record<string, StrokeCap> = {
butt: StrokeCap.BUTT,
round: StrokeCap.ROUND,
square: StrokeCap.SQUARE,
};
const SCALE_MODES: Record<string, ScaleModeType> = {
cover: ScaleModeType.COVER,
contain: ScaleModeType.FIT,
fill: ScaleModeType.FILL,
};
const FONT_STYLES: Record<string, FontStyle> = {
normal: FontStyle.NORMAL,
italic: FontStyle.ITALIC,
oblique: FontStyle.OBLIQUE,
};
const TEXT_ALIGNS: Record<string, TextAlign> = {
left: TextAlign.LEFT,
center: TextAlign.CENTER,
right: TextAlign.RIGHT,
};
const TEXT_BASELINES: Record<string, TextBaseline> = {
top: TextBaseline.TOP,
middle: TextBaseline.MIDDLE,
bottom: TextBaseline.BOTTOM,
alphabetic: TextBaseline.ALPHABETIC,
};
const TEXT_CASES: Record<string, TextCase> = {
original: TextCase.ORIGINAL,
upper: TextCase.UPPER,
lower: TextCase.LOWER,
};
const FONT_WEIGHTS: Record<string, string> = {
normal: '400',
bold: '700',
};
// The authored props that overwrite a caption preset's base coat (its
// TextStyle and its intrinsic `fill`). The `preset` handler re-runs them
// after writing the preset's defaults: props are not applied in authored
// order, so some may have landed before it.
const CAPTION_OVERRIDE_PROPS = [
'fontSize',
'fontFamily',
'fontWeight',
'fontStyle',
'textAlign',
'textBaseline',
'textCase',
'letterSpacing',
'leading',
'fill',
] as const;
/**
* A numeric prop's value, or undefined for none. A boolean is none, not 0
* or 1: `false` is how an editor unsets a prop (the writer spells it as the
* attribute's absence), and a number prop has no true.
*/
function toNumber(value: unknown) {
if (value === undefined || value === null || typeof value === 'boolean') {
return undefined;
}
const number = Number(value);
return Number.isFinite(number) ? number : undefined;
}
function toSeconds(value: unknown): number | undefined {
if (typeof value !== 'number' && typeof value !== 'string') {
return undefined;
}
return parseTime(value);
}
export class RuntimeDocument implements ProjectDocument<SceneNode> {
public readonly stage: SceneNode;
private readonly world: World;
public constructor(world: World) {
this.world = world;
const root = world.get(Root)!;
this.stage = {
entity: root,
native: true,
tag: '',
props: {},
parent: null,
children: [],
element: null,
};
root.add(Host);
root.set(Host, this.stage);
this.resolutionSignal[1](this.readResolution());
}
/**
* The node of `entity`: the one object the document and the renderer both
* hold for it (see `Host`), so `===` between two of them means what it
* says. An entity the document never created is adopted here rather than
* refused — it has no place in the tree yet, which is what an empty node
* says — so an editor can hand any entity to `insertNode` or `setProperty`.
*/
public node(entity: Entity): SceneNode {
const held = entity.get(Host);
if (held) return held;
const node: SceneNode = {
entity,
native: true,
tag: '',
props: {},
parent: null,
children: [],
element: null,
};
entity.add(Host);
entity.set(Host, node);
return node;
}
public createElement(tag: string): SceneNode {
// camelCase composition tags are DOM elements.
if (tag.charAt(0) === tag.charAt(0).toLowerCase()) {
if (typeof document === 'undefined') {
throw new Error(`<${tag}> requires a DOM`);
}
if (tag === 'audio' || tag === 'video') {
throw new Error(
`<${tag}> is not supported as HTML content; use the <${tag}> composition element outside the HTML subtree`,
);
}
if (tag === 'canvas') {
throw new Error('<canvas> is not supported as HTML content; use <surface> for custom drawing');
}
const element = SVGElements.has(tag)
? document.createElementNS('http://www.w3.org/2000/svg', tag)
: document.createElement(tag);
const entity = createEntity(this.world);
const node: SceneNode = {
entity,
native: false,
tag,
props: {},
parent: null,
children: [],
element,
};
entity.add(Host);
entity.set(Host, node);
return node;
}
const name = tag.charAt(0).toLowerCase() + tag.slice(1);
let entity: Entity;
let element: Element | null = null;
switch (name) {
case 'stage':
entity = this.stage.entity;
break;
case 'scene': {
entity = createEntity(this.world);
entity.add(Geometry);
entity.set(Geometry, { value: GeometryType.RECT });
entity.add(Position);
entity.set(Position, { x: 0, y: 0 });
entity.add(Scene);
entity.add(ClipsContent);
entity.add(Playback);
resizeEntity(this.world, entity, { width: 1920, height: 1080 });
break;
}
case 'group': {
// No Size: a group's box is the union of its children's.
entity = createEntity(this.world);
entity.add(Group);
entity.add(Position);
entity.set(Position, { x: 0, y: 0 });
break;
}
case 'sequence': {
entity = createEntity(this.world);
entity.add(Sequential);
break;
}
case 'captions': {
entity = createEntity(this.world);
entity.add(Geometry);
entity.set(Geometry, { value: GeometryType.TEXT });
entity.add(Position);
entity.set(Position, { x: 0, y: 0 });
entity.add(Chars);
entity.add(Caption);
entity.add(TextStyle);
entity.set(TextStyle, CAPTION_PRESET_STYLES[CaptionType.CLASSIC]);
entity.add(Color);
entity.set(Color, { value: CAPTION_PRESET_FILLS[CaptionType.CLASSIC]! });
break;
}
case 'adjustmentLayer': {
entity = createEntity(this.world);
entity.add(AdjustmentLayer);
entity.add(Position);
entity.set(Position, { x: 0, y: 0 });
resizeEntity(this.world, entity, { width: 1920, height: 1080 });
break;
}
case 'rect': {
entity = createEntity(this.world);
entity.add(Geometry);
entity.set(Geometry, { value: GeometryType.RECT });
entity.add(Position);
entity.set(Position, { x: 0, y: 0 });
resizeEntity(this.world, entity, { width: 100, height: 100 });
break;
}
case 'ellipse':
case 'polygon': {
entity = createEntity(this.world);
entity.add(Geometry);
entity.set(Geometry, { value: name === 'ellipse' ? GeometryType.ELLIPSE : GeometryType.POLYGON });
entity.add(Position);
entity.set(Position, { x: 0, y: 0 });
resizeEntity(this.world, entity, { width: 100, height: 100 });
break;
}
case 'path': {
entity = createEntity(this.world);
entity.add(Geometry);
entity.set(Geometry, { value: GeometryType.PATH });
entity.add(Position);
entity.set(Position, { x: 0, y: 0 });
resizeEntity(this.world, entity, { width: 100, height: 100 });
break;
}
case 'text': {
// No Size: a text without one sizes itself to its glyphs.
entity = createEntity(this.world);
entity.add(Geometry);
entity.set(Geometry, { value: GeometryType.TEXT });
entity.add(Position);
entity.set(Position, { x: 0, y: 0 });
entity.add(Chars);
entity.add(TextStyle);
break;
}
case 'textRange': {
entity = createEntity(this.world);
entity.add(TextRange);
entity.set(TextRange, { start: 0, end: null });
entity.add(TextStyle);
break;
}
case 'video': {
entity = createEntity(this.world);
entity.add(Geometry);
entity.set(Geometry, { value: GeometryType.RECT });
entity.add(Position);
entity.set(Position, { x: 0, y: 0 });
entity.add(Paint);
entity.set(Paint, { value: PaintType.VIDEO });
resizeEntity(this.world, entity, { width: 1920, height: 1080 });
break;
}
case 'image': {
entity = createEntity(this.world);
entity.add(Geometry);
entity.set(Geometry, { value: GeometryType.RECT });
entity.add(Position);
entity.set(Position, { x: 0, y: 0 });
entity.add(Paint);
entity.set(Paint, { value: PaintType.IMAGE });
resizeEntity(this.world, entity, { width: 1920, height: 1080 });
break;
}
case 'audio': {
entity = createEntity(this.world);
entity.add(Geometry);
entity.set(Geometry, { value: GeometryType.RECT });
entity.add(Position);
entity.set(Position, { x: 0, y: 0 });
entity.add(Audio);
entity.add(Paint);
entity.set(Paint, { value: PaintType.WAVEFORM });
resizeEntity(this.world, entity, { width: 500, height: 150 });
break;
}
case 'solidPaint':
case 'linearGradientPaint':
case 'radialGradientPaint':
case 'angularGradientPaint':
case 'shaderPaint':
case 'surfacePaint':
case 'htmlPaint':
case 'imagePaint':
case 'videoPaint': {
entity = createEntity(this.world);
entity.add(Paint);
entity.set(Paint, { value: PAINT_TYPES[name]! });
if (name === 'solidPaint') entity.add(Color);
if (name === 'shaderPaint') entity.add(Shader);
if (name === 'surfacePaint') {
element = document.createElement('canvas');
}
if (name === 'htmlPaint') {
const root = document.createElement('div');
root.style.cssText = 'position:absolute;left:0;top:0;overflow:hidden;pointer-events:none;';
const canvas = this.world.get(RenderSurface)?.canvas;
assert(canvas instanceof HTMLCanvasElement, 'HTML paint must be on a canvas');
canvas.toggleAttribute('layoutsubtree', true);
canvas.appendChild(root);
element = root;
}
break;
}
case 'html': {
entity = createEntity(this.world);
entity.add(Geometry);
entity.set(Geometry, { value: GeometryType.RECT });
entity.add(Position);
entity.set(Position, { x: 0, y: 0 });
entity.add(Paint);
entity.set(Paint, { value: PaintType.HTML });
const root = document.createElement('div');
root.style.cssText = 'position:absolute;left:0;top:0;overflow:hidden;pointer-events:none;';
const canvas = this.world.get(RenderSurface)?.canvas;
assert(canvas instanceof HTMLCanvasElement, 'HTML paint must be on a canvas');
canvas.toggleAttribute('layoutsubtree', true);
canvas.appendChild(root);
element = root;
resizeEntity(this.world, entity, { width: 100, height: 100 });
break;
}
case 'surface': {
// A rect whose intrinsic paint is the surface, like <video>'s is
// its media: the host lives on the geometry itself.
entity = createEntity(this.world);
entity.add(Geometry);
entity.set(Geometry, { value: GeometryType.RECT });
entity.add(Position);
entity.set(Position, { x: 0, y: 0 });
entity.add(Paint);
entity.set(Paint, { value: PaintType.SURFACE });
element = document.createElement('canvas');
resizeEntity(this.world, entity, { width: 100, height: 100 });
break;
}
case 'colorStop': {
entity = createEntity(this.world);
entity.add(ColorStop);
break;
}
case 'stroke': {
entity = createEntity(this.world);
entity.add(Stroke);
entity.add(Paint);
entity.set(Paint, { value: PaintType.SOLID });
entity.add(StrokeStyle);
break;
}
case 'shadow': {
entity = createEntity(this.world);
entity.add(Shadow);
entity.add(Color);
break;
}
case 'effect': {
entity = createEntity(this.world);
entity.add(Effect);
entity.set(Effect, { type: EffectType.LAYER_BLUR, value: 0 });
break;
}
case 'clipPath': {
entity = createEntity(this.world);
entity.add(ClipPath);
break;
}
case 'mask': {
entity = createEntity(this.world);
entity.add(Mask);
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.
entity = createEntity(this.world);
entity.add(KeyframeTrack);
break;
}
case 'keyframe': {
entity = createEntity(this.world);
entity.add(Keyframe);
entity.set(Keyframe, { easing: '' });
break;
}
default:
throw new Error(
`<${tag}> is not supported yet (only composition elements exported by @diffusionstudio/jsx are accepted).`,
);
}
// The stage is the document's own node rather than one it creates: a
// project spelling `<stage>` addresses the one already there.
if (entity === this.stage.entity) {
return this.stage;
}
const node: SceneNode = {
entity,
native: true,
tag: name,
props: {},
parent: null,
children: [],
element,
};
entity.add(Host);
entity.set(Host, node);
return node;
}
public createTextNode(text: string): SceneNode {
const entity = createEntity(this.world);
const node: SceneNode = {
entity,
native: false,
tag: '#text',
props: {},
parent: null,
children: [],
element: document.createTextNode(text),
};
entity.add(Host);
entity.set(Host, node);
return node;
}
public replaceText(node: SceneNode, text: string): void {
if (!isDomText(node)) return;
node.element.data = text;
const owner = node.parent;
if (owner) syncChars(owner);
}
public isTextNode(node: SceneNode): boolean {
return isDomText(node);
}
/**
* Replaces everything a `<text>` says. Its children rather than a prop, so
* an editor changing it comes here instead of through `setProperty`. The
* text nodes the reconciler holds keep their identity — the first says all
* of it and the rest say nothing — so a render that later updates one of
* them still lands where it did. An entity holding none (a text drawn on
* the canvas, whose element is not written yet) gets `Chars` alone.
*/
public setText(entity: Entity, text: string): void {
const node = this.node(entity);
const parts = textParts(node);
if (parts.length === 0) {
entity.add(Chars);
entity.set(Chars, { value: text });
return;
}
for (const [index, part] of parts.entries()) {
part.element.data = index === 0 ? text : '';
}
syncChars(node);
}
public setProperty(node: SceneNode, name: string, value: unknown): void {
if (!isSceneNode(node)) return;
if (!node.native && node.element instanceof Element) {
setDomProperty(node.element, name, value);
}
const { entity } = node;
// The stage and anything adopted from outside are no element of the
// project's, so nothing they are given is written down as one.
if (node.tag !== '' && !UNAUTHORED_PROPS.has(name)) {
if (value === undefined) delete node.props[name];
else node.props[name] = value;
}
switch (name) {
case LOOP_ATTR: {
if (typeof value !== 'string' || !value) {
entity.remove(Loop);
return;
}
entity.add(Loop);
entity.set(Loop, { value });
return;
}
case SOURCE_ATTR: {
if (typeof value !== 'string' || !value) {
entity.remove(Source);
return;
}
entity.add(Source);
entity.set(Source, { value });
return;
}
case 'name': {
if (typeof value !== 'string' || !value) {
entity.remove(Name);
return;
}
entity.add(Name);
entity.set(Name, { value });
return;
}
case 'selected': {
if (value === true && entity !== this.stage.entity) {
entity.add(Selected);
} else {
entity.remove(Selected);
}
return;
}
case 'active': {
// Uniqueness and root-only are the runtime's observers' business.
if (value === true && entity !== this.stage.entity) {
entity.add(Active);
} else {
entity.remove(Active);
}
return;
}
case 'clipHeight': {
const height = toNumber(value);
if (height === undefined) {
entity.remove(ClipHeight);
return;
}
entity.add(ClipHeight);
entity.set(ClipHeight, { value: height });
return;
}
case 'expanded': {
if (value === true) {
entity.add(Expanded);
} else {
entity.remove(Expanded);
}
return;
}
case 'timeline': {
if (!Array.isArray(value) || value.length !== 3) return;
const numbers = value.map(toNumber);
if (!numbers.includes(undefined)) {
setTimelineView(this.world, entity, (numbers as TimelineView));
}
return;
}
case 'playhead': {
if (!entity.has(Scene)) return;
const seconds = toSeconds(value);
if (seconds !== undefined) {
setPlayhead(this.world, entity, this.toFrames(seconds));
}
return;
}
case 'x':
case 'y': {
if (entity.has(Sequential)) return;
entity.add(Position);
entity.set(Position, { [name]: toNumber(value) ?? 0 });
return;
}
case 'offsetX':
case 'offsetY': {
if (entity.has(Sequential)) return;
entity.add(Offset);
entity.set(Offset, { [name === 'offsetX' ? 'x' : 'y']: toNumber(value) ?? 0 });
return;
}
case 'rotation': {
if (entity.has(Sequential)) return;
entity.add(Rotation);
entity.set(Rotation, { value: toNumber(value) ?? 0 });
return;
}
case 'scale': {
// Uniform; wins over scaleX/scaleY while present (motion system).
if (entity.has(Sequential)) return;
const scale = toNumber(value);
if (scale === undefined) {
entity.remove(UniformScale);
return;
}
entity.add(UniformScale);
entity.set(UniformScale, { value: scale });
return;
}
case 'scaleX':
case 'scaleY': {
if (entity.has(Sequential)) return;
entity.add(Scale);
entity.set(Scale, { [name === 'scaleX' ? 'x' : 'y']: toNumber(value) ?? 1 });
return;
}
case 'pivotX':
case 'pivotY': {
const { entity, props } = node;
if (entity.has(Sequential)) return;
// One trait for both axes: absent, the node turns about its
// anchor (a group about its origin), so an axis left out of a
// pivot that has the other is 0, like an unset x.
const x = toNumber(props.pivotX);
const y = toNumber(props.pivotY);
if (x === undefined && y === undefined) {
entity.remove(Pivot);
return;
}
entity.add(Pivot);
entity.set(Pivot, { x: x ?? 0, y: y ?? 0 });
return;
}
case 'constrainX':
case 'constrainY': {
const { entity, props } = node;
// A sequence is not a spatial construct; it mirrors its parent's frame.
if (entity.has(Sequential)) return;
const horizontal = typeof props.constrainX === 'string' ? HORIZONTAL_CONSTRAINTS[props.constrainX] : undefined;
const vertical = typeof props.constrainY === 'string' ? VERTICAL_CONSTRAINTS[props.constrainY] : undefined;
if (horizontal === undefined && vertical === undefined) {
entity.remove(Constraint);
entity.remove(ConstraintCache);
return;
}
entity.add(Constraint);
entity.set(Constraint, {
horizontal: horizontal ?? ConstraintType.MIN,
vertical: vertical ?? ConstraintType.MIN,
});
return;
}
case 'cornerRadius': {
const radius = toNumber(value);
if (radius === undefined) {
entity.remove(CornerRadius);
} else {
entity.add(CornerRadius);
entity.set(CornerRadius, { value: radius });
}
// The corners without a radius of their own take this one.
this.syncCornerRadii(node);
return;
}
case 'cornerRadiusTopLeft':
case 'cornerRadiusTopRight':
case 'cornerRadiusBottomRight':
case 'cornerRadiusBottomLeft': {
this.syncCornerRadii(node);
return;
}
case 'pointCount': {
if (entity.get(Geometry)?.value !== GeometryType.POLYGON) return;
const count = toNumber(value);
if (count === undefined) {
entity.remove(PointCount);
} else {
entity.add(PointCount);
entity.set(PointCount, { value: clampPointCount(count) });
}
return;
}
case 'd': {
if (typeof value !== 'string') {
entity.remove(VectorPath);
return;
}
const { geometry, error } = parsePath(value);
if (error !== null) {
console.warn(`[path] ${error} in d="${value}"`);
}
entity.add(VectorPath);
entity.set(VectorPath, { geometry });
return;
}
case 'viewBox': {
const numbers = typeof value === 'string' ? value.trim().split(/[\s,]+/).map(Number) : [];
const [x, y, width, height] = numbers;
if (numbers.length !== 4 || numbers.some((n) => !Number.isFinite(n)) || width! <= 0 || height! <= 0) {
entity.remove(ViewBox);
return;
}
entity.add(ViewBox);
entity.set(ViewBox, { x: x!, y: y!, width: width!, height: height! });
return;
}
case 'fillRule': {
if (value === 'evenodd') {
entity.add(EvenOdd);
} else {
entity.remove(EvenOdd);
}
return;
}
case 'trimStart':
case 'trimEnd':
case 'trimOffset': {
const start = toNumber(node.props.trimStart);
const end = toNumber(node.props.trimEnd);
const offset = toNumber(node.props.trimOffset);
if (start === undefined && end === undefined && offset === undefined) {
entity.remove(PathTrim);
return;
}
entity.add(PathTrim);
entity.set(PathTrim, { start: start ?? 0, end: end ?? 1, offset: offset ?? 0 });
return;
}
case 'blendMode': {
const mode = typeof value === 'string' ? BLEND_MODES[value] : undefined;
if (mode === undefined || mode === BlendModeType.SOURCE_OVER) {
entity.remove(BlendMode);
return;
}
entity.add(BlendMode);
entity.set(BlendMode, { value: mode });
return;
}
case 'inverted': {
if (!entity.has(Mask)) return;
entity.set(Mask, { inverted: value === true });
return;
}
case 'smoothing': {
if (!entity.has(Mask)) return;
const amount = toNumber(value) ?? DEFAULT_MASK_SMOOTHING;
entity.set(Mask, { smoothing: Math.min(1, Math.max(0, amount)) });
return;
}
case 'keepAspectRatio': {
this.syncAspectLock(node);
return;
}
case 'hidden': {
if (value === true && entity !== this.stage.entity) {
entity.add(Hidden);
} else {
entity.remove(Hidden);
}
return;
}
case 'playbackRate': {
const rate = toNumber(value);
if (rate === undefined || rate === 0) {
entity.remove(PlaybackRate);
} else {
entity.add(PlaybackRate);
entity.set(PlaybackRate, { value: rate });
}
// The rate scales the authored window onto the runtime's traits,
// so they are re-derived with it.
this.syncTiming(node);
return;
}
case 'transition': {
if (typeof value !== 'object' || value === null) {
entity.remove(Transition);
return;
}
if (!entity.has(Transition)) {
entity.add(Transition);
entity.set(Transition, { type: TransitionType.DISSOLVE, duration: this.toFrames(1) });
}
const spec = value as { type?: unknown; duration?: unknown };
if ('type' in spec) {
const type = typeof spec.type === 'string' ? TRANSITION_TYPES[spec.type] : undefined;
entity.set(Transition, { type: type ?? TransitionType.DISSOLVE });
}
if ('duration' in spec) {
entity.set(Transition, { duration: this.toFrames(toSeconds(spec.duration) ?? 1) });
}
return;
}
case 'wgsl': {
if (!entity.has(Shader)) return;
entity.set(Shader, { code: typeof value === 'string' ? value : '' });
return;
}
case 'uniforms': {
if (!entity.has(Shader)) return;
const uniforms = typeof value === 'object' && value !== null && !Array.isArray(value)
? { ...(value as Record<string, number | number[] | string>) }
: null;
entity.set(Shader, { uniforms });
return;
}
case 'width':
case 'height': {
const size = toNumber(value);
if (entity.has(Stroke)) {
// A stroke's width is its line width; it has no box.
if (name === 'width') entity.set(StrokeStyle, { width: size ?? 1 });
return;
}
if (size === undefined) {
// A text is the one element whose box is optional: with
// neither bound authored it sizes itself to its glyphs
// again. Size holds both, so it only goes when both are.
const other = name === 'width' ? 'height' : 'width';
if (isText(entity) && toNumber(node.props[other]) === undefined) {
entity.remove(Size);
}
return;
}
// The lock pins the authored bounds, and this is one of them.
if (node.props.keepAspectRatio === true) {
this.syncAspectLock(node);
}
resizeEntity(this.world, entity, { [name]: size });
return;
}
case 'join': {
if (!entity.has(Stroke)) return;
const join = typeof value === 'string' ? STROKE_JOINS[value] : undefined;
entity.set(StrokeStyle, { join: join ?? StrokeJoin.MITER });
return;
}
case 'cap': {
if (!entity.has(Stroke)) return;
const cap = typeof value === 'string' ? STROKE_CAPS[value] : undefined;
entity.set(StrokeStyle, { cap: cap ?? StrokeCap.BUTT });
return;
}
case 'miterLimit': {
if (!entity.has(Stroke)) return;
entity.set(StrokeStyle, { miterLimit: toNumber(value) ?? 10 });
return;
}
case 'dash':
case 'dashGap':
case 'dashOffset': {
if (!entity.has(Stroke)) return;
const dash = toNumber(node.props.dash);
const gap = toNumber(node.props.dashGap);
const offset = toNumber(node.props.dashOffset);
if (dash === undefined && gap === undefined && offset === undefined) {
entity.remove(StrokeDash);
return;
}
// An unset gap is the dash length as written; a `dash` track
// leaves it there.
entity.add(StrokeDash);
entity.set(StrokeDash, {
dash: Math.max(0, dash ?? 0),
gap: Math.max(0, gap ?? dash ?? 0),
offset: offset ?? 0,
});
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. Path data, on a `d` track, is an outline instead.
const path = typeof value === 'string' && PATH_DATA.test(value) ? parsePath(value).geometry : null;
entity.set(Keyframe, { value: path ? 0 : toNumber(value) ?? parseColor(value) ?? 0, path });
return;
}
if (!entity.has(Effect)) return;
entity.set(Effect, { value: toNumber(value) ?? 0 });
return;
}
case 'property': {
if (!entity.has(KeyframeTrack)) return;
this.resolveTrackProperty(entity, value);
return;
}
case 'time': {
if (!entity.has(Keyframe)) return;
const seconds = toSeconds(value);
entity.set(Keyframe, { time: this.toFrames(seconds ?? 0) });
return;
}
case 'easing': {
if (!entity.has(Keyframe)) return;
const easing = typeof value === 'string' ? value.replace(/\s+/g, '') : '';
entity.set(Keyframe, { easing: EASINGS[easing] ?? easing });
return;
}
case 'blur': {
const blur = toNumber(value);
if (blur === undefined) {
entity.remove(Blur);
return;
}
entity.add(Blur);
entity.set(Blur, { value: blur });
return;
}
case 'start':
case 'end':
case 'sourceIn':
case 'sourceOut': {
if (entity.has(Mask)) {
// A mask's frames start at this source time of its parent.
if (name === 'sourceIn') {
entity.set(Mask, { offset: this.toFrames(toSeconds(value) ?? 0) })
};
return;
}
if (entity.has(TextRange)) {
// A range's start/end are character indices, not times; an
// unset end runs to the end of the text.
if (name === 'start') {
entity.set(TextRange, { start: Math.max(0, Math.trunc(toNumber(value) ?? 0)) });
}
if (name === 'end') {
const end = toNumber(value);
entity.set(TextRange, { end: end === undefined ? null : Math.max(0, Math.trunc(end)) });
}
return;
}
this.syncTiming(node);
return;
}
case 'frameRate': {
// Frames per second for a frames-directory source, which is the
// only thing that says how long it lasts. The world's own frame
// rate is the composition's and is not authored per element, so
// this name is free to mean the source's.
const fps = toNumber(value);
if (fps === undefined || fps <= 0) {
entity.remove(SourceFrameRate);
return;
}
entity.add(SourceFrameRate);
entity.set(SourceFrameRate, { value: fps });
return;
}
case 'src': {
// The resolution running for the old src is superseded by
// whatever this one starts.
entity.remove(LoadRequest, PendingSource);
// `false` is how an editor unsets a prop (the writer drops the attribute).
if (typeof value !== 'string' || value === '') {
entity.remove(AssetId);
return;
}
const known = getAsset(this.world, value);
if (known) {
bindAsset(entity, known);
return;
}
entity.remove(AssetId);
entity.add(LoadRequest);
entity.set(LoadRequest, { value });
return;
}
case 'objectFit': {
const mode = typeof value === 'string' ? SCALE_MODES[value] : undefined;
if (mode === undefined) {
entity.remove(ScaleMode);
return;
}
entity.add(ScaleMode);
entity.set(ScaleMode, { value: mode });
return;
}
case 'volume': {
// Decibels; -Infinity is silence, not an invalid number.
const decibels = value === -Infinity ? value : toNumber(value);
if (decibels === undefined) {
entity.remove(Volume);
return;
}
entity.add(Volume);
entity.set(Volume, { value: decibels });
return;
}
case 'muted': {
if (value === true) {
entity.add(Muted);
} else {
entity.remove(Muted);
}
return;
}
case 'syncTo': {
entity.remove(PendingSync);
if (typeof value !== 'string' || value === '') {
entity.remove(SyncRequest);
return;
}
entity.add(SyncRequest);
entity.set(SyncRequest, { value });
return;
}
case 'fill':
case 'color': {
const color = parseColor(value);
if (color === null) {
entity.remove(Color);
return;
}
entity.add(Color);
entity.set(Color, { value: color });
return;
}
case 'opacity': {
const opacity = toNumber(value);
if (opacity === undefined) {
entity.remove(Opacity);
return;
}
entity.add(Opacity);
entity.set(Opacity, { value: opacity });
return;
}
case 'offset': {
if (entity.has(ColorStop)) {
entity.set(ColorStop, { offset: toNumber(value) ?? 0 });
}
return;
}
case 'x1':
case 'y1':
case 'x2':
case 'y2': {
if (entity.get(Paint)?.value !== PaintType.LINEAR_GRADIENT) return;
entity.add(LinearGradient);
entity.set(LinearGradient, { [name]: toNumber(value) ?? LINEAR_GRADIENT_DEFAULTS[name as keyof typeof LINEAR_GRADIENT_DEFAULTS] });
return;
}
case 'cx':
case 'cy':
case 'rx':
case 'ry': {
const paint = entity.get(Paint)?.value;
if (paint !== PaintType.RADIAL_GRADIENT && paint !== PaintType.ANGULAR_GRADIENT) return;
entity.add(EllipticalGradient);
entity.set(EllipticalGradient, { [name]: toNumber(value) ?? ELLIPTICAL_GRADIENT_DEFAULTS[name as keyof typeof ELLIPTICAL_GRADIENT_DEFAULTS] });
return;
}
case 'fontSize': {
const size = toNumber(value);
entity.add(TextStyle);
entity.set(TextStyle, { fontSize: size !== undefined && size > 0 ? Math.round(size) : undefined });
return;
}
case 'fontFamily': {
const family = typeof value === 'string' ? value.trim() : '';
entity.add(TextStyle);
entity.set(TextStyle, { fontFamily: family || undefined });
return;
}
case 'fontWeight': {
// Authored as a CSS keyword or a number; the trait keeps the numeric string.
const weight = value === undefined || value === null ? '' : String(value).trim();
const numeric = FONT_WEIGHTS[weight] ?? weight;
entity.add(TextStyle);
entity.set(TextStyle, { fontWeight: numeric && Number.isFinite(Number(numeric)) ? numeric : undefined });
return;
}
case 'fontStyle': {
entity.add(TextStyle);
entity.set(TextStyle, { fontStyle: typeof value === 'string' ? FONT_STYLES[value] : undefined });
return;
}
case 'textAlign': {
entity.add(TextStyle);
entity.set(TextStyle, { textAlign: typeof value === 'string' ? TEXT_ALIGNS[value] : undefined });
return;
}
case 'textBaseline': {
entity.add(TextStyle);
entity.set(TextStyle, { textBaseline: typeof value === 'string' ? TEXT_BASELINES[value] : undefined });
return;
}
case 'textCase': {
entity.add(TextStyle);
entity.set(TextStyle, { textCase: typeof value === 'string' ? TEXT_CASES[value] : undefined });
return;
}
case 'letterSpacing': {
entity.add(TextStyle);
entity.set(TextStyle, { letterSpacing: toNumber(value) });
return;
}
case 'leading': {
const leading = toNumber(value);
entity.add(TextStyle);
entity.set(TextStyle, { leading: leading !== undefined && leading > 0 ? leading : undefined });
return;
}
case 'preset': {
if (!entity.has(Caption)) return;
const preset = typeof value === 'string' ? CAPTION_PRESETS[value] : undefined;
const type = preset ?? CaptionType.CLASSIC;
entity.set(Caption, { type });
// The preset is the caption's base coat: write its styles and
// its intrinsic fill, then re-run the authored overrides that
// may already have been applied before this prop was.
entity.add(TextStyle);
entity.set(TextStyle, CAPTION_PRESET_STYLES[type]);
const fill = CAPTION_PRESET_FILLS[type];
if (fill === undefined) {
entity.remove(Color);
} else {
entity.add(Color);
entity.set(Color, { value: fill });
}
for (const prop of CAPTION_OVERRIDE_PROPS) {
const authored = node.props[prop];
if (authored !== undefined) this.setProperty(node, prop, authored);
}
return;
}
case 'colors': {
if (!entity.has(Caption)) return;
const colors: number[] = [];
if (Array.isArray(value)) {
value.forEach((entry, index) => {
const color = parseColor(entry);
if (color !== null) colors[index] = color;
});
}
entity.set(Caption, { colors });
return;
}
case 'verticalAlign': {
if (!entity.has(Caption)) return;
entity.set(Caption, {
verticalAlign: typeof value === 'string'
? CAPTION_ALIGNS[value]
: undefined,
});
return;
}
case 'workarea': {
// Two times or none: a half-authored range says nothing, and
// `false` is what the editor writes to take the brackets off.
const range = Array.isArray(value) ? value.map(toSeconds) : [];
const [start, end] = range;
if (range.length !== 2 || start === undefined || end === undefined) {
entity.remove(Workarea);
return;
}
entity.add(Workarea);
entity.set(Workarea, { start: this.toFrames(start), end: this.toFrames(end) });
return;
}
case 'background': {
const color = parseColor(value);
this.stage.entity.set(Background, { value: color ?? DEFAULT_BACKGROUND });
return;
}
case 'camera': {
if (!Array.isArray(value) || value.length !== 6) return;
const numbers = value.map(toNumber);
if (!numbers.includes(undefined)) {
setCameraMatrix(this.world, (numbers as CameraMatrix));
}
return;
}
default:
// children/ref and anything from a richer vocabulary: ignored, so
// such a project still renders what this host understands.
return;
}
}
/** Seconds as frames of this project. */
private toFrames(seconds: number): number {
return secondsToFrames(seconds, this.world.get(FrameRate)?.value ?? 30);
}
/**
* Reconciles the authored time props (`start`/`end`/`sourceIn`/`sourceOut`,
* the copy this node holds) into the runtime's own vocabulary, Delay and
* Trim. Recomputed whole from the props on every one of them (and on
* `playbackRate`, which scales the window), so the order Solid sets them in
* does not matter.
*
* Delay places the node's local time 0 on its parent's timeline: the
* authored start, pulled back by the stretch of source the trim skips
* (`start - sourceIn/rate`), so the trimmed window opens at the start. The
* trim is the source window; an authored end becomes source frames through
* the rate, and whichever of it and sourceOut closes first wins. With no
* out bound at all the trim stays open (`end: null`) and the runtime runs
* the clip to its source's natural end.
*/
private syncTiming(node: SceneNode): void {
const { entity, props } = node;
const rate = toNumber(props.playbackRate) || 1;
const start = toSeconds(props.start);
const end = toSeconds(props.end);
const sourceIn = toSeconds(props.sourceIn);
const sourceOut = toSeconds(props.sourceOut);
const startFrames = start === undefined ? 0 : this.toFrames(start);
const sourceInFrames = sourceIn === undefined ? 0 : this.toFrames(sourceIn);
const delay = startFrames - sourceInFrames / rate;
if (delay === 0) {
entity.remove(Delay);
} else {
entity.add(Delay);
entity.set(Delay, { value: delay });
}
let out: number | null = null;
if (end !== undefined) {
out = sourceInFrames + (this.toFrames(end) - startFrames) * rate;
}
if (sourceOut !== undefined) {
const frames = this.toFrames(sourceOut);
out = out === null ? frames : Math.min(out, frames);
}
if (sourceInFrames === 0 && out === null) {
entity.remove(Trim);
} else {
entity.add(Trim);
entity.set(Trim, { start: sourceInFrames, end: out });
}
}
/**
* Writes a track's runtime property path from its authored `property`,
* against the entity holding it (a `width` track under a stroke drives the
* line width). Called when the prop is set and again on insertion, since
* Solid sets props before the track has a parent.
*/
private resolveTrackProperty(track: Entity, property: unknown): void {
const path = typeof property === 'string' ? trackPropertyPath(getParentEntity(track), property) : undefined;
track.set(KeyframeTrack, { property: path ?? '' });
}
/**
* Derives `KeepAspectRatio` from the props as authored: the lock pins the
* authored bounds, or stays empty when neither is authored so a resize
* keeps the ratio the box currently has (see `lockedRatio` in the
* runtime's resize action). Re-derived on `keepAspectRatio` and on either
* bound, so the order Solid sets them in does not matter — never seeded
* from the entity's current `Size`, which before the bounds apply is only
* the element's default box.
*/
private syncAspectLock(node: SceneNode): void {
const { entity, props } = node;
if (props.keepAspectRatio !== true) {
entity.remove(KeepAspectRatio);
return;
}
entity.add(KeepAspectRatio);
entity.set(KeepAspectRatio, {
width: toNumber(props.width) ?? 0,
height: toNumber(props.height) ?? 0,
});
}
/**
* Derives `MixedCornerRadius` from the five radius props as authored: it
* is present while any corner has a radius of its own, and a corner
* without one takes `cornerRadius`. Recomputed whole on every one of the
* five, so the order Solid sets them in does not matter.
*/
private syncCornerRadii(node: SceneNode): void {
const { entity, props } = node;
const corners = CORNER_PROPS.map((name) => toNumber(props[name]));
if (corners.every((corner) => corner === undefined)) {
entity.remove(MixedCornerRadius);
return;
}
const uniform = toNumber(props.cornerRadius) ?? 0;
const [topLeft, topRight, bottomRight, bottomLeft] = corners.map((corner) => corner ?? uniform);
entity.add(MixedCornerRadius);
entity.set(MixedCornerRadius, { topLeft, topRight, bottomRight, bottomLeft });
}
/**
* Puts `node` under `parent`, in front of `anchor` or last.
*
* `children` is written first — it is what the document answers from —
* and the traits are derived from it: `ChildOf` for the parent, then
* `ItemIndex` over the element children in the order they now sit in.
*
* A text node under a parent that is not a `<text>` is an inert
* placeholder rather than an error: it is how the renderer marks the spot
* a conditional or an emptied list left behind (`cleanChildren`), and the
* next value takes its place. Only a `<text>` reads its text children back
* out as `Chars`.
*/
public insertNode(parent: SceneNode, node: SceneNode, anchor?: SceneNode): void {
if (isDomText(parent)) {
throw new Error('Text cannot contain children.');
}
const candidate = (!parent.native || parent.tag === 'html' || parent.tag === 'htmlPaint')
? parent.element
: null;
const domContainer = candidate instanceof Element ? candidate : null;
if (isDomText(node)) {
detach(node);
const at = anchor === undefined ? -1 : parent.children.indexOf(anchor);
if (at === -1) parent.children.push(node);
else parent.children.splice(at, 0, node);
node.parent = parent;
if (domContainer) {
const domAnchor = anchor?.element;
domContainer.insertBefore(
node.element,
domAnchor?.parentNode === domContainer ? domAnchor : null,
);
} else {
node.element.remove();
}
syncChars(parent);
return;
}
if (domContainer) {
if (node.native || !(node.element instanceof Element)) {
throw new Error('A composition element cannot be HTML content.');
}
detach(node);
const at = anchor === undefined ? -1 : parent.children.indexOf(anchor);
if (at === -1) parent.children.push(node);
else parent.children.splice(at, 0, node);
node.parent = parent;
const domAnchor = anchor?.element;
domContainer.insertBefore(node.element, domAnchor?.parentNode === domContainer ? domAnchor : null);
return;
}
if (!node.native) {
throw new Error('DOM content must be inside <html> or <htmlPaint>.');
}
if (parent.entity === node.entity) return;
// Checked before anything moves: `appendChild` asserts the same
// thing, but only once the node has left the parent it had.
if (
getParentEntity(node.entity) !== parent.entity &&
getEntityTree(this.world, node.entity).includes(parent.entity)
) {
throw new Error('Cannot parent entity into its own subtree');
}
detach(node);
const at = anchor === undefined ? -1 : parent.children.indexOf(anchor);
if (at === -1) parent.children.push(node);
else parent.children.splice(at, 0, node);
node.parent = parent;
if (getParentEntity(node.entity) !== parent.entity) {
// appendChild only takes top-level entities, so a move between two
// parents goes back through the stage on the way.
const current = getParentNode(node.entity);
if (current !== null) {
removeChild(this.world, node.entity, current);
}
appendChild(this.world, node.entity, parent.entity);
if (node.entity.has(KeyframeTrack)) {
this.resolveTrackProperty(node.entity, node.props.property);
}
}
let index = 0;
for (const sibling of parent.children) {
if (!sibling.native) continue;
sibling.entity.add(ItemIndex);
sibling.entity.set(ItemIndex, { value: index++ });
}
}
private destroySubtree(node: SceneNode): void {
for (const child of [...node.children]) {
this.destroySubtree(child);
}
node.children.length = 0;
node.parent = null;
node.element?.remove();
if (node.entity.isAlive() && node.entity !== this.stage.entity) {
attempt(() => node.entity.destroy());
}
}
/**
* Takes `node` out of the document. The parent it comes out of is the one
* it has rather than the one the caller names: a move has already put it
* in the new one by the time the renderer asks the old one to drop it.
*/
public removeNode(_parent: SceneNode, node: SceneNode): void {
detach(node);
if (node.entity.has(Stage)) {
for (const child of [...node.children]) {
this.removeNode(node, child);
}
node.entity.set(Background, { value: DEFAULT_BACKGROUND });
node.entity.remove(Source);
return;
}
this.destroySubtree(node);
}
// The timeline clock behind `useTicker`. One Solid signal per document;
// the equality check keeps a paused scene from propagating at all.
private readonly ticker = createSignal<ProjectTick>(
{ time: 0, frame: 0, delta: 0, playing: false },
{ equals: (a, b) => a.time === b.time && a.frame === b.frame && a.delta === b.delta && a.playing === b.playing },
);
private lastTickTime: number | null = null;
public tick(): ProjectTick {
return this.ticker[0]();
}
// The rasterization density behind `useResolution`: device pixels per
// composition pixel, camera zoom excluded — a constant 1 in the live
// editor, the export scale offline. Read into a signal alongside
// the ticker, so an encoder that learns its scale only after the mount
// still propagates it before the first frame is sampled.
private readonly resolutionSignal = createSignal(1);
public resolution(): number {
return this.resolutionSignal[0]();
}
// The value the resolution signal is fed with: the surface's pixel ratio
// only while exporting — a realtime world always reports 1, so a project
// never sees the display's pixel ratio.
private readResolution(): number {
if (this.world.get(Mode)?.value === 'realtime') return 1;
return this.world.get(RenderSurface)?.resolution ?? 1;
}
/**
* The barrier behind `useTicker().hold`: a project's own async work, put
* where the frames in flight wait for it — the same list the decoders push
* their readiness onto, drained by `warmupAssets` before the first frame
* and by the encoder before each one after it. Held during the mount, the
* first frame waits for it; held during a tick, that frame does — hold on
* every tick, as a decoder that is not ready does, for work that is not
* done once.
*
* The list is null in realtime (nothing collects), so a live mount holds
* nothing and pays nothing.
*
* Settled either way and bounded: the decoders' promises are the engine's
* own, this one is a project's, and neither a rejection nor a promise that
* never settles may take an export down with it.
*/
public hold(work: Promise<unknown>): void {
const promises = this.world.get(FramePromises)?.list;
if (!promises) return;
let timer: ReturnType<typeof setTimeout> | undefined;
const expired = new Promise<void>((resolve) => {
timer = setTimeout(() => {
console.warn(`[hold] gave up after ${HOLD_TIMEOUT_MS}ms — rendering the frame without it`);
resolve();
}, HOLD_TIMEOUT_MS);
});
promises.push(
Promise.race([Promise.resolve(work).catch((error) => console.error('[hold]', error)), expired])
.finally(() => clearTimeout(timer)),
);
}
/**
* Reads the playhead into the ticker signal. Called by the playback system
* once per tick (through the world's `Tickers` set — see `mount`), so
* a project's memos re-run before motion and render look at the world.
*/
public advanceTicker(): void {
const target = this.tickTarget();
const computed = target?.get(Computed);
const time = computed?.localTimeInSeconds ?? 0;
const delta = this.lastTickTime === null ? 0 : time - this.lastTickTime;
this.lastTickTime = time;
this.resolutionSignal[1](this.readResolution());
this.ticker[1]({
time,
frame: computed?.localTime ?? 0,
delta,
playing: target?.get(Playback)?.playing ?? false,
});
}
/**
* The entity whose playhead the ticker reads: the nearest Playback carrier
* at or above the active scene. Resolved per tick rather than cached — the
* active scene changes with the view, and a capture world (which activates
* nothing) answers with its one Playback root instead.
*/
private tickTarget(): Entity | null {
let current = getActiveEntity(this.world);
while (current?.isAlive()) {
if (current.has(Playback)) return current;
current = getParentEntity(current);
}
return this.world.queryFirst(Playback) ?? null;
}
public getParentNode(node: SceneNode): SceneNode | undefined {
return node.parent ?? undefined;
}
public getFirstChild(node: SceneNode): SceneNode | undefined {
return node.children[0];
}
public getNextSibling(node: SceneNode): SceneNode | undefined {
const parent = node.parent;
if (parent === null) return undefined;
const at = parent.children.indexOf(node);
return at === -1 ? undefined : parent.children[at + 1];
}
public dispose(): void {
for (const entity of this.world.entities) {
if (!entity.isAlive() || entity.has(IsExcluded) || entity === this.stage.entity) continue;
const element = entity.get(Host)?.element;
if (element instanceof HTMLImageElement) {
attempt(() => URL.revokeObjectURL(element.src));
}
attempt(() => element?.remove());
attempt(() => entity.destroy());
}
// The world is free for the next mount. A document already replaced by
// another leaves the registry as it found it.
if (documents.get(this.world) === this) {
documents.delete(this.world);
}
}
}
/**
* Prop assignment for real DOM nodes below an HTML paint. This mirrors the
* useful, non-interactive part of Solid's DOM conventions: reactive styles,
* classes, attributes and explicit HTML/text content. Pointer and media event
* handlers are ignored because the subtree is rasterized into the canvas.
*/
function setDomProperty(element: Element | null, name: string, value: unknown): void {
if (
typeof value === 'function'
|| name.startsWith('on')
|| element === null
|| name === 'children'
|| name === 'ref'
) return;
if (name === 'style') {
const style = (element as HTMLElement | SVGElement).style;
if (typeof value === 'string') {
style.cssText = value;
} else if (typeof value === 'object' && value !== null) {
Object.assign(style, value);
} else {
style.cssText = '';
}
return;
}
if (name === 'class' || name === 'className') {
if (value === undefined || value === null || value === false) element.removeAttribute('class');
else element.setAttribute('class', String(value));
return;
}
if (name === 'classList') {
if (typeof value === 'object' && value !== null) {
for (const [key, enabled] of Object.entries(value)) {
element.classList.toggle(key, Boolean(enabled));
}
}
return;
}
if (name === 'innerHTML') {
element.innerHTML = value === undefined || value === null ? '' : String(value);
return;
}
if (name === 'textContent') {
element.textContent = value === undefined || value === null ? '' : String(value);
return;
}
if (value === undefined || value === null || value === false) {
element.removeAttribute(name);
} else {
element.setAttribute(name, value === true ? '' : String(value));
}
}
const documents = new WeakMap<World, RuntimeDocument>();
export function getRuntimeDocument(world: World): RuntimeDocument {
const document = documents.get(world);
if (document === undefined) {
throw new Error("The requested world has no runtime document");
}
return document;
}
/**
* The world's runtime document, for the length of one mount. A world holds at
* most one: the stage it renders into is a world singleton, so a second
* document would append its project's entities alongside the first's, and the
* ones already there would be reachable only through the earlier `Mount`.
* Dispose the running mount before starting another.
*/
export function createRuntimeDocument(world: World): RuntimeDocument {
if (documents.has(world)) {
throw new Error('This world already has a mounted project — dispose it before mounting another');
}
const document = new RuntimeDocument(world);
documents.set(world, document);
return document;
}
function assert(condition: unknown, message: string): asserts condition {
if (!condition) {
throw new Error(message);
}
}
function attempt<T>(fn: () => T): T | undefined {
try {
return fn();
} catch (error) {
return undefined;
}
}