Skip to content

The VS Code of video editing, built for agents.

TypeScript

Refactor runtime package queries and enhance timeline indexing

konstantin-paulusf3b16bd02152
diff --git a/packages/runtime/src/actions/overlap.ts b/packages/runtime/src/actions/overlap.ts
new file mode 100644
index 00000000..b5b09fbc
--- /dev/null
+++ b/packages/runtime/src/actions/overlap.ts
@@ -0,0 +1,2 @@
+// Sequential overlap resolution (was api/overlap.ts). Lives in actions, not
+// queries: it trims, deletes, and splits clips via the overwrite model.
diff --git a/packages/runtime/src/index.ts b/packages/runtime/src/index.ts
index 4fdda0cc..44c3960e 100644
--- a/packages/runtime/src/index.ts
+++ b/packages/runtime/src/index.ts
@@ -2,6 +2,7 @@ export * from './constants';
export * from './traits';
export * from './world/create-world';
export * from './world/serialize';
+export * from './queries';
export * from './capture';
export * from './fonts';
export * from './utils';
diff --git a/packages/runtime/src/queries/hierarchy.ts b/packages/runtime/src/queries/hierarchy.ts
new file mode 100644
index 00000000..661972fa
--- /dev/null
+++ b/packages/runtime/src/queries/hierarchy.ts
@@ -0,0 +1,94 @@
+/* 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 { Not } from 'koota';
+
+import { ChildOf, Deleted, Computed, Name, Playback, PlaybackRate } from '../traits';
+import { isScene } from './predicates';
+
+import type { Entity, World, QueryParameter } from 'koota';
+
+export function getParentEntity(entity: Entity | null | undefined): Entity | null {
+ if (!entity) return null;
+ return entity.targetFor(ChildOf) ?? null;
+}
+
+/**
+ * Nearest ancestor of `entity` (excluding `entity` itself) that is a scene, or null.
+ */
+export function getSceneAncestor(entity: Entity): Entity | null {
+ let current = getParentEntity(entity);
+ while (current !== null) {
+ if (isScene(current)) return current;
+ current = getParentEntity(current);
+ }
+ return null;
+}
+
+export function getSiblingEntities(world: World, entity: Entity, ...traits: QueryParameter[]): Entity[] {
+ const parent = getParentEntity(entity);
+ if (parent === null) return [];
+
+ return [...world.query(ChildOf(parent), Not(Deleted), ...traits)];
+}
+
+export function getEntityTree(world: World, root: Entity): Entity[] {
+ const tree: Entity[] = [];
+
+ const walk = (entity: Entity): Entity[] => {
+ tree.push(entity);
+
+ for (const child of world.query(ChildOf(entity), Not(Deleted))) {
+ walk(child);
+ }
+
+ return tree;
+ };
+
+ return walk(root);
+}
+
+/**
+ * Returns the local frame for a node in its own source/content time: the
+ * timeline frame relative to the node's delay, scaled by its playback rate.
+ * This matches `Computed.localTime` (the space keyframes are sampled
+ * in), so keyframes authored at any playback rate land on the right content
+ * frame.
+ */
+export function getNodeLocalFrame(node: Entity): number {
+ const delay = node.get(Computed)?.delay ?? 0;
+ const playbackRate = node.get(PlaybackRate)?.value ?? 1;
+
+ let current: Entity | null = node;
+ while (current) {
+ const parent = getParentEntity(current);
+
+ // must be a root playback entity
+ if (current.has(Playback) && parent === null) {
+ const currentTime = current.get(Computed)?.localTime ?? 0;
+ return Math.round((currentTime - delay) * playbackRate);
+ }
+
+ current = parent;
+ }
+
+ return 0;
+}
+
+export function getNextName(world: World, prefix: string): string {
+ let max = 0;
+ const pattern = new RegExp(`^${prefix} (\\d+)$`);
+
+ // Deleted tombstones keep their Name and still count, so an undo can't
+ // resurrect a duplicate name.
+ for (const entity of world.query(Name)) {
+ const match = entity.get(Name)!.value.match(pattern);
+ if (match) {
+ const n = parseInt(match[1] ?? '0');
+ if (n > max) max = n;
+ }
+ }
+
+ return `${prefix} ${max + 1}`;
+}
diff --git a/packages/runtime/src/queries/index.ts b/packages/runtime/src/queries/index.ts
index 215cfefd..a20852d5 100644
--- a/packages/runtime/src/queries/index.ts
+++ b/packages/runtime/src/queries/index.ts
@@ -1 +1,3 @@
-// Re-exports read-side query helpers.
+export * from './predicates';
+export * from './hierarchy';
+export * from './timeline-index';
diff --git a/packages/runtime/src/queries/overlap.ts b/packages/runtime/src/queries/overlap.ts
deleted file mode 100644
index db11df01..00000000
--- a/packages/runtime/src/queries/overlap.ts
+++ /dev/null
@@ -1 +0,0 @@
-// Spatial and temporal overlap queries (was api/overlap.ts).
diff --git a/packages/runtime/src/queries/predicates.ts b/packages/runtime/src/queries/predicates.ts
new file mode 100644
index 00000000..227a93a7
--- /dev/null
+++ b/packages/runtime/src/queries/predicates.ts
@@ -0,0 +1,68 @@
+/* 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 {
+ Scene, Group, Sequential, Audio, AdjustmentLayer, Caption, Geometry, IsMask,
+ Paint, Cache,
+} from '../traits';
+import { GeometryType, PaintType } from '../constants';
+
+import type { Entity } from 'koota';
+
+export function isScene(entity: Entity): boolean {
+ return entity.has(Scene);
+}
+
+export function isGroup(entity: Entity): boolean {
+ return entity.has(Group);
+}
+
+export function isGroupLike(entity: Entity): boolean {
+ return entity.has(Group) || entity.has(Scene);
+}
+
+export function isSequence(entity: Entity): boolean {
+ return entity.has(Sequential);
+}
+
+export function isAudio(entity: Entity): boolean {
+ return entity.has(Audio);
+}
+
+export function isAdjustmentLayer(entity: Entity): boolean {
+ return entity.has(AdjustmentLayer);
+}
+
+export function isCaption(entity: Entity): boolean {
+ return entity.has(Caption);
+}
+
+export function isText(entity: Entity): boolean {
+ return entity.get(Geometry)?.value === GeometryType.TEXT;
+}
+
+export function isRect(entity: Entity): boolean {
+ return entity.get(Geometry)?.value === GeometryType.RECT;
+}
+
+/** A vanilla rect — not a container (group/scene/sequence) or audio clip.
+ * (Captions live on TEXT geometry, so they're naturally excluded.) */
+export function isShape(entity: Entity): boolean {
+ return entity.get(Geometry)?.value === GeometryType.RECT
+ && !entity.has(Group)
+ && !entity.has(Scene)
+ && !entity.has(Audio);
+}
+
+export function isMask(entity: Entity): boolean {
+ return entity.has(IsMask);
+}
+
+export function hasHtmlPaint(entity: Entity): boolean {
+ return (entity.get(Cache)?.fills ?? []).some(fill => fill.get(Paint)?.value === PaintType.HTML);
+}
+
+export function hasSurfacePaint(entity: Entity): boolean {
+ return (entity.get(Cache)?.fills ?? []).some(fill => fill.get(Paint)?.value === PaintType.SURFACE);
+}
diff --git a/packages/runtime/src/queries/timeline-index.ts b/packages/runtime/src/queries/timeline-index.ts
index 236f52bc..5bb0c54a 100644
--- a/packages/runtime/src/queries/timeline-index.ts
+++ b/packages/runtime/src/queries/timeline-index.ts
@@ -1 +1,149 @@
-// Derived timeline layer index (was api/timeline-index.ts).
+/* 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 { Not } from 'koota';
+
+import {
+ ChildOf, Deleted, Keyframe, KeyframeTrack, IsMask, Geometry, Group,
+ AdjustmentLayer, Expanded,
+} from '../traits';
+import { isSequence } from './predicates';
+import { sortByItemIndex } from '../utils/sort';
+
+import type { Entity, World } from 'koota';
+
+export type TimelineNodeKind = 'geometry' | 'sub-item' | 'keyframe-track';
+
+export type TimelineNode = {
+ entity: Entity;
+ kind: TimelineNodeKind;
+ expanded: boolean;
+ expandable: boolean;
+ children: TimelineNode[];
+};
+
+export type TimelineIndexValue = {
+ root: Entity | null;
+ layers: TimelineNode[];
+};
+
+export function buildTimelineLayers(world: World, parent: Entity): TimelineNode[] {
+ const sequence = isSequence(parent);
+
+ const tracks: Entity[] = [];
+ const geoms: Entity[] = [];
+ const masks: Entity[] = [];
+ const subitems: Entity[] = [];
+
+ for (const child of world.query(ChildOf(parent), Not(Deleted))) {
+ if (child.has(Keyframe)) continue;
+ if (sequence && !hasKeyframes(world, child)) continue;
+
+ if (child.has(KeyframeTrack)) {
+ tracks.push(child);
+ } else if (child.has(IsMask)) {
+ masks.push(child);
+ } else if (child.has(Geometry) || child.has(Group) || child.has(AdjustmentLayer)) {
+ geoms.push(child);
+ } else {
+ subitems.push(child);
+ }
+ }
+
+ tracks.sort(sortByItemIndex).reverse();
+ geoms.sort(sortByItemIndex).reverse();
+ masks.sort(sortByItemIndex).reverse();
+ subitems.sort(sortByItemIndex).reverse();
+
+ const nodes: TimelineNode[] = [];
+
+ for (const track of tracks) {
+ nodes.push({
+ entity: track,
+ kind: 'keyframe-track',
+ expanded: false,
+ expandable: false,
+ children: [],
+ });
+ }
+
+ for (const subitem of subitems) {
+ const node = buildNode(world, subitem, 'sub-item');
+ if (node.expandable) {
+ nodes.push(node);
+ }
+ }
+
+ for (const geom of geoms) {
+ nodes.push(buildNode(world, geom, 'geometry'));
+ }
+
+ for (const mask of masks) {
+ nodes.push(buildNode(world, mask, 'geometry'));
+ }
+
+ return nodes;
+}
+
+/**
+ * Build one row node. Expanded nodes get their subtree; collapsed ones stay
+ * empty and only probe whether a subtree exists.
+ */
+function buildNode(world: World, entity: Entity, kind: TimelineNodeKind): TimelineNode {
+ if (!entity.has(Expanded)) {
+ return {
+ entity,
+ kind,
+ expanded: false,
+ expandable: isExpandable(world, entity),
+ children: [],
+ };
+ }
+
+ const children = buildTimelineLayers(world, entity);
+ return {
+ entity,
+ kind,
+ expanded: true,
+ expandable: children.length > 0,
+ children,
+ };
+}
+
+/**
+ * Early-exit probe: check if a layer could be expanded.
+ */
+function isExpandable(world: World, parent: Entity): boolean {
+ const sequence = isSequence(parent);
+
+ for (const child of world.query(ChildOf(parent), Not(Deleted))) {
+ if (child.has(Keyframe)) continue;
+ if (sequence && !hasKeyframes(world, child)) continue;
+ if (
+ child.has(IsMask) ||
+ child.has(Geometry) ||
+ child.has(Group) ||
+ child.has(AdjustmentLayer) ||
+ child.has(KeyframeTrack) ||
+ isExpandable(world, child)
+ ) {
+ return true;
+ }
+ }
+
+ return false;
+}
+
+/**
+ * Deep probe: does the subtree contain a live KeyframeTrack? Tracks are
+ * deleted with their last keyframe, so track presence implies keyframes.
+ */
+function hasKeyframes(world: World, entity: Entity): boolean {
+ for (const child of world.query(ChildOf(entity), Not(Deleted))) {
+ if (child.has(KeyframeTrack)) return true;
+ if (hasKeyframes(world, child)) return true;
+ }
+
+ return false;
+}
diff --git a/packages/runtime/src/utils/index.ts b/packages/runtime/src/utils/index.ts
index 9be421e1..47779cc2 100644
--- a/packages/runtime/src/utils/index.ts
+++ b/packages/runtime/src/utils/index.ts
@@ -1,3 +1,4 @@
// Pure helpers only: time, sort, transition, captions follow. DOM-touching utils (cursor, interaction) stay in apps/web.
export * from './text';
export * from './live-mounts';
+export * from './sort';
diff --git a/packages/runtime/src/utils/sort.ts b/packages/runtime/src/utils/sort.ts
new file mode 100644
index 00000000..7f885697
--- /dev/null
+++ b/packages/runtime/src/utils/sort.ts
@@ -0,0 +1,26 @@
+/* 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 { ItemIndex, Computed, Keyframe } from '../traits';
+
+import type { Entity } from 'koota';
+
+// Plain comparators (the bitecs versions were world-bound factories; koota
+// entities carry their world, so these pass to sort() directly).
+
+export function sortByItemIndex(a: Entity, b: Entity): number {
+ return (a.get(ItemIndex)?.value ?? 0) - (b.get(ItemIndex)?.value ?? 0);
+}
+
+export function sortByStartTime(a: Entity, b: Entity): number {
+ return (a.get(Computed)?.start ?? 0) - (b.get(Computed)?.start ?? 0);
+}
+
+export function sortByOffset(a: Entity, b: Entity): number {
+ return (a.get(Computed)?.stopOffset ?? 0) - (b.get(Computed)?.stopOffset ?? 0);
+}
+
+export function sortByFrame(a: Entity, b: Entity): number {
+ return (a.get(Keyframe)?.time ?? 0) - (b.get(Keyframe)?.time ?? 0);
+}