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.jsonindex 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.mdnew file mode 100644index 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.mdindex 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.jsonindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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,);