Skip to content

The VS Code of video editing, built for agents.

TypeScript

Update runtime package with new asset management features and dependencies

konstantin-paulus0ea1ee28cd7d
diff --git a/package-lock.json b/package-lock.json
index e3aac64d..dfa6a387 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -7,6 +7,7 @@
"": {
"name": "@diffusionstudio/editor",
"version": "0.132.0",
+ "hasInstallScript": true,
"license": "MPL-2.0",
"workspaces": [
"apps/*",
@@ -12331,7 +12332,8 @@
"dependencies": {
"animejs": "^4.4.1",
"koota": "^0.6.6",
- "mediabunny": "^1.32.2"
+ "mediabunny": "^1.32.2",
+ "sqids": "^0.3.0"
},
"devDependencies": {
"typescript": "~5.9.3"
diff --git a/packages/runtime/MIGRATION.md b/packages/runtime/MIGRATION.md
new file mode 100644
index 00000000..4b3092de
--- /dev/null
+++ b/packages/runtime/MIGRATION.md
@@ -0,0 +1,89 @@
+# bitecs → koota migration status
+
+Working doc for migrating the editor engine from bitecs (in `apps/web/src/components/engine/`) into this headless runtime package. Written so a fresh session can continue without prior context.
+
+## Goal and ground rules
+
+- `@diffusionstudio/runtime` holds everything that must run without a DOM and without solid-js (so the CLI/node capture path can consume it). Browser-only systems (input, keyboard, camera controller, HUD, dom sync, timeline canvas UI), persistence (`db/`, Dexie), history, and Solid reactivity stay in `apps/web`. Solid bindings live in `packages/koota-solid`.
+- The persisted document format (`EntityRecord`, was `DBEntity`) is frozen: field names and value shapes must keep loading existing projects. Enums stay numbers, tags stay `{}`, `Hidden`/`ClipsContent` stay `true`, `Playback` persists only `loop` as 0/1, `KeyframeTrack` persists only `property`.
+- Breaking API/type changes inside the codebase are fine (established convention); the storage format is not.
+- Comments: lean, only constraints code can't show. No em dashes in prose. Tabs, MPL header on ported files.
+
+## Done
+
+| Slice | Where | Notes |
+|---|---|---|
+| Traits (all ~85 components) | `src/traits/*` | Split by concern: node, transform, style, text, timing, audio, motion, derived, media, interaction, relations, world |
+| Constants/enums | `src/constants.ts` | `ScaleMode` enum renamed `ScaleModeType` (collides with the ScaleMode trait; matches Geometry/GeometryType pattern) |
+| World singletons | `src/traits/world.ts` | The bitecs `createWorld({...})` context bag became world traits: Project, Mode, ActiveScene, Camera, Background, Time (was timestamp), FrameRate, RenderSurface (canvas+ctx+resolution), AudioEngine (injected, no ctor arg), Fonts, Mounts, FramePromises (was world.promises), DocumentRoot |
+| `createRuntimeWorld(projectId)` | `src/world/create-world.ts` | Side-effect free except spawning the document root. No AudioContext/window access |
+| Document root model | everywhere | See below, this replaced "parentless = top-level" |
+| Serialization | `src/world/serialize.ts` | serializeEntity / deserializeEntity / cloneFromRecords / stripMountIdentity / cloneSubtree. No events layer; plain add+set. `defined()` strips undefined so partial records merge over trait defaults |
+| Store access helper | `src/world/store.ts` | `store(world, trait)`: memoized lazy registration + `getStore`. koota registers stores on first add/query; bare `getStore` throws on a fresh world. Use this in all systems |
+| Read queries | `src/queries/{predicates,hierarchy,timeline-index}.ts` | Predicates lost the world param (`isScene(entity)`). `getNextName` scans `world.query(Name)` incl. Deleted tombstones. `TimelineNode.eid` became `entity: Entity` |
+| Transform system | `src/systems/transform.ts` | Store-indexed hot path (`store()` + `entity.id()`), no snapshots, no change events. Roots = `ChildOf(getDocument(world))`. Headless world without canvas skips culling instead of crashing |
+| Motion system | `src/systems/motion.ts` | resetAnimatedValues + getPropertyPaths (property table) + sampleTrack + applyAnimation. animejs dep. See semantic notes |
+| Moved verbatim | `src/math/*`, `src/utils/{text-motion,live-mounts}.ts`, `src/fonts/types.ts` | All dependency-free |
+| Time utils | `src/utils/time.ts` | snap/frames helpers, `computeTrimStart/End` (entity-based), `findGeometryAsset`, `findAssetDuration` (Assets + FrameRate world traits). `src/utils/assert.ts` added (was `@/utils`) |
+| Asset/folder model | `src/assets/types.ts`, world traits `Assets`/`Folders`/`AssetIds` | Structural types (no zod); `AssetFileHandle = { getFile() }` so node/Electron handles satisfy it. sqids dep for id allocation |
+| Actions: entities, hierarchy | `src/actions/{entities,hierarchy}.ts` | See semantic notes. `createEntity` spawns Computed (with non-default width/height/end/duration/strokeWidth) + Cache + ChildOf(document) |
+| Actions: cache + timing upkeep | `src/actions/{cache,timing}.ts` | Split of `api/utils.ts`: rebuildCaches/aggregateKeyframeTracks/findClosestParentGeometry; recomputeEntityTimeRange, propagate/bubble, trim clamp/pin, reactTo* hooks |
+| Actions: resize, keyframe, overlap | `src/actions/{resize,keyframe,overlap}.ts` | Constraint seeding = ConstraintCache trait presence (was undefined store slots). Overlap uses cloneSubtree + computeTrimStart/End |
+| Actions: group, frame, clipboard | `src/actions/{group,frame,clipboard}.ts` | frame.ts also hosts `switchActiveScene` (was api/base.ts): sets the ActiveScene world trait, nothing else |
+| Actions: assets, folders (model) | `src/actions/{assets,folders}.ts` | allocateId/raiseIdCounter, appendAssets/upsertAsset/removeAssets, getAssetFile/Blob, insertAssetInTimeline; folder tree ops return changed records for app persistence |
+| Seeds (types only, rest follows) | `src/utils/text.ts` (Token/Line/TokenOptions), `src/capture/format.ts` (ContainerFormat) | The remaining engine files merge into these on their slice |
+
+Verification style used so far: `npx tsc --noEmit` in the package, plus throwaway `smoke-test.tmp.ts` in the package root run with `npm exec --yes tsx@latest -- smoke-test.tmp.ts`, deleted afterwards (no test infra in the package yet). koota caps live worlds at 16; call `world.destroy()` in test loops.
+
+## Document root model
+
+Every world spawns one entity tagged `DocumentRoot` (`createRuntimeWorld`). All rendered entities are its descendants; "top-level" means "direct child of the document", never "has no parent".
+
+- `getDocument(world)` returns it; `getParentNode(entity)` returns the parent or null when the parent is the document (use wherever top-level matters); `getParentEntity` returns the raw parent including the document.
+- Serialization contract: the document id is per-session, so `serializeEntity` omits `ChildOf` when the parent is the root, and `cloneFromRecords` attaches parentless records to the target world's document. Record shape on disk is unchanged.
+- `cloneSubtree` still keeps an outside-the-subtree parent (records with `ChildOf` are not rehomed).
+- `ChildOf = relation({ exclusive: true, autoDestroy: 'orphan' })`, so `getDocument(world).destroy()` tears down the whole document; clearing a project = destroy + respawn root.
+- Actions honor this: `createEntity` spawns as a document child; `appendChild` asserts `getParentNode(entity) === null` ("already has a parent" = has a non-document parent) and relies on exclusive re-targeting; `removeChild` re-parents to the document instead of dropping ChildOf. `cloneFromRecords` attaches parentless records to the document, so paste/duplicate roots land there too.
+
+## Deliberate semantic changes vs bitecs
+
+- Single-value components became `{ value }` traits (Rotation, Name, Volume, Geometry, Paint, ...). `Playback.playing/loop` and `AudioPlayback.wasPlaying` are booleans on the trait, mapped to/from 0/1 at the serialize boundary.
+- `Caption.colors` and `Shader.uniforms` are copied on restore (fixed latent aliasing between clones from shared records).
+- Restoring `Size` no longer calls `resizeEntity`; it is a plain set (resize side effects belong to actions).
+- Motion has no iteration ordering (bitecs used `Hierarchy(ChildOf)`, but the loop only writes the entity's own Computed and its sub-entity cluster, so order cannot matter). Also no top-level exclusion: anything carrying animation data animates. Under bitecs, keyframed scenes promoted to top level silently froze; now they play. If freezing is wanted, strip tracks in the promotion action.
+- Deleted is a runtime-only tombstone tag (undo support), never serialized.
+- Actions are plain world-first functions (matching queries/systems), not koota `createActions`: they return entities/records and call each other freely, which the bound-record pattern only obscures. No history layer: bitecs `world.history.push/transaction` wrappers are gone; actions write directly and the app groups undo steps by observing koota events. Selection-scoped actions (group, frame, reorderSelection, clipboard) still key off the runtime-defined `Selected` trait.
+- appendChild/removeChild dropped their bitecs side calls: `persistEntity`, `syncInteractiveState`, `rebuildTimelineIndex` (app-side via observers/signals) and `disconnectAudioBus` (media slice; decoder/bus disposal hooks return with it). `unpersistEntity` and the dispose* helpers from `api/utils.ts` were likewise not ported yet.
+- `clampTrimToAssetDuration` now goes through `entity.set(Trim)` (fires change events) but only when actually clamping; bitecs wrote the store silently. `reactToChildDetached` is exported for the observers slice to hook Deleted onAdd.
+- `switchActiveScene` only sets the ActiveScene world trait; timeline buffer clearing and index rebuild stay app-side. `frameSelection` calls it once (bitecs called it redundantly inside and outside the transaction).
+- `insertAssetInTimeline` returns the created entity or null when no scene is active (no toast). Folder ops are sync and return the changed records (`deleteFolder` returns removed folder/asset ids) so the app can persist; `moveAssetsToFolder` updates records in place instead of re-fronting them like `saveAsset` did. Panel navigation state (current folder) stays app-side.
+- Decoder/host handle traits (`src/traits/media.ts`) are AoS traits typed as opaque `object` until the decoders move in; `entity.get(VideoDecoder)` returns the instance directly.
+
+## koota facts learned (0.6.6)
+
+- **Local patch (do not lose):** `patches/koota+0.6.6.patch`, applied by the root `postinstall` (`patch-package`). Fixes `checkQuery`/`checkQueryTracking`: `Or(...)` was evaluated per trait bitmask generation (32 traits each) and required a match in every generation, so Or queries created after the Or'd traits straddle a generation boundary silently returned empty. On a koota bump, retest (register 40 dummy traits, then create a fresh Or query) before dropping the patch.
+- `Not(...)` accepts plain traits only. Relation pairs, wildcard or concrete (`Not(ChildOf('*'))`, `Not(ChildOf(doc))`), throw at runtime. If an indexed exclusion is ever needed, maintain a tag via `onAdd/onRemove(ChildOf(target))` observers.
+- No hierarchy-ordered queries (bitecs `Hierarchy(ChildOf)` has no equivalent). Transform does its own parent-first DFS from the document; that ordering is load-bearing there (world matrices, cull inheritance).
+- Trait schemas allow primitives/null/undefined; object or array fields need callback initializers (`colors: () => [] as number[]`). AoS traits: `trait(() => instance)`.
+- World traits are backed by a hidden internal world entity (`world[$internal].worldEntity`, IsExcluded). Do not build on it; it is not public API. `world.id()` is a world slot index, not an entity.
+- Max 16 live worlds. Entity numbers encode worldId+generation; stores are indexed by `entity.id()`.
+- Entities read back from store arrays / trait fields keep their methods (they are numbers; koota patches the prototype).
+- `entity.set(trait, data)` throws if the trait is missing; `entity.add` is idempotent and never resets existing values; `set` with a partial object merges over current values. Hence the add-then-set pattern everywhere in serialize and actions. On an exclusive relation, `add(ChildOf(newParent))` re-targets in place.
+
+## Remaining work (suggested order)
+
+1. **Observers / cache upkeep**: the bitecs `api/observers.ts` logic that fills `Cache` (children, fills, shadows, strokes, effects, textRanges, masks, keyframeTracks, keyframes, animations) from ChildOf + tags. Decide: koota `onAdd/onRemove(ChildOf('*'))` subscriptions (runtime-owned) vs recompute passes. Systems and timeline-index already consume `Cache`; actions rebuild it imperatively via `actions/cache.ts` (as bitecs did), and `reactToChildDetached` awaits its Deleted onAdd hook. Also decide where Deleted-tombstone pruning and `unpersistEntity` land.
+2. **Media** (`src/media/`): move `engine/decoders/*` wholesale (video, audio, image, sequence, caption/, html, shader, surface, frame-cache, keyframe-index, time-stretcher, audio-peaks) plus `services/audio-bus.ts`. Then tighten the handle trait types in `src/traits/media.ts` to the concrete classes and delete the `Handle = object` placeholder. Reinstate the dispose hooks the actions slice dropped: `disconnectAudioBus` in appendChild/removeChild, decoder disposal in `reactToAssetChange`'s Caption branch, and the dispose* subtree walkers from `api/utils.ts`.
+3. **Playback system**: `systems/playback.ts` (computes `Computed.localTime/start/end/duration/visibility`, drives decoders, pushes into `FramePromises`, uses AudioEngine + Mounts). Depends on media.
+4. **Capture** (`src/capture/`): `engine/encode/*` (encoder, image-encoder, buffer, format, utils). Uses Mode, FramePromises, RenderSurface.
+5. **Render system**: `systems/render.ts` is runtime-capable (OffscreenCanvas) and needed for headless capture; it consumes text layout (`utils/text.ts` full port: layout/measure/render join the Token seed).
+6. **Fonts**: `engine/font/{utils,fixtures}.ts` (check DOM usage: document.fonts needs an injection seam or stays app-side).
+7. **Remaining utils**: captions, transition, contact-sheet, audio-sync, transcode (audit each for DOM/app deps; DOM-touching ones stay app-side).
+8. **App rewrite** (`apps/web`): engine shell wires canvas/AudioContext/DPR into world traits, app-side world traits (input, HUD, selection tool, history, store, timelineIndex signal), history/persistence via koota events (including wrapping the folder/asset model ops with Dexie writes and re-implementing `syncInteractiveState` over `ChildOf(document)` queries: `Not(ChildOf('*'))` throws in koota), UI to `packages/koota-solid` hooks, timeline UI consumes new `TimelineNode.entity`. Delete `engine/components`, `engine/api` progressively.
+9. **CLI**: point node capture at the runtime package.
+
+## Layout reminders
+
+- Package exports: root `.` plus `./traits`, `./systems`, `./media`, `./capture` (see package.json). Everything currently also re-exported from root `src/index.ts`.
+- tsconfig sets `erasableSyntaxOnly: false` (enums with reverse lookups, same as apps/web).
+- Deps: koota (patched), mediabunny, animejs, sqids (asset/folder id allocation).
diff --git a/packages/runtime/README.md b/packages/runtime/README.md
index 29d61374..413e6ff5 100644
--- a/packages/runtime/README.md
+++ b/packages/runtime/README.md
@@ -3,3 +3,5 @@
Headless editor runtime built on [koota](https://github.com/pmndrs/koota): traits, world creation and serialization, actions, deterministic systems, media decoding, and capture.
Must work without a DOM and without solid-js so the CLI and node capture can consume it directly. Browser-only concerns (input, keyboard, HUD, timeline canvas UI, persistence) live in `apps/web`; Solid reactivity bindings live in `@diffusionstudio/koota-solid`.
+
+The bitecs to koota migration is in progress; see [MIGRATION.md](./MIGRATION.md) for status, design decisions, koota gotchas (including the local koota patch), and the remaining work.
diff --git a/packages/runtime/package.json b/packages/runtime/package.json
index 446a096a..5149ac08 100644
--- a/packages/runtime/package.json
+++ b/packages/runtime/package.json
@@ -23,7 +23,8 @@
"dependencies": {
"animejs": "^4.4.1",
"koota": "^0.6.6",
- "mediabunny": "^1.32.2"
+ "mediabunny": "^1.32.2",
+ "sqids": "^0.3.0"
},
"devDependencies": {
"typescript": "~5.9.3"
diff --git a/packages/runtime/src/actions/assets.ts b/packages/runtime/src/actions/assets.ts
index 4edd3d83..854a0854 100644
--- a/packages/runtime/src/actions/assets.ts
+++ b/packages/runtime/src/actions/assets.ts
@@ -1 +1,199 @@
-// Asset actions (was api/assets.ts, minus persistence: storage stays app-side).
+/* 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/. */
+
+// Asset model actions (was api/assets.ts, model only). Loading, probing,
+// OPFS/db persistence, uploads, and pickers stay app-side; the runtime owns
+// the in-memory metadata store, id allocation, and timeline insertion.
+
+import Sqids from 'sqids';
+
+import { GeometryType, PaintType } from '../constants';
+import {
+ Geometry, Paint, Audio, Caption, Hidden, Name, AssetId, Delay, Trim,
+ KeepAspectRatio, Computed, Assets, AssetIds, ActiveScene,
+} from '../traits';
+import { store } from '../world/store';
+import { secondsToFrames } from '../utils/time';
+import { createEntity } from './entities';
+import { appendChild } from './hierarchy';
+import { resizeEntity } from './resize';
+
+import type { Entity, World } from 'koota';
+import type { Asset, Transcript } from '../assets/types';
+
+const sqids = new Sqids({ minLength: 4 });
+
+/**
+ * Allocates the next id in the project's shared asset/folder id space, so an
+ * id never refers to both an asset and a folder.
+ */
+export function allocateId(world: World): string {
+ const counter = (world.get(AssetIds)?.counter ?? 0) + 1;
+ world.set(AssetIds, { counter });
+ return sqids.encode([counter]);
+}
+
+/**
+ * Raises the id counter past every sqid in `ids`. Non-sqid ids (e.g. legacy
+ * "fld-…" folder ids) are ignored. Restores may run in parallel, so this only
+ * ever raises the counter.
+ */
+export function raiseIdCounter(world: World, ids: Iterable<string>): void {
+ let counter = world.get(AssetIds)?.counter ?? 0;
+ for (const id of ids) {
+ const decoded = sqids.decode(id);
+ const num = decoded[0];
+ if (decoded.length === 1 && Number.isFinite(num) && num! > counter) {
+ counter = num!;
+ }
+ }
+ world.set(AssetIds, { counter });
+}
+
+/**
+ * Appends one or more assets to the in-memory store. New assets are ordered
+ * first; existing records win on id conflict.
+ */
+export function appendAssets(world: World, ...incoming: Asset[]): void {
+ const map = world.get(Assets)!;
+ const existing = Array.from(map.values());
+ map.clear();
+ for (const asset of incoming) map.set(asset.id, asset);
+ for (const asset of existing) map.set(asset.id, asset);
+}
+
+/**
+ * Inserts or replaces an asset at the front of the in-memory store (newest
+ * first). The app persists it and refreshes its reactive views.
+ */
+export function upsertAsset(world: World, asset: Asset): Asset {
+ const map = world.get(Assets)!;
+ const existing = Array.from(map.values()).filter(a => a.id !== asset.id);
+ map.clear();
+ map.set(asset.id, asset);
+ existing.forEach(a => map.set(a.id, a));
+ return asset;
+}
+
+/** Removes one or more assets from the in-memory store. */
+export function removeAssets(world: World, ...ids: string[]): void {
+ const map = world.get(Assets)!;
+ for (const id of ids) map.delete(id);
+}
+
+const assetFileCache = new WeakMap<Asset['handle'], Promise<File>>();
+
+/**
+ * Returns the File backing an asset, reusing an in-flight or already-resolved
+ * read for the same handle.
+ */
+export function getAssetFile(asset: Pick<Asset, 'handle'>): Promise<File> {
+ const { handle } = asset;
+ const cached = assetFileCache.get(handle);
+ if (cached) return cached;
+
+ const promise = handle.getFile();
+ assetFileCache.set(handle, promise);
+ promise.catch(() => {
+ if (assetFileCache.get(handle) === promise) {
+ assetFileCache.delete(handle);
+ }
+ });
+ return promise;
+}
+
+/** Returns the File/Blob backing an asset, or null if the asset is missing. */
+export async function getAssetBlob(world: World, id: string): Promise<Blob | null> {
+ const asset = world.get(Assets)?.get(id);
+ if (!asset) return null;
+
+ return await getAssetFile(asset);
+}
+
+/**
+ * Composes the entity tree for an asset dropped into the active scene: a
+ * geometry sized to the asset with the matching paint/caption/audio setup.
+ * Returns the created node, or null when there is no active scene.
+ */
+export async function insertAssetInTimeline(
+ world: World,
+ asset: Asset,
+ mode: 'playhead' | 'start',
+): Promise<Entity | null> {
+ const scene = world.get(ActiveScene)?.entity ?? null;
+ if (scene === null) return null;
+
+ const delay = mode === 'playhead' ? store(world, Computed).localTime[scene.id()] ?? 0 : 0;
+
+ // Resolve any async asset data up front so all the entity mutations below
+ // run synchronously (the app wraps them in a single undo step).
+ let transcriptTrim: { start: number; end: number } | null = null;
+ if (asset.type === 'TRANSCRIPT') {
+ // Transcript should be trimmed to the span of recognized words
+ const file = await getAssetFile(asset);
+ const transcript = JSON.parse(await file.text()) as Transcript;
+ const lastWord = transcript.at(-1)?.words.at(-1);
+ const firstWord = transcript.at(0)?.words.at(0);
+ transcriptTrim = {
+ start: secondsToFrames(firstWord?.start),
+ end: secondsToFrames(lastWord?.end),
+ };
+ }
+
+ const entity = createEntity(world);
+ entity.add(Name);
+ entity.set(Name, { value: asset.name });
+ entity.add(Delay);
+ entity.set(Delay, { value: delay });
+
+ if (asset.type === 'IMAGE' || asset.type === 'VIDEO' || asset.type === 'SEQUENCE') {
+ const width = Math.round(asset.width);
+ const height = Math.round(asset.height);
+ resizeEntity(world, entity, { width, height });
+ entity.add(KeepAspectRatio);
+ entity.set(KeepAspectRatio, { width, height });
+ }
+
+ if (asset.type === 'TRANSCRIPT') {
+ entity.add(Geometry);
+ entity.set(Geometry, { value: GeometryType.TEXT });
+ entity.add(Caption);
+ if (transcriptTrim) {
+ entity.add(Trim);
+ entity.set(Trim, transcriptTrim);
+ }
+ } else {
+ entity.add(Geometry);
+ entity.set(Geometry, { value: GeometryType.RECT });
+
+ // Other assets need a paint sub-entity
+ let paint = PaintType.IMAGE;
+ if (asset.type === 'SEQUENCE') paint = PaintType.SEQUENCE;
+ if (asset.type === 'VIDEO') paint = PaintType.VIDEO;
+ if (asset.type === 'AUDIO') paint = PaintType.WAVEFORM;
+ const fill = createEntity(world);
+ fill.add(Paint);
+ fill.set(Paint, { value: paint });
+ fill.add(AssetId);
+ fill.set(AssetId, { value: asset.id });
+ if (asset.type === 'AUDIO') {
+ fill.add(Hidden);
+ }
+ appendChild(world, fill, entity);
+ }
+
+ if (asset.type === 'AUDIO') {
+ entity.add(Audio);
+ resizeEntity(world, entity, { width: 500, height: 150 });
+ }
+
+ if (asset.type === 'AUDIO' || asset.type === 'TRANSCRIPT') {
+ entity.add(AssetId);
+ entity.set(AssetId, { value: asset.id });
+ }
+
+ appendChild(world, entity, scene);
+
+ return entity;
+}
diff --git a/packages/runtime/src/actions/cache.ts b/packages/runtime/src/actions/cache.ts
new file mode 100644
index 00000000..4fdcaba2
--- /dev/null
+++ b/packages/runtime/src/actions/cache.ts
@@ -0,0 +1,129 @@
+/* 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/. */
+
+// Cache upkeep after structural changes (was part of api/utils.ts). Cache and
+// KeyframeTrack.target are derived state, so they are written through stores
+// without change events; the app observes the authoring writes instead.
+
+import { Not, Or } from 'koota';
+
+import { store } from '../world/store';
+import {
+ ChildOf, Deleted, Cache,
+ Geometry, Group, AdjustmentLayer, IsMask, Paint, Stroke, Shadow, Effect,
+ TextRange, KeyframeTrack, Keyframe, Animation,
+} from '../traits';
+import { isDocument } from '../queries/predicates';
+import { getParentNode } from '../queries/hierarchy';
+import { sortByFrame, sortByItemIndex } from '../utils/sort';
+import { resetAnimatedValues } from '../systems/motion';
+
+import type { Entity, World } from 'koota';
+
+/**
+ * Refresh the parent's Cache lists that the attached/detached entity
+ * participates in. Call after a ChildOf change with the affected parent.
+ */
+export function rebuildCaches(world: World, entity: Entity, parent: Entity | null) {
+ if (parent === null || isDocument(parent)) return;
+ if (!parent.has(Cache)) parent.add(Cache);
+
+ const cache = store(world, Cache);
+ const pid = parent.id();
+
+ if (entity.has(Geometry) || entity.has(Group) || entity.has(AdjustmentLayer)) {
+ cache.children[pid] = [...world.query(
+ Or(Geometry, Group, AdjustmentLayer), ChildOf(parent), Not(IsMask), Not(Deleted),
+ )].sort(sortByItemIndex);
+ }
+
+ if (entity.has(IsMask)) {
+ cache.masks[pid] = [...world.query(Geometry, IsMask, ChildOf(parent), Not(Deleted))]
+ .sort(sortByItemIndex);
+ }
+
+ if (entity.has(KeyframeTrack)) {
+ const node = findClosestParentGeometry(parent);
+ aggregateKeyframeTracks(world, node);
+ resetAnimatedValues(world, node);
+ }
+
+ if (entity.has(Keyframe)) {
+ cache.keyframes[pid] = [...world.query(Keyframe, ChildOf(parent), Not(Deleted))]
+ .sort(sortByFrame);
+ }
+
+ if (entity.has(Animation)) {
+ cache.animations[pid] = [...world.query(Animation, ChildOf(parent), Not(Deleted))]
+ .sort(sortByItemIndex);
+ resetAnimatedValues(world, parent);
+ }
+
+ if (entity.has(Paint)) {
+ cache.fills[pid] = [...world.query(Paint, ChildOf(parent), Not(Deleted))]
+ .sort(sortByItemIndex);
+ }
+
+ if (entity.has(Stroke)) {
+ cache.strokes[pid] = [...world.query(Stroke, ChildOf(parent), Not(Deleted))]
+ .sort(sortByItemIndex);
+ }
+
+ if (entity.has(Effect)) {
+ cache.effects[pid] = [...world.query(Effect, ChildOf(parent), Not(Shadow), Not(Deleted))]
+ .sort(sortByItemIndex);
+ }
+
+ if (entity.has(Shadow)) {
+ cache.shadows[pid] = [...world.query(Shadow, ChildOf(parent), Not(Effect), Not(Deleted))]
+ .sort(sortByItemIndex);
+ }
+
+ if (entity.has(TextRange)) {
+ cache.textRanges[pid] = [...world.query(TextRange, ChildOf(parent), Not(Deleted))]
+ .sort(sortByItemIndex);
+ }
+}
+
+/** Nearest self-or-ancestor node entity (geometry, group, adjustment layer). */
+export function findClosestParentGeometry(entity: Entity): Entity | null {
+ let current: Entity | null = entity;
+ while (current) {
+ if (current.has(Geometry) || current.has(Group) || current.has(AdjustmentLayer)) {
+ return current;
+ }
+ current = getParentNode(current);
+ }
+ return null;
+}
+
+/**
+ * Collect every KeyframeTrack under a node, stopping at nested nodes (each
+ * enclosing node owns its own cache entry). Refreshes the denormalised
+ * `target` field on each track so consumers iterating the cache can look up
+ * the animated entity without walking ChildOf.
+ */
+export function aggregateKeyframeTracks(world: World, node: Entity | null): void {
+ if (node === null) return;
+ if (!node.has(Cache)) node.add(Cache);
+
+ const keyframeTrack = store(world, KeyframeTrack);
+ const tracks: Entity[] = [];
+
+ const walk = (entity: Entity) => {
+ for (const child of world.query(ChildOf(entity), Not(Deleted))) {
+ if (child.has(KeyframeTrack)) {
+ keyframeTrack.target[child.id()] = getParentNode(child);
+ tracks.push(child);
+ continue;
+ }
+ // Stop at nested nodes; each owns its own cache entry.
+ if (child.has(Geometry) || child.has(Group) || child.has(AdjustmentLayer)) continue;
+ walk(child);
+ }
+ };
+
+ walk(node);
+ store(world, Cache).keyframeTracks[node.id()] = tracks;
+}
diff --git a/packages/runtime/src/actions/clipboard.ts b/packages/runtime/src/actions/clipboard.ts
index 22db48d2..f38c8a0a 100644
--- a/packages/runtime/src/actions/clipboard.ts
+++ b/packages/runtime/src/actions/clipboard.ts
@@ -1 +1,99 @@
-// Clipboard model: copy/paste of entity subtrees (was api/clipboard.ts, minus navigator.clipboard access).
+/* 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/. */
+
+// Clipboard model: copy/paste of entity subtrees as records (was
+// api/clipboard.ts). Module-level, in-memory; navigator.clipboard bridging
+// stays app-side.
+
+import { Or } from 'koota';
+
+import { Geometry, Group, Scene, Selected, Position, Computed } from '../traits';
+import { store } from '../world/store';
+import { getEntityTree, getParentNode } from '../queries/hierarchy';
+import {
+ cloneFromRecords, cloneSubtree, serializeEntity, stripMountIdentity,
+} from '../world/serialize';
+import { removeChild, appendChild } from './hierarchy';
+
+import type { Entity, World } from 'koota';
+import type { EntityRecord } from '../world/serialize';
+
+type ClipboardEntry = {
+ root: number;
+ records: EntityRecord[];
+};
+
+let clipboard: ClipboardEntry[] = [];
+
+export function copySelection(world: World) {
+ const selection = [...world.query(Selected, Or(Geometry, Group))];
+ if (selection.length === 0) return;
+
+ clipboard = selection.map(entity => ({
+ root: entity,
+ records: getEntityTree(world, entity).map(e => serializeEntity(e)),
+ }));
+}
+
+export function pasteClipboard(world: World) {
+ if (clipboard.length === 0) return;
+
+ const selection = [...world.query(Selected, Or(Scene, Group))];
+ const targetParent = selection[0] ?? null;
+
+ const copyRoots: Entity[] = [];
+
+ for (const snapshot of clipboard) {
+ const result = cloneFromRecords(world, stripMountIdentity(snapshot.records));
+ const rootCopy = result.get(snapshot.root);
+ if (!rootCopy || (!rootCopy.has(Geometry) && !rootCopy.has(Group))) continue;
+
+ copyRoots.push(rootCopy);
+
+ const currentParent = getParentNode(rootCopy);
+
+ if (currentParent !== null) {
+ removeChild(world, rootCopy, currentParent);
+ }
+ if (targetParent !== null) {
+ appendChild(world, rootCopy, targetParent);
+ }
+ }
+
+ for (const entity of world.query(Selected)) entity.remove(Selected);
+ copyRoots.forEach(entity => entity.add(Selected));
+}
+
+export function duplicateSelection(world: World, { offset = true }: { offset?: boolean } = {}) {
+ const selection = [...world.query(Selected, Or(Geometry, Group))];
+ if (selection.length === 0) return;
+
+ const snapshots = selection.map(entity => ({
+ root: entity,
+ tree: getEntityTree(world, entity),
+ }));
+
+ const computed = store(world, Computed);
+ const copyRoots: Entity[] = [];
+
+ for (const snapshot of snapshots) {
+ const result = cloneSubtree(world, snapshot.tree);
+ const rootCopy = result.get(snapshot.root);
+ if (!rootCopy || (!rootCopy.has(Geometry) && !rootCopy.has(Group))) continue;
+
+ copyRoots.push(rootCopy);
+
+ const currentParent = getParentNode(rootCopy);
+ if (offset && currentParent === null) {
+ // Source's Computed is populated; the copy's isn't refreshed until the
+ // next caching pass.
+ const nextX = (rootCopy.get(Position)?.x ?? 0) + computed.width[snapshot.root.id()]!;
+ rootCopy.add(Position);
+ rootCopy.set(Position, { x: nextX });
+ }
+ }
+
+ for (const entity of world.query(Selected)) entity.remove(Selected);
+ copyRoots.forEach(entity => entity.add(Selected));
+}
diff --git a/packages/runtime/src/actions/entities.ts b/packages/runtime/src/actions/entities.ts
index 06a9d192..fd7357e4 100644
--- a/packages/runtime/src/actions/entities.ts
+++ b/packages/runtime/src/actions/entities.ts
@@ -1 +1,44 @@
-// Entity lifecycle actions: create, duplicate, delete (was api/entities.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/. */
+
+// Entity lifecycle actions (was api/entities.ts). No history layer here: the
+// app records undo entries by observing koota add/remove/change events.
+
+import { DEFAULT_DURATION_FRAMES } from '../constants';
+import { ChildOf, Computed, Cache, Deleted } from '../traits';
+import { getDocument, getEntityTree } from '../queries/hierarchy';
+
+import type { Entity, World } from 'koota';
+
+/**
+ * Spawn an empty document entity. Computed/Cache are pre-attached (systems
+ * index into their stores unconditionally), and the entity starts as a child
+ * of the document root, i.e. top-level, until appendChild re-parents it.
+ */
+export function createEntity(world: World): Entity {
+ return world.spawn(
+ // Overrides where the neutral trait default differs from the values a
+ // fresh unparented entity must render with.
+ Computed({
+ width: 300,
+ height: 300,
+ strokeWidth: 1,
+ end: DEFAULT_DURATION_FRAMES,
+ duration: DEFAULT_DURATION_FRAMES,
+ }),
+ Cache,
+ ChildOf(getDocument(world)),
+ );
+}
+
+/**
+ * Soft-delete an entity and its subtree: tag with Deleted so queries skip it
+ * but undo can resurrect it. Hard destruction happens when the app prunes
+ * tombstones (or the document root is destroyed).
+ */
+export function deleteEntity(world: World, entity: Entity) {
+ for (const e of getEntityTree(world, entity)) {
+ e.add(Deleted);
+ }
+}
diff --git a/packages/runtime/src/actions/folders.ts b/packages/runtime/src/actions/folders.ts
index 2bd6eb0b..7a51f751 100644
--- a/packages/runtime/src/actions/folders.ts
+++ b/packages/runtime/src/actions/folders.ts
@@ -1 +1,188 @@
-// Folder actions (was api/folders.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/. */
+
+// Folder model actions (was api/folders.ts, model only). Pure in-memory tree
+// operations over the Folders/Assets world traits; the app persists the
+// returned records and keeps its own panel navigation state.
+
+import { Assets, Folders } from '../traits';
+import { allocateId } from './assets';
+
+import type { World } from 'koota';
+import type { Asset, Folder } from '../assets/types';
+
+/**
+ * A folder's effective parent: its stored parentId, or root when the parent
+ * record no longer exists (dangling references degrade to root instead of
+ * hiding the folder).
+ */
+export function effectiveParentId(world: World, folder: Folder): string | null {
+ const folders = world.get(Folders)!;
+ return folder.parentId !== null && folders.has(folder.parentId)
+ ? folder.parentId
+ : null;
+}
+
+/**
+ * The folder an asset effectively lives in: its stored folderId, or root when
+ * that folder no longer exists.
+ */
+export function assetFolderId(world: World, asset: Asset): string | null {
+ const folderId = asset.folderId ?? null;
+ return folderId !== null && world.get(Folders)!.has(folderId) ? folderId : null;
+}
+
+/**
+ * True when `id` is a descendant of `ancestorId` in the folder tree.
+ */
+export function isDescendantFolder(world: World, id: string, ancestorId: string): boolean {
+ const folders = world.get(Folders)!;
+ const visited = new Set<string>();
+ let current = folders.get(id);
+ while (current && current.parentId !== null && !visited.has(current.id)) {
+ if (current.parentId === ancestorId) return true;
+ visited.add(current.id);
+ current = folders.get(current.parentId);
+ }
+ return false;
+}
+
+/**
+ * The next free `base`/`base N` name among a parent's children.
+ */
+export function uniqueFolderName(world: World, base: string, parentId: string | null): string {
+ const names = new Set(
+ Array.from(world.get(Folders)!.values())
+ .filter(folder => effectiveParentId(world, folder) === parentId)
+ .map(folder => folder.name),
+ );
+ let name = base;
+ for (let i = 2; names.has(name); i++) name = `${base} ${i}`;
+ return name;
+}
+
+/**
+ * The next free "New folder"/"New folder N" name among a parent's children.
+ */
+export function nextFolderName(world: World, parentId: string | null): string {
+ return uniqueFolderName(world, 'New folder', parentId);
+}
+
+/**
+ * Finds a direct child folder of `parentId` by name (case-insensitive),
+ * creating it when missing.
+ */
+export function ensureFolder(world: World, name: string, parentId: string | null = null): Folder {
+ const target = name.trim().toLowerCase();
+ for (const folder of world.get(Folders)!.values()) {
+ if (
+ effectiveParentId(world, folder) === parentId &&
+ folder.name.trim().toLowerCase() === target
+ ) {
+ return folder;
+ }
+ }
+ return createFolder(world, name, parentId);
+}
+
+/**
+ * Creates a folder under `parentId` (null = root).
+ */
+export function createFolder(world: World, name: string, parentId: string | null = null): Folder {
+ const folders = world.get(Folders)!;
+ const folder: Folder = {
+ id: allocateId(world),
+ name,
+ parentId: parentId !== null && folders.has(parentId) ? parentId : null,
+ createdAt: new Date().toISOString(),
+ };
+
+ folders.set(folder.id, folder);
+ return folder;
+}
+
+/**
+ * Renames a folder. Returns the updated record, or null when nothing changed.
+ */
+export function renameFolder(world: World, id: string, name: string): Folder | null {
+ const folders = world.get(Folders)!;
+ const folder = folders.get(id);
+ if (!folder || folder.name === name) return null;
+
+ const next = { ...folder, name };
+ folders.set(id, next);
+ return next;
+}
+
+/**
+ * Moves assets into a folder (null = root). Ignores unknown asset ids and
+ * unknown target folders. Returns the updated assets.
+ */
+export function moveAssetsToFolder(world: World, ids: string[], folderId: string | null): Asset[] {
+ if (folderId !== null && !world.get(Folders)!.has(folderId)) return [];
+
+ const assets = world.get(Assets)!;
+ const moved: Asset[] = [];
+ for (const id of ids) {
+ const asset = assets.get(id);
+ if (!asset || (asset.folderId ?? null) === folderId) continue;
+ const next = { ...asset, folderId };
+ assets.set(id, next);
+ moved.push(next);
+ }
+ return moved;
+}
+
+/**
+ * Re-parents a folder (null = root). Returns the updated record, or null when
+ * the move is invalid (unknown folder/target, or a cycle: dropping a folder
+ * into itself or one of its descendants).
+ */
+export function moveFolder(world: World, id: string, parentId: string | null): Folder | null {
+ const folders = world.get(Folders)!;
+ const folder = folders.get(id);
+ if (!folder) return null;
+ if (parentId === id) return null;
+ if (parentId !== null) {
+ if (!folders.has(parentId)) return null;
+ if (isDescendantFolder(world, parentId, id)) return null;
+ }
+ if (folder.parentId === parentId) return folder;
+
+ const next = { ...folder, parentId };
+ folders.set(id, next);
+ return next;
+}
+
+/**
+ * Deletes a folder subtree with its contents from the in-memory model.
+ * Returns the removed folder and asset ids so the app can persist the
+ * deletions (and navigate out of the doomed subtree first).
+ */
+export function deleteFolder(world: World, id: string): { folderIds: string[]; assetIds: string[] } {
+ const folders = world.get(Folders)!;
+ if (!folders.has(id)) return { folderIds: [], assetIds: [] };
+
+ const subtree = new Set([id]);
+ let grew = true;
+ while (grew) {
+ grew = false;
+ for (const candidate of folders.values()) {
+ if (candidate.parentId !== null && subtree.has(candidate.parentId) && !subtree.has(candidate.id)) {
+ subtree.add(candidate.id);
+ grew = true;
+ }
+ }
+ }
+
+ const assets = world.get(Assets)!;
+ const assetIds = Array.from(assets.values())
+ .filter(asset => asset.folderId != null && subtree.has(asset.folderId))
+ .map(asset => asset.id);
+
+ for (const assetId of assetIds) assets.delete(assetId);
+ for (const folderId of subtree) folders.delete(folderId);
+
+ return { folderIds: [...subtree], assetIds };
+}
diff --git a/packages/runtime/src/actions/frame.ts b/packages/runtime/src/actions/frame.ts
index 2fa1732c..e57bc372 100644
--- a/packages/runtime/src/actions/frame.ts
+++ b/packages/runtime/src/actions/frame.ts
@@ -1 +1,122 @@
-// Frame and scene actions (was api/frame.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/. */
+
+// Frame and scene actions (was api/frame.ts, plus switchActiveScene from
+// api/base.ts). The app reacts to ActiveScene changes (clearing timeline
+// buffers, rebuilding its index) through its own world-trait observer.
+
+import { Or } from 'koota';
+
+import { store } from '../world/store';
+import { GeometryType, PaintType } from '../constants';
+import {
+ Geometry, Group, Scene, ClipsContent, Playback, Paint, Color, Selected,
+ Position, Name, LocalTransform, Computed, ActiveScene,
+} from '../traits';
+import { isScene } from '../queries/predicates';
+import { getNextName, getParentNode } from '../queries/hierarchy';
+import { aabbFromTransformedRect } from '../math';
+import { computeLocalMatrix } from '../systems/transform';
+import { assert } from '../utils/assert';
+import { createEntity } from './entities';
+import { appendChild, removeChild } from './hierarchy';
+import { resizeEntity } from './resize';
+
+import type { Entity, World } from 'koota';
+
+/** Retarget the playhead/timeline scene (not undoable state). */
+export function switchActiveScene(world: World, entity: Entity | null): void {
+ if (entity !== null) {
+ assert(isScene(entity), 'Entity is not a scene');
+ }
+
+ if (world.get(ActiveScene)?.entity === entity) return;
+
+ world.set(ActiveScene, { entity });
+}
+
+/**
+ * Wrap the current node selection in a new SCENE (a clipped, playable frame).
+ * Mirrors `groupSelection`, but the wrapper is a Scene with its own fixed Size
+ * derived from the selection's bounding box, plus the clipping/playback/fill a
+ * scene needs. Already-existing scenes in the selection are skipped; scenes
+ * can't be nested. Children's positions are rewritten into the scene's local
+ * space so their on-canvas position is preserved. Returns the new scene's
+ * entity, or null if there was nothing to frame.
+ */
+export function frameSelection(world: World): Entity | null {
+ const selection = [...world.query(Selected, Or(Geometry, Group))]
+ .filter(entity => !isScene(entity));
+ if (selection.length === 0) return null;
+
+ const computed = store(world, Computed);
+
+ const targetParent = getParentNode(selection[0]!);
+ const frameables = selection.filter(entity => getParentNode(entity) === targetParent);
+
+ // Bounding box of children in target-parent local space.
+ let minX = Infinity;
+ let minY = Infinity;
+ let maxX = -Infinity;
+ let maxY = -Infinity;
+ for (const entity of frameables) {
+ const mat = entity.get(LocalTransform) ?? { a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 };
+ const w = computed.width[entity.id()]!;
+ const h = computed.height[entity.id()]!;
+ const bounds = aabbFromTransformedRect(mat, w, h);
+ if (bounds.minX < minX) minX = bounds.minX;
+ if (bounds.minY < minY) minY = bounds.minY;
+ if (bounds.maxX > maxX) maxX = bounds.maxX;
+ if (bounds.maxY > maxY) maxY = bounds.maxY;
+ }
+
+ const x = Math.round(minX);
+ const y = Math.round(minY);
+ const width = Math.max(1, Math.round(maxX - minX));
+ const height = Math.max(1, Math.round(maxY - minY));
+
+ // A scene is a RECT geometry carrying the Scene/ClipsContent/Playback
+ // tags plus a solid fill; the same recipe the scene draw tool uses.
+ const scene = createEntity(world);
+ scene.add(Geometry);
+ scene.set(Geometry, { value: GeometryType.RECT });
+ scene.add(Scene);
+ scene.add(ClipsContent);
+ scene.add(Playback);
+ scene.add(Name);
+ scene.set(Name, { value: getNextName(world, 'Scene') });
+ scene.add(Position);
+ scene.set(Position, { x, y });
+ if (targetParent) appendChild(world, scene, targetParent);
+ resizeEntity(world, scene, { width, height });
+
+ const fill = createEntity(world);
+ fill.add(Paint);
+ fill.set(Paint, { value: PaintType.SOLID });
+ fill.add(Color);
+ fill.set(Color, { value: 0x000000 });
+ appendChild(world, fill, scene);
+
+ for (const child of frameables) {
+ const prevX = child.get(Position)?.x ?? 0;
+ const prevY = child.get(Position)?.y ?? 0;
+ const parent = getParentNode(child);
+ if (parent) removeChild(world, child, parent);
+ appendChild(world, child, scene);
+ child.add(Position);
+ child.set(Position, { x: prevX - x, y: prevY - y });
+ // Refresh the child's cached local matrix now; the next transform pass
+ // re-derives world transforms from it.
+ computeLocalMatrix(world, child);
+ }
+
+ for (const entity of world.query(Selected)) entity.remove(Selected);
+ scene.add(Selected);
+
+ // Make the freshly created frame the active scene (mirrors the scene tool),
+ // so the timeline retargets to it.
+ switchActiveScene(world, scene);
+
+ return scene;
+}
diff --git a/packages/runtime/src/actions/group.ts b/packages/runtime/src/actions/group.ts
index 326f278e..0792f16a 100644
--- a/packages/runtime/src/actions/group.ts
+++ b/packages/runtime/src/actions/group.ts
@@ -1 +1,139 @@
+/* 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/. */
+
// Group and ungroup actions (was api/group.ts).
+
+import { Not, Or } from 'koota';
+
+import { store } from '../world/store';
+import {
+ ChildOf, Deleted, Geometry, Group, Sequential, Selected, Position, Name,
+ ItemIndex, LocalTransform, Computed,
+} from '../traits';
+import { getNextName, getParentNode } from '../queries/hierarchy';
+import { aabbFromTransformedRect } from '../math';
+import { computeLocalMatrix } from '../systems/transform';
+import { sortByItemIndex } from '../utils/sort';
+import { createEntity, deleteEntity } from './entities';
+import { appendChild, removeChild } from './hierarchy';
+import { resolveNewSequenceOverlaps } from './overlap';
+
+import type { Entity, World } from 'koota';
+
+/**
+ * Wrap the current node selection in a new GROUP. All selected nodes must
+ * share the same parent; scenes are skipped. Children's positions are
+ * rewritten into the group's local space so their on-canvas position is
+ * preserved.
+ */
+export function groupSelection(world: World, sequential: boolean = false): Entity | null {
+ const selection = [...world.query(Selected, Or(Geometry, Group))];
+ if (selection.length === 0) return null;
+
+ const computed = store(world, Computed);
+
+ const targetParent = getParentNode(selection[0]!);
+
+ const groupables = selection
+ .filter(entity => getParentNode(entity) === targetParent)
+ .sort(sortByItemIndex);
+
+ // Bounding box of children in target-parent local space.
+ let minX = Infinity;
+ let minY = Infinity;
+ let maxX = -Infinity;
+ let maxY = -Infinity;
+ for (const entity of groupables) {
+ const mat = entity.get(LocalTransform) ?? { a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 };
+ const w = computed.width[entity.id()]!;
+ const h = computed.height[entity.id()]!;
+ const bounds = aabbFromTransformedRect(mat, w, h);
+ if (bounds.minX < minX) minX = bounds.minX;
+ if (bounds.minY < minY) minY = bounds.minY;
+ if (bounds.maxX > maxX) maxX = bounds.maxX;
+ if (bounds.maxY > maxY) maxY = bounds.maxY;
+ }
+
+ // Sequences sit at the parent's origin (they're passthrough); plain
+ // groups sit at the children's AABB origin so their own pivot lines up.
+ const x = sequential ? 0 : Math.round(minX);
+ const y = sequential ? 0 : Math.round(minY);
+
+ const topItemIndex = groupables[groupables.length - 1]!.get(ItemIndex)?.value ?? 0;
+
+ const group = createEntity(world);
+ group.add(Group);
+ if (sequential) {
+ group.add(Sequential);
+ }
+ group.add(Position);
+ group.set(Position, { x, y });
+ group.add(Name);
+ group.set(Name, { value: getNextName(world, sequential ? 'Sequence' : 'Group') });
+ if (targetParent) appendChild(world, group, targetParent);
+ group.add(ItemIndex);
+ group.set(ItemIndex, { value: topItemIndex });
+
+ for (const [index, entity] of groupables.entries()) {
+ const prevX = entity.get(Position)?.x ?? 0;
+ const prevY = entity.get(Position)?.y ?? 0;
+ const parent = getParentNode(entity);
+ if (parent) removeChild(world, entity, parent);
+ appendChild(world, entity, group);
+ entity.add(ItemIndex);
+ entity.set(ItemIndex, { value: index });
+ entity.add(Position);
+ entity.set(Position, { x: prevX - x, y: prevY - y });
+ // Refresh the child's cached local matrix now; the next transform pass
+ // re-derives world transforms from it.
+ computeLocalMatrix(world, entity);
+ }
+
+ if (sequential) {
+ resolveNewSequenceOverlaps(world, group);
+ }
+
+ for (const entity of world.query(Selected)) entity.remove(Selected);
+ group.add(Selected);
+
+ return group;
+}
+
+/**
+ * Inverse of `groupSelection`. For every GROUP in the current selection,
+ * lift its direct children up to the group's parent and remove the group.
+ * Children's positions are rewritten so they stay put on canvas.
+ */
+export function ungroupSelection(world: World): void {
+ const groups = [...world.query(Selected, Group)];
+ if (groups.length === 0) return;
+
+ const promoted: Entity[] = [];
+
+ for (const group of groups) {
+ const targetParent = getParentNode(group);
+ const groupX = group.get(Position)?.x ?? 0;
+ const groupY = group.get(Position)?.y ?? 0;
+ // Spread is important here: the query result changes while re-parenting.
+ const children = [...world.query(ChildOf(group), Not(Deleted))];
+ for (const child of children) {
+ removeChild(world, child, group);
+ child.add(Position);
+ child.set(Position, {
+ x: (child.get(Position)?.x ?? 0) + groupX,
+ y: (child.get(Position)?.y ?? 0) + groupY,
+ });
+
+ if (targetParent) {
+ appendChild(world, child, targetParent);
+ }
+ promoted.push(child);
+ }
+
+ deleteEntity(world, group);
+ }
+
+ for (const entity of world.query(Selected)) entity.remove(Selected);
+ promoted.forEach(entity => entity.add(Selected));
+}
diff --git a/packages/runtime/src/actions/hierarchy.ts b/packages/runtime/src/actions/hierarchy.ts
index 88d82ffd..a0dad585 100644
--- a/packages/runtime/src/actions/hierarchy.ts
+++ b/packages/runtime/src/actions/hierarchy.ts
@@ -1 +1,128 @@
-// Parenting and ordering actions (was api/hierarchy.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/. */
+
+// Parenting and ordering actions (was api/hierarchy.ts). ChildOf is exclusive,
+// so re-parenting is a single add; "no parent" does not exist under the
+// document root model: detached entities go back to being document children.
+
+import { Not, Or } from 'koota';
+
+import {
+ ChildOf, Deleted, Geometry, Group, AdjustmentLayer, ItemIndex, Selected,
+} from '../traits';
+import { getDocument, getEntityTree, getParentNode } from '../queries/hierarchy';
+import { assert } from '../utils/assert';
+import { sortByItemIndex } from '../utils/sort';
+import { rebuildCaches } from './cache';
+import { propagateSize, resolveConstraintOffsets } from './resize';
+import { reactToChildAttached } from './timing';
+
+import type { Entity, World } from 'koota';
+
+export type ReorderTarget = 'front' | 'back' | number;
+
+export function appendChild(world: World, entity: Entity, parent: Entity): void {
+ assert(getParentNode(entity) === null, 'Entity already has a parent');
+ assert(parent !== entity, 'Cannot parent entity into itself');
+ assert(!getEntityTree(world, entity).includes(parent), 'Cannot parent entity into its own subtree');
+
+ entity.add(ChildOf(parent));
+ rebuildCaches(world, entity, parent);
+ propagateSize(world, entity);
+ resolveConstraintOffsets(world, entity);
+ reactToChildAttached(world, entity);
+}
+
+export function removeChild(world: World, entity: Entity, parent: Entity): void {
+ assert(getParentNode(entity) === parent, 'Entity is not a child of the specified parent');
+
+ // Back to top-level: re-target to the document (never drop ChildOf).
+ entity.add(ChildOf(getDocument(world)));
+ rebuildCaches(world, entity, parent);
+}
+
+/**
+ * Move a single entity within its node siblings by rewriting `ItemIndex`
+ * on every sibling. `target` may be:
+ * - `'front'`: move to the last index (highest ItemIndex = drawn on top)
+ * - `'back'`: move to index 0 (lowest ItemIndex = drawn first)
+ * - a number: move to that absolute index (clamped into range)
+ */
+export function reorderEntity(world: World, entity: Entity, target: ReorderTarget): void {
+ const parent = getParentNode(entity);
+ if (parent === null) return;
+ const siblings = [...world.query(
+ ChildOf(parent), Not(Deleted), Or(Geometry, Group, AdjustmentLayer),
+ )].sort(sortByItemIndex);
+ const index = siblings.indexOf(entity);
+ if (index === -1) return;
+ const newIndex = resolveReorderIndex(target, siblings.length);
+ if (index === newIndex) return;
+ siblings.splice(newIndex, 0, siblings.splice(index, 1)[0]!);
+ for (const [idx, sibling] of siblings.entries()) {
+ sibling.add(ItemIndex);
+ sibling.set(ItemIndex, { value: idx });
+ }
+}
+
+/**
+ * Move the current node selection within its parent. `target` may be:
+ * - `'front'`: move all selected entities to the front
+ * - `'back'`: move all selected entities to the back
+ * - a number: insert the selected entities starting at that absolute index
+ *
+ * Selections that span multiple parents are reordered per-parent; the
+ * relative order of the selected entities within each parent is preserved.
+ */
+export function reorderSelection(world: World, target: ReorderTarget): void {
+ const selection = [...world.query(Selected, Or(Geometry, Group, AdjustmentLayer))];
+ if (selection.length === 0) return;
+
+ const byParent = new Map<Entity, Set<Entity>>();
+ for (const entity of selection) {
+ const parent = getParentNode(entity);
+ if (parent === null) continue;
+ if (!byParent.has(parent)) byParent.set(parent, new Set());
+ byParent.get(parent)!.add(entity);
+ }
+
+ for (const [parent, selected] of byParent) {
+ const siblings = [...world.query(
+ ChildOf(parent), Not(Deleted), Or(Geometry, Group, AdjustmentLayer),
+ )].sort(sortByItemIndex);
+ const selectedOrdered = siblings.filter(entity => selected.has(entity));
+ const rest = siblings.filter(entity => !selected.has(entity));
+
+ let newOrder: Entity[];
+ if (target === 'front') {
+ newOrder = [...rest, ...selectedOrdered];
+ } else if (target === 'back') {
+ newOrder = [...selectedOrdered, ...rest];
+ } else {
+ // Insert the selected block starting at the target index, clamped so
+ // the whole block still fits inside the sibling array.
+ const maxStart = Math.max(0, rest.length);
+ const insertAt = Math.max(0, Math.min(maxStart, Math.trunc(target)));
+ newOrder = [...rest.slice(0, insertAt), ...selectedOrdered, ...rest.slice(insertAt)];
+ }
+
+ let changed = false;
+ for (let i = 0; i < newOrder.length; i++) {
+ if (newOrder[i] !== siblings[i]) { changed = true; break; }
+ }
+ if (!changed) continue;
+
+ for (const [idx, sibling] of newOrder.entries()) {
+ sibling.add(ItemIndex);
+ sibling.set(ItemIndex, { value: idx });
+ }
+ }
+}
+
+function resolveReorderIndex(target: ReorderTarget, length: number): number {
+ if (target === 'front') return length - 1;
+ if (target === 'back') return 0;
+ // Numeric target: clamp into [0, length - 1].
+ return Math.max(0, Math.min(length - 1, Math.trunc(target)));
+}
diff --git a/packages/runtime/src/actions/index.ts b/packages/runtime/src/actions/index.ts
index fa4aff1d..2acf0fa9 100644
--- a/packages/runtime/src/actions/index.ts
+++ b/packages/runtime/src/actions/index.ts
@@ -1 +1,23 @@
-// Re-exports all action groups, bound with koota createActions.
+/* 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/. */
+
+// Write-path actions (was api/*). Plain world-first functions, matching the
+// queries/systems convention, rather than koota createActions: actions here
+// return entities/records and call each other freely, which the bound-record
+// pattern only obscures. No history or persistence layer: the app records
+// undo entries and schedules writes by observing koota add/remove/change
+// events on the traits these actions touch.
+
+export * from './entities';
+export * from './hierarchy';
+export * from './cache';
+export * from './timing';
+export * from './resize';
+export * from './keyframe';
+export * from './overlap';
+export * from './group';
+export * from './frame';
+export * from './clipboard';
+export * from './assets';
+export * from './folders';
diff --git a/packages/runtime/src/actions/keyframe.ts b/packages/runtime/src/actions/keyframe.ts
index 838a2236..4113fea4 100644
--- a/packages/runtime/src/actions/keyframe.ts
+++ b/packages/runtime/src/actions/keyframe.ts
@@ -1 +1,191 @@
+/* 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/. */
+
// Keyframe actions (was api/keyframe.ts).
+
+import { Not } from 'koota';
+
+import {
+ ChildOf, Deleted, Geometry, Group, AdjustmentLayer, KeyframeTrack, Keyframe,
+} from '../traits';
+import { getNodeLocalFrame, getParentNode } from '../queries/hierarchy';
+import { getPropertyPaths } from '../systems/motion';
+import { createEntity, deleteEntity } from './entities';
+import { appendChild } from './hierarchy';
+
+import type { Entity, World } from 'koota';
+import type { PropertyPath } from '../systems/motion';
+
+/**
+ * Find the KeyframeTrack entity (if any) for a (target, property) pair.
+ */
+export function findKeyframeTrackEntity(world: World, target: Entity, property: string): Entity | null {
+ for (const track of world.query(KeyframeTrack, ChildOf(target), Not(Deleted))) {
+ if (track.get(KeyframeTrack)!.property === property) return track;
+ }
+ return null;
+}
+
+/**
+ * Collect all keyframe entities for a (target, property) pair.
+ */
+export function getKeyframeTrack(world: World, target: Entity, property: string): Entity[] {
+ const track = findKeyframeTrackEntity(world, target, property);
+ if (track === null) return [];
+ return [...world.query(Keyframe, ChildOf(track), Not(Deleted))];
+}
+
+/**
+ * Find the target node for a given entity: itself or the nearest ancestor
+ * that is a geometry, group, or adjustment layer.
+ */
+export function findKeyframeTargetNode(entity: Entity): Entity | null {
+ let current: Entity | null = entity;
+ while (current) {
+ if (current.has(Geometry) || current.has(Group) || current.has(AdjustmentLayer)) {
+ return current;
+ }
+ current = getParentNode(current);
+ }
+ return null;
+}
+
+/**
+ * Get the KeyframeTrack entity for (target, property), creating one if missing.
+ */
+function ensureKeyframeTrackEntity(world: World, target: Entity, property: PropertyPath): Entity {
+ const existing = findKeyframeTrackEntity(world, target, property);
+ if (existing !== null) return existing;
+
+ const track = createEntity(world);
+ track.add(KeyframeTrack);
+ track.set(KeyframeTrack, { property });
+ appendChild(world, track, target);
+ return track;
+}
+
+/**
+ * Add a keyframe at the current local time for (target, property).
+ * Reads the current value from the target. If a keyframe at this exact time
+ * already exists, its value is overwritten.
+ */
+export function syncKeyframeTrack(world: World, entity: Entity, property: PropertyPath) {
+ const worldProps = getPropertyPaths(world);
+ const node = findKeyframeTargetNode(entity);
+ if (node === null) return;
+
+ const track = findKeyframeTrackEntity(world, entity, property);
+ if (track === null) return;
+
+ const localFrame = getNodeLocalFrame(node);
+ const existing = [...world.query(Keyframe, ChildOf(track), Not(Deleted))]
+ .find(kf => kf.get(Keyframe)!.time === localFrame);
+
+ const currentValue = worldProps[property].authored[entity.id()] ?? 0;
+ if (typeof currentValue !== 'number') return;
+
+ if (existing) {
+ existing.set(Keyframe, { value: currentValue });
+ } else {
+ const kf = createEntity(world);
+ kf.add(Keyframe);
+ kf.set(Keyframe, {
+ time: localFrame,
+ value: currentValue,
+ easing: 'linear',
+ });
+ appendChild(world, kf, track);
+ }
+}
+
+/**
+ * Toggle a keyframe at the current local time for (target, property).
+ * Creates the KeyframeTrack on first use; removes it when its last keyframe
+ * is toggled off.
+ */
+export function toggleKeyframeTrack(world: World, entity: Entity, property: PropertyPath) {
+ const worldProps = getPropertyPaths(world);
+ const node = findKeyframeTargetNode(entity);
+ if (node === null) return;
+
+ const localFrame = getNodeLocalFrame(node);
+ const track = findKeyframeTrackEntity(world, entity, property);
+
+ let trackKeyframes: Entity[] = [];
+ if (track !== null) {
+ trackKeyframes = [...world.query(Keyframe, ChildOf(track), Not(Deleted))];
+ }
+
+ const existing = trackKeyframes.find(kf => kf.get(Keyframe)!.time === localFrame);
+
+ const currentValue = worldProps[property].authored[entity.id()] ?? 0;
+ if (typeof currentValue !== 'number') return;
+
+ if (existing) {
+ deleteEntity(world, existing);
+ // If that was the track's last keyframe, drop the track too.
+ if (track && trackKeyframes.length === 1) {
+ deleteEntity(world, track);
+ }
+ return;
+ }
+
+ const target = ensureKeyframeTrackEntity(world, entity, property);
+ const kf = createEntity(world);
+ kf.add(Keyframe);
+ kf.set(Keyframe, {
+ time: localFrame,
+ value: currentValue,
+ easing: 'linear',
+ });
+ appendChild(world, kf, target);
+}
+
+/**
+ * Declaratively replace all keyframes for (target, property): creates the
+ * track on first use, deletes it when `keyframes` is empty. Times are local
+ * frames; values are in the property's authored unit.
+ */
+export function setKeyframeTrack(
+ world: World,
+ target: Entity,
+ property: PropertyPath,
+ keyframes: ReadonlyArray<{ time: number; value: number; easing?: string }>,
+): void {
+ const existing = findKeyframeTrackEntity(world, target, property);
+
+ if (existing !== null) {
+ for (const kf of world.query(Keyframe, ChildOf(existing), Not(Deleted))) {
+ deleteEntity(world, kf);
+ }
+ if (keyframes.length === 0) {
+ deleteEntity(world, existing);
+ return;
+ }
+ }
+ if (keyframes.length === 0) return;
+
+ const track = existing ?? ensureKeyframeTrackEntity(world, target, property);
+ const sorted = [...keyframes].sort((a, b) => a.time - b.time);
+ for (const kf of sorted) {
+ const entity = createEntity(world);
+ entity.add(Keyframe);
+ entity.set(Keyframe, {
+ time: kf.time,
+ value: kf.value,
+ easing: kf.easing ?? '',
+ });
+ appendChild(world, entity, track);
+ }
+}
+
+export function removeKeyframeTrack(world: World, entity: Entity, property: PropertyPath) {
+ const track = findKeyframeTrackEntity(world, entity, property);
+ if (track === null) return;
+
+ const keyframes = [...world.query(Keyframe, ChildOf(track), Not(Deleted))];
+
+ keyframes.forEach(kf => deleteEntity(world, kf));
+ deleteEntity(world, track);
+}
diff --git a/packages/runtime/src/actions/overlap.ts b/packages/runtime/src/actions/overlap.ts
index b5b09fbc..badce904 100644
--- a/packages/runtime/src/actions/overlap.ts
+++ b/packages/runtime/src/actions/overlap.ts
@@ -1,2 +1,180 @@
+/* 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/. */
+
// Sequential overlap resolution (was api/overlap.ts). Lives in actions, not
// queries: it trims, deletes, and splits clips via the overwrite model.
+
+import { Not, Or } from 'koota';
+
+import { store } from '../world/store';
+import {
+ ChildOf, Deleted, Geometry, Group, Sequential, Trim, Computed,
+} from '../traits';
+import { isGroup } from '../queries/predicates';
+import { getEntityTree, getParentNode } from '../queries/hierarchy';
+import { computeTrimStart, computeTrimEnd } from '../utils/time';
+import { cloneSubtree } from '../world/serialize';
+import { deleteEntity } from './entities';
+
+import type { Entity, World } from 'koota';
+
+/**
+ * Enforce the "no two direct children overlap in time" invariant of a
+ * Sequential container after a clip has been moved (dragged + released).
+ *
+ * For every dragged clip whose direct parent is Sequential, each conflicting
+ * sibling is resolved against the dragged clip's [start, end) span using an
+ * overwrite model:
+ * - fully covered → removed
+ * - overlaps left edge → trimmed (out-point pulled back to the drop start)
+ * - overlaps right edge→ trimmed (in-point pushed to the drop end)
+ * - fully engulfs → split into two halves around the dropped clip
+ *
+ * Group siblings are resolved recursively at the leaf level; their bounds
+ * recompute from their remaining children, and an emptied group is removed.
+ */
+export function resolveSequentialOverlaps(world: World, dragged: Entity[]): void {
+ if (dragged.length === 0) return;
+
+ const computed = store(world, Computed);
+
+ // Dragged clips never trim or remove each other.
+ const ignore = new Set(dragged);
+
+ for (const entity of dragged) {
+ const parent = getParentNode(entity);
+ if (parent === null || !parent.has(Sequential)) continue;
+
+ const occStart = computed.start[entity.id()];
+ const occEnd = computed.end[entity.id()];
+ if (occStart === undefined || occEnd === undefined || occEnd <= occStart) continue;
+
+ // Snapshot the sibling list before mutating: resolution deletes, trims,
+ // and clones, all of which change the live query result.
+ const siblings = [...world.query(Or(Geometry, Group), ChildOf(parent), Not(Deleted))]
+ .filter(sibling => !ignore.has(sibling));
+
+ for (const sibling of siblings) {
+ resolveEntityOverlap(world, sibling, occStart, occEnd, ignore);
+ }
+ }
+}
+
+/**
+ * Enforce the no-overlap invariant on a *freshly created* Sequential container.
+ *
+ * resolveSequentialOverlaps has an authoritative set: the clips the user just
+ * dragged. On creation there is none: every child is a peer that merely happened
+ * to overlap on the canvas. We pick a deterministic precedence instead; earlier
+ * clips win and keep their full extent; later clips yield, trimmed back to start
+ * after the clip preceding them (fully-covered clips are removed).
+ *
+ * Children are processed in start-frame order with each one authoritative over
+ * all later siblings. Because every authoritative pass trims *all* later
+ * siblings uniformly, each clip's start stays monotonic by rank, so the "dropped
+ * clip lands inside a sibling" split case from resolveEntityOverlap cannot arise
+ * here; only edge trims and removals.
+ */
+export function resolveNewSequenceOverlaps(world: World, sequence: Entity): void {
+ if (!sequence.has(Sequential)) return;
+
+ const computed = store(world, Computed);
+
+ const children = [...world.query(Or(Geometry, Group), ChildOf(sequence), Not(Deleted))]
+ .sort((a, b) => (computed.start[a.id()] ?? 0) - (computed.start[b.id()] ?? 0));
+
+ // No dragged clips to protect; group recursion has no leaves to skip.
+ const ignore = new Set<Entity>();
+
+ for (let i = 0; i < children.length; i++) {
+ const entity = children[i]!;
+ // An earlier authoritative clip may have removed or trimmed this one.
+ if (entity.has(Deleted)) continue;
+ const occStart = computed.start[entity.id()];
+ const occEnd = computed.end[entity.id()];
+ if (occStart === undefined || occEnd === undefined || occEnd <= occStart) continue;
+
+ for (let j = i + 1; j < children.length; j++) {
+ const sibling = children[j]!;
+ if (sibling.has(Deleted)) continue;
+ resolveEntityOverlap(world, sibling, occStart, occEnd, ignore);
+ }
+ }
+}
+
+/**
+ * Resolve a single entity against the occupied [occStart, occEnd) span.
+ * Groups recurse to their children; leaf clips are trimmed, removed, or split.
+ */
+function resolveEntityOverlap(
+ world: World,
+ entity: Entity,
+ occStart: number,
+ occEnd: number,
+ ignore: Set<Entity>,
+): void {
+ const computed = store(world, Computed);
+
+ const start = computed.start[entity.id()];
+ const end = computed.end[entity.id()];
+ if (start === undefined || end === undefined) return;
+
+ // No temporal overlap. Touching edges (end === occStart or start === occEnd)
+ // are abutting, not overlapping.
+ if (end <= occStart || start >= occEnd) return;
+
+ // Plain groups (incl. nested Sequential containers) have no intrinsic trim;
+ // resolve their leaves and let the group's bounds recompute from what's left.
+ if (isGroup(entity)) {
+ if (start >= occStart && end <= occEnd) {
+ // Whole group sits inside the dropped span: remove it outright.
+ deleteEntity(world, entity);
+ return;
+ }
+
+ const children = [...world.query(Or(Geometry, Group), ChildOf(entity), Not(Deleted))]
+ .filter(child => !ignore.has(child));
+ for (const child of children) {
+ resolveEntityOverlap(world, child, occStart, occEnd, ignore);
+ }
+
+ // If every child was removed, the group is now empty: drop it too.
+ const remaining = world.query(Or(Geometry, Group), ChildOf(entity), Not(Deleted));
+ if (remaining.length === 0) deleteEntity(world, entity);
+ return;
+ }
+
+ const startCovered = start >= occStart;
+ const endCovered = end <= occEnd;
+
+ if (startCovered && endCovered) {
+ // Fully covered: remove it.
+ deleteEntity(world, entity);
+ } else if (!startCovered && endCovered) {
+ // Overlaps the dropped clip's left edge: keep the left remainder by
+ // pulling the out-point back to the drop start.
+ entity.add(Trim);
+ entity.set(Trim, { end: computeTrimEnd(entity, occStart) });
+ } else if (startCovered && !endCovered) {
+ // Overlaps the dropped clip's right edge: keep the right remainder by
+ // pushing the in-point forward to the drop end.
+ entity.add(Trim);
+ entity.set(Trim, { start: computeTrimStart(entity, occEnd) });
+ } else {
+ // The dropped clip lands inside this one: split it into two halves around
+ // the span. Clone first so the copy inherits the original (un-shrunk)
+ // trim, then shrink the original to the left half and the copy to the
+ // right half.
+ const copyTrimStart = computeTrimStart(entity, occEnd);
+ const result = cloneSubtree(world, getEntityTree(world, entity));
+ const copy = result.get(entity);
+
+ entity.add(Trim);
+ entity.set(Trim, { end: computeTrimEnd(entity, occStart) });
+ if (copy !== undefined) {
+ copy.add(Trim);
+ copy.set(Trim, { start: copyTrimStart });
+ }
+ }
+}
diff --git a/packages/runtime/src/actions/resize.ts b/packages/runtime/src/actions/resize.ts
index 291e9eeb..b0355867 100644
--- a/packages/runtime/src/actions/resize.ts
+++ b/packages/runtime/src/actions/resize.ts
@@ -1 +1,214 @@
+/* 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/. */
+
// Resize and layout actions (was api/resize.ts).
+
+import { store } from '../world/store';
+import { ConstraintType } from '../constants';
+import {
+ ChildOf, Group, Size, Position, Constraint, ConstraintCache,
+ KeepAspectRatio, Sequential, Computed,
+} from '../traits';
+import { getParentNode } from '../queries/hierarchy';
+import { syncKeyframeTrack } from './keyframe';
+
+import type { Entity, World } from 'koota';
+
+type ResizeParams = { width?: number; height?: number };
+
+/**
+ * Resize an entity. Enforces aspect ratio, writes the final Size, propagates
+ * Computed size down the subtree, reapplies sibling constraints, and syncs
+ * the width/height keyframe tracks. Group/Sequential entities don't own a Size
+ * so calling this on one strips the trait instead.
+ */
+export function resizeEntity(world: World, entity: Entity, params: ResizeParams): void {
+ if (entity.has(Group)) {
+ entity.remove(Size);
+ return;
+ }
+
+ let { width, height } = params;
+
+ // Enforce aspect ratio
+ const aspect = entity.get(KeepAspectRatio);
+ if (aspect && aspect.width > 0 && aspect.height > 0) {
+ const ratio = aspect.width / aspect.height;
+
+ if (width !== undefined && height === undefined) {
+ height = Math.round(width / ratio);
+ } else if (height !== undefined && width === undefined) {
+ width = Math.round(height * ratio);
+ } else if (width !== undefined && height !== undefined) {
+ height = Math.round(width / ratio);
+ }
+ }
+
+ entity.add(Size);
+ entity.set(Size, {
+ ...(width !== undefined && { width: Math.round(width) }),
+ ...(height !== undefined && { height: Math.round(height) }),
+ });
+ propagateSize(world, entity);
+ resolveConstraintOffsets(world, entity);
+
+ if (width !== undefined) {
+ syncKeyframeTrack(world, entity, 'width');
+ }
+ if (height !== undefined) {
+ syncKeyframeTrack(world, entity, 'height');
+ }
+}
+
+export function propagateSize(world: World, entity: Entity) {
+ const size = entity.get(Size);
+ if (!size) return;
+
+ const computed = store(world, Computed);
+ computed.width[entity.id()] = Math.round(size.width);
+ computed.height[entity.id()] = Math.round(size.height);
+
+ for (const child of world.query(ChildOf(entity), Size)) {
+ propagateSize(world, child);
+ }
+}
+
+export function resolveConstraintOffsets(world: World, entity: Entity): void {
+ // Sequences aren't spatial constructs; they mirror their parent's frame.
+ let dims: Entity | null = entity;
+ while (dims !== null && dims.has(Sequential)) {
+ dims = getParentNode(dims);
+ }
+ if (dims === null) return;
+
+ resolveConstraintOffsetsAgainst(world, entity, dims);
+}
+
+function resolveConstraintOffsetsAgainst(world: World, entity: Entity, dims: Entity): void {
+ const computed = store(world, Computed);
+ const cache = store(world, ConstraintCache);
+
+ // Sequential children are transparent: resolve their children against the
+ // same spatial parent.
+ for (const child of world.query(ChildOf(entity), Sequential)) {
+ resolveConstraintOffsetsAgainst(world, child, dims);
+ }
+
+ for (const child of world.query(ChildOf(entity), Constraint)) {
+ if (child.has(Sequential)) continue;
+
+ const cid = child.id();
+ const curParentW = computed.width[dims.id()]!;
+ const curParentH = computed.height[dims.id()]!;
+ const curChildW = computed.width[cid]!;
+ const curChildH = computed.height[cid]!;
+
+ // First time seeing this child (e.g. constraint just assigned): seed the
+ // cache without adjusting position.
+ if (!child.has(ConstraintCache)) {
+ child.add(ConstraintCache);
+ cache.parentWidth[cid] = curParentW;
+ cache.parentHeight[cid] = curParentH;
+ cache.childWidth[cid] = curChildW;
+ cache.childHeight[cid] = curChildH;
+ resolveConstraintOffsets(world, child);
+ continue;
+ }
+
+ const prevParentW = cache.parentWidth[cid]!;
+ const prevParentH = cache.parentHeight[cid]!;
+ const prevChildW = cache.childWidth[cid]!;
+ const prevChildH = cache.childHeight[cid]!;
+
+ // Update caches
+ cache.parentWidth[cid] = curParentW;
+ cache.parentHeight[cid] = curParentH;
+ cache.childWidth[cid] = curChildW;
+ cache.childHeight[cid] = curChildH;
+
+ // No change
+ if (prevParentW === curParentW && prevParentH === curParentH) continue;
+
+ const constraint = child.get(Constraint)!;
+ const dpW = curParentW - prevParentW;
+ const dpH = curParentH - prevParentH;
+ const dcW = curChildW - prevChildW;
+ const dcH = curChildH - prevChildH;
+ const positionX = computed.positionX[cid]!;
+ const positionY = computed.positionY[cid]!;
+
+ child.add(Position);
+
+ // Resizing constraints (STRETCH/SCALE) record their new dimension here
+ // rather than writing it straight away, so a locked aspect ratio can
+ // couple the two axes before the Size is committed.
+ let newChildW: number | undefined;
+ let newChildH: number | undefined;
+
+ if (constraint.horizontal === ConstraintType.MAX) {
+ child.set(Position, { x: positionX + dpW - dcW });
+ } else if (constraint.horizontal === ConstraintType.CENTER) {
+ child.set(Position, { x: positionX + dpW / 2 - dcW / 2 });
+ } else if (constraint.horizontal === ConstraintType.STRETCH) {
+ // Pin both left and right edges: hold the left edge in place and grow
+ // the child by the parent's width delta so the right margin stays
+ // constant.
+ newChildW = curChildW + dpW;
+ } else if (constraint.horizontal === ConstraintType.SCALE && prevParentW !== 0) {
+ // Scale offset and width by the parent's horizontal ratio so the child
+ // keeps its relative position and proportion.
+ const scale = curParentW / prevParentW;
+ newChildW = Math.round(curChildW * scale);
+ child.set(Position, { x: positionX * scale });
+ }
+
+ if (constraint.vertical === ConstraintType.MAX) {
+ child.set(Position, { y: positionY + dpH - dcH });
+ } else if (constraint.vertical === ConstraintType.CENTER) {
+ child.set(Position, { y: positionY + dpH / 2 - dcH / 2 });
+ } else if (constraint.vertical === ConstraintType.STRETCH) {
+ // Pin both top and bottom edges: hold the top edge in place and grow
+ // the child by the parent's height delta so the bottom margin stays
+ // constant.
+ newChildH = curChildH + dpH;
+ } else if (constraint.vertical === ConstraintType.SCALE && prevParentH !== 0) {
+ // Scale offset and height by the parent's vertical ratio so the child
+ // keeps its relative position and proportion.
+ const scale = curParentH / prevParentH;
+ newChildH = Math.round(curChildH * scale);
+ child.set(Position, { y: positionY * scale });
+ }
+
+ // When the child's aspect ratio is locked, drive the other dimension from
+ // whichever axis resized so the proportion is preserved. Width wins when
+ // both axes resize, mirroring resizeEntity's precedence.
+ const aspect = child.get(KeepAspectRatio);
+ if (
+ aspect && aspect.width > 0 && aspect.height > 0 &&
+ (newChildW !== undefined || newChildH !== undefined)
+ ) {
+ const ratio = aspect.width / aspect.height;
+ if (newChildW !== undefined) {
+ newChildH = Math.round(newChildW / ratio);
+ } else if (newChildH !== undefined) {
+ newChildW = Math.round(newChildH * ratio);
+ }
+ }
+
+ if (newChildW !== undefined) {
+ child.add(Size);
+ child.set(Size, { width: newChildW });
+ computed.width[cid] = newChildW;
+ cache.childWidth[cid] = newChildW;
+ }
+ if (newChildH !== undefined) {
+ child.add(Size);
+ child.set(Size, { height: newChildH });
+ computed.height[cid] = newChildH;
+ cache.childHeight[cid] = newChildH;
+ }
+
+ resolveConstraintOffsets(world, child);
+ }
+}
diff --git a/packages/runtime/src/actions/timing.ts b/packages/runtime/src/actions/timing.ts
new file mode 100644
index 00000000..e993045c
--- /dev/null
+++ b/packages/runtime/src/actions/timing.ts
@@ -0,0 +1,203 @@
+/* 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/. */
+
+// Time-range recomputation after structural or asset changes (was part of
+// api/utils.ts). Computed is derived state (store writes, no events); Trim is
+// authored, so trim edits go through entity.set and fire change events.
+
+import { store } from '../world/store';
+import { DEFAULT_DURATION_FRAMES } from '../constants';
+import {
+ Geometry, Group, Paint, Audio, Caption, Cache, Computed, Delay,
+ PlaybackRate, Trim,
+} from '../traits';
+import { isGroupLike } from '../queries/predicates';
+import { getParentNode } from '../queries/hierarchy';
+import { findAssetDuration } from '../utils/time';
+
+import type { Entity, World } from 'koota';
+
+export function recomputeEntityTimeRange(world: World, entity: Entity): void {
+ const computed = store(world, Computed);
+ const eid = entity.id();
+
+ const parent = getParentNode(entity);
+ const parentDelay = parent !== null ? (computed.delay[parent.id()] ?? 0) : 0;
+ const ownDelay = entity.get(Delay)?.value ?? 0;
+ const accumulatedDelay = parentDelay + ownDelay;
+
+ computed.delay[eid] = accumulatedDelay;
+
+ const playbackRate = entity.get(PlaybackRate)?.value ?? 1;
+
+ let start: number;
+ let end: number;
+
+ if (entity.has(Trim)) {
+ const trim = entity.get(Trim)!;
+ start = Math.round(accumulatedDelay + trim.start / playbackRate);
+ end = Math.round(accumulatedDelay + trim.end / playbackRate);
+ } else if (isGroupLike(entity)) {
+ const children = entity.get(Cache)?.children ?? [];
+ if (children.length === 0) {
+ start = accumulatedDelay;
+ end = accumulatedDelay + DEFAULT_DURATION_FRAMES;
+ } else {
+ let minStart = Infinity;
+ let maxEnd = -Infinity;
+ for (const child of children) {
+ const cs = computed.start[child.id()] ?? accumulatedDelay;
+ const ce = computed.end[child.id()] ?? accumulatedDelay;
+ if (cs < minStart) minStart = cs;
+ if (ce > maxEnd) maxEnd = ce;
+ }
+ start = minStart;
+ end = maxEnd;
+ }
+ } else {
+ const assetDuration = findAssetDuration(world, entity);
+ const sourceDuration = assetDuration ?? DEFAULT_DURATION_FRAMES;
+ start = accumulatedDelay;
+ end = Math.round(accumulatedDelay + sourceDuration / playbackRate);
+ }
+
+ computed.start[eid] = start;
+ computed.end[eid] = end;
+ computed.duration[eid] = end - start;
+}
+
+/**
+ * Recompute an entity and every descendant node. Use when something that
+ * affects accumulated delay or playback rate changes; every child below
+ * needs its delay refreshed.
+ */
+export function propagateTimeRangeDown(world: World, entity: Entity): void {
+ recomputeEntityTimeRange(world, entity);
+ for (const child of entity.get(Cache)?.children ?? []) {
+ propagateTimeRangeDown(world, child);
+ }
+ for (const mask of entity.get(Cache)?.masks ?? []) {
+ propagateTimeRangeDown(world, mask);
+ }
+ recomputeEntityTimeRange(world, entity);
+}
+
+/**
+ * Walk upward recomputing any ancestor whose bounds depend on its children
+ * (group-like without an explicit Trim). Call with the entity that changed.
+ */
+export function bubbleTimeRangeUp(world: World, child: Entity): void {
+ const entity = getParentNode(child);
+ if (entity === null) return;
+
+ const dependsOnChildren = isGroupLike(entity) && !entity.has(Trim);
+ if (!dependsOnChildren) return;
+
+ recomputeEntityTimeRange(world, entity);
+ bubbleTimeRangeUp(world, entity);
+}
+
+/**
+ * Clamp a Trim's end so it never exceeds the entity's available asset
+ * duration. Caller is responsible for triggering downstream recomputes.
+ */
+export function clampTrimToAssetDuration(world: World, entity: Entity): void {
+ if (!entity.has(Trim)) return;
+
+ const assetDuration = findAssetDuration(world, entity);
+ if (!assetDuration) return;
+
+ const trim = entity.get(Trim)!;
+ if (trim.end > assetDuration) {
+ entity.set(Trim, { end: assetDuration });
+ }
+}
+
+/**
+ * "Paint is removed" rule: if the geometry has no Trim, pin its current
+ * computed duration as a fresh Trim so the entity does not silently fall
+ * back to the 16s default after losing its asset source.
+ */
+export function pinTrimToCurrentDuration(world: World, entity: Entity): void {
+ if (entity.has(Trim)) return;
+
+ const playbackRate = entity.get(PlaybackRate)?.value ?? 1;
+ const globalDuration = store(world, Computed).duration[entity.id()] ?? 0;
+ const localDuration = Math.round(globalDuration * playbackRate);
+
+ entity.add(Trim);
+ entity.set(Trim, { start: 0, end: localDuration });
+}
+
+/**
+ * Recompute trim when the asset id of an entity changes.
+ */
+export function reactToAssetChange(world: World, entity: Entity) {
+ if (entity.has(Paint)) {
+ reactToPaintChange(world, entity);
+ } else if (entity.has(Audio)) {
+ reactToGeometryDurationChange(world, entity);
+ } else if (entity.has(Caption)) {
+ // Re-pointed transcript: the caption decoder must re-resolve with the
+ // new asset. Decoder disposal moves in with the media slice.
+ }
+}
+
+/**
+ * Re-clamp the parent geometry's trim and bubble the new bounds up.
+ */
+export function reactToPaintChange(world: World, paint: Entity) {
+ const entity = getParentNode(paint);
+ if (entity === null || !entity.has(Geometry)) return;
+
+ clampTrimToAssetDuration(world, entity);
+ recomputeEntityTimeRange(world, entity);
+ bubbleTimeRangeUp(world, entity);
+}
+
+/**
+ * Recompute a geometry's bounds and bubble. Used when something other than
+ * its own Trim/Delay shifts its duration (e.g. an attached asset id on an
+ * Audio entity).
+ */
+export function reactToGeometryDurationChange(world: World, entity: Entity) {
+ if (!entity.has(Geometry)) return;
+
+ clampTrimToAssetDuration(world, entity);
+ recomputeEntityTimeRange(world, entity);
+ bubbleTimeRangeUp(world, entity);
+}
+
+export function reactToChildAttached(world: World, child: Entity) {
+ if (child.has(Geometry) || child.has(Group)) {
+ propagateTimeRangeDown(world, child);
+ bubbleTimeRangeUp(world, child);
+ return;
+ }
+
+ if (child.has(Paint)) {
+ reactToPaintChange(world, child);
+ }
+}
+
+/**
+ * Deleted onAdd hook (covers the user-facing "remove" path). Mirror of
+ * reactToChildAttached: if the dying entity is a geometry the parent group's
+ * bounds may shrink; if it's a paint the parent geometry may lose its asset
+ * source and needs a Trim pinned at its current duration.
+ */
+export function reactToChildDetached(world: World, child: Entity) {
+ if (child.has(Geometry) || child.has(Group)) {
+ bubbleTimeRangeUp(world, child);
+ return;
+ }
+
+ if (child.has(Paint)) {
+ const parent = getParentNode(child);
+ if (parent === null || !parent.has(Geometry)) return;
+ // Pin the current duration before recomputing; otherwise the geometry
+ // would silently fall back to the 16s default after losing its paint.
+ pinTrimToCurrentDuration(world, parent);
+ }
+}
diff --git a/packages/runtime/src/assets/types.ts b/packages/runtime/src/assets/types.ts
new file mode 100644
index 00000000..8a9c81af
--- /dev/null
+++ b/packages/runtime/src/assets/types.ts
@@ -0,0 +1,96 @@
+/* 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/. */
+
+// Asset and folder metadata model. The runtime only needs what resolves
+// durations, dimensions, and file bytes; the app layers persistence (zod
+// schemas, IndexedDB records) on top with structurally compatible shapes.
+
+/** Whatever hands out the asset's bytes: a FileSystemFileHandle in the
+ * browser, a path-backed handle in Electron or node. */
+export interface AssetFileHandle {
+ getFile(): Promise<File>;
+}
+
+/** Directory of numbered frame files backing a SEQUENCE asset. Typed to the
+ * web FileSystemDirectoryHandle surface the decoders iterate. */
+export interface AssetDirectoryHandle {
+ entries(): AsyncIterableIterator<[string, { kind: string; getFile?: () => Promise<File> }]>;
+}
+
+export type TranscriptWord = { text: string; start: number; end: number };
+
+export type Transcript = { text: string; words: TranscriptWord[] }[];
+
+interface AssetBase {
+ id: string;
+ hash: string;
+ createdAt: string;
+ lastModified?: number;
+ name: string;
+ mimeType: string;
+ size?: number;
+ handle: AssetFileHandle;
+ generationId?: string | null;
+ generationKey?: string | null;
+ folderId?: string | null;
+}
+
+export interface ImageAsset extends AssetBase {
+ type: 'IMAGE';
+ width: number;
+ height: number;
+}
+
+export interface AudioAsset extends AssetBase {
+ type: 'AUDIO';
+ duration: number;
+ sampleRate: number;
+ channels: number;
+ transcript?: Transcript;
+}
+
+export interface VideoAsset extends AssetBase {
+ type: 'VIDEO';
+ duration: number;
+ width: number;
+ height: number;
+ frameRate: number;
+ bitRate: number;
+ sampleRate?: number;
+ channels?: number;
+ transcript?: Transcript;
+}
+
+export interface TranscriptAsset extends AssetBase {
+ type: 'TRANSCRIPT';
+}
+
+export interface ScriptAsset extends AssetBase {
+ type: 'SCRIPT';
+}
+
+// `handle` points to the first frame's file so generic preview code works.
+export interface SequenceAsset extends AssetBase {
+ type: 'SEQUENCE';
+ width: number;
+ height: number;
+ frameRate: number;
+ duration: number;
+ directoryHandle: AssetDirectoryHandle;
+}
+
+export type Asset =
+ | ImageAsset
+ | AudioAsset
+ | VideoAsset
+ | TranscriptAsset
+ | ScriptAsset
+ | SequenceAsset;
+
+export interface Folder {
+ id: string;
+ name: string;
+ parentId: string | null;
+ createdAt: string;
+}
diff --git a/packages/runtime/src/constants.ts b/packages/runtime/src/constants.ts
index 9091b4ea..85ac283f 100644
--- a/packages/runtime/src/constants.ts
+++ b/packages/runtime/src/constants.ts
@@ -2,6 +2,10 @@
* 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/. */
+export const CONONICAL_TIME_BASE = 1e6;
+
+export const DEFAULT_DURATION_FRAMES = 16 * 30;
+
export enum BlendMode {
SOURCE_OVER,
MULTIPLY,
diff --git a/packages/runtime/src/index.ts b/packages/runtime/src/index.ts
index 25fa8317..5b41e0a1 100644
--- a/packages/runtime/src/index.ts
+++ b/packages/runtime/src/index.ts
@@ -4,6 +4,8 @@ export * from './world/create-world';
export * from './world/serialize';
export * from './world/store';
export * from './queries';
+export * from './actions';
+export * from './assets/types';
export * from './systems';
export * from './math';
export * from './capture';
diff --git a/packages/runtime/src/traits/world.ts b/packages/runtime/src/traits/world.ts
index e77e1761..45d1c63c 100644
--- a/packages/runtime/src/traits/world.ts
+++ b/packages/runtime/src/traits/world.ts
@@ -7,6 +7,7 @@ import { trait, type Entity } from 'koota';
import { createLiveMounts } from '../utils/live-mounts';
import type { FontSource } from '../fonts/types';
+import type { Asset, Folder } from '../assets/types';
// Singleton state attached to the world itself (world.get/world.set).
// Replaces the bitecs createWorld({...}) context bag. Only headless runtime
@@ -64,6 +65,16 @@ export const AudioEngine = trait({
// Fonts registered for text layout.
export const Fonts = trait({ list: () => [] as FontSource[] });
+// Asset metadata by id (model only; the app persists and rehydrates it).
+export const Assets = trait(() => new Map<string, Asset>());
+
+// Asset-library folder tree by id (model only, like Assets).
+export const Folders = trait(() => new Map<string, Folder>());
+
+// Allocation state for the project's shared asset/folder id space (sqids
+// over a monotonic counter), so an id never refers to both kinds.
+export const AssetIds = trait({ counter: 0 });
+
// Live JSX mount registry; running graphs advance once per frame.
export const Mounts = trait(() => createLiveMounts());
diff --git a/packages/runtime/src/utils/assert.ts b/packages/runtime/src/utils/assert.ts
new file mode 100644
index 00000000..2444272f
--- /dev/null
+++ b/packages/runtime/src/utils/assert.ts
@@ -0,0 +1,7 @@
+/* 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/. */
+
+export function assert(condition: unknown, message: string): asserts condition {
+ if (!condition) throw new Error(message);
+}
diff --git a/packages/runtime/src/utils/index.ts b/packages/runtime/src/utils/index.ts
index 4bae7df2..a458d2f2 100644
--- a/packages/runtime/src/utils/index.ts
+++ b/packages/runtime/src/utils/index.ts
@@ -1,5 +1,7 @@
-// Pure helpers only: time, sort, transition, captions follow. DOM-touching utils (cursor, interaction) stay in apps/web.
+// Pure helpers only: transition, captions follow. DOM-touching utils (cursor, interaction) stay in apps/web.
+export * from './assert';
export * from './text';
export * from './live-mounts';
export * from './sort';
export * from './text-motion';
+export * from './time';
diff --git a/packages/runtime/src/utils/time.ts b/packages/runtime/src/utils/time.ts
new file mode 100644
index 00000000..41bc5ad2
--- /dev/null
+++ b/packages/runtime/src/utils/time.ts
@@ -0,0 +1,102 @@
+/* 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 { CONONICAL_TIME_BASE, PaintType } from '../constants';
+import {
+ Audio, AssetId, Cache, Computed, Paint, PlaybackRate, Assets, FrameRate,
+} from '../traits';
+
+import type { Entity, World } from 'koota';
+import type { Asset } from '../assets/types';
+
+export function snapToMs(seconds: number) {
+ return Math.round(seconds * CONONICAL_TIME_BASE) / CONONICAL_TIME_BASE;
+}
+
+export function snapToFps(seconds: number, fps: number = 30) {
+ return Math.round(seconds * fps) / fps;
+}
+
+export function secondsToFrames(seconds: number = 0, fps: number = 30) {
+ return Math.round(seconds * fps);
+}
+
+export function framesToSeconds(frames: number = 0, fps: number = 30) {
+ return snapToMs(frames / fps);
+}
+
+/**
+ * Computes the trim start frame (local) for a given entity,
+ * based on the specified start frame (global) and playback rate.
+ */
+export function computeTrimStart(entity: Entity, start: number) {
+ const delay = entity.get(Computed)?.delay ?? 0;
+ const playbackRate = entity.get(PlaybackRate)?.value ?? 1;
+
+ return Math.round((start - delay) * playbackRate);
+}
+
+/**
+ * Computes the trim end frame (local) for a given entity,
+ * based on the specified end frame (global) and playback rate.
+ */
+export function computeTrimEnd(entity: Entity, end: number) {
+ const delay = entity.get(Computed)?.delay ?? 0;
+ const playbackRate = entity.get(PlaybackRate)?.value ?? 1;
+
+ return Math.round((end - delay) * playbackRate);
+}
+
+/** The asset backing a geometry: its own AssetId, or the first fill's. */
+export function findGeometryAsset(world: World, entity: Entity): Asset | null {
+ const assets = world.get(Assets);
+ if (!assets) return null;
+
+ const ownId = entity.get(AssetId)?.value;
+ if (ownId) {
+ const asset = assets.get(ownId);
+ if (asset) return asset;
+ }
+
+ for (const fill of entity.get(Cache)?.fills ?? []) {
+ const fillId = fill.get(AssetId)?.value;
+ if (fillId) {
+ const asset = assets.get(fillId);
+ if (asset) return asset;
+ }
+ }
+
+ return null;
+}
+
+/**
+ * Intrinsic duration (in project frames) of the media asset attached to an
+ * entity: the audio asset on Audio clips, else the first video/sequence fill.
+ * Null when nothing time-based is attached.
+ */
+export function findAssetDuration(world: World, entity: Entity): number | null {
+ const assets = world.get(Assets);
+ if (!assets) return null;
+ const frameRate = world.get(FrameRate)?.value ?? 30;
+
+ if (entity.has(Audio)) {
+ const asset = assets.get(entity.get(AssetId)?.value ?? '');
+
+ if (asset?.type === 'AUDIO' || asset?.type === 'VIDEO') {
+ return secondsToFrames(asset.duration, frameRate);
+ }
+ }
+
+ for (const fill of entity.get(Cache)?.fills ?? []) {
+ const paint = fill.get(Paint)?.value;
+ if (paint === PaintType.VIDEO || paint === PaintType.SEQUENCE) {
+ const asset = assets.get(fill.get(AssetId)?.value ?? '');
+ if (asset && (asset.type === 'VIDEO' || asset.type === 'SEQUENCE')) {
+ return secondsToFrames(asset.duration, frameRate);
+ }
+ }
+ }
+
+ return null;
+}
diff --git a/packages/runtime/src/world/create-world.ts b/packages/runtime/src/world/create-world.ts
index ceecbd4a..19813797 100644
--- a/packages/runtime/src/world/create-world.ts
+++ b/packages/runtime/src/world/create-world.ts
@@ -16,6 +16,9 @@ import {
RenderSurface,
AudioEngine,
Fonts,
+ Assets,
+ Folders,
+ AssetIds,
Mounts,
FramePromises,
} from '../traits/world';
@@ -38,6 +41,9 @@ export function createRuntimeWorld(projectId: string) {
RenderSurface,
AudioEngine,
Fonts,
+ Assets,
+ Folders,
+ AssetIds,
Mounts,
FramePromises,
);