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/. */
/**
* Undo and redo for the mounted project. The history is a listener on the
* one funnel every mutation already goes through: it keeps the edits the
* `DocumentEditor` reports as invertible pairs, and an undo replays the
* inverses through the same editor commands the edit was made with — so the
* canvas changes the way any edit changes it, and the file hears about it
* through the same writer. Nothing here knows about a disk, or a second way
* to change anything.
*
* Everything is addressed by `Source` stamp, never by entity: entities die
* on remount, stamps survive it. When an undo has to put an element back
* (or a redo insert one again), the reinsert mints fresh pending sources —
* the history pairs them with the ones it recorded and rewrites itself, the
* same rename it hears from `restamp` when a write answers with real names.
*
* The history is cleared whenever a bundle is (re)mounted: a mount comes
* from the file, and edits recorded against a document that is gone cannot
* be replayed against the one that replaced it.
*/
import { Source, getEntityChildren } from '@diffusionstudio/runtime';
import { authoredElement, renderAuthored } from '@diffusionstudio/reconciler';
import { createSignal } from 'solid-js';
import { getDocumentEditor } from './editor';
import type { AuthoredTree } from '@diffusionstudio/reconciler';
import type { InspectValue, PropValue } from '@diffusionstudio/jsx';
import type { Entity, World } from 'koota';
import type { CapturedNode, DocumentEditor, EntityEdit } from './editor';
/**
* Props that are pointing and viewing rather than composition: undoing them
* is not what anyone means by undo, so they pass through to the file without
* entering the history.
*/
const EXCLUDED_PROPS: ReadonlySet<string> = new Set(['selected', 'active', 'camera', 'expanded', 'clipHeight', 'timeline', 'playhead']);
/**
* How long after one step a same-shaped step still merges into it. Edits
* that arrive through the DOM rather than a canvas gesture — an inspector
* slider, repeated nudges — come as bursts of tiny transactions; within
* this window a repeat of the same props reads as one continuing adjustment.
*/
const COALESCE_WINDOW = 600;
/** How many steps back the history keeps; beyond it, the oldest fall off. */
const MAX_TRANSACTIONS = 100;
/**
* One recorded edit with what it takes to play it in either direction. An
* insert's and a remove's `node` is the element as captured at the moment it
* existed (see `CapturedNode`); `parent`/`before` are its place. A move's
* two ends are both spelled out. All sources, everywhere, are rewritten as
* renames come in.
*/
interface PropOp {
kind: 'prop';
source: string;
name: string;
before: unknown;
after: unknown;
}
interface TextOp {
kind: 'text';
source: string;
before: string;
after: string;
}
interface InsertOp {
kind: 'insert';
parent: string;
before?: string;
node: CapturedNode;
}
interface RemoveOp {
kind: 'remove';
parent: string;
before?: string;
node: CapturedNode;
}
interface MoveOp {
kind: 'move';
source: string;
fromParent?: string;
fromBefore?: string;
toParent: string;
toBefore?: string;
}
/**
* An `@inspect` variable, set. Addressed by file and variable name — no
* source, no entity, so renames never touch it and it replays against
* whatever the current mount declared under that name.
*/
interface VariableOp {
kind: 'variable';
file: string;
name: string;
before: InspectValue;
after: InspectValue;
}
type HistoryOp = PropOp | TextOp | InsertOp | RemoveOp | MoveOp | VariableOp;
/**
* The identity a sliding op coalesces on: the same prop of the same element,
* or the same variable, adjusted again is one continuing adjustment.
*/
const slidingKey = (op: HistoryOp): string | undefined => {
if (op.kind === 'prop') return `prop ${op.source} ${op.name}`;
if (op.kind === 'variable') return `variable ${op.file} ${op.name}`;
return undefined;
};
/**
* One undo step: the ops of one gesture, or of one synchronous burst of
* edits (a shortcut, a compound command, an inspector change). `broken`
* marks a step holding an edit that could not be captured whole — replaying
* around it would lie, so committing it clears the history instead.
*/
interface Transaction {
ops: HistoryOp[];
gesture: boolean;
committedAt: number;
broken?: boolean;
}
export class EditHistory {
private readonly world: World;
private readonly editor: DocumentEditor;
private undos: Transaction[] = [];
private redos: Transaction[] = [];
/** The transaction edits are landing in right now, not yet a step. */
private open: Transaction | null = null;
/** The transaction being replayed right now: renames reach it too. */
private replaying: Transaction | null = null;
private gesture = false;
private scheduled = false;
private applying = false;
/** Bumped on every change, so the menu's disabled states stay honest. */
private readonly changed: () => void;
private readonly version: () => number;
public constructor(world: World) {
this.world = world;
this.editor = getDocumentEditor(world);
this.editor.onEdit((edit) => this.record(edit));
this.editor.onRename((ids) => this.rename(ids));
const [version, setVersion] = createSignal(0);
this.version = version;
this.changed = () => setVersion((current) => current + 1);
}
/** Whether there is a step to undo. Reactive under a Solid computation. */
public canUndo(): boolean {
this.version();
return this.undos.length > 0 || (this.open?.ops.length ?? 0) > 0;
}
/** Whether there is a step to redo. Reactive under a Solid computation. */
public canRedo(): boolean {
this.version();
return this.redos.length > 0;
}
/**
* Starts over, for a fresh mount: what was recorded against the previous
* document cannot be replayed against this one.
*/
public reset(): void {
this.undos = [];
this.redos = [];
this.open = null;
this.gesture = false;
this.changed();
}
/**
* Brackets a pointer hold: every edit from press to release — however
* many frames a drag writes — is one step. A press while a burst is
* still open commits it first, so the gesture starts on its own step.
*/
public beginGesture(): void {
if (this.open) this.commit();
this.gesture = true;
}
public endGesture(): void {
if (!this.gesture) return;
this.gesture = false;
if (this.open) this.commit();
}
/** Takes back the last step, and hands it to redo. */
public undo(): void {
if (this.open) this.commit();
const transaction = this.undos.pop();
if (!transaction) return;
this.replay(transaction, [...transaction.ops].reverse(), (op) => this.revert(op));
this.redos.push(transaction);
this.changed();
}
/** Plays the last undone step again, and hands it back to undo. */
public redo(): void {
if (this.open) this.commit();
const transaction = this.redos.pop();
if (!transaction) return;
this.replay(transaction, transaction.ops, (op) => this.apply(op));
this.undos.push(transaction);
this.changed();
}
/**
* Runs one direction of a step through the editor. `applying` keeps the
* recorder from hearing the replay as new edits; the writer hears it like
* any other change, which is the point. The transaction is held where
* renames can reach it: a reinsert in the middle of it renames sources
* its own later ops refer to.
*/
private replay(transaction: Transaction, ops: HistoryOp[], step: (op: HistoryOp) => void): void {
this.applying = true;
this.replaying = transaction;
try {
for (const op of ops) step(op);
} finally {
this.applying = false;
this.replaying = null;
}
}
/** ---- Recording ---- */
private record(edit: EntityEdit): void {
if (this.applying) return;
switch (edit.kind) {
// An unroll renders exactly what the loop rendered: nothing to
// invert. The edits that follow it address the settled copies.
case 'unroll':
return;
case 'prop': {
if (EXCLUDED_PROPS.has(edit.name)) return;
// No inverse reported (see `reportEdit`): not undoable, and a
// step pretending otherwise would restore the wrong value.
if (!('previous' in edit)) return;
const transaction = this.ensureOpen();
// A drag writes the same prop every frame; one op, sliding.
const existing = transaction.ops.find(
(op): op is PropOp => op.kind === 'prop' && op.source === edit.source && op.name === edit.name,
);
if (existing) {
existing.after = edit.value;
return;
}
transaction.ops.push({ kind: 'prop', source: edit.source, name: edit.name, before: edit.previous, after: edit.value });
return;
}
case 'text': {
const transaction = this.ensureOpen();
const existing = transaction.ops.find(
(op): op is TextOp => op.kind === 'text' && op.source === edit.source,
);
if (existing) {
existing.after = edit.value;
return;
}
transaction.ops.push({ kind: 'text', source: edit.source, before: edit.previous ?? '', after: edit.value });
return;
}
case 'variable': {
const transaction = this.ensureOpen();
// A slider writes the same variable every frame; one op, sliding.
const existing = transaction.ops.find(
(op): op is VariableOp => op.kind === 'variable' && op.file === edit.file && op.name === edit.name,
);
if (existing) {
existing.after = edit.value;
return;
}
transaction.ops.push({ kind: 'variable', file: edit.file, name: edit.name, before: edit.previous, after: edit.value });
return;
}
case 'insert': {
const transaction = this.ensureOpen();
// The element as it stands, live values included, rather than
// the wire form the edit carries: a redo re-renders it the way
// `duplicate` renders a copy. Children arrive as inserts of
// their own (parents first), so the node holds none.
const entity = this.resolve(edit.source);
const element = entity ? authoredElement(entity) : undefined;
transaction.ops.push({
kind: 'insert',
parent: edit.parent,
...(edit.before ? { before: edit.before } : {}),
node: {
source: edit.source,
tag: edit.tag,
props: element ? element.props : { ...edit.props },
...(edit.text === undefined ? {} : { text: edit.text }),
children: [],
},
});
return;
}
case 'move': {
const transaction = this.ensureOpen();
transaction.ops.push({
kind: 'move',
source: edit.source,
toParent: edit.parent,
...(edit.before ? { toBefore: edit.before } : {}),
...(edit.fromParent ? { fromParent: edit.fromParent } : {}),
...(edit.fromBefore ? { fromBefore: edit.fromBefore } : {}),
});
return;
}
case 'remove': {
const transaction = this.ensureOpen();
if (!edit.parent || !edit.node) {
// Gone without a capture: nothing can put it back, and any
// older step referring into it would replay wrong.
transaction.broken = true;
return;
}
transaction.ops.push({
kind: 'remove',
parent: edit.parent,
...(edit.before ? { before: edit.before } : {}),
node: edit.node,
});
return;
}
}
}
/**
* The transaction edits are landing in, opened on the first of them. A
* burst outside a gesture commits on the microtask, so everything one
* event handler did — a shortcut over a whole selection, a compound
* command — is one step.
*/
private ensureOpen(): Transaction {
if (!this.open) {
this.open = { ops: [], gesture: this.gesture, committedAt: 0 };
this.changed();
}
if (!this.gesture && !this.scheduled) {
this.scheduled = true;
queueMicrotask(() => {
this.scheduled = false;
// A gesture that began meanwhile owns the step now.
if (!this.gesture && this.open) this.commit();
});
}
return this.open;
}
private commit(): void {
const transaction = this.open;
this.open = null;
if (!transaction) return;
if (transaction.broken) {
// Better no history than a history that lies.
this.undos = [];
this.redos = [];
this.changed();
return;
}
if (transaction.ops.length === 0) return;
transaction.committedAt = performance.now();
const last = this.undos[this.undos.length - 1];
if (last && this.coalesces(last, transaction)) {
for (const op of transaction.ops as (PropOp | VariableOp)[]) {
const target = last.ops.find(
(candidate): candidate is PropOp | VariableOp => slidingKey(candidate) === slidingKey(op),
);
if (target) target.after = op.after;
}
last.committedAt = transaction.committedAt;
} else {
this.undos.push(transaction);
if (this.undos.length > MAX_TRANSACTIONS) this.undos.shift();
}
this.redos = [];
this.changed();
}
/**
* Whether `next` is `last` still going: both bursts of sliding ops only —
* props or variables, never gestures (two drags are two steps) — over the
* same keys, close enough in time. A slider writes this shape.
*/
private coalesces(last: Transaction, next: Transaction): boolean {
if (last.gesture || next.gesture) return false;
if (next.committedAt - last.committedAt > COALESCE_WINDOW) return false;
const keysOf = (transaction: Transaction): Set<string> | undefined => {
const keys = new Set<string>();
for (const op of transaction.ops) {
const key = slidingKey(op);
if (key === undefined) return undefined;
keys.add(key);
}
return keys;
};
const lastKeys = keysOf(last);
const nextKeys = keysOf(next);
if (!lastKeys || !nextKeys) return false;
return lastKeys.size === nextKeys.size && [...nextKeys].every((entry) => lastKeys.has(entry));
}
/** ---- Replaying ---- */
private revert(op: HistoryOp): void {
switch (op.kind) {
case 'prop': {
const entity = this.resolve(op.source);
if (entity) this.editor.editProperty(entity, op.name, op.before as PropValue);
return;
}
case 'text': {
const entity = this.resolve(op.source);
if (entity) this.editor.editText(entity, op.before);
return;
}
case 'insert': {
const entity = this.resolve(op.node.source);
if (entity) this.editor.remove(entity);
return;
}
case 'remove': {
this.reinsert(op);
return;
}
case 'move': {
if (!op.fromParent) return;
const entity = this.resolve(op.source);
const parent = this.resolve(op.fromParent);
if (!entity || !parent) return;
const anchor = op.fromBefore === undefined ? undefined : this.resolve(op.fromBefore);
this.editor.reparent(entity, parent, anchor);
return;
}
case 'variable': {
this.editor.editVariable(op.file, op.name, op.before);
return;
}
}
}
private apply(op: HistoryOp): void {
switch (op.kind) {
case 'prop': {
const entity = this.resolve(op.source);
if (entity) this.editor.editProperty(entity, op.name, op.after as PropValue);
return;
}
case 'text': {
const entity = this.resolve(op.source);
if (entity) this.editor.editText(entity, op.after);
return;
}
case 'insert': {
this.reinsert(op);
return;
}
case 'remove': {
const entity = this.resolve(op.node.source);
if (entity) this.editor.remove(entity);
return;
}
case 'move': {
const entity = this.resolve(op.source);
const parent = this.resolve(op.toParent);
if (!entity || !parent) return;
const anchor = op.toBefore === undefined ? undefined : this.resolve(op.toBefore);
this.editor.reparent(entity, parent, anchor);
return;
}
case 'variable': {
this.editor.editVariable(op.file, op.name, op.after);
return;
}
}
}
/**
* Puts a captured element back where it was. The reinsert renders it the
* way a paste renders a copy, so the entities are real and the writer
* hears an insert like any other — under fresh pending sources, which
* the history immediately pairs with the recorded ones and renames
* itself by, so every other step naming the old sources now names the
* reborn element. An anchor that is not there anymore means last, the
* same answer the writer gives.
*/
private reinsert(op: InsertOp | RemoveOp): void {
const parent = this.resolve(op.parent);
if (!parent) return;
const anchor = op.before === undefined ? undefined : this.resolve(op.before);
const [top] = this.editor.insertElement(parent, () => renderAuthored(toAuthored(op.node)), anchor);
if (!top) return;
const ids: Record<string, string> = {};
this.pair(op.node, top, ids);
this.rename(ids);
}
/**
* Pairs a captured subtree with the entities its reinsert produced, in
* authored order — the render is the capture replayed, so the shapes
* match position for position.
*/
private pair(node: CapturedNode, entity: Entity, ids: Record<string, string>): void {
const source = entity.get(Source)?.value;
if (source && source !== node.source) ids[node.source] = source;
const children = getEntityChildren(this.world, entity).filter((child) => authoredElement(child) !== undefined);
node.children.forEach((child, index) => {
const live = children[index];
if (live) this.pair(child, live, ids);
});
}
/**
* Rewrites every source the history holds, wherever it appears — both
* stacks, the open transaction, and the step being replayed right now.
* Fed by `restamp` (a write answered with real names) and by `reinsert`
* (a reborn element got new ones).
*/
private rename(ids: Record<string, string>): void {
if (Object.keys(ids).length === 0) return;
const next = (source: string): string => ids[source] ?? source;
const transactions = [
...this.undos,
...this.redos,
...(this.open ? [this.open] : []),
...(this.replaying ? [this.replaying] : []),
];
for (const transaction of transactions) {
for (const op of transaction.ops) {
switch (op.kind) {
case 'prop':
case 'text':
op.source = next(op.source);
break;
case 'move':
op.source = next(op.source);
op.toParent = next(op.toParent);
if (op.toBefore !== undefined) op.toBefore = next(op.toBefore);
if (op.fromParent !== undefined) op.fromParent = next(op.fromParent);
if (op.fromBefore !== undefined) op.fromBefore = next(op.fromBefore);
break;
case 'insert':
case 'remove':
op.parent = next(op.parent);
if (op.before !== undefined) op.before = next(op.before);
renameNode(op.node, next);
break;
}
}
}
}
/** The living entity stamped with `source`, or undefined for none. */
private resolve(source: string): Entity | undefined {
for (const entity of this.world.query(Source)) {
if (entity.isAlive() && entity.get(Source)!.value === source) return entity;
}
return undefined;
}
}
/** A captured node as `renderAuthored` takes it. */
function toAuthored(node: CapturedNode): AuthoredTree {
return {
tag: node.tag,
props: { ...node.props },
...(node.text === undefined ? {} : { text: node.text }),
children: node.children.map(toAuthored),
};
}
function renameNode(node: CapturedNode, next: (source: string) => string): void {
node.source = next(node.source);
for (const child of node.children) renameNode(child, next);
}
const histories = new WeakMap<World, EditHistory>();
/** The history for `world`, created on first use. Outlives mounts, like the editor; `reset` it per mount. */
export function getEditHistory(world: World): EditHistory {
let history = histories.get(world);
if (!history) {
history = new EditHistory(world);
histories.set(world, history);
}
return history;
}