Skip to content

The VS Code of video editing, built for agents.

TypeScript

Refactor document editing and node management in the editor

konstantin-paulus0aa88ae4c7c6
diff --git a/apps/web/src/engine/editor.ts b/apps/web/src/engine/editor.ts
index f80568ec..1548f5d5 100644
--- a/apps/web/src/engine/editor.ts
+++ b/apps/web/src/engine/editor.ts
@@ -204,7 +204,7 @@ export class DocumentEditor {
/** Writes a prop to the document and reports it. */
public editProperty(entity: Entity, name: string, value: PropValue): void {
- this.document.setProperty({ entity }, name, value);
+ this.document.setProperty(this.document.node(entity), name, value);
this.reportEdit(entity, name, value);
}
@@ -424,9 +424,10 @@ export class DocumentEditor {
if (anchor) this.settle(anchor);
const created = new Map<Entity, Recorded>();
+ const document = this.document;
const dispose = createRoot((dispose) => {
withDocument(this.recording(created), () =>
- insert({ entity: parent }, element, anchor ? { entity: anchor } : null),
+ insert(document.node(parent), element, anchor ? document.node(anchor) : null),
);
return dispose;
});
@@ -693,7 +694,8 @@ export class DocumentEditor {
const wasActive = entity.has(Active);
try {
- this.document.insertNode({ entity: parent }, { entity }, anchor ? { entity: anchor } : undefined);
+ const document = this.document;
+ document.insertNode(document.node(parent), document.node(entity), anchor ? document.node(anchor) : undefined);
} catch {
return false;
}
@@ -745,7 +747,7 @@ export class DocumentEditor {
// Cut from the file as one iteration's element, not the body's.
this.settle(entity);
const source = entity.get(Source)!.value;
- document.removeNode({ entity: getParentEntity(entity) ?? document.stage.entity }, { entity });
+ document.removeNode(document.node(getParentEntity(entity) ?? document.stage.entity), document.node(entity));
this.sink?.({ kind: 'remove', source });
}
@@ -777,7 +779,7 @@ export class DocumentEditor {
for (const entity of doomed) {
if (!entity.isAlive()) continue;
const parent = getParentEntity(entity);
- document.removeNode({ entity: parent ?? document.stage.entity }, { entity });
+ document.removeNode(document.node(parent ?? document.stage.entity), document.node(entity));
}
}
diff --git a/packages/reconciler/src/document.ts b/packages/reconciler/src/document.ts
index 2e42f23e..02d09514 100644
--- a/packages/reconciler/src/document.ts
+++ b/packages/reconciler/src/document.ts
@@ -11,8 +11,18 @@ import type { AssetRef } from '@diffusionstudio/jsx';
import { trait, type Entity, type World } from 'koota';
import type { ProjectDocument } from './host';
+/**
+ * One element of the document, and its place in it. `parent` and `children`
+ * are the tree the reconciler reads back: text nodes and element nodes in the
+ * one order they were inserted in, which is what the document answers
+ * `getFirstChild` and `getNextSibling` from.
+ */
export interface SceneNode {
readonly entity: Entity;
+ tag: string;
+ props: Record<string, unknown>;
+ parent: SceneNode | null;
+ children: HostNode[];
}
/**
@@ -33,32 +43,7 @@ export interface TextNode {
export type HostNode = SceneNode | TextNode;
-/**
- * The text nodes a `<text>` entity holds, in order.
- *
- * The world is the document's only store: everything the document knows
- * about a node lives on that node's entity as a trait, and nothing is
- * mirrored in fields on `RuntimeDocument`. State that lives in two places
- * drifts as soon as one side (a cascade destroy, a move, an undo) is
- * updated without the other; state that lives on the entity is destroyed,
- * copied and observed together with it. When the document needs something
- * new, add a trait here — do not add a Map/Set field to the class.
- *
- * Text nodes themselves are the one thing not backed by an entity (they
- * are the reconciler's, held by identity), which is why they hang off their
- * parent entity via this trait rather than the other way around.
- */
-const TextParts = trait(() => new Set<TextNode>());
-
-/**
- * What the project wrote on an entity's element, in the vocabulary of the JSX
- * rather than of the traits it became: the tag, and every prop as last set.
- * Kept so an editor can spell an entity back out as an element — which is how
- * a loop's iterations get written down one by one — without reading the traits
- * backwards. `children` is not a prop here: an element's text is `Chars`, and
- * its element children are the entity's.
- */
-const Authored = trait(() => ({ tag: '', props: {} as Record<string, unknown> }));
+const Host = trait(() => null as SceneNode | null);
/** Props that address or wire an element rather than describe it. */
const UNAUTHORED_PROPS: ReadonlySet<string> = new Set([SOURCE_ATTR, LOOP_ATTR, 'children', 'ref']);
@@ -85,11 +70,11 @@ export interface AuthoredElement {
* undefined for an entity no document created (the stage included).
*/
export function authoredElement(entity: Entity): AuthoredElement | undefined {
- const authored = entity.get(Authored);
- if (authored === undefined) return undefined;
+ const node = entity.get(Host);
+ if (!node || node.tag === '') return undefined;
const text = isText(entity) ? entity.get(Chars)?.value : undefined;
- return { tag: authored.tag, props: { ...authored.props }, ...(text ? { text } : {}) };
+ return { tag: node.tag, props: { ...node.props }, ...(text ? { text } : {}) };
}
/** An authored element with the authored elements under it, in order. */
@@ -121,31 +106,49 @@ export function isSceneNode(node: HostNode): node is SceneNode {
}
/**
- * The text nodes of `entity` in order; empty when it holds none.
+ * The text nodes among `node`'s children, in order; empty when it holds none.
*/
-function textParts(entity: Entity): TextNode[] {
- return Array.from(entity.get(TextParts) ?? []);
+function textParts(node: SceneNode): TextNode[] {
+ return node.children.filter((child): child is TextNode => !isSceneNode(child));
}
/**
- * Re-derives `Chars` from the text nodes `entity` currently holds.
+ * 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(entity: Entity): void {
- if (!entity.isAlive()) return;
+function syncChars(node: SceneNode): void {
+ const { entity } = node;
+ if (!entity.isAlive() || !isText(entity)) return;
entity.add(Chars);
- entity.set(Chars, { value: textParts(entity).map((part) => part.text).join('') });
+ entity.set(Chars, { value: textParts(node).map((part) => part.text).join('') });
}
/**
- * Detaches `node` from its parent entity and refreshes that entity's text.
+ * Takes `node` out of the children of whatever parent it has, and refreshes
+ * that parent's text.
*/
-function detachText(node: TextNode): void {
+function detach(node: HostNode): void {
const parent = node.parent;
if (parent === null) return;
- parent.entity.get(TextParts)?.delete(node);
+ const at = parent.children.indexOf(node);
+ if (at !== -1) parent.children.splice(at, 1);
node.parent = null;
- syncChars(parent.entity);
+ syncChars(parent);
+}
+
+/**
+ * Cuts the links inside a subtree about to be destroyed, so whatever the
+ * reconciler still holds out of it reads as detached — the way its entities
+ * read as destroyed.
+ */
+function detachSubtree(node: SceneNode): void {
+ for (const child of node.children) {
+ if (isSceneNode(child)) detachSubtree(child);
+ child.parent = null;
+ }
+ node.children.length = 0;
}
const TIME_TRAITS = {
@@ -395,7 +398,27 @@ export class RuntimeDocument implements ProjectDocument<HostNode> {
public constructor(world: World) {
this.world = world;
- this.stage = { entity: world.get(Root)! };
+ const root = world.get(Root)!;
+ this.stage = { entity: root, tag: '', props: {}, parent: null, children: [] };
+ root.add(Host);
+ root.set(Host, this.stage);
+ }
+
+ /**
+ * 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, tag: '', props: {}, parent: null, children: [] };
+ entity.add(Host);
+ entity.set(Host, node);
+ return node;
}
public createElement(tag: string): SceneNode | SurfaceNode {
@@ -595,23 +618,31 @@ export class RuntimeDocument implements ProjectDocument<HostNode> {
);
}
- if (entity !== this.stage.entity) {
- entity.add(Authored);
- entity.set(Authored, { tag: name, props: {} });
+ // 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,
+ tag: name,
+ props: {},
+ parent: null,
+ children: []
+ };
+
if (name === 'surface' || name === 'surfacePaint') {
- // A getter, not a copy: the node holds no state of its own.
- const node: SurfaceNode = {
- entity,
+ Object.assign(node, {
get canvas() {
return entity.get(SurfaceHostHandle)?.canvas ?? null;
},
- };
- return node;
+ })
}
- return { entity };
+ entity.add(Host);
+ entity.set(Host, node);
+ return node;
}
public createTextNode(text: string): TextNode {
@@ -622,7 +653,7 @@ export class RuntimeDocument implements ProjectDocument<HostNode> {
if (isSceneNode(node)) return;
node.text = text;
if (node.parent) {
- syncChars(node.parent.entity);
+ syncChars(node.parent);
}
}
@@ -639,7 +670,8 @@ export class RuntimeDocument implements ProjectDocument<HostNode> {
* the canvas, whose element is not written yet) gets `Chars` alone.
*/
public setText(entity: Entity, text: string): void {
- const parts = textParts(entity);
+ const node = this.node(entity);
+ const parts = textParts(node);
if (parts.length === 0) {
entity.add(Chars);
@@ -650,17 +682,18 @@ export class RuntimeDocument implements ProjectDocument<HostNode> {
for (const [index, part] of parts.entries()) {
part.text = index === 0 ? text : '';
}
- syncChars(entity);
+ syncChars(node);
}
public setProperty(node: HostNode, name: string, value: unknown): void {
if (!isSceneNode(node)) return;
const { entity } = node;
- const authored = entity.get(Authored);
- if (authored && !UNAUTHORED_PROPS.has(name)) {
- if (value === undefined) delete authored.props[name];
- else authored.props[name] = value;
+ // 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) {
@@ -779,14 +812,14 @@ export class RuntimeDocument implements ProjectDocument<HostNode> {
entity.set(CornerRadius, { value: radius });
}
// The corners without a radius of their own take this one.
- this.syncCornerRadii(entity);
+ this.syncCornerRadii(node);
return;
}
case 'cornerRadiusTopLeft':
case 'cornerRadiusTopRight':
case 'cornerRadiusBottomRight':
case 'cornerRadiusBottomLeft': {
- this.syncCornerRadii(entity);
+ this.syncCornerRadii(node);
return;
}
case 'blendMode': {
@@ -874,7 +907,7 @@ export class RuntimeDocument implements ProjectDocument<HostNode> {
// 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(entity.get(Authored)?.props[other]) === undefined) {
+ if (isText(entity) && toNumber(node.props[other]) === undefined) {
entity.remove(Size);
}
return;
@@ -1016,7 +1049,7 @@ export class RuntimeDocument implements ProjectDocument<HostNode> {
// A `<captions>` without a src transcribes its scene instead.
if (entity.has(Caption)) {
entity.add(TranscriptionRequest);
- entity.set(TranscriptionRequest, { seed: toNumber(entity.get(Authored)?.props.seed) ?? 0 });
+ entity.set(TranscriptionRequest, { seed: toNumber(node.props.seed) ?? 0 });
}
return;
}
@@ -1216,7 +1249,7 @@ export class RuntimeDocument implements ProjectDocument<HostNode> {
if (entity.has(LoadRequest) || entity.has(GenerationRequest)) return;
- const src = entity.get(Authored)?.props.src;
+ const src = node.props.src;
if (src === undefined || src === null || src === '') return;
// A resolution running for the old modifiers must not bind late.
@@ -1237,7 +1270,7 @@ export class RuntimeDocument implements ProjectDocument<HostNode> {
if (!entity.has(Caption)) return;
// An authored src mounts a transcript directly; there is no
// transcription for the seed to key.
- if (entity.get(Authored)?.props.src !== undefined) return;
+ if (node.props.src !== undefined) return;
if (entity.has(LoadRequest) || entity.has(GenerationRequest)) return;
// A resolution running for another seed must not bind late
@@ -1289,8 +1322,8 @@ export class RuntimeDocument implements ProjectDocument<HostNode> {
* without one takes `cornerRadius`. Recomputed whole on every one of the
* five, so the order Solid sets them in does not matter.
*/
- private syncCornerRadii(entity: Entity): void {
- const props = entity.get(Authored)?.props ?? {};
+ 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);
@@ -1304,40 +1337,46 @@ export class RuntimeDocument implements ProjectDocument<HostNode> {
}
/**
- * Entity handles are minted per lookup, so every comparison here is between
- * entities: two handles for the same node are never the same object. Text
- * nodes are the exception, held by identity (see `TextNode`).
+ * 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: HostNode, node: HostNode, anchor?: HostNode): void {
if (!isSceneNode(parent)) {
throw new Error('Text cannot contain children.');
}
- if (!isSceneNode(node)) {
- if (!isText(parent.entity)) {
- throw new Error('Only <text> takes text children.');
- }
-
- if (node.parent && node.parent.entity !== parent.entity) {
- detachText(node);
+ if (isSceneNode(node)) {
+ 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');
}
+ }
- // The Set keeps insertion order, so a reorder is a rebuild.
- parent.entity.add(TextParts);
- const parts = textParts(parent.entity).filter((part) => part !== node);
- const at = anchor && !isSceneNode(anchor) ? parts.indexOf(anchor) : -1;
- if (at === -1) parts.push(node);
- else parts.splice(at, 0, node);
- parent.entity.set(TextParts, new Set(parts));
+ 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;
- node.parent = parent;
- syncChars(parent.entity);
+ if (!isSceneNode(node)) {
+ syncChars(parent);
return;
}
- if (parent.entity === node.entity) return;
-
-
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.
@@ -1350,80 +1389,61 @@ export class RuntimeDocument implements ProjectDocument<HostNode> {
appendChild(this.world, node.entity, parent.entity);
if (node.entity.has(KeyframeTrack)) {
- this.resolveTrackProperty(node.entity, node.entity.get(Authored)?.props.property);
+ this.resolveTrackProperty(node.entity, node.props.property);
}
if (node.entity.has(SurfaceHostHandle)) {
syncSurfaceSize(this.world, parent.entity);
}
}
- const siblings = getEntityChildren(this.world, parent.entity).filter((sibling) => sibling !== node.entity);
- const at = anchor && isSceneNode(anchor) ? siblings.indexOf(anchor.entity) : -1;
- if (at === -1) siblings.push(node.entity);
- else siblings.splice(at, 0, node.entity);
- for (const [index, sibling] of siblings.entries()) {
- sibling.add(ItemIndex);
- sibling.set(ItemIndex, { value: index });
+ let index = 0;
+ for (const sibling of parent.children) {
+ if (!isSceneNode(sibling)) continue;
+ sibling.entity.add(ItemIndex);
+ sibling.entity.set(ItemIndex, { value: index++ });
}
}
+ /**
+ * 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: HostNode, node: HostNode): void {
- if (!isSceneNode(node)) {
- detachText(node);
- return;
- }
+ detach(node);
+
+ if (!isSceneNode(node)) return;
if (node.entity.has(Stage)) {
- for (const child of getEntityChildren(this.world, node.entity)) {
- this.removeNode(node, { entity: child });
+ for (const child of [...node.children]) {
+ this.removeNode(node, child);
}
node.entity.set(Background, { value: DEFAULT_BACKGROUND });
node.entity.remove(Source);
return;
}
- // Destroy cascades through the subtree; the text nodes held for it go too.
- for (const entity of getEntityTree(this.world, node.entity)) {
- const texts = entity.get(TextParts);
- if (texts === undefined) continue;
- for (const text of texts) {
- text.parent = null;
- }
- entity.remove(TextParts);
- }
+
+ // Destroy cascades through the subtree; whatever the reconciler still
+ // holds out of it — a text node, a node a ref kept — learns it has no
+ // parent, the way the entities learn they are gone.
+ detachSubtree(node);
// ChildOf auto-destroys orphans, so paints go with it.
node.entity.destroy();
}
public getParentNode(node: HostNode): SceneNode | undefined {
- if (!isSceneNode(node)) return node.parent ?? undefined;
- const parent = getParentEntity(node.entity);
- return parent === null ? undefined : { entity: parent };
+ return node.parent ?? undefined;
}
public getFirstChild(node: HostNode): HostNode | undefined {
- if (!isSceneNode(node)) return undefined;
- const text = node.entity.get(TextParts)?.values().next().value;
- if (text !== undefined) return text;
- const child = getEntityChildren(this.world, node.entity).at(0);
- return child === undefined ? undefined : { entity: child };
+ return isSceneNode(node) ? node.children[0] : undefined;
}
public getNextSibling(node: HostNode): HostNode | undefined {
- if (!isSceneNode(node)) {
- // A text entity has only text nodes to iterate.
- if (node.parent === null) return undefined;
- const parts = textParts(node.parent.entity);
- const at = parts.indexOf(node);
- return at === -1 ? undefined : parts[at + 1];
- }
-
- const parent = this.getParentNode(node);
- if (parent === undefined) return undefined;
- const siblings = getEntityChildren(this.world, parent.entity);
- const at = siblings.indexOf(node.entity);
- if (at === -1) return undefined;
- const next = siblings[at + 1];
- return next === undefined ? undefined : { entity: next };
+ const parent = node.parent;
+ if (parent === null) return undefined;
+ const at = parent.children.indexOf(node);
+ return at === -1 ? undefined : parent.children[at + 1];
}