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/. */
/**
* The editing side of a mounted project: what an editor does to the document
* (change a prop, add an element) and how those changes are reported back in
* the vocabulary of the JSX, so whoever mounted the project can write them to
* the source. The document itself only knows how to be rendered into; this is
* where the commands live.
*/
import { Active, Background, Chars, colorToHex, Computed, DEFAULT_BACKGROUND, FrameRate, framesToSeconds, getActiveEntity, getEntityChildren, getEntityTree, getIntrinsicPaint, getParentEntity, getTimelineOrigin, isText, Loop, PaintType, Selected, Sequential, setActive, Size, Source, Stage } from '@diffusionstudio/runtime';
import { isPropValue, SOURCE_ATTR } from '@diffusionstudio/jsx';
import { createRoot } from 'solid-js';
import { authoredElement, authoredTree, getRuntimeDocument, insert, isSceneNode, renderAuthored, withDocument } from '@diffusionstudio/reconciler';
import { findInspectEntry } from './inspect';
import { AssetSelection } from './traits';
import type { SceneNode } from '@diffusionstudio/runtime';
import type { InspectValue, PropValue } from '@diffusionstudio/jsx';
import type { Entity, World } from 'koota';
import type { AuthoredTree, ProjectDocument, RuntimeDocument } from '@diffusionstudio/reconciler';
/**
* A property the editor changed, in the vocabulary of the JSX rather than of
* the traits it was written to: `source` is the element it belongs to (its
* SOURCE_ATTR stamp) and `value` is what a project would have written there.
* Whoever mounts the document decides what to do with these — writing them
* back to disk is the point, but nothing here knows about a disk.
*/
export interface PropEdit {
kind: 'prop';
source: string;
name: string;
value: PropValue;
/**
* What the element authored for `name` before this edit — `false` for a
* prop it did not author, the same value an editor unsets one with. The
* history inverts the edit from this; the writer ignores it. Absent on an
* edit reported after the fact (`reportEdit` with no previous), which is
* therefore not invertible.
*/
previous?: unknown;
}
/**
* What a `<text>` says, changed. Its content is its children rather than a
* prop, so it travels as an edit of its own; `value` is the literal the file
* gets between the tags.
*/
export interface TextEdit {
kind: 'text';
source: string;
value: string;
/** What the `<text>` said before this edit. Inverse info, as on `PropEdit`. */
previous?: string;
}
/**
* An element the editor added. The entity already exists in the world when
* this is reported, stamped with the pending `source`; whoever writes it to
* disk answers with the real one and re-stamps (see `isPendingSource`).
* `parent` is the source of the element it was inserted under and `before`,
* when present, the sibling it was placed in front of; without it, appended.
* `text` is the literal content of a text element (its `children`), which is
* not a prop and so travels separately.
*/
export interface InsertEdit {
kind: 'insert';
source: string;
parent: string;
tag: string;
props: Record<string, PropValue>;
before?: string;
text?: string;
}
/**
* An element the editor moved to another parent: `parent` is the element it
* belongs to now and `before`, when present, the sibling it was placed in
* front of; without it, last. The entity is already there when this is
* reported. Nesting is the one thing a prop cannot say, so this is its own
* edit: dragging a clip into a scene has to move the element itself.
*/
export interface MoveEdit {
kind: 'move';
source: string;
parent: string;
before?: string;
/**
* Where the element came from: the parent it left and the sibling it stood
* in front of there, when the file names them. Inverse info, as on
* `PropEdit` — moving it back is these two spots swapped in.
*/
fromParent?: string;
fromBefore?: string;
}
/**
* A deleted subtree as it stood the moment before it went, one node per
* authored element: the source it was stamped with, what a project would
* author it as (live values included — this never crosses a wire), and its
* children in order. What an undo needs to put the subtree back, and to pair
* the old sources with the new ones the reinsert mints.
*/
export interface CapturedNode {
source: string;
tag: string;
props: Record<string, unknown>;
text?: string;
children: CapturedNode[];
}
/**
* An element the editor deleted, descendants included: they were its content
* in the file and went with it on the canvas, so only the top of a deleted
* subtree is reported. The entity is already gone when this is — `parent`,
* `before` and `node` are its place and its content as they stood just
* before, captured for the history (the writer ignores them, as on
* `PropEdit`); absent when the subtree could not be captured whole.
*/
export interface RemoveEdit {
kind: 'remove';
source: string;
parent?: string;
before?: string;
node?: CapturedNode;
}
/**
* One iteration of a loop as the canvas rendered it: for every element of the
* loop body, by source, the props it came out with and (for a text) its
* content, plus — for every iteration but the first, which keeps the body's
* own names — the pending source its entity has been re-stamped with, so the
* write can answer with the real one (see `isPendingSource`).
*/
export type LoopIteration = Record<string, { props: Record<string, PropValue>; text?: string; pending?: string }>;
/**
* A `<For>`/`<Index>` the editor needs written out as its iterations, so that
* one of them can be edited without the others: `source` is any element of
* the loop's body (the writer finds the loop from it) and `iterations` what
* each rendering of that body came to. Reported before the edit that needed
* it; the entities are already re-stamped when it is. `loop` is the stamp
* they carried (see `Loop`), for `unsettle` to give back if the write declines.
*/
export interface UnrollEdit {
kind: 'unroll';
source: string;
loop: string;
iterations: LoopIteration[];
}
/**
* An `@inspect` variable the editor set (see `engine/inspect`). Not an
* element's edit at all: it is addressed by file and variable name rather
* than by source stamp, and the writer overwrites the declaration's
* initializer. `previous` is the inverse for the history, as on `PropEdit`.
*/
export interface VariableEdit {
kind: 'variable';
file: string;
name: string;
value: InspectValue;
previous: InspectValue;
}
export type EntityEdit = PropEdit | TextEdit | InsertEdit | MoveEdit | RemoveEdit | UnrollEdit | VariableEdit;
/**
* Sources of elements the editor created that no write has named yet. Shaped
* so `parseSource` rejects them (no `:`): they must never reach a file as an
* address, only as the key a write answers with the real source for.
*/
const PENDING_PREFIX = 'pending#';
let pendingCounter = 0;
export const isPendingSource = (source: string): boolean => source.startsWith(PENDING_PREFIX);
const nextPendingSource = (): string => `${PENDING_PREFIX}${++pendingCounter}`;
/** Whether an entity was rendered by a loop the source has not been asked to unroll yet. */
export const isLooped = (entity: Entity): boolean => entity.isAlive() && entity.has(Loop);
/** What `insertElement` learns about each element while it renders. */
interface Recorded {
tag: string;
props: Record<string, PropValue>;
}
/**
* A prop as an edit can carry it (a `PropValue`): a value a file spells as
* it is, or undefined for anything else — an element is written with whatever
* of it the file can say, and the rest is the project's to keep, not the
* writer's to guess at. The one place that decides this, so a new kind of
* value is taught here once.
*/
function wireValue(value: unknown): PropValue | undefined {
return isPropValue(value) ? value : undefined;
}
/** `wireValue` over a whole authored element, dropping what will not travel. */
function wireProps(props: Record<string, unknown>): Record<string, PropValue> {
const wired: Record<string, PropValue> = {};
for (const [name, value] of Object.entries(props)) {
const wire = wireValue(value);
if (wire !== undefined) wired[name] = wire;
}
return wired;
}
/**
* `entity`'s subtree as a `CapturedNode`, or undefined for an entity that is
* not an addressable element (no authored element, or no source) — a child
* like that is simply left out, the way `authoredTree` leaves out derived
* sub-entities. `authoredElement` already copies the props, so the capture
* does not change under the caller afterwards.
*/
function captureNode(world: World, entity: Entity): CapturedNode | undefined {
const element = authoredElement(entity);
const source = entity.get(Source)?.value;
if (!element || !source) return undefined;
const children: CapturedNode[] = [];
for (const child of getEntityChildren(world, entity)) {
const node = captureNode(world, child);
if (node) children.push(node);
}
return {
source,
tag: element.tag,
props: element.props,
...(element.text === undefined ? {} : { text: element.text }),
children,
};
}
/**
* The source of the next sibling after `entity` that the file can name — the
* `before` a reinsert at this spot would use — or undefined for none (last).
*/
function nextSourceAfter(world: World, entity: Entity): string | undefined {
const parent = getParentEntity(entity);
if (!parent) return undefined;
const siblings = getEntityChildren(world, parent);
for (const sibling of siblings.slice(siblings.indexOf(entity) + 1)) {
const source = sibling.get(Source)?.value;
if (source) return source;
}
return undefined;
}
/**
* The props of a `<video>`/`<image>` that only mean something while the node
* plays media, dropped when the intrinsic paint is removed (see
* `removeIntrinsicPaint`): the source, what qualifies it (its fit, its
* window, a frames directory's rate), and the audio mix a rect has no track
* to apply to. `start`/`end` stay: they place the clip, media or not.
*/
const MEDIA_PROPS = ['src', 'objectFit', 'frameRate', 'sourceIn', 'sourceOut', 'volume', 'muted', 'syncTo'] as const;
/**
* What `copy` took: the subtrees as authored, and the source of the parent
* they were copied out of (by stamp, so it outlives a remount), which `paste`
* needs to keep a clip out of the sequence it came from.
*/
interface Clipboard {
trees: AuthoredTree[];
parent?: string;
}
export class DocumentEditor {
private readonly world: World;
private readonly sinks = new Set<(edit: EntityEdit) => void>();
private readonly renames = new Set<(ids: Record<string, string>) => void>();
private clipboard: Clipboard = { trees: [] };
public constructor(world: World) {
this.world = world;
}
/** The document of the current mount. */
private get document(): RuntimeDocument {
return getRuntimeDocument(this.world);
}
/**
* Listens for edits made through this editor. Every listener hears every
* edit — the writer takes them to the file, the history keeps them —
* in the order they subscribed. Returns an unsubscribe.
*/
public onEdit(sink: (edit: EntityEdit) => void): () => void {
this.sinks.add(sink);
return () => {
this.sinks.delete(sink);
};
}
/**
* Listens for `restamp`: whoever holds sources of their own (the history)
* hears the same renames the entities get. Returns an unsubscribe.
*/
public onRename(listener: (ids: Record<string, string>) => void): () => void {
this.renames.add(listener);
return () => {
this.renames.delete(listener);
};
}
private emit(edit: EntityEdit): void {
for (const sink of [...this.sinks]) sink(edit);
}
/** Writes a prop to the document and reports it. */
public editProperty(entity: Entity, name: string, value: PropValue): void {
const node = this.document.node(entity);
let previous = node.props[name];
// The stage keeps no authored record (see RuntimeDocument.setProperty),
// so its one editable prop reads its previous value off the trait; the
// default spells as the attribute's absence, like any unset prop.
if (name === 'background' && previous === undefined) {
const background = entity.get(Background)?.value;
if (background !== undefined && background !== DEFAULT_BACKGROUND) previous = colorToHex(background);
}
this.document.setProperty(node, name, value);
this.reportEdit(entity, name, value, wireValue(previous) ?? false);
}
/**
* Sets an `@inspect` variable and reports it: the signal moves the
* composition (one reactive graph, no remount), the report takes the value
* to the declaration's initializer and into the history. A name the mount
* did not declare is ignored — an undo can outlive the registry entry it
* was recorded against.
*/
public editVariable(file: string, name: string, value: InspectValue): void {
const entry = findInspectEntry(this.world, file, name);
if (!entry) return;
// Against the committed value, not the live one
const previous = entry.committed();
entry.commit(value);
if (previous === value) return;
this.emit({ kind: 'variable', file, name, value, previous });
}
/**
* Writes what a `<text>` says to the document and reports it. Settled
* first for the same reason a prop is: one iteration of a loop cannot say
* something the others do not.
*/
public editText(entity: Entity, text: string): void {
const previous = entity.get(Chars)?.value ?? '';
this.document.setText(entity, text);
this.settle(entity);
const source = entity.get(Source)?.value;
if (source) {
this.emit({ kind: 'text', source, value: text, previous });
}
}
/**
* Reports an edit whose change the editor already made itself. An entity a
* loop rendered is settled first (see `settle`): its element is every
* iteration's until the loop is unrolled, and the file hears about that
* before it hears the value. `previous` is the inverse for the history
* (see `PropEdit`); a caller that cannot say what the value was leaves it
* out, and the edit is not undoable.
*/
public reportEdit(entity: Entity, name: string, value: PropValue, previous?: unknown): void {
this.settle(entity);
const source = entity.get(Source)?.value;
if (source) {
this.emit({ kind: 'prop', source, name, value, ...(previous === undefined ? {} : { previous }) });
}
}
/**
* Selects `entities`, replacing the current selection unless `extend` is
* 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.
*/
public select(entities: Entity | Entity[], options: { extend?: boolean } = {}): void {
const next = new Set(Array.isArray(entities) ? entities : [entities]);
const assetSelection = this.world.get(AssetSelection);
if (assetSelection && (assetSelection.ids.length || assetSelection.folders.length)) {
this.world.set(AssetSelection, { ids: [], folders: [] });
}
if (!options.extend) {
for (const entity of [...this.world.query(Selected)]) {
if (!next.has(entity)) this.setSelected(entity, false);
}
}
for (const entity of next) {
this.setSelected(entity, true);
}
}
/** Takes `entities` out of the selection, leaving the rest as it is. */
public deselect(entities: Entity | Entity[]): void {
for (const entity of Array.isArray(entities) ? entities : [entities]) {
this.setSelected(entity, false);
}
}
public clearSelection(): void {
this.select([]);
}
/**
* Points the timeline at `entity` (or at nothing). Same route as
* `select`: `setActive` enforces the runtime's rules and writes the trait,
* and the file learns `active` moved, `false` for the one it left.
*/
public activate(entity: Entity | null): void {
const current = getActiveEntity(this.world);
if (current === entity) return;
setActive(this.world, entity);
if (current?.isAlive() && !isLooped(current)) this.reportEdit(current, 'active', false);
if (entity && !isLooped(entity)) this.reportEdit(entity, 'active', true);
}
/**
* Selection and activation of a looped entity stay on the canvas: pointing
* at one iteration is not a reason to write the loop out, and the loop
* body cannot say which iteration is meant. Once an edit has settled the
* loop, they travel like anyone's.
*/
private setSelected(entity: Entity, selected: boolean): void {
if (!entity.isAlive() || entity.has(Stage) || entity.has(Selected) === selected) return;
if (selected) entity.add(Selected);
else entity.remove(Selected);
if (!isLooped(entity)) this.reportEdit(entity, 'selected', selected);
}
/**
* Makes `entity` one the file can address on its own. An entity a loop
* rendered shares its element — and so its source — with every other
* iteration, so a write to it would be a write to all of them; before the
* first edit reaches one, the loop is reported for unrolling with what each
* iteration rendered, so the writer can spell the iterations out as
* elements of their own and land the edit on the right one.
*
* The iterations are read off the canvas: the loop's entities are the
* children of one parent that carry its stamp, in order, and the body
* repeats through them (`a b a b` for a body of two elements). Every
* iteration but the first is re-stamped with a pending source on the spot,
* so anything the editor does to it from here on is addressed to its own
* copy and waits for that copy's name (see the edit writer). The stamps
* come off every entity of the loop, so this happens once; if the write
* declines, `unsettle` puts everything back and the loop stays as it was.
*
* Left alone, with nothing reported, when the loop is not one the canvas
* can spell out: an iteration that rendered something different from the
* others, a loop within a loop, an element with no source. The writer
* refuses to write into a loop, so such an edit is reported as skipped
* rather than reaching every iteration.
*/
private settle(entity: Entity): void {
if (!isLooped(entity)) return;
const loop = entity.get(Loop)!.value;
const stamped = (candidate: Entity | null): boolean => candidate !== null && candidate.get(Loop)?.value === loop;
// Up to the top of this iteration, and to the element the loop rendered into.
let top = entity;
while (stamped(getParentEntity(top))) top = getParentEntity(top)!;
const container = getParentEntity(top);
if (container === null || isLooped(container)) return;
const roots = getEntityChildren(this.world, container).filter(stamped);
const first = roots[0]?.get(Source)?.value;
if (!first) return;
// The body's top-level sources repeat once per iteration.
const width = roots.findIndex((root, index) => index > 0 && root.get(Source)?.value === first);
const stride = width === -1 ? roots.length : width;
if (roots.length % stride !== 0) return;
const count = roots.length / stride;
if (!roots.every((root, index) => root.get(Source)?.value === roots[index % stride]!.get(Source)?.value)) return;
// What each iteration rendered, element by element, and the entities
// to re-stamp once it is all known to be spellable.
const iterations: LoopIteration[] = [];
const restamp: [Entity, string][] = [];
for (let index = 0; index < count; index++) {
const iteration: LoopIteration = {};
for (const root of roots.slice(index * stride, (index + 1) * stride)) {
for (const member of getEntityTree(this.world, root)) {
// Only what the project authored: the runtime's own
// sub-entities are derived from that, not written.
const authored = authoredElement(member);
if (!authored) continue;
const source = member.get(Source)?.value;
// A loop within the loop, or an element the file does not
// know, or one the body renders twice: not spellable.
if (!source || !stamped(member) || source in iteration) return;
const pending = index > 0 ? nextPendingSource() : undefined;
iteration[source] = { props: wireProps(authored.props), ...(authored.text === undefined ? {} : { text: authored.text }), ...(pending ? { pending } : {}) };
if (pending) restamp.push([member, pending]);
}
}
iterations.push(iteration);
}
for (const [member, pending] of restamp) member.set(Source, { value: pending });
for (const root of roots) {
for (const member of getEntityTree(this.world, root)) member.remove(Loop);
}
this.emit({ kind: 'unroll', source: first, loop, iterations });
}
/**
* Takes back an unroll the write declined: the entities go back to the
* sources they had and to being the loop's, so that pointing at them stays
* on the canvas and the next edit asks again. Nothing is destroyed — the
* loop still renders them, it just cannot be written to.
*/
public unsettle(edit: UnrollEdit): void {
const originals = new Map<string, string>();
const members = new Set<string>();
for (const iteration of edit.iterations) {
for (const [source, { pending }] of Object.entries(iteration)) {
members.add(source);
if (pending) originals.set(pending, source);
}
}
for (const entity of this.world.query(Source)) {
const current = entity.get(Source)!.value;
const original = originals.get(current);
if (original) entity.set(Source, { value: original });
if (original || members.has(current)) {
entity.add(Loop);
entity.set(Loop, { value: edit.loop });
}
}
}
/**
* Adds elements the way a project would author them, under `parent` and in
* front of `anchor` (or last):
*
* editor.insertElement(scene, () => <Rect x={10} width={200} height={300} />)
*
* `element` is rendered like a piece of a project (the PascalCase
* components of "./elements", since an app's own JSX compiles for the DOM),
* so the entities are real from this call on: same recipe, traits, and
* ordering a compiled render gets. What they lack is a name in the file, so
* each is stamped with a pending source that `restamp` replaces once the
* write answers, and reported as an insert in creation order (parents
* before children, so a nested tree lands in one write). Returns the
* top-level entities created; nothing when the parent has no source to be
* written under.
*/
public insertElement(parent: Entity, element: () => unknown, anchor?: Entity): Entity[] {
if (!parent.get(Source)?.value) return [];
// A child of one iteration's element, not of every iteration's.
this.settle(parent);
if (anchor) this.settle(anchor);
const created = new Map<Entity, Recorded>();
const document = this.document;
const dispose = createRoot((dispose) => {
withDocument(this.recording(created), () =>
insert(document.node(parent), element, anchor ? document.node(anchor) : null),
);
return dispose;
});
// Nothing here stays reactive: the values were the tool's, and the
// entities outlive the graph that produced them (as on unmount).
dispose();
for (const [entity, { tag, props }] of created) {
const parentEntity = getParentEntity(entity);
const parentSource = parentEntity?.get(Source)?.value;
if (!parentEntity || !parentSource) continue;
// Placed in front of the next sibling that was already there. New
// siblings are skipped: they are appended after this one, or share
// its anchor, and either way the order in the file comes out right.
const siblings = getEntityChildren(this.world, parentEntity);
const before = siblings
.slice(siblings.indexOf(entity) + 1)
.find((sibling) => !created.has(sibling))
?.get(Source)?.value;
// A text element's content arrived as text nodes, which the document
// has already folded into Chars; that is what the file gets.
const text = isText(entity) ? entity.get(Chars)?.value : undefined;
this.emit({
kind: 'insert',
source: entity.get(Source)!.value,
parent: parentSource,
tag,
props,
...(before ? { before } : {}),
...(text === undefined ? {} : { text }),
});
}
return [...created.keys()].filter((entity) => !created.has(getParentEntity(entity)!));
}
/**
* Copies `entities`, subtrees included, and reports the copies as inserts
* so they land in the file too. A copy is spelled from what its source was
* authored as (`authoredTree`), so it has the same props — the same
* position — and sits in the same parent, right on top of its source
* (inserted after it in order). Only the tops of the selected subtrees are
* copied: a descendant of another one goes with it.
*
* The exception is a node inside a sequence: two clips at the same time
* conflict there, so the copy goes to the nearest parent that is not a
* sequence, on top of the sequence it came out of. A sequence has no
* spatial identity and no time of its own, so the same props put the copy
* where the source is.
*
* The selection moves to the copies (`selected` is not copied, nor is
* `active`: one entity holds it). Returns the copies' top-level entities.
*/
public duplicate(entities: Entity | Entity[]): Entity[] {
const copies: Entity[] = [];
for (const source of this.subtreeRoots(entities)) {
const tree = this.spell(source);
if (!tree) continue;
// Out of any sequence, on top of what it left.
let below = source;
let parent = getParentEntity(below);
while (parent && parent.has(Sequential)) {
below = parent;
parent = getParentEntity(below);
}
if (!parent) continue;
const siblings = getEntityChildren(this.world, parent);
const anchor = siblings[siblings.indexOf(below) + 1];
copies.push(...this.insertElement(parent, () => renderAuthored(tree), anchor));
}
if (copies.length) this.select(copies);
return copies;
}
/**
* Copies `entities` where they stand: each copy goes in the parent its
* original is in, directly after it, rather than out of the sequence
* around it the way `duplicate` places one. Two clips at the same time do
* conflict in a sequence, so this is for a caller that is about to move
* the two apart — a split, whose halves end up adjacent rather than on
* top of each other — and not for one that leaves them where they land.
*
* The original is settled first (see `settle`): the copy is placed
* against it, so the file has to be able to name that one clip and not
* just the loop body it was rendered from. The selection is left alone,
* since what a copy in place means is the caller's to say. Returns the
* pairs it made, in the order of the originals.
*/
public duplicateInPlace(entities: Entity | Entity[]): { original: Entity; copy: Entity }[] {
const pairs: { original: Entity; copy: Entity }[] = [];
for (const original of this.subtreeRoots(entities)) {
const parent = getParentEntity(original);
if (!parent) continue;
this.settle(original);
const tree = this.spell(original);
if (!tree) continue;
const siblings = getEntityChildren(this.world, parent);
const anchor = siblings[siblings.indexOf(original) + 1];
const [copy] = this.insertElement(parent, () => renderAuthored(tree), anchor);
if (copy) pairs.push({ original, copy });
}
return pairs;
}
/**
* Puts `entities` inside a new element of their own: `element` is rendered
* where the first of them stood and they all move into it, in the order
* they were already in. Only the ones sharing that first one's parent take
* part — a wrap has one place to put things.
*
* Nothing is rewritten on the way in, which is what a `<sequence>` wants:
* it has no space or time of its own, so its children keep the position
* and the start they had. A wrapper that does sit somewhere would need its
* children's positions rewritten into it, and this does not do that.
*
* The selection is left alone. Returns the wrapper, or null when there is
* nothing to wrap, nowhere to write it, or nothing that would go in — an
* empty element is not worth putting in the file.
*/
public wrap(entities: Entity | Entity[], element: () => unknown): Entity | null {
const roots = new Set(this.subtreeRoots(entities));
const first = [...roots][0];
if (!first) return null;
const parent = getParentEntity(first);
if (!parent) return null;
const members = getEntityChildren(this.world, parent).filter((entity) => roots.has(entity));
if (members.length === 0) return null;
// In front of the first member, so the wrapper takes their place among
// the siblings rather than landing at the end of them.
const [wrapper] = this.insertElement(parent, element, members[0]);
if (!wrapper) return null;
// Moved back to front, each in front of the one after it: the last has
// nothing to go in front of, and every other one is placed against a
// member that is in there already. Appending them in order reads the
// same on the canvas, but not in the file, where an element still
// waiting to be inserted lands before a move of one the file has.
const moved: Entity[] = [];
for (const member of [...members].reverse()) {
if (this.reparent(member, wrapper, moved[0])) moved.unshift(member);
}
if (moved.length === 0) {
this.remove(wrapper);
return null;
}
return wrapper;
}
/**
* Takes a node's intrinsic media off by rewriting the element: a `<video>`
* or `<image>` becomes the `<rect>` it otherwise was — same box, same
* timing, same children (fills, strokes, animations) — with the props that
* only meant something while it played media dropped (see `MEDIA_PROPS`).
* What the media implied rather than the element authored is pinned so
* only the picture goes away: the box (a media element defaults to
* 1920x1080 where a rect is 100x100) and the span (a clip lasts its
* footage where a rect falls back to the default; the same pin the runtime
* makes when a geometry loses its paint, see `pinTrimToCurrentBounds`).
* Goes to the file the way the fill picker swaps a fill's kind: the
* insert of the rect, then the removal of the old element. The selection
* and the timeline's active pointer move to the rect. Returns the rect,
* or null when the node has no intrinsic media to remove.
*/
public removeIntrinsicPaint(node: Entity): Entity | null {
const intrinsic = getIntrinsicPaint(node);
if (intrinsic !== PaintType.VIDEO && intrinsic !== PaintType.IMAGE) return null;
const parent = getParentEntity(node);
if (!parent) return null;
// Spelled as its own element, not every iteration's of a loop.
this.settle(node);
const tree = this.spell(node);
if (!tree) return null;
const props = { ...tree.props };
for (const name of MEDIA_PROPS) {
delete props[name];
}
const size = node.get(Size);
if (size) {
props.width ??= size.width;
props.height ??= size.height;
}
const fps = this.world.get(FrameRate)?.value ?? 30;
if (props.start === undefined) {
// A start the runtime derived (a syncTo correlation) rather than
// the element authored.
const start = Math.round((node.get(Computed)?.start ?? 0) - getTimelineOrigin(node));
if (start > 0) props.start = framesToSeconds(start, fps);
}
if (props.end === undefined) {
const end = (node.get(Computed)?.end ?? 0) - getTimelineOrigin(node);
if (end > 0) props.end = framesToSeconds(end, fps);
}
const rect: AuthoredTree = { tag: 'rect', props, children: tree.children };
const wasSelected = node.has(Selected);
const wasActive = node.has(Active);
const [next] = this.insertElement(parent, () => renderAuthored(rect), node);
if (!next) return null;
this.remove(node);
if (wasSelected) this.select(next);
if (wasActive) this.activate(next);
return next;
}
/**
* Takes a copy of `entities` (the tops of their subtrees, as `duplicate`
* would) for `paste`. Nothing is reported: the file only changes when the
* copy lands. Leaves the clipboard alone when there is nothing to copy.
*/
public copy(entities: Entity | Entity[]): void {
const roots = this.subtreeRoots(entities);
const trees = roots.map((root) => this.spell(root)).filter((tree) => tree !== undefined);
if (!trees.length) return;
this.clipboard = { trees, parent: getParentEntity(roots[0]!)?.get(Source)?.value };
}
/** Whether `paste` has anything to insert. Not reactive: read it when asked. */
public canPaste(): boolean {
return this.clipboard.trees.length > 0;
}
/**
* Inserts what `copy` took under `parent`, in front of `anchor` or last,
* with the same props it was copied with — same position, if the parent is
* the same. Pasting back into the sequence it was copied out of would put a
* clip on top of itself, so that goes to the sequence's parent instead, on
* top of the sequence (`duplicate`'s rule). The selection moves to the
* copies. Returns their top-level entities.
*/
public paste(parent: Entity, anchor?: Entity): Entity[] {
const { trees, parent: copiedFrom } = this.clipboard;
if (!trees.length) return [];
if (parent.has(Sequential) && copiedFrom !== undefined && parent.get(Source)?.value === copiedFrom) {
const outer = getParentEntity(parent);
if (!outer) return [];
const siblings = getEntityChildren(this.world, outer);
anchor = siblings[siblings.indexOf(parent) + 1];
parent = outer;
}
const copies: Entity[] = [];
for (const tree of trees) {
copies.push(...this.insertElement(parent, () => renderAuthored(tree), anchor));
}
if (copies.length) this.select(copies);
return copies;
}
/**
* The tops of the subtrees `entities` span: those the file can address,
* minus any that sit under another of them, in the given order.
*/
private subtreeRoots(entities: Entity | Entity[]): Entity[] {
const wanted = new Set(
(Array.isArray(entities) ? entities : [entities]).filter(
(entity) => entity.isAlive() && !entity.has(Stage) && !!entity.get(Source)?.value,
),
);
return [...wanted].filter((entity) => {
for (let parent = getParentEntity(entity); parent; parent = getParentEntity(parent)) {
if (wanted.has(parent)) return false;
}
return true;
});
}
/**
* `entity`'s subtree as a project would author a copy of it: `selected`
* goes (the copy is selected on its own terms) and so does `active` (one
* entity holds it).
*/
private spell(entity: Entity): AuthoredTree | undefined {
const tree = authoredTree(this.world, entity);
if (!tree) return undefined;
delete tree.props.selected;
delete tree.props.active;
return tree;
}
/**
* Moves `entity` under `parent`, in front of `anchor` or last, and reports
* it so the element moves in the file too. The move goes through the
* document, so the canvas ends up exactly where a project nesting it that
* way would have put it (ordering included).
*/
public reparent(entity: Entity, parent: Entity, anchor?: Entity): boolean {
if (!entity.get(Source)?.value || !parent.get(Source)?.value) return false;
// Appending where it already is, last, is the one move that changes
// nothing. Appending from anywhere else in the same parent is a real
// move — it is how a node is sent to the end of its siblings.
if (getParentEntity(entity) === parent && anchor === undefined) {
const siblings = getEntityChildren(this.world, parent);
if (siblings[siblings.length - 1] === entity) return false;
}
// Checked here rather than left to the document: a move into itself is
// a no-op there (nothing to report), and one into its own subtree is
// caught only after the node has already left the parent it had.
if (entity === parent || getEntityTree(this.world, entity).includes(parent)) return false;
// Each end of the move has to be one element, not every iteration's.
this.settle(entity);
this.settle(parent);
if (anchor) this.settle(anchor);
const source = entity.get(Source)!.value;
const parentSource = parent.get(Source)!.value;
// Where it stands now, before the document moves it: the inverse move.
const fromParent = getParentEntity(entity)?.get(Source)?.value;
const fromBefore = nextSourceAfter(this.world, entity);
const wasActive = entity.has(Active);
try {
const document = this.document;
document.insertNode(document.node(parent), document.node(entity), anchor ? document.node(anchor) : undefined);
} catch {
return false;
}
// An anchor the file does not name cannot be pointed at; appending is
// the honest answer, and where the document put it either way.
const before = anchor?.get(Source)?.value;
this.emit({
kind: 'move',
source,
parent: parentSource,
...(before ? { before } : {}),
...(fromParent ? { fromParent } : {}),
...(fromBefore ? { fromBefore } : {}),
});
// Only a root holds the active tag (see world/observers), so a node
// that just stopped being one has lost it; the file hears that here
// rather than keeping an `active` its own rules would strip on reload.
if (wasActive && !entity.has(Active)) {
this.reportEdit(entity, 'active', false);
}
return true;
}
/**
* Deletes `entities` and everything under them, and reports it so the
* elements leave the file too. Only the tops of the doomed subtrees are
* reported: a descendant of another doomed entity goes with it, in the file
* as on the canvas. The stage, and anything the file does not know (no
* source), stays. Returns the entities that were removed at the top level.
*/
public remove(entities: Entity | Entity[]): Entity[] {
const doomed = new Set(
(Array.isArray(entities) ? entities : [entities]).filter(
(entity) => entity.isAlive() && !entity.has(Stage) && !!entity.get(Source)?.value,
),
);
const roots = [...doomed].filter((entity) => {
for (let parent = getParentEntity(entity); parent; parent = getParentEntity(parent)) {
if (doomed.has(parent)) return false;
}
return true;
});
const document = this.document;
for (const entity of roots) {
if (!entity.isAlive()) continue;
// Cut from the file as one iteration's element, not the body's.
this.settle(entity);
const source = entity.get(Source)!.value;
// Its place and its content, the moment before they go. A doomed
// sibling can be the `before`: the undo reinserts in reverse order,
// so it is back by the time anything is placed against it.
const parentSource = getParentEntity(entity)?.get(Source)?.value;
const before = nextSourceAfter(this.world, entity);
const node = captureNode(this.world, entity);
document.removeNode(document.node(getParentEntity(entity) ?? document.stage.entity), document.node(entity));
this.emit({
kind: 'remove',
source,
...(parentSource ? { parent: parentSource } : {}),
...(before ? { before } : {}),
...(node ? { node } : {}),
});
}
return roots;
}
/**
* Re-stamps entities whose element earned a name, as `old source -> new`.
* Queried rather than remembered: the entities that survived are the ones
* the world still holds.
*/
public restamp(ids: Record<string, string>): void {
for (const entity of this.world.query(Source)) {
const next = ids[entity.get(Source)!.value];
if (next) entity.set(Source, { value: next });
}
for (const listener of [...this.renames]) listener(ids);
}
/**
* Takes back an element whose insert could not be written: it has no
* place in the file, so it has no place on the canvas either.
*/
public discardPending(source: string): void {
if (!isPendingSource(source)) return;
const document = this.document;
// Snapshot: destroying cascades through the subtree, and a live query
// would hand back children that went with their parent.
const doomed = [...this.world.query(Source)].filter((entity) => entity.get(Source)?.value === source);
for (const entity of doomed) {
if (!entity.isAlive()) continue;
const parent = getParentEntity(entity);
document.removeNode(document.node(parent ?? document.stage.entity), document.node(entity));
}
}
/**
* The document as `insertElement` renders into it: the same host, with
* every element created stamped pending and its tag and literal props
* noted in `created`. The document itself never learns it was watched.
*/
private recording(created: Map<Entity, Recorded>): ProjectDocument<SceneNode> {
const document = this.document;
return {
stage: document.stage,
createElement: (tag) => {
const node = document.createElement(tag);
if (isSceneNode(node) && node !== document.stage) {
document.setProperty(node, SOURCE_ATTR, nextPendingSource());
created.set(node.entity, { tag: tag.charAt(0).toLowerCase() + tag.slice(1), props: {} });
}
return node;
},
setProperty: (node, name, value) => {
const recorded = isSceneNode(node) ? created.get(node.entity) : undefined;
if (recorded && name !== SOURCE_ATTR && name !== 'children' && name !== 'ref') {
const wire = wireValue(value);
if (wire !== undefined) recorded.props[name] = wire;
}
document.setProperty(node, name, value);
},
createTextNode: (text) => document.createTextNode(text),
replaceText: (node, text) => document.replaceText(node, text),
isTextNode: (node) => document.isTextNode(node),
insertNode: (parent, node, anchor) => document.insertNode(parent, node, anchor),
removeNode: (parent, node) => document.removeNode(parent, node),
getParentNode: (node) => document.getParentNode(node),
getFirstChild: (node) => document.getFirstChild(node),
getNextSibling: (node) => document.getNextSibling(node),
};
}
}
const editors = new WeakMap<World, DocumentEditor>();
/** The editor for `world`, created on first use. Outlives mounts: it reads the current document per call. */
export function getDocumentEditor(world: World): DocumentEditor {
let editor = editors.get(world);
if (!editor) {
editor = new DocumentEditor(world);
editors.set(world, editor);
}
return editor;
}