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 {
AdjustmentLayer,
ChildOf,
Computed,
Culled,
FrameRate,
Geometry,
Group,
Hidden,
Muted,
Position,
Root,
Selected,
Soloed,
Time,
Tool,
ToolType,
Workarea,
getActiveEntity,
getCameraMatrix,
getEntityChildren,
getParentEntity,
getParentNode,
getSelection,
isGroupLike,
isSequence,
Library,
setPlayhead,
shuttlePlayback,
stopPlayback,
store,
togglePlayback,
} from '@diffusionstudio/runtime';
import { Not, Or } from 'koota';
import { claimClipboard, hasMedia, readClipboardMedia } from '@/lib/clipboard';
import { pasteClipboardMedia } from '../asset-actions';
import { zoomBy, zoomTo, zoomToFit, zoomToSelection } from '../camera';
import { applyMasks, applySelectionAsMask, cancelMask } from '../mask';
import { getDocumentEditor } from '../editor';
import { groupSelection, ungroupSelection, unwrapSequenceSelection, wrapSelectionInScene, wrapSelectionInSequence } from '../group';
import { getEditHistory } from '../history';
import { withEmptiedTracks } from '../keyframes';
import { cancelObjectMask, getObjectTrack, trackObjectMask, undoMaskStroke } from '../object-mask';
import { beginPathEdit, deletePickedVertex, endPathEdit, finishPen, isPathEditing, isPenDrawing, selectedPath } from '../path-tool';
import { splitAtPlayhead } from '../split';
import { Keys, MODIFIER_KEYS, ObjectMaskTool, Pointer } from '../traits';
import { editTransform } from './interactions';
import type { ClipboardMedia } from '@/lib/clipboard';
import type { TransformWrite } from './interactions';
import type { CameraMatrix } from '@diffusionstudio/runtime';
import type { Entity, World } from 'koota';
type Shortcut = {
keys: string[];
action: (world: World) => void;
active?: (world: World) => boolean;
}
/** The node kinds a shortcut selects, hides or seeks around. */
const NODES = Or(Geometry, Group, AdjustmentLayer);
export function undoEdit(world: World): void {
getEditHistory(world).undo();
}
export function redoEdit(world: World): void {
getEditHistory(world).redo();
}
export function deleteSelection(world: World): void {
const selected = [...world.query(Selected)];
if (selected.length) {
getDocumentEditor(world).remove(withEmptiedTracks(selected));
}
};
export function duplicateSelection(world: World): void {
const selected = [...world.query(Selected)];
if (selected.length) {
getDocumentEditor(world).duplicate(selected);
}
}
export function copySelection(world: World): void {
const selected = [...world.query(Selected)];
if (selected.length) {
getDocumentEditor(world).copy(selected);
claimClipboard();
}
}
/** Copy and delete in one, so the clipboard holds what the stage lost. */
export function cutSelection(world: World): void {
copySelection(world);
deleteSelection(world);
}
/**
* Pastes what the clipboard holds, from a menu or the palette: see
* `pasteInto`. ⌘V pastes from its paste event instead (see the engine).
*/
export async function pasteSelection(world: World): Promise<void> {
await pasteInto(world, await readClipboardMedia());
}
/**
* Pastes where the selection points: into a selected container (a scene or
* group, on top of its children), on top of a selected leaf in that leaf's
* parent, or, with nothing selected, into the active scene. The editor keeps
* a paste out of the sequence it was copied from.
*
* `media` copied in another app since the editor's last copy (a screenshot,
* files from the Finder) is pasted instead: imported into the library, then
* inserted into the same parent, or a new scene when there is none.
*/
export async function pasteInto(world: World, media: ClipboardMedia): Promise<void> {
const [selected] = world.query(Selected);
if (selected === undefined) {
const active = getActiveEntity(world) ?? undefined;
if (hasMedia(media)) await pasteMedia(world, media, active);
else if (active) getDocumentEditor(world).paste(active);
return;
}
if (isGroupLike(selected)) {
if (hasMedia(media)) await pasteMedia(world, media, selected);
else getDocumentEditor(world).paste(selected);
return;
}
const parent = getParentEntity(selected);
if (parent === null) return;
if (hasMedia(media)) {
await pasteMedia(world, media, parent);
return;
}
const siblings = getEntityChildren(world, parent);
getDocumentEditor(world).paste(parent, siblings[siblings.indexOf(selected) + 1]);
}
async function pasteMedia(world: World, media: ClipboardMedia, parent: Entity | undefined): Promise<void> {
const library = world.get(Library);
if (library) await pasteClipboardMedia(world, library, media, parent);
}
const NUDGE = 1;
const NUDGE_FAST = 10;
/**
* Moves every selected node by `dx`, `dy` in its own parent's space, the same
* `x`/`y` a drag writes, so a nudge is a drag of a known distance without the
* snapping. Measured from where the node is drawn rather than from the prop,
* and written to the position track as well as the prop, so nudging an
* animated node moves it from where its keyframes put it (a drag does the
* same; see `editTransform`).
*/
export function nudgeSelection(world: World, dx: number, dy: number): void {
const editor = getDocumentEditor(world);
const computed = store(world, Computed);
for (const entity of getSelection(world)) {
if (!entity.has(Position)) continue;
const eid = entity.id();
const writes: TransformWrite[] = [];
if (dx) writes.push(['x', Math.round((computed.positionX[eid] ?? 0) + dx)]);
if (dy) writes.push(['y', Math.round((computed.positionY[eid] ?? 0) + dy)]);
editTransform(world, editor, entity, writes);
}
}
const nudge = (dx: number, dy: number) => (world: World): void => nudgeSelection(world, dx, dy);
/** How long space has to be held to read as a pan and not as a tap. */
const SPACE_HAND_DELAY = 200;
/**
* The camera as it stood when space went down over the stage; null when
* space is up, or when the press was one that cannot turn into a pan.
*/
let spaceCamera: CameraMatrix | null = null;
/**
* The tool space borrowed the hand from, put back on release; null while
* space does not hold the hand.
*/
let spaceTool: ToolType | null = null;
/**
* When the space press went down, so a hold long enough to be a pan can be
* told from a tap; null once the hand has taken over, or once space is up.
*/
let spacePressedAt: number | null = null;
/** Puts the hand in the toolbar for as long as space holds it. */
function takeHandTool(world: World): void {
spacePressedAt = null;
if (spaceTool !== null) return;
spaceTool = world.get(Tool)?.value ?? ToolType.MOVE;
world.set(Tool, { value: ToolType.HAND });
}
/** Gives back whatever tool space borrowed the hand from. */
function releaseHandTool(world: World): void {
spacePressedAt = null;
if (spaceTool === null) return;
world.set(Tool, { value: spaceTool });
spaceTool = null;
}
function toggleActivePlayback(world: World): void {
const scene = getActiveEntity(world);
if (scene) togglePlayback(world, scene);
}
/**
* J and L, the shuttle pair: each press runs the active scene faster the way
* it is already going, or turns it around at 1x. K parks it.
*/
const shuttle = (direction: 1 | -1) => (world: World): void => {
const scene = getActiveEntity(world);
if (scene) shuttlePlayback(world, scene, direction);
};
function stopActivePlayback(world: World): void {
const scene = getActiveEntity(world);
if (scene) stopPlayback(world, scene);
}
function onSpacePressed(world: World): void {
// The hand waits out the delay wherever the pointer is; what the pointer
// decides is only when playback gets its toggle. Over the stage the press
// could still become a pan, so playback waits for a release that left the
// camera where it was; anywhere else it toggles here and now.
spacePressedAt = world.get(Time)?.now ?? 0;
if (world.get(Pointer)?.over) {
spaceCamera = getCameraMatrix(world);
} else {
spaceCamera = null;
toggleActivePlayback(world);
}
}
function onSpaceLifted(world: World): void {
const camera = getCameraMatrix(world);
if (spaceCamera?.every((value, index) => value === camera[index])) {
toggleActivePlayback(world);
}
spaceCamera = null;
releaseHandTool(world);
}
/**
* What space does by being held rather than by moving, which the tables
* cannot express: the hand takes over once the press outlasts
* `SPACE_HAND_DELAY`, and a hold the window loses focus mid-way through
* never sees a release (`held` is cleared without a lift), so the borrowed
* tool goes back on the first frame the key is no longer down.
*/
function updateSpaceHold(world: World, held: Set<string>): void {
if (!held.has(' ')) {
spaceCamera = null;
releaseHandTool(world);
return;
}
if (spacePressedAt === null) return;
if ((world.get(Time)?.now ?? 0) - spacePressedAt >= SPACE_HAND_DELAY) {
takeHandTool(world);
}
}
/**
* Picks a tool. While space holds the hand the pick is what the release
* goes back to, so the hand keeps the stage until the key is up.
*/
const selectTool = (value: ToolType) => (world: World): void => {
if (spaceTool !== null) {
spaceTool = value;
return;
}
world.set(Tool, { value });
};
/**
* Moves the active scene's playhead by `frames`, the same seek a scrub of the
* ruler comes to. Nothing to seek without an active scene.
*/
export function seekBy(world: World, frames: number): void {
const scene = getActiveEntity(world);
if (!scene) return;
setPlayhead(world, scene, (store(world, Computed).localTime[scene.id()] ?? 0) + frames);
}
const seekFrames = (frames: number) => (world: World): void => seekBy(world, frames);
const seekSeconds = (seconds: number) => (world: World): void =>
seekBy(world, Math.round(seconds * (world.get(FrameRate)?.value ?? 30)));
/**
* Parks the playhead on the selection's outer edge: the earliest frame any of
* it starts on, or the frame just past the last of it to end. `end` is
* exclusive everywhere else — the frame a following clip begins on, and the
* one a cut at the boundary leaves the playhead on — so it is here too.
*
* The scene is the context the clips are edited in rather than a clip on it,
* so having it selected is not an edge to jump to.
*/
export function seekToSelectionEdge(world: World, edge: 'start' | 'end'): void {
const scene = getActiveEntity(world);
if (!scene) return;
const computed = store(world, Computed);
const clips = [...world.query(Selected, NODES)].filter(entity => entity !== scene);
if (!clips.length) return;
const frames = clips.map(entity => computed[edge][entity.id()] ?? 0);
setPlayhead(world, scene, edge === 'start' ? Math.min(...frames) : Math.max(...frames));
}
const seekSelectionEdge = (edge: 'start' | 'end') => (world: World): void =>
seekToSelectionEdge(world, edge);
/**
* Parks the playhead at one end of the active scene. A work area is the
* stretch that plays and exports, so while there is one its edges are the
* ends: seeking past them would leave the playhead where playback cannot
* pick up, and the next play would snap back in anyway.
*/
export function seekToTimelineEdge(world: World, edge: 'start' | 'end'): void {
const scene = getActiveEntity(world);
if (!scene) return;
const workarea = scene.has(Workarea) ? scene.get(Workarea) : undefined;
setPlayhead(world, scene, edge === 'start'
? workarea?.start ?? 0
: workarea?.end ?? store(world, Computed).duration[scene.id()] ?? 0);
}
const seekTimelineEdge = (edge: 'start' | 'end') => (world: World): void =>
seekToTimelineEdge(world, edge);
/** How much of the zoom a step takes, in or out. */
const ZOOM_STEP = 1.25;
const zoom = (factor: number) => (world: World): void => zoomBy(world, factor);
const zoomActualSize = (world: World): void => zoomTo(world, 1);
/**
* Hides the selection, or brings it back once all of it is hidden — the same
* property the eye in the layer list writes, one write per node.
*/
export function toggleSelectionHidden(world: World): void {
const editor = getDocumentEditor(world);
const selected = [...world.query(Selected, NODES)];
if (!selected.length) return;
const hide = selected.some(entity => !entity.has(Hidden));
for (const entity of selected) editor.editProperty(entity, 'hidden', hide);
}
/**
* Mutes the selection, or unmutes it once all of it is muted — the property
* the mute button in the layer list writes, one write per node.
*/
export function toggleSelectionMuted(world: World): void {
const editor = getDocumentEditor(world);
const selected = [...world.query(Selected, NODES)];
if (!selected.length) return;
const mute = selected.some(entity => !entity.has(Muted));
for (const entity of selected) editor.editProperty(entity, 'muted', mute);
}
/**
* Solos the first selected node, or takes the solo off it. Solo is
* monitoring rather than composition, so it is the trait alone, never an
* edit, and only one node holds it (as the layer list's solo button has it).
*/
export function toggleSelectionSoloed(world: World): void {
const [entity] = world.query(Selected, NODES);
if (entity === undefined) return;
const wasSoloed = entity.has(Soloed);
for (const other of world.query(Soloed)) other.remove(Soloed);
if (!wasSoloed) entity.add(Soloed);
}
/**
* Sends the selection to the front or the back of its siblings. Which of two
* nodes is drawn on top is which of them the file lists last, so a restack is
* a move through the document rather than an index written to the node. A
* selection spanning parents is restacked inside each of them, and the moved
* nodes keep the order they had among themselves.
*/
export function restackSelection(world: World, target: 'front' | 'back'): void {
const editor = getDocumentEditor(world);
const selected = new Set([...world.query(Selected, NODES)]);
if (!selected.size) return;
const parents = new Set<Entity>();
for (const entity of selected) {
const parent = getParentEntity(entity);
if (parent !== null) parents.add(parent);
}
for (const parent of parents) {
const siblings = getEntityChildren(world, parent);
const moving = siblings.filter(entity => selected.has(entity));
if (target === 'front') {
// Appended one after the other, each lands on top of the last, so
// the order they were in is the order they end up in.
for (const entity of moving) editor.reparent(entity, parent);
continue;
}
// All of them go before the backmost sibling that is staying put —
// the one node the whole block has to end up behind.
const anchor = siblings.find(entity => !selected.has(entity));
if (anchor === undefined) continue;
for (const entity of moving) editor.reparent(entity, parent, anchor);
}
}
const restack = (target: 'front' | 'back') => (world: World): void => restackSelection(world, target);
/**
* Selects everything the stage holds directly — the scenes and whatever else
* sits loose on it, rather than what is inside them.
*/
export function selectAll(world: World): void {
const root = world.get(Root);
if (!root) return;
const entities = [...world.query(NODES, ChildOf(root), Not(Hidden), Not(Culled))];
if (entities.length) getDocumentEditor(world).select(entities);
}
/**
* Selects what holds the selection. A sequence is a container the timeline
* draws rather than a node the canvas selects, so the walk goes on through
* it; a node the stage holds directly has nothing to go up to.
*/
export function selectParents(world: World): void {
const selected = [...world.query(Selected, NODES)];
if (!selected.length) return;
const parents = new Set<Entity>();
for (const entity of selected) {
let parent = getParentNode(entity);
while (parent !== null && isSequence(parent)) {
parent = getParentNode(parent);
}
if (parent !== null) parents.add(parent);
}
if (parents.size) getDocumentEditor(world).select([...parents]);
}
/**
* Selects what the selection holds, one level down, sequences seen through
* the same way `selectParents` sees through them. What is hidden or out of
* range is not there to be stepped into.
*/
export function selectChildren(world: World): void {
const selected = [...world.query(Selected, NODES)];
if (!selected.length) return;
const children = new Set<Entity>();
const collect = (parent: Entity): void => {
for (const child of world.query(NODES, ChildOf(parent), Not(Hidden), Not(Culled))) {
if (isSequence(child)) collect(child);
else children.add(child);
}
};
for (const entity of selected) collect(entity);
if (children.size) getDocumentEditor(world).select([...children]);
}
/** Drops the selection, and whatever tool was drawing with it. */
function deselect(world: World): void {
getDocumentEditor(world).clearSelection();
const tool = world.get(Tool)?.value ?? ToolType.MOVE;
if (tool !== ToolType.MOVE && tool !== ToolType.HAND) selectTool(ToolType.MOVE)(world);
}
const objectMaskTool = (world: World): boolean => world.get(Tool)?.value === ToolType.OBJECT_MASK;
/** A brush stroke to take back: ⌘Z undoes strokes before it undoes edits. */
const maskStrokeToUndo = (world: World): boolean => {
const track = getObjectTrack();
return objectMaskTool(world) && track?.status === 'seeded' && track.strokes.length > 0;
};
const maskTool = (world: World): boolean => world.get(Tool)?.value === ToolType.MASK;
/** Enter on a lone selected path edits its vertices, where it would otherwise step into children. */
const pathToEdit = (world: World) => world.get(Tool)?.value === ToolType.MOVE && selectedPath(world) !== null;
const editSelectedPath = (world: World) => beginPathEdit(world, selectedPath(world)!);
const PRESSED_SHORTCUTS: readonly Shortcut[] = [
// Mask tool shortcuts, ahead of the Esc and ⌘↵ the rest of the editor answers to.
{ keys: ['escape'], action: cancelMask, active: maskTool },
{ keys: ['enter', 'mod', '!shift', '!alt'], action: applyMasks, active: maskTool },
// The pen ends its path on Esc or Enter, the path editor goes down on
// either, and Delete takes out its picked vertex rather than the path.
{ keys: ['escape'], action: (world) => finishPen(world, false), active: isPenDrawing },
{ keys: ['enter'], action: (world) => finishPen(world, false), active: isPenDrawing },
{ keys: ['escape'], action: endPathEdit, active: isPathEditing },
{ keys: ['enter', '!mod'], action: endPathEdit, active: isPathEditing },
{ keys: ['backspace'], action: deletePickedVertex, active: isPathEditing },
{ keys: ['delete'], action: deletePickedVertex, active: isPathEditing },
{ keys: ['z', 'mod', '!shift'], action: undoEdit },
{ keys: ['z', 'mod', 'shift'], action: redoEdit },
{ keys: ['backspace'], action: deleteSelection },
{ keys: ['delete'], action: deleteSelection },
{ keys: ['d', 'mod', '!shift'], action: duplicateSelection },
{ keys: ['g', 'mod', '!shift'], action: groupSelection },
{ keys: ['g', 'mod', 'shift'], action: ungroupSelection },
{ keys: ['m', 'meta', 'control'], action: applySelectionAsMask },
{ keys: ['enter', 'mod', '!shift', '!alt'], action: wrapSelectionInScene },
{ keys: ['enter', 'mod', 'alt', '!shift'], action: wrapSelectionInSequence },
{ keys: ['enter', 'mod', 'alt', 'shift'], action: unwrapSequenceSelection },
{ keys: ['b', 'mod'], action: splitAtPlayhead },
{ keys: ['c', 'mod'], action: copySelection },
{ keys: ['x', 'mod'], action: cutSelection },
{ keys: ['h', 'mod', 'shift'], action: toggleSelectionHidden },
{ keys: ['a', 'mod'], action: selectAll },
{ keys: ['=', 'mod'], action: zoom(ZOOM_STEP) },
{ keys: ['+', 'mod'], action: zoom(ZOOM_STEP) },
{ keys: ['-', 'mod'], action: zoom(1 / ZOOM_STEP) },
{ keys: ['0', 'mod'], action: zoomActualSize },
{ keys: ['1', 'mod'], action: zoomToFit },
{ keys: ['2', 'mod'], action: zoomToSelection },
{ keys: ['v', '!mod'], action: selectTool(ToolType.MOVE) },
{ keys: ['h', '!mod'], action: selectTool(ToolType.HAND) },
{ keys: ['f', '!mod'], action: selectTool(ToolType.SCENE) },
{ keys: ['t', '!mod'], action: selectTool(ToolType.TEXT) },
{ keys: ['r', '!mod'], action: selectTool(ToolType.RECT) },
{ keys: ['o', '!mod'], action: selectTool(ToolType.ELLIPSE) },
{ keys: ['p', '!mod'], action: selectTool(ToolType.PEN), active: (world) => !objectMaskTool(world) },
{ keys: ['m', '!mod'], action: selectTool(ToolType.OBJECT_MASK) },
{ keys: ['a', '!mod'], action: seekFrames(-1) },
{ keys: ['d', '!mod'], action: seekFrames(1) },
{ keys: ['w', '!mod'], action: seekSeconds(1) },
{ keys: ['s', '!mod'], action: seekSeconds(-1) },
{ keys: [';', '!mod'], action: seekSelectionEdge('start') },
{ keys: ["'", '!mod'], action: seekSelectionEdge('end') },
// fn ←/→ on macOS, Home/End elsewhere.
{ keys: ['home'], action: seekTimelineEdge('start') },
{ keys: ['end'], action: seekTimelineEdge('end') },
{ keys: ['j', '!mod'], action: shuttle(-1) },
{ keys: ['k', '!mod'], action: stopActivePlayback },
{ keys: ['l', '!mod'], action: shuttle(1) },
{ keys: [']', '!mod'], action: restack('front') },
{ keys: ['[', '!mod'], action: restack('back') },
{ keys: ['\\', '!mod'], action: selectParents },
{ keys: ['enter', '!mod'], action: editSelectedPath, active: pathToEdit },
{ keys: ['enter', '!mod'], action: selectChildren },
{ keys: ['escape'], action: deselect },
{ keys: ['arrowleft', '!shift'], action: nudge(-NUDGE, 0) },
{ keys: ['arrowright', '!shift'], action: nudge(NUDGE, 0) },
{ keys: ['arrowup', '!shift'], action: nudge(0, -NUDGE) },
{ keys: ['arrowdown', '!shift'], action: nudge(0, NUDGE) },
{ keys: ['arrowleft', 'shift'], action: nudge(-NUDGE_FAST, 0) },
{ keys: ['arrowright', 'shift'], action: nudge(NUDGE_FAST, 0) },
{ keys: ['arrowup', 'shift'], action: nudge(0, -NUDGE_FAST) },
{ keys: ['arrowdown', 'shift'], action: nudge(0, NUDGE_FAST) },
{ keys: [' '], action: onSpacePressed },
// Object mask tool shortcuts
{ keys: ['p', '!mod'], action: (world) => world.set(ObjectMaskTool, { mode: 'points' }), active: objectMaskTool },
{ keys: ['b', '!mod'], action: (world) => world.set(ObjectMaskTool, { mode: 'brush' }), active: objectMaskTool },
{ keys: ['escape'], action: cancelObjectMask, active: objectMaskTool },
{ keys: ['enter', 'mod', '!shift', '!alt'], action: trackObjectMask, active: objectMaskTool },
{ keys: ['z', 'mod', '!shift'], action: undoMaskStroke, active: maskStrokeToUndo },
];
const LIFTED_SHORTCUTS: readonly Shortcut[] = [
{ keys: [' '], action: onSpaceLifted },
];
/**
* Whether `moved` — the keys that went down, or up, this frame — spells the
* shortcut: one of its keys has to be the one that moved, the rest have to
* be held, and a '!' key has to be up. The key that moved is matched
* against `moved` rather than `held` because a lift takes it out of `held`,
* and a tap shorter than a frame is over before the frame runs.
*
* Only a non-modifier can be the trigger: ⌘Z means Z pressed under ⌘, not ⌘
* pressed over a Z — and `held` can hold a stale letter, since macOS drops
* the key-up of a key released while ⌘ is down, so a fresh ⌘ press must not
* complete a shortcut on its own.
*/
function matches(world: World, shortcut: Shortcut, moved: Set<string>, held: Set<string>): boolean {
let triggered = false;
for (const key of shortcut.keys) {
if (key.startsWith('!')) {
if (held.has(key.slice(1))) return false;
} else if (moved.has(key) && !MODIFIER_KEYS.has(key)) {
triggered = true;
} else if (!held.has(key)) {
return false;
}
}
return triggered && (shortcut.active?.(world) ?? true);
}
/** On a frame with a fresh press or release, runs the shortcut it spells. */
export function shortcutSystem(world: World): void {
const keys = world.get(Keys);
if (!keys) return;
if (keys.pressed.size) {
PRESSED_SHORTCUTS.find(shortcut => matches(world, shortcut, keys.pressed, keys.held))?.action(world);
}
if (keys.lifted.size) {
LIFTED_SHORTCUTS.find(shortcut => matches(world, shortcut, keys.lifted, keys.held))?.action(world);
}
updateSpaceHold(world, keys.held);
}