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 {
ChildOf,
Geometry, Paint, Group, Scene, Audio, AdjustmentLayer, ClipPath, Shadow, Stroke,
Hidden, ClipsContent, Name, Key, AssetId, ItemIndex, MountScript, MountPath,
Caption,
Position, Offset, Rotation, Scale, UniformScale, Anchor, Pivot, Skew, Size, Flip,
Constraint, KeepAspectRatio,
Opacity, BlendMode, Color, CornerRadius, MixedCornerRadius, PointCount, Blur, ScaleMode, Effect, Mask,
VectorPath, EvenOdd, ViewBox, PathTrim,
ColorStop, LinearGradient, EllipticalGradient, StrokeStyle, StrokeDash, Shader,
Chars, TextStyle,
Delay, Trim, PlaybackRate, SourceFrameRate,
Playback, Sequential, Transition, ClipHeight, Expanded,
Volume, Muted,
KeyframeTrack, Keyframe, Animation, Stage,
} from '../traits';
import { createEntity } from '../actions/entities';
import { formatPath, parsePath } from '../math/path';
import type { Entity, World } from 'koota';
/**
* Plain-object snapshot of one entity's traits. Used to clone entity
* subtrees in-memory (copy/paste, duplicate, split-on-overlap) via
* serialize -> deserialize onto fresh entities. Not a persisted format —
* no storage or backward-compatibility guarantees; persistence is a
* separate, not-yet-built app-side concern.
*/
export interface EntityRecord {
id: string;
eid: number;
Geometry?: number;
Paint?: number;
Group?: {};
Scene?: {};
Audio?: {};
AdjustmentLayer?: {};
Effect?: {
type?: number;
value?: number;
};
Mask?: {
offset?: number;
inverted?: boolean;
smoothing?: number;
};
Caption?: {
type?: number;
colors?: number[];
verticalAlign?: number;
};
ClipPath?: {};
Shadow?: {};
Stroke?: {};
Name?: string;
Key?: string;
MountScript?: {
mountId: string;
scriptAssetId: string;
};
MountPath?: {
mountId: string;
path: string;
};
ChildOf?: number;
ItemIndex?: number;
ClipHeight?: number;
Expanded?: {};
Position?: {
x?: number;
y?: number;
};
Offset?: {
x?: number;
y?: number;
};
Rotation?: number;
Scale?: {
x?: number;
y?: number;
};
UniformScale?: number;
Anchor?: {
x?: number;
y?: number;
};
Pivot?: {
x?: number;
y?: number;
};
Skew?: {
x?: number;
y?: number;
};
Size?: {
width?: number;
height?: number;
};
Flip?: {
x?: -1 | 1;
y?: -1 | 1;
};
Opacity?: number;
BlendMode?: number;
CornerRadius?: number;
MixedCornerRadius?: {
topLeft: number;
topRight: number;
bottomRight: number;
bottomLeft: number;
};
PointCount?: number;
/** A path's outline as path data, which is what it is authored as. */
VectorPath?: string;
EvenOdd?: {};
ViewBox?: { x: number; y: number; width: number; height: number };
PathTrim?: { start: number; end: number; offset: number };
Color?: number;
Blur?: number;
AssetId?: string;
ScaleMode?: number;
Shader?: {
code?: string;
uniforms?: Record<string, number | number[] | string>;
};
Volume?: number;
Muted?: {};
ColorStop?: {
offset?: number;
};
LinearGradient?: {
x1?: number;
y1?: number;
x2?: number;
y2?: number;
};
EllipticalGradient?: {
cx?: number;
cy?: number;
rx?: number;
ry?: number;
};
StrokeStyle?: {
width?: number;
join?: number;
cap?: number;
miterLimit?: number;
};
StrokeDash?: { dash: number; gap: number; offset: number };
Hidden?: boolean;
ClipsContent?: boolean;
Sequential?: {};
Playback?: {
loop?: number;
};
Delay?: number;
Trim?: {
start: number;
end: number | null;
};
PlaybackRate?: number;
SourceFrameRate?: number;
Constraint?: {
horizontal?: number;
vertical?: number;
};
KeepAspectRatio?: {
width?: number;
height?: number;
};
Transition?: {
type?: number;
duration?: number;
};
KeyframeTrack?: {
property?: string;
};
Keyframe?: {
time?: number;
value?: number;
easing?: string;
/** A `d` keyframe's outline, as path data. */
path?: string;
};
Animation?: {
duration?: number;
delay?: number;
type?: number;
phase?: number;
};
Chars?: string;
TextStyle?: {
leading?: number;
fontSize?: number;
fontFamily?: string;
fontWeight?: string;
fontStyle?: number;
textAlign?: number;
textBaseline?: number;
textCase?: number;
letterSpacing?: number;
};
}
export function serializeEntity(entity: Entity): EntityRecord {
const record: EntityRecord = { id: String(entity), eid: entity };
if (entity.has(Geometry)) {
record.Geometry = entity.get(Geometry)!.value;
}
if (entity.has(Paint)) {
record.Paint = entity.get(Paint)!.value;
}
if (entity.has(Group)) {
record.Group = {};
}
if (entity.has(Scene)) {
record.Scene = {};
}
if (entity.has(Audio)) {
record.Audio = {};
}
if (entity.has(AdjustmentLayer)) {
record.AdjustmentLayer = {};
}
if (entity.has(Effect)) {
const effect = entity.get(Effect)!;
record.Effect = { type: effect.type, value: effect.value };
}
if (entity.has(Mask)) {
const mask = entity.get(Mask)!;
record.Mask = { offset: mask.offset, inverted: mask.inverted, smoothing: mask.smoothing };
}
if (entity.has(Shadow)) {
record.Shadow = {};
}
if (entity.has(Stroke)) {
record.Stroke = {};
}
if (entity.has(Name)) {
record.Name = entity.get(Name)!.value;
}
if (entity.has(Key)) {
record.Key = entity.get(Key)!.value;
}
if (entity.has(MountScript)) {
const mount = entity.get(MountScript)!;
record.MountScript = { mountId: mount.mountId, scriptAssetId: mount.scriptAssetId };
}
if (entity.has(MountPath)) {
const mount = entity.get(MountPath)!;
record.MountPath = { mountId: mount.mountId, path: mount.path };
}
if (entity.has(ItemIndex)) {
record.ItemIndex = entity.get(ItemIndex)!.value ?? 0;
}
if (entity.has(ClipHeight)) {
record.ClipHeight = entity.get(ClipHeight)!.value;
}
if (entity.has(Expanded)) {
record.Expanded = {};
}
const parent = entity.targetFor(ChildOf);
if (parent !== undefined && !parent.has(Stage)) {
record.ChildOf = parent;
}
if (entity.has(ClipPath)) {
record.ClipPath = {};
}
if (entity.has(Position)) {
const position = entity.get(Position)!;
record.Position = { x: position.x, y: position.y };
}
if (entity.has(Offset)) {
const offset = entity.get(Offset)!;
record.Offset = { x: offset.x, y: offset.y };
}
if (entity.has(Rotation)) {
record.Rotation = entity.get(Rotation)!.value;
}
if (entity.has(Scale)) {
const scale = entity.get(Scale)!;
record.Scale = { x: scale.x, y: scale.y };
}
if (entity.has(UniformScale)) {
record.UniformScale = entity.get(UniformScale)!.value;
}
if (entity.has(Anchor)) {
const anchor = entity.get(Anchor)!;
record.Anchor = { x: anchor.x, y: anchor.y };
}
if (entity.has(Pivot)) {
const pivot = entity.get(Pivot)!;
record.Pivot = { x: pivot.x, y: pivot.y };
}
if (entity.has(Skew)) {
const skew = entity.get(Skew)!;
record.Skew = { x: skew.x, y: skew.y };
}
if (entity.has(Size)) {
const size = entity.get(Size)!;
record.Size = { width: size.width, height: size.height };
}
if (entity.has(Flip)) {
const flip = entity.get(Flip)!;
record.Flip = { x: flip.x, y: flip.y };
}
if (entity.has(Opacity)) {
record.Opacity = entity.get(Opacity)!.value;
}
if (entity.has(BlendMode)) {
record.BlendMode = entity.get(BlendMode)!.value;
}
if (entity.has(CornerRadius)) {
record.CornerRadius = entity.get(CornerRadius)!.value;
}
if (entity.has(PointCount)) {
record.PointCount = entity.get(PointCount)!.value;
}
const geometry = entity.get(VectorPath)?.geometry;
if (geometry) {
// Full precision: a copy is the same outline, not one rounded for a file.
record.VectorPath = formatPath(geometry, 6);
}
if (entity.has(EvenOdd)) {
record.EvenOdd = {};
}
if (entity.has(ViewBox)) {
const { x, y, width, height } = entity.get(ViewBox)!;
record.ViewBox = { x, y, width, height };
}
if (entity.has(PathTrim)) {
const { start, end, offset } = entity.get(PathTrim)!;
record.PathTrim = { start, end, offset };
}
if (entity.has(MixedCornerRadius)) {
const radius = entity.get(MixedCornerRadius)!;
record.MixedCornerRadius = {
topLeft: radius.topLeft,
topRight: radius.topRight,
bottomRight: radius.bottomRight,
bottomLeft: radius.bottomLeft,
};
}
if (entity.has(Color)) {
record.Color = entity.get(Color)!.value;
}
if (entity.has(Blur)) {
record.Blur = entity.get(Blur)!.value;
}
if (entity.has(AssetId)) {
record.AssetId = entity.get(AssetId)!.value;
}
if (entity.has(ScaleMode)) {
record.ScaleMode = entity.get(ScaleMode)!.value;
}
if (entity.has(Shader)) {
const shader = entity.get(Shader)!;
record.Shader = { code: shader.code, uniforms: shader.uniforms ?? undefined };
}
if (entity.has(Volume)) {
record.Volume = entity.get(Volume)!.value;
}
if (entity.has(Muted)) {
record.Muted = {};
}
if (entity.has(ColorStop)) {
record.ColorStop = { offset: entity.get(ColorStop)!.offset };
}
if (entity.has(LinearGradient)) {
const { x1, y1, x2, y2 } = entity.get(LinearGradient)!;
record.LinearGradient = { x1, y1, x2, y2 };
}
if (entity.has(EllipticalGradient)) {
const { cx, cy, rx, ry } = entity.get(EllipticalGradient)!;
record.EllipticalGradient = { cx, cy, rx, ry };
}
if (entity.has(StrokeStyle)) {
const stroke = entity.get(StrokeStyle)!;
record.StrokeStyle = {
width: stroke.width,
join: stroke.join,
cap: stroke.cap,
miterLimit: stroke.miterLimit,
};
}
if (entity.has(StrokeDash)) {
const { dash, gap, offset } = entity.get(StrokeDash)!;
record.StrokeDash = { dash, gap, offset };
}
if (entity.has(Hidden)) {
record.Hidden = true;
}
if (entity.has(ClipsContent)) {
record.ClipsContent = true;
}
if (entity.has(Sequential)) {
record.Sequential = {};
}
if (entity.has(Playback)) {
record.Playback = {
loop: entity.get(Playback)!.loop ? 1 : 0,
};
}
if (entity.has(Delay)) {
record.Delay = entity.get(Delay)!.value;
}
if (entity.has(Trim)) {
const trim = entity.get(Trim)!;
record.Trim = { start: trim.start, end: trim.end };
}
if (entity.has(SourceFrameRate)) {
record.SourceFrameRate = entity.get(SourceFrameRate)!.value;
}
if (entity.has(PlaybackRate)) {
record.PlaybackRate = entity.get(PlaybackRate)!.value;
}
if (entity.has(Transition)) {
const transition = entity.get(Transition)!;
record.Transition = { type: transition.type, duration: transition.duration };
}
if (entity.has(Constraint)) {
const constraint = entity.get(Constraint)!;
record.Constraint = { horizontal: constraint.horizontal, vertical: constraint.vertical };
}
if (entity.has(KeepAspectRatio)) {
const aspect = entity.get(KeepAspectRatio)!;
record.KeepAspectRatio = { width: aspect.width, height: aspect.height };
}
if (entity.has(KeyframeTrack)) {
// `target` is rebuilt from ChildOf when tracks are aggregated after load.
record.KeyframeTrack = { property: entity.get(KeyframeTrack)!.property };
}
if (entity.has(Keyframe)) {
const keyframe = entity.get(Keyframe)!;
record.Keyframe = {
time: keyframe.time,
value: keyframe.value,
easing: keyframe.easing,
...(keyframe.path ? { path: formatPath(keyframe.path, 6) } : {}),
};
}
if (entity.has(Animation)) {
const animation = entity.get(Animation)!;
record.Animation = {
duration: animation.duration,
delay: animation.delay,
type: animation.type,
phase: animation.phase,
};
}
if (entity.has(Caption)) {
const caption = entity.get(Caption)!;
record.Caption = {
type: caption.type,
colors: caption.colors?.map(v => v),
verticalAlign: caption.verticalAlign,
};
}
if (entity.has(Chars)) {
record.Chars = entity.get(Chars)!.value;
}
if (entity.has(TextStyle)) {
const style = entity.get(TextStyle)!;
record.TextStyle = {
leading: style.leading,
fontSize: style.fontSize,
fontFamily: style.fontFamily,
fontWeight: style.fontWeight,
fontStyle: style.fontStyle,
textAlign: style.textAlign,
textBaseline: style.textBaseline,
textCase: style.textCase,
letterSpacing: style.letterSpacing,
};
}
return record;
}
// Records store partial objects with possibly-undefined fields; setting those
// verbatim would overwrite trait defaults with undefined.
function defined<T extends object>(value: T): Partial<T> {
const out: Record<string, unknown> = {};
for (const [key, entry] of Object.entries(value)) {
if (entry !== undefined) out[key] = entry;
}
return out as Partial<T>;
}
export function deserializeEntity(entity: Entity, e: Partial<EntityRecord>): void {
if (e.Geometry !== undefined) {
entity.add(Geometry);
entity.set(Geometry, { value: e.Geometry });
}
if (e.Paint !== undefined) {
entity.add(Paint);
entity.set(Paint, { value: e.Paint });
}
if (e.Group !== undefined) {
entity.add(Group);
}
if (e.Scene !== undefined) {
entity.add(Scene);
}
if (e.Audio !== undefined) {
entity.add(Audio);
}
if (e.AdjustmentLayer !== undefined) {
entity.add(AdjustmentLayer);
}
if (e.Effect !== undefined) {
entity.add(Effect);
entity.set(Effect, defined(e.Effect));
}
if (e.Mask !== undefined) {
entity.add(Mask);
entity.set(Mask, defined(e.Mask));
}
if (e.Shadow !== undefined) {
entity.add(Shadow);
}
if (e.Stroke !== undefined) {
entity.add(Stroke);
}
if (e.Name !== undefined) {
entity.add(Name);
entity.set(Name, { value: e.Name });
}
if (e.Key !== undefined) {
entity.add(Key);
entity.set(Key, { value: e.Key });
}
if (e.MountScript !== undefined) {
entity.add(MountScript);
entity.set(MountScript, defined(e.MountScript));
}
if (e.MountPath !== undefined) {
entity.add(MountPath);
entity.set(MountPath, defined(e.MountPath));
}
if (e.ItemIndex !== undefined) {
entity.add(ItemIndex);
entity.set(ItemIndex, { value: e.ItemIndex });
}
if (e.ClipHeight !== undefined) {
entity.add(ClipHeight);
entity.set(ClipHeight, { value: e.ClipHeight });
}
if (e.Expanded !== undefined) {
entity.add(Expanded);
}
if (e.ClipPath !== undefined) {
entity.add(ClipPath);
}
if (e.Position !== undefined) {
entity.add(Position);
entity.set(Position, defined(e.Position));
}
if (e.Offset !== undefined) {
entity.add(Offset);
entity.set(Offset, defined(e.Offset));
}
if (e.Rotation !== undefined) {
entity.add(Rotation);
entity.set(Rotation, { value: e.Rotation });
}
if (e.Scale !== undefined) {
entity.add(Scale);
entity.set(Scale, defined(e.Scale));
}
if (e.UniformScale !== undefined) {
entity.add(UniformScale);
entity.set(UniformScale, { value: e.UniformScale });
}
if (e.Anchor !== undefined) {
entity.add(Anchor);
entity.set(Anchor, defined(e.Anchor));
}
if (e.Pivot !== undefined) {
entity.add(Pivot);
entity.set(Pivot, defined(e.Pivot));
}
if (e.Skew !== undefined) {
entity.add(Skew);
entity.set(Skew, defined(e.Skew));
}
if (e.Size !== undefined) {
entity.add(Size);
entity.set(Size, defined(e.Size));
}
if (e.Flip !== undefined) {
entity.add(Flip);
entity.set(Flip, defined(e.Flip));
}
if (e.Opacity !== undefined) {
entity.add(Opacity);
entity.set(Opacity, { value: e.Opacity });
}
if (e.BlendMode !== undefined) {
entity.add(BlendMode);
entity.set(BlendMode, { value: e.BlendMode });
}
if (e.CornerRadius !== undefined) {
entity.add(CornerRadius);
entity.set(CornerRadius, { value: e.CornerRadius });
}
if (e.PointCount !== undefined) {
entity.add(PointCount);
entity.set(PointCount, { value: e.PointCount });
}
if (e.VectorPath !== undefined) {
entity.add(VectorPath);
entity.set(VectorPath, { geometry: parsePath(e.VectorPath).geometry });
}
if (e.EvenOdd !== undefined) {
entity.add(EvenOdd);
}
if (e.ViewBox !== undefined) {
entity.add(ViewBox);
entity.set(ViewBox, e.ViewBox);
}
if (e.PathTrim !== undefined) {
entity.add(PathTrim);
entity.set(PathTrim, e.PathTrim);
}
if (e.MixedCornerRadius !== undefined) {
entity.add(MixedCornerRadius);
entity.set(MixedCornerRadius, defined(e.MixedCornerRadius));
}
if (e.Color !== undefined) {
entity.add(Color);
entity.set(Color, { value: e.Color });
}
if (e.Blur !== undefined) {
entity.add(Blur);
entity.set(Blur, { value: e.Blur });
}
if (e.AssetId !== undefined) {
entity.add(AssetId);
entity.set(AssetId, { value: e.AssetId });
}
if (e.ScaleMode !== undefined) {
entity.add(ScaleMode);
entity.set(ScaleMode, { value: e.ScaleMode });
}
if (e.Shader !== undefined) {
entity.add(Shader);
entity.set(Shader, {
code: e.Shader.code ?? '',
uniforms: e.Shader.uniforms ? { ...e.Shader.uniforms } : null,
});
}
if (e.Volume !== undefined) {
entity.add(Volume);
entity.set(Volume, { value: e.Volume });
}
if (e.Muted !== undefined) {
entity.add(Muted);
}
if (e.ColorStop !== undefined) {
entity.add(ColorStop);
entity.set(ColorStop, defined(e.ColorStop));
}
if (e.LinearGradient !== undefined) {
entity.add(LinearGradient);
entity.set(LinearGradient, defined(e.LinearGradient));
}
if (e.EllipticalGradient !== undefined) {
entity.add(EllipticalGradient);
entity.set(EllipticalGradient, defined(e.EllipticalGradient));
}
if (e.StrokeStyle !== undefined) {
entity.add(StrokeStyle);
entity.set(StrokeStyle, defined(e.StrokeStyle));
}
if (e.StrokeDash !== undefined) {
entity.add(StrokeDash);
entity.set(StrokeDash, e.StrokeDash);
}
if (e.Hidden !== undefined) {
entity.add(Hidden);
}
if (e.ClipsContent !== undefined) {
entity.add(ClipsContent);
}
if (e.Sequential !== undefined) {
entity.add(Sequential);
}
if (e.Playback !== undefined) {
entity.add(Playback);
entity.set(Playback, { loop: !!e.Playback.loop });
}
if (e.Delay !== undefined) {
entity.add(Delay({ value: e.Delay }));
}
if (e.Trim !== undefined) {
entity.add(Trim({ start: e.Trim.start, end: e.Trim.end }));
}
if (e.SourceFrameRate !== undefined) {
entity.add(SourceFrameRate({ value: e.SourceFrameRate }));
}
if (e.PlaybackRate !== undefined) {
entity.add(PlaybackRate({ value: e.PlaybackRate }));
}
if (e.Transition !== undefined) {
entity.add(Transition);
entity.set(Transition, defined(e.Transition));
}
if (e.Constraint !== undefined) {
entity.add(Constraint);
entity.set(Constraint, defined(e.Constraint));
}
if (e.KeepAspectRatio !== undefined) {
entity.add(KeepAspectRatio);
entity.set(KeepAspectRatio, defined(e.KeepAspectRatio));
}
if (e.KeyframeTrack !== undefined) {
entity.add(KeyframeTrack);
entity.set(KeyframeTrack, defined(e.KeyframeTrack));
}
if (e.Keyframe !== undefined) {
const { path, ...keyframe } = e.Keyframe;
entity.add(Keyframe);
entity.set(Keyframe, defined({ ...keyframe, path: path === undefined ? undefined : parsePath(path).geometry }));
}
if (e.Animation !== undefined) {
entity.add(Animation);
entity.set(Animation, defined(e.Animation));
}
if (e.Caption !== undefined) {
entity.add(Caption);
entity.set(Caption, defined({
type: e.Caption.type,
colors: e.Caption.colors ? [...e.Caption.colors] : undefined,
verticalAlign: e.Caption.verticalAlign,
}));
}
if (e.Chars !== undefined) {
entity.add(Chars);
entity.set(Chars, { value: e.Chars });
}
if (e.TextStyle !== undefined) {
entity.add(TextStyle);
entity.set(TextStyle, defined(e.TextStyle));
}
// Attach to parent last so add/change observers see every trait this entity
// has (KeyframeTrack, Keyframe, Animation, ClipPath, ...). Otherwise derived
// caches stay empty and the UI/motion system can't find them after reload.
if (e.ChildOf !== undefined) {
entity.add(ChildOf(e.ChildOf as Entity));
}
}
export function cloneFromRecords(world: World, records: EntityRecord[]) {
const eidMap = new Map<number, Entity>();
for (const record of records) {
eidMap.set(record.eid, createEntity(world));
}
for (const record of records) {
const entity = eidMap.get(record.eid)!;
const copy = { ...record };
try {
if (copy.ChildOf !== undefined) {
copy.ChildOf = eidMap.get(copy.ChildOf) ?? copy.ChildOf;
}
deserializeEntity(entity, copy);
} catch (error) {
entity.destroy();
console.error(error);
}
}
return eidMap;
}
/**
* Strips mount identity from records so a *same-world* copy doesn't collide
* with the original mount's id; adopt would otherwise bind two entities to one
* `MountPath`. A duplicated/pasted mount becomes plain static entities: its
* runtime hosts won't re-run (a documented limitation; re-mount to re-animate).
* The export/capture clone (`cloneFromRecords` directly) keeps identity so it
* can adopt.
*/
export function stripMountIdentity(records: EntityRecord[]): EntityRecord[] {
return records.map(({ MountScript: _script, MountPath: _path, ...rest }) => rest);
}
export function cloneSubtree(world: World, tree: Entity[]) {
const records = tree.map(entity => serializeEntity(entity));
return cloneFromRecords(world, stripMountIdentity(records));
}