Skip to content

The VS Code of video editing, built for agents.

TypeScript

Refactor mount and insert commands for improved clarity and functionality

konstantin-pauluse011b1d59377
diff --git a/apps/cli/reference/README.md b/apps/cli/reference/README.md
index 8119f399..ecc06222 100644
--- a/apps/cli/reference/README.md
+++ b/apps/cli/reference/README.md
@@ -48,7 +48,7 @@ How the surface is divided:
- [`dapi node tree`](./node/tree.md): an entity's subtree as nested JSON
- [`dapi node grep`](./node/grep.md): search entity records with a regex
- [`dapi node capture`](./node/capture.md): capture a node as a PNG
-- [`dapi node insert`](./node/insert.md): render a JSX module into an existing parent
+- [`dapi node insert`](./node/insert.md): insert JSX tags into an existing parent
- [`dapi node rm`](./node/rm.md): delete entities
- [`dapi node cp`](./node/cp.md): deep-clone nodes
- [`dapi node patch`](./node/patch.md): assign JSX props on existing entities
diff --git a/apps/cli/reference/jsx/README.md b/apps/cli/reference/jsx/README.md
index b7aa8720..7c3ac8df 100644
--- a/apps/cli/reference/jsx/README.md
+++ b/apps/cli/reference/jsx/README.md
@@ -28,7 +28,7 @@ The pipeline is driven by two commands: [`dapi mount`](../mount.md) renders the
| [audio-sync.md](./audio-sync.md) | `syncTo` audio alignment |
| [captions.md](./captions.md) | `<captions>` and style presets |
| [generate.md](./generate.md) | Declarative AI asset generation (`generate.*`) |
-| [lifecycle.md](./lifecycle.md) | Render lifecycle: one-shot vs `--live`, `useTicker` |
+| [lifecycle.md](./lifecycle.md) | Mount lifecycle: always live, persisted + re-executed, `useTicker` |
| [errors.md](./errors.md) | Where each pipeline stage fails and with what effect |
## Pipeline
diff --git a/apps/cli/reference/jsx/html-paint.md b/apps/cli/reference/jsx/html-paint.md
index 5a2f80e6..7a30d762 100644
--- a/apps/cli/reference/jsx/html-paint.md
+++ b/apps/cli/reference/jsx/html-paint.md
@@ -17,7 +17,7 @@ Inside `<html>`, every tag is a DOM element: names the editor also uses (`<rect>
## Reactivity
-The children are part of the project's Solid graph: signals in attributes and text update the live DOM, and the drawn content follows on the next frame. With [`dapi mount --live`](../mount.md) the graph stays alive, so `useTicker` or timers can drive the markup:
+The children are part of the project's Solid graph: signals in attributes and text update the live DOM, and the drawn content follows on the next frame. A [`dapi mount`](../mount.md) stays live, so the graph keeps running and `useTicker` or timers can drive the markup:
```tsx
const [count, setCount] = createSignal(0);
diff --git a/apps/cli/reference/jsx/lifecycle.md b/apps/cli/reference/jsx/lifecycle.md
index c89688ea..69f7ff57 100644
--- a/apps/cli/reference/jsx/lifecycle.md
+++ b/apps/cli/reference/jsx/lifecycle.md
@@ -1,31 +1,16 @@
# Lifecycle
-## One-shot render (default)
+## A mount stays live
-Mounting is a **one-shot render**: the reactive graph exists to *compose* the document (loops, conditionals, derived values, component props), not to drive it afterward.
+After `dapi mount` returns, its reactive graph keeps running: signals, effects, timers, and [`useTicker`](#useticker) keep driving the mounted entities. Updates land in the document immediately (not as undo steps) — prop writes, conditional inserts and removals (`<Show>`, `<For>`), text, and reactive `src` swaps including `generate.*`. The materialized nodes are ordinary editable entities; asset generation is owned by the engine. `syncTo` and new `<captions>` are mount-only and throw if changed after commit. A run ends when a later `mount` claims one of its root keys (swapping the entities and disposing the old graph) or the project closes.
-1. The component tree renders synchronously into the staging root; `onMount` callbacks flush once.
-2. The subtree commits and the reactive root is **disposed**. Signal changes after commit do not affect the document.
-3. Ownership transfers to the document: every materialized node is a fully editable composition node. Asset generation is owned by the engine, not the reactive graph, so it proceeds normally after disposal.
+The compiled module is persisted with the document and re-executed in every context: reload rebuilds the graph and its runtime hosts (`<surface>`/`<html>`), and export and capture drive the ticker across the frames they render. Re-execution binds to the existing entities rather than re-authoring them, so hand-edits survive; it rewrites only the props your effects animate. This requires the module's structure to be deterministic: `Math.random()` and `Date.now()` must not decide element counts or `<Show>`/`<For>` branches (using them inside an effect is fine).
-The update path is **re-running the project**, which rebuilds the mount root in place, like refreshing a webpage; unchanged asset specs hit the generation cache.
-
-## Live mode (`dapi mount --live`)
-
-`--live` skips the disposal in step 2: the reactive root stays mounted after the command returns, so signals, effects, and timers keep driving the composition. Everything else is unchanged; the nodes are ordinary editable entities and generation blocks the command as usual.
-
-A live run ends when:
-
-- a later `mount` (live or not) claims one of its root keys: the keyed replacement swaps the entities and disposes the old graph (`onCleanup` callbacks flush), or
-- the project or app closes.
-
-Inside a live graph, updates behave as in any Solid app: prop writes, conditional inserts and removals (`<Show>`, `<For>`), and text updates land in the document immediately. They are not recorded as undo steps. A reactive `src` swap works, including `generate.*` refs (the node shows its generating state until the new asset lands). Two things stay mount-only and throw if changed after commit: `syncTo` and creating new `<captions>`; re-mount for those.
-
-`node insert` is always one-shot; only `mount` supports `--live`.
+`node insert` renders into an existing parent and is not persisted or kept live.
## `useTicker`
-Live graphs can subscribe to the project's timeline instead of reaching for wall-clock timers:
+A mount can subscribe to the project's timeline instead of reaching for wall-clock timers:
```tsx
import { useTicker } from "@diffusionstudio/jsx";
@@ -50,7 +35,7 @@ Call it in a component body. It returns accessors for the playhead of the scene
| `delta()` | Seconds advanced since the previous engine tick: 0 while paused, negative on a backward scrub or loop |
| `playing()` | Whether the scene is playing |
-The values respect play, pause, scrubbing, looping, and playback speed, which wall-clock timers do not. Each accessor only propagates when its value changes, so a paused scene re-runs nothing and `frame()` consumers update at most once per frame. In a one-shot mount the first value renders and then freezes; the hook is only useful with `--live`.
+The values respect play, pause, scrubbing, looping, and playback speed, which wall-clock timers do not. Each accessor only propagates when its value changes, so a paused scene re-runs nothing and `frame()` consumers update at most once per frame. Ticker-driven drawing follows the playhead in the editor and in exports and captures; wall-clock timers (`setInterval`, `requestAnimationFrame`) render live but do not appear in exports.
## `useFile`
@@ -76,4 +61,4 @@ function Logo() {
}
```
-Returns Solid's `createResource` tuple unchanged: `[file, { mutate, refetch }]`. The `file` accessor reads `undefined` until resolution completes, then the `File`; `file.loading` and `file.error` report progress and failure. Resolution is async (fetch a URL, read a path or library asset, await a `generate.*` ref) and only runs in a live graph; in a one-shot mount there is no effect to consume the result.
+Returns Solid's `createResource` tuple unchanged: `[file, { mutate, refetch }]`. The `file` accessor reads `undefined` until resolution completes, then the `File`; `file.loading` and `file.error` report progress and failure. Resolution is async (fetch a URL, read a path or library asset, await a `generate.*` ref); export and capture await the first resolution before rendering frame 0. A `node insert` has no surviving effect to consume the result.
diff --git a/apps/cli/reference/jsx/paints.md b/apps/cli/reference/jsx/paints.md
index da425b43..69e9cc1b 100644
--- a/apps/cli/reference/jsx/paints.md
+++ b/apps/cli/reference/jsx/paints.md
@@ -26,4 +26,4 @@ Both names of a pair work everywhere; names shared with SVG (`<linearGradient>`,
Colors accept any CSS color; alpha is ignored (use `opacity`). `color`, `opacity`, and `offset` are animatable (see [keyframes.md](./keyframes.md)), so gradients can animate. Paints have no spatial or timing props and cannot be document roots.
-Paints are live entities like any other: patch them with [`dapi node patch`](../node/patch.md), and add a stop to an existing gradient with [`dapi node insert`](../node/insert.md) (`node insert <paintId> --code '<colorStop offset={0.5} color="#FF0055" />'`).
+Paints are live entities like any other: patch them with [`dapi node patch`](../node/patch.md), and add a stop to an existing gradient with [`dapi node insert`](../node/insert.md) (`node insert <paintId> '<colorStop offset={0.5} color="#FF0055" />'`).
diff --git a/apps/cli/reference/jsx/surface-paint.md b/apps/cli/reference/jsx/surface-paint.md
index c96a9f2e..da96745a 100644
--- a/apps/cli/reference/jsx/surface-paint.md
+++ b/apps/cli/reference/jsx/surface-paint.md
@@ -25,7 +25,7 @@ A paint backed by a **canvas you draw yourself** (long form: `<surfacePaint>`).
## Reactivity
-The engine samples the canvas every frame, so anything you draw shows up on the next frame. Under [`dapi mount --live`](../mount.md) the reactive graph stays alive: create effects in the ref to redraw from signals, or drive frame-accurate motion from the ticker's composition time:
+The engine samples the canvas every frame, so anything you draw shows up on the next frame. A [`dapi mount`](../mount.md) stays live, so the reactive graph keeps running: create effects in the ref to redraw from signals, or drive frame-accurate motion from the ticker's composition time:
```tsx
<surface width={400} height={400}
@@ -79,8 +79,12 @@ Anything that accepts an existing canvas plugs in directly; a detached canvas is
Like all paints it stacks with siblings in document order and clips to the parent's box (including `cornerRadius`). `<surfacePaint>` takes no children.
+## Persistence and export
+
+The compiled module is persisted with the document, so the drawing is reproducible, not ephemeral: on reload, export, and `dapi node capture` the engine re-executes it and redraws into a fresh canvas driven by that context's playhead, so ticker surfaces animate in exports. The bitmap itself is not stored; your code reproduces it. This assumes the module's structure is deterministic (`Math.random()`/`Date.now()` must not decide the shape of the tree; using them inside a draw effect is fine).
+
## Requirements and limitations
-- The drawing is code, so the content lives only as long as its mount: it is not persisted with the document. Exports and captures started while the mount is alive sample the live canvas.
+- Duplicating or copy-pasting a mounted surface yields a static copy (the drawing does not re-run for the copy); re-mount to get a fresh animated instance.
- Only the `ref` attribute form on the element itself is routed; refs inside spread props are not.
- A real DOM `<canvas>` is not available inside [`<html>`](./html-paint.md) content — its pixels don't survive the html-in-canvas rasterization. Use `<surface>` for hand-drawn graphics instead.
diff --git a/apps/cli/reference/mount.md b/apps/cli/reference/mount.md
index dd27b438..1386591d 100644
--- a/apps/cli/reference/mount.md
+++ b/apps/cli/reference/mount.md
@@ -11,9 +11,9 @@ Exactly one of:
- `<path>`: path to a `.tsx` / `.jsx` / `.ts` / `.js` entry module.
- `--code <str>`: inline module source, compiled identically. The `export default () =>` wrapper is optional; a bare JSX expression (no `export default` in the source) is wrapped into a component module automatically.
-Optionally:
+## Lifecycle
-- `--live`: keep the reactive graph alive after mounting, so signals, effects, timers, and [`useTicker`](./jsx/lifecycle.md#useticker) keep driving the mounted entities. Without it the graph is disposed once the mount lands (the entities stay, reactivity stops). A live run ends when a later mount claims one of its root keys or the project closes (see [jsx/lifecycle.md](./jsx/lifecycle.md)).
+A mount stays live: its reactive graph keeps running after the command returns, so signals, effects, timers, and [`useTicker`](./jsx/lifecycle.md#useticker) keep driving the mounted entities. The compiled module is persisted with the document and re-executed in every context, so the mount is restored on reload and its ticker-driven [`<surface>`](./jsx/surface-paint.md)/[`<html>`](./jsx/html-paint.md) animate in exports and captures (the module's structure must be deterministic). See [jsx/lifecycle.md](./jsx/lifecycle.md).
## Output
diff --git a/apps/cli/reference/node/insert.md b/apps/cli/reference/node/insert.md
index 419759a0..ed79e398 100644
--- a/apps/cli/reference/node/insert.md
+++ b/apps/cli/reference/node/insert.md
@@ -1,17 +1,15 @@
-# `dapi node insert <parentId> (<path> | --code <str>) [--index <N>]`
+# `dapi node insert <parentId> <code> [--index <N>]`
-Compiles a Solid JSX project module and executes it in the app; the same pipeline as [`mount`](../mount.md), including declared asset generation, but instead of mounting the rendered roots into the document, inserts them as children of an existing entity. Because the result is inserted rather than reconciled, root elements take no `key`: every run inserts fresh entities; there is no replace-or-create matching and nothing is deleted.
+Compiles an inline JSX fragment and inserts its rendered roots as children of an existing entity; the same pipeline as [`mount`](../mount.md), including declared asset generation, but instead of mounting into the document it inserts under an existing parent. Because the result is inserted rather than reconciled, root elements take no `key`: every run inserts fresh entities; there is no replace-or-create matching and nothing is deleted.
-The full JSX code syntax lives in [jsx/](../jsx/README.md).
+The payload is **bare JSX tags** — no `export default`, no file path. Unlike `mount`, an insert renders once and is then discarded: it is never persisted, restored, or kept live, so a component that relies on reactivity (signals, effects, `useTicker`) has nothing to drive it. Reach for [`mount`](../mount.md) when you want a live, reproducible program. The full JSX syntax lives in [jsx/](../jsx/README.md).
-The rendered roots must be valid as children of the target parent, following the JSX containment rules: a node parent takes any element or paint root except `<scene>` (scenes only exist at the document top level) and `<colorStop>`; a gradient paint parent takes only `<colorStop>` roots. That is how a stop is added to an existing gradient (`node insert <paintId> --code '<colorStop offset={0.5} color="#FF0055" />'`); other sub-entities take no children.
+The rendered roots must be valid as children of the target parent, following the JSX containment rules: a node parent takes any element or paint root except `<scene>` (scenes only exist at the document top level) and `<colorStop>`; a gradient paint parent takes only `<colorStop>` roots. That is how a stop is added to an existing gradient (`node insert <paintId> '<colorStop offset={0.5} color="#FF0055" />'`); other sub-entities take no children.
## Input
- `<parentId>`: entity id of the parent to insert into (required)
-- Project module, exactly one of:
- - `<path>`: path to the module file
- - `--code <str>`: inline module source; the `export default () =>` wrapper is optional, a bare JSX expression is wrapped automatically (e.g. `--code '<rect width={100} height={100} />'`)
+- `<code>`: inline JSX tags to insert, e.g. `'<rect width={100} height={100} />'` (required). Bare tags only — the source is rejected before contacting the app if it contains `export default` or doesn't look like JSX.
- `-i, --index <N>`: the inserted node's 0-based position among the parent's children, a non-negative integer (optional; default = append after the last child; values past the end are clamped). Node roots only: paints stack in insertion order and color stops render sorted by `offset`, so `--index` is rejected for them.
## Output
@@ -20,4 +18,4 @@ None.
## Errors
-Exits non-zero if `<parentId>` doesn't resolve to a live entity, if compilation or evaluation fails, if a rendered root is invalid as a child of the parent (e.g. a `<scene>`, or a non-`<colorStop>` in a gradient paint), or if `--index` is given for a paint or color stop root. On any of these, **nothing is inserted**.
+Exits non-zero if `<code>` is not a bare JSX fragment (contains `export default`, or has no tags), if `<parentId>` doesn't resolve to a live entity, if compilation or evaluation fails, if a rendered root is invalid as a child of the parent (e.g. a `<scene>`, or a non-`<colorStop>` in a gradient paint), or if `--index` is given for a paint or color stop root. On any of these, **nothing is inserted**.
diff --git a/apps/cli/src/cli-channels.ts b/apps/cli/src/cli-channels.ts
index 55d3c0cc..e390b66f 100644
--- a/apps/cli/src/cli-channels.ts
+++ b/apps/cli/src/cli-channels.ts
@@ -68,7 +68,6 @@ export type NodeDeleteResult = { id: number };
export type MountRequest = {
code: string;
- live?: boolean;
};
export type NodeInsertRequest = {
diff --git a/apps/cli/src/index.ts b/apps/cli/src/index.ts
index f763e709..0ed7c005 100644
--- a/apps/cli/src/index.ts
+++ b/apps/cli/src/index.ts
@@ -669,7 +669,7 @@ async function mediaWaveform(ref: string, opts: MediaPreviewOptions): Promise<vo
const MOUNT_EXTENSIONS = new Set([".tsx", ".jsx", ".ts", ".js"]);
-type MountOptions = { code?: string; live?: boolean };
+type MountOptions = { code?: string };
// Validates the (<path> | --code) pair shared by `mount` and `node insert`,
// then compiles the module. Compile errors fail here, before the app is contacted.
@@ -708,7 +708,7 @@ async function mountProject(path: string | undefined, opts: MountOptions): Promi
const stop = startSpinner("Mounting project");
try {
- await editor.mount.mutate({ code, live: opts.live }, GENERATE);
+ await editor.mount.mutate({ code }, GENERATE);
stop();
} catch (e) {
stop();
@@ -716,9 +716,9 @@ async function mountProject(path: string | undefined, opts: MountOptions): Promi
}
}
-type NodeInsertOptions = MountOptions & { index?: string };
+type NodeInsertOptions = { index?: string };
-async function nodeInsert(parentId: string, path: string | undefined, opts: NodeInsertOptions): Promise<void> {
+async function nodeInsert(parentId: string, source: string, opts: NodeInsertOptions): Promise<void> {
const [eid] = parseNodeIds([parentId]);
let index: number | undefined;
@@ -731,7 +731,25 @@ async function nodeInsert(parentId: string, path: string | undefined, opts: Node
index = n;
}
- const code = await compileProjectInput(path, opts.code);
+ // `insert` takes a JSX fragment inline, not a module or a file: it renders
+ // once and is discarded, so a live program has nothing to drive it. Validate
+ // loosely — reject the module form and require something that looks like a tag.
+ if (/\bexport\s+default\b/.test(source)) {
+ console.error("`dapi node insert` takes JSX tags, not a component module — drop `export default` (use `dapi mount` for a live program).");
+ process.exit(1);
+ }
+ if (!/<\s*[A-Za-z]/.test(source)) {
+ console.error("`dapi node insert` expects JSX tags, e.g. '<rect width={10} height={10} />'.");
+ process.exit(1);
+ }
+
+ let code: string;
+ try {
+ code = await compileProject({ code: source });
+ } catch (e) {
+ console.error((e as Error).message);
+ process.exit(1);
+ }
const stop = startSpinner("Inserting entities");
try {
@@ -1070,14 +1088,10 @@ program
program
.command("mount")
.description(
- `Compile a Solid JSX project module and mount its roots into the canvas. Re-mounting reconciles rather than duplicates: each top-level element carries a \`key\`, and a root replaces the node with that key or creates it (a new <scene key> becomes the active scene and the camera focuses it). By default the module's reactive graph is disposed once the mount lands (the entities stay, but signals, effects, and timers stop); pass --live to keep it running. Long-running when the module declares AI assets (blocks until generation finishes). Compile errors fail before the app is contacted; on success, inspect the result with \`dapi context\` or \`dapi node tree\`.`,
+ `Compile a Solid JSX project module and mount its roots into the canvas. Re-mounting reconciles rather than duplicates: each top-level element carries a \`key\`, and a root replaces the node with that key or creates it (a new <scene key> becomes the active scene and the camera focuses it). A mount stays live: its reactive graph keeps running (signals, effects, timers, \`useTicker\`), and the persisted module is re-executed in every context, so the mount is restored on reload and ticker-driven <surface>/<html> animate in exports and captures (structure must be deterministic). Long-running when the module declares AI assets (blocks until generation finishes). Compile errors fail before the app is contacted; inspect the result with \`dapi context\` or \`dapi node tree\`.`,
)
.argument("[path]", "path to a .tsx / .jsx / .ts / .js entry module")
.option("--code <str>", "inline module source; export default wrapper optional for bare JSX")
- .option(
- "--live",
- "keep the reactive graph alive after mounting: signals, effects, and timers keep driving the mounted entities until the app closes or a later mount claims one of its root keys (same key -> the old run is unmounted)",
- )
.action((path: string | undefined, opts: MountOptions) => mountProject(path, opts));
const asset = program
@@ -1339,13 +1353,12 @@ node
node
.command("insert")
.description(
- `Compile a Solid JSX project module and insert its rendered roots as children of an existing entity: the same pipeline as \`mount\` (including AI asset generation), but it inserts fresh entities every run rather than reconciling by key, and deletes nothing. Roots must be valid children of the parent (a node takes any element or paint except <scene> and <colorStop>; a gradient paint takes only <colorStop> roots, which is how you add a stop to a gradient).`,
+ `Insert JSX tags as children of an existing entity. The payload is an inline JSX fragment, e.g. \`'<rect width={10} height={10} />'\` — bare tags, no \`export default\`: an insert renders once and is discarded, so there is no live graph to drive (use \`dapi mount\` for anything reactive). Otherwise it shares the \`mount\` pipeline, including AI asset generation, but inserts fresh entities every run rather than reconciling by key, and deletes nothing. Roots must be valid children of the parent (a node takes any element or paint except <scene> and <colorStop>; a gradient paint takes only <colorStop> roots, which is how you add a stop to a gradient).`,
)
.argument("<parentId>", "entity id of the parent to insert into — a node, or a gradient paint for <colorStop> roots")
- .argument("[path]", "path to a .tsx / .jsx / .ts / .js entry module")
- .option("--code <str>", "inline module source; export default wrapper optional for bare JSX")
+ .argument("<code>", "JSX tags to insert, e.g. '<rect width={10} height={10} />' (no export default)")
.option("-i, --index <n>", "0-based position among the parent's existing children (node roots only; default: append at the end)")
- .action((parentId: string, path: string | undefined, opts: NodeInsertOptions) => nodeInsert(parentId, path, opts));
+ .action((parentId: string, code: string, opts: NodeInsertOptions) => nodeInsert(parentId, code, opts));
node
.command("rm")
diff --git a/apps/web/src/components/engine/api/assets.ts b/apps/web/src/components/engine/api/assets.ts
index ca3b4169..67fd257f 100644
--- a/apps/web/src/components/engine/api/assets.ts
+++ b/apps/web/src/components/engine/api/assets.ts
@@ -383,6 +383,52 @@ async function probeMediaMetadata(file: Blob, mimeType: string) {
assert(false, 'Unsupported file type');
}
+/**
+ * Stores a compiled project module (the source a `dapi mount` executed) as a
+ * content-addressed SCRIPT asset, so any world can re-run it. The hash is a
+ * SHA-256 of the module text, so identical re-mounts dedup to one asset. The
+ * bytes live as a `.js` file in the same OPFS `assets` folder as any media.
+ */
+export async function createScriptAsset(world: EngineWorld, code: string): Promise<Asset> {
+ const state = assetState(world);
+
+ const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(code));
+ const hash = 'script:' + Array.from(new Uint8Array(digest))
+ .map((b) => b.toString(16).padStart(2, '0'))
+ .join('');
+
+ const existing = Array.from(world.assets.values()).find((asset) => asset.hash === hash);
+ if (existing) return existing;
+
+ const id = allocateId(world);
+ const mimeType = 'text/javascript';
+ const uniqueName = id + mimeTypeToExtension(mimeType);
+
+ const directory = await state.directoryHandle;
+ const assetsFolder = await directory.getDirectoryHandle('assets', { create: true });
+ const fileHandle = await assetsFolder.getFileHandle(uniqueName, { create: true });
+ const writable = await fileHandle.createWritable();
+ await writable.write(new Blob([code], { type: mimeType }));
+ await writable.close();
+
+ const file = await fileHandle.getFile();
+
+ return saveAsset(world, {
+ id,
+ hash,
+ createdAt: new Date().toISOString(),
+ lastModified: file.lastModified,
+ name: uniqueName,
+ mimeType,
+ size: file.size,
+ handle: fileHandle,
+ generationId: null,
+ generationKey: null,
+ folderId: null,
+ type: 'SCRIPT',
+ });
+}
+
/**
* Describes a local file as an ephemeral Asset: full metadata, but no id
* allocation and no persistence — the library is never touched. The path
diff --git a/apps/web/src/components/engine/api/clipboard.ts b/apps/web/src/components/engine/api/clipboard.ts
index de6aeced..48ab6cda 100644
--- a/apps/web/src/components/engine/api/clipboard.ts
+++ b/apps/web/src/components/engine/api/clipboard.ts
@@ -3,7 +3,7 @@
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
import { hasComponent, query, Or } from 'bitecs';
-import { cloneFromRecords, cloneSubtree, serializeEntity } from './serialize';
+import { cloneFromRecords, cloneSubtree, serializeEntity, stripMountIdentity } from './serialize';
import { getEntityTree } from './query';
import { getParentEntity } from './base';
import { addComponent, clearComponent, setComponent } from './events';
@@ -41,7 +41,7 @@ export function pasteClipboard(world: EngineWorld) {
const copyRootEids: number[] = [];
for (const snapshot of clipboard) {
- const result = cloneFromRecords(world, snapshot.records);
+ const result = cloneFromRecords(world, stripMountIdentity(snapshot.records));
const rootCopyEid = result.get(snapshot.root);
if (!rootCopyEid || (!hasComponent(world, rootCopyEid, c.Geometry) && !hasComponent(world, rootCopyEid, c.Group))) continue;
diff --git a/apps/web/src/components/engine/api/engine.ts b/apps/web/src/components/engine/api/engine.ts
index 895936d7..06e567cb 100644
--- a/apps/web/src/components/engine/api/engine.ts
+++ b/apps/web/src/components/engine/api/engine.ts
@@ -15,6 +15,7 @@ import { inputSystem } from '../systems/input-system';
import { createCameraController } from '../systems';
import { hudSystem } from '../systems/hud';
import { createKeyboardSystem } from '../systems/keyboard';
+import { realizeMounts } from '@/utils/mount';
import { createSignal } from 'solid-js';
import type Stats from 'stats.js';
@@ -42,6 +43,7 @@ export function createEngine(id: string) {
keyboard.init();
await restoreWorld(world);
+ await realizeMounts(world);
const c = world.components;
// Auto-select the first scene as the active timeline
diff --git a/apps/web/src/components/engine/api/observers.ts b/apps/web/src/components/engine/api/observers.ts
index 8c250df6..77965a4d 100644
--- a/apps/web/src/components/engine/api/observers.ts
+++ b/apps/web/src/components/engine/api/observers.ts
@@ -127,6 +127,18 @@ export function observeWorld(world: EngineWorld) {
utils.persistEntity(world, eid);
});
+ observe(world, "set", c.MountScript, (eid, { mountId, scriptAssetId }) => {
+ c.MountScript.mountId[eid] = mountId ?? c.MountScript.mountId[eid] ?? "";
+ c.MountScript.scriptAssetId[eid] = scriptAssetId ?? c.MountScript.scriptAssetId[eid] ?? "";
+ utils.persistEntity(world, eid);
+ });
+
+ observe(world, "set", c.MountPath, (eid, { mountId, path }) => {
+ c.MountPath.mountId[eid] = mountId ?? c.MountPath.mountId[eid] ?? "";
+ c.MountPath.path[eid] = path ?? c.MountPath.path[eid] ?? "";
+ utils.persistEntity(world, eid);
+ });
+
observe(world, "set", c.Position, (eid, { x, y }) => {
c.Position.x[eid] = x ?? c.Position.x[eid] ?? 0;
c.Position.y[eid] = y ?? c.Position.y[eid] ?? 0;
diff --git a/apps/web/src/components/engine/api/serialize.ts b/apps/web/src/components/engine/api/serialize.ts
index 9e3577b1..319244f0 100644
--- a/apps/web/src/components/engine/api/serialize.ts
+++ b/apps/web/src/components/engine/api/serialize.ts
@@ -50,6 +50,18 @@ export function serializeEntity(world: EngineWorld, eid: number): DBEntity {
if (hasComponent(world, eid, c.Key)) {
record.Key = c.Key[eid];
}
+ if (hasComponent(world, eid, c.MountScript)) {
+ record.MountScript = {
+ mountId: c.MountScript.mountId[eid],
+ scriptAssetId: c.MountScript.scriptAssetId[eid],
+ };
+ }
+ if (hasComponent(world, eid, c.MountPath)) {
+ record.MountPath = {
+ mountId: c.MountPath.mountId[eid],
+ path: c.MountPath.path[eid],
+ };
+ }
if (hasComponent(world, eid, c.ItemIndex)) {
record.ItemIndex = c.ItemIndex[eid] ?? 0;
}
@@ -268,6 +280,12 @@ export function deserializeEntity(world: EngineWorld, eid: number, e: Partial<DB
if (e.Key !== undefined) {
setComponent(world, eid, c.Key, e.Key);
}
+ if (e.MountScript !== undefined) {
+ setComponent(world, eid, c.MountScript, e.MountScript);
+ }
+ if (e.MountPath !== undefined) {
+ setComponent(world, eid, c.MountPath, e.MountPath);
+ }
if (e.ItemIndex !== undefined) {
setComponent(world, eid, c.ItemIndex, e.ItemIndex);
}
@@ -424,7 +442,19 @@ export function cloneFromRecords(world: EngineWorld, records: DBEntity[]) {
return eidMap;
}
+/**
+ * Strips mount identity from records so a *same-world* copy doesn't collide
+ * with the original mount's id — adopt would otherwise bind two entities to one
+ * `MountPath`. A duplicated/pasted mount becomes plain static entities: its
+ * runtime hosts won't re-run (a documented limitation; re-mount to re-animate).
+ * The export/capture clone (`cloneFromRecords` directly) keeps identity so it
+ * can adopt.
+ */
+export function stripMountIdentity(records: DBEntity[]): DBEntity[] {
+ return records.map(({ MountScript: _script, MountPath: _path, ...rest }) => rest);
+}
+
export function cloneSubtree(world: EngineWorld, tree: number[]) {
const records = tree.map(e => serializeEntity(world, e));
- return cloneFromRecords(world, records);
+ return cloneFromRecords(world, stripMountIdentity(records));
}
diff --git a/apps/web/src/components/engine/components/components.ts b/apps/web/src/components/engine/components/components.ts
index 9b3d7813..7ad56601 100644
--- a/apps/web/src/components/engine/components/components.ts
+++ b/apps/web/src/components/engine/components/components.ts
@@ -76,6 +76,21 @@ export const Name = [] as string[];
// Stable identity for entities.
export const Key = [] as string[];
+// On a mount's root entity: the compiled module (a SCRIPT asset) that a world
+// re-executes to rebuild this mount's reactive graph and runtime hosts.
+export const MountScript = {
+ mountId: [] as string[],
+ scriptAssetId: [] as string[],
+};
+
+// On every entity a mount materializes: its stable structural key (an index
+// path from the mount root), so a re-run in adopt mode can bind to the existing
+// entity instead of minting a new one.
+export const MountPath = {
+ mountId: [] as string[],
+ path: [] as string[],
+};
+
export const Position = {
x: [] as number[],
y: [] as number[],
diff --git a/apps/web/src/components/engine/db/schemas.ts b/apps/web/src/components/engine/db/schemas.ts
index de8071c5..1631d4ec 100644
--- a/apps/web/src/components/engine/db/schemas.ts
+++ b/apps/web/src/components/engine/db/schemas.ts
@@ -119,6 +119,12 @@ export const transcriptAssetSchema = assetBaseSchema.extend({
export type TranscriptAsset = z.infer<typeof transcriptAssetSchema>;
+export const scriptAssetSchema = assetBaseSchema.extend({
+ type: z.literal('SCRIPT'),
+});
+
+export type ScriptAsset = z.infer<typeof scriptAssetSchema>;
+
// `handle` points to the first frame's file (so generic preview/thumbnail
export const sequenceAssetSchema = assetBaseSchema.extend({
type: z.literal('SEQUENCE'),
@@ -136,6 +142,7 @@ export const assetSchema = z.discriminatedUnion('type', [
audioAssetSchema,
videoAssetSchema,
transcriptAssetSchema,
+ scriptAssetSchema,
sequenceAssetSchema,
]);
diff --git a/apps/web/src/components/engine/encode/encoder.ts b/apps/web/src/components/engine/encode/encoder.ts
index a4915be6..15dc1fad 100644
--- a/apps/web/src/components/engine/encode/encoder.ts
+++ b/apps/web/src/components/engine/encode/encoder.ts
@@ -24,11 +24,10 @@ import { playbackSystem } from '../systems/playback';
import { motionSystem } from '../systems/motion';
import { transformSystem } from '../systems/transform';
import { renderSystem } from '../systems/render';
-import { shareHtmlHosts } from '../decoders/html';
-import { shareSurfaceHosts } from '../decoders/surface';
import { cloneFromRecords, serializeEntity } from '../api/serialize';
import { getEntityTree } from '../api/query';
import { AudioBus } from '../services/audio-bus';
+import { realizeMounts } from '@/utils/mount';
import type { EngineWorld } from '../api/world';
import type { EncoderConfig } from './interfaces';
@@ -133,10 +132,10 @@ export async function createEncoder(sourceWorld: EngineWorld, config: EncoderCon
c.AudioPlayback.contextOffsetInSeconds[sceneEid] = 0;
c.AudioPlayback.timelineOffsetInSeconds[sceneEid] = playheadStartSeconds;
- if (videoEnabled) {
- shareHtmlHosts(sourceWorld, world, eidMap);
- shareSurfaceHosts(sourceWorld, world, eidMap);
- }
+ // Re-execute any mounts into this offline world so it owns its own reactive
+ // graphs + runtime hosts (surface/html). The per-frame playbackSystem then
+ // drives them via world.liveMounts, so ticker-animated surfaces render.
+ const mounts = videoEnabled ? await realizeMounts(world) : null;
// Set up mediabunny output
const buffer = await TargetBuffer.create(config.target);
@@ -339,6 +338,10 @@ export async function createEncoder(sourceWorld: EngineWorld, config: EncoderCon
};
} finally {
URL.revokeObjectURL(audioWorkletUrl);
+ // Free the graphs + hosts realized above (this offline world is
+ // discarded, so nothing else disposes them — an HtmlHost otherwise
+ // leaks a canvas on document.body).
+ mounts?.disposeAll();
}
};
diff --git a/apps/web/src/components/engine/encode/image-encoder.ts b/apps/web/src/components/engine/encode/image-encoder.ts
index e55df055..2c74ad28 100644
--- a/apps/web/src/components/engine/encode/image-encoder.ts
+++ b/apps/web/src/components/engine/encode/image-encoder.ts
@@ -18,6 +18,7 @@ import { cloneFromRecords, serializeEntity } from '../api/serialize';
import { shareHtmlHosts } from '../decoders/html';
import { shareSurfaceHosts } from '../decoders/surface';
import { getEntityTree } from '../api/query';
+import { realizeMounts } from '@/utils/mount';
import { framesToSeconds, formatTimestamp, stampTimestampLabel } from '../utils';
import { assert } from '@/utils';
@@ -86,6 +87,7 @@ export async function createImageEncoder(sourceWorld: EngineWorld, config: Image
shareHtmlHosts(sourceWorld, world, eidMap);
shareSurfaceHosts(sourceWorld, world, eidMap);
+ const mounts = await realizeMounts(world);
const clonedEids = [...eidMap.values()];
const c = world.components;
@@ -208,6 +210,10 @@ export async function createImageEncoder(sourceWorld: EngineWorld, config: Image
type: 'error',
error: e instanceof Error ? e : new Error('Unknown error'),
};
+ } finally {
+ // Free the graphs + hosts realized above (this offline world is
+ // discarded; realized HtmlHosts otherwise leak a canvas on document.body).
+ mounts.disposeAll();
}
};
diff --git a/apps/web/src/components/engine/types/db.ts b/apps/web/src/components/engine/types/db.ts
index f847d5a4..f87aed6a 100644
--- a/apps/web/src/components/engine/types/db.ts
+++ b/apps/web/src/components/engine/types/db.ts
@@ -24,6 +24,14 @@ export interface DBEntity {
Stroke?: {};
Name?: string;
Key?: string;
+ MountScript?: {
+ mountId: string;
+ scriptAssetId: string;
+ };
+ MountPath?: {
+ mountId: string;
+ path: string;
+ };
ChildOf?: number;
ItemIndex?: number;
ClipHeight?: number;
diff --git a/apps/web/src/components/engine/utils/live-mounts.ts b/apps/web/src/components/engine/utils/live-mounts.ts
index 8ff079ae..97961708 100644
--- a/apps/web/src/components/engine/utils/live-mounts.ts
+++ b/apps/web/src/components/engine/utils/live-mounts.ts
@@ -3,15 +3,17 @@
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
/**
- * Live JSX mounts (`dapi mount --live`) keep their Solid reactive graph
- * running after the mount lands, so signals, effects, and timers keep
- * driving the mounted entities. A run stays alive until the world is
+ * JSX mounts (`dapi mount`) keep their Solid reactive graph running after
+ * the mount lands, so signals, effects, and timers keep driving the mounted
+ * entities. A run stays alive until the world is
* disposed or a later mount claims one of its root keys: the keyed root
* replacement already deletes its entities, so the superseded graph is
* disposed with them. Root keys are read live rather than snapshotted, so
* roots a running graph adds or removes later still reconcile.
*/
export type LiveMount = {
+ /** Identity shared by every entity of this mount; unique per running graph. */
+ mountId: string;
rootKeys: () => string[];
advance: () => void;
dispose: () => void;
@@ -27,6 +29,12 @@ export function createLiveMounts() {
mount.advance();
}
},
+ hasMount(mountId: string): boolean {
+ for (const mount of mounts) {
+ if (mount.mountId === mountId) return true;
+ }
+ return false;
+ },
supersede(keys: string[]): void {
for (const mount of mounts) {
if (keys.some((key) => mount.rootKeys().includes(key))) {
diff --git a/apps/web/src/components/sidebar-left/assets.tsx b/apps/web/src/components/sidebar-left/assets.tsx
index 822eb99b..b520a6ff 100644
--- a/apps/web/src/components/sidebar-left/assets.tsx
+++ b/apps/web/src/components/sidebar-left/assets.tsx
@@ -73,6 +73,7 @@ export function Assets() {
const selectedFilter = assetFilter();
return list.filter((asset) => {
+ if (asset.type === "SCRIPT") return false;
if (selectedFilter !== "ALL" && asset.type !== selectedFilter) return false;
if (q) return asset.name.toLowerCase().includes(q);
return assetFolderId(world, asset) === folders.currentId();
diff --git a/apps/web/src/context/editor-api/mount.ts b/apps/web/src/context/editor-api/mount.ts
index 229d10ed..5818f280 100644
--- a/apps/web/src/context/editor-api/mount.ts
+++ b/apps/web/src/context/editor-api/mount.ts
@@ -3,9 +3,12 @@
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
import { renderProject } from "@diffusionstudio/jsx";
+import { nanoid } from "nanoid";
import { reorderEntity, switchActiveScene } from "@/components/engine";
+import { createScriptAsset } from "@/components/engine/api/assets";
import { WorldDocument, importProjectModule } from "@/utils/jsx";
+import { documentRootKeys } from "@/utils/mount";
import { assert } from "@/utils";
import { resolveEntityEid } from "./node";
import { hasComponent } from "bitecs";
@@ -14,26 +17,16 @@ import type { Accessor } from "solid-js";
import type { MountRequest, NodeInsertRequest } from "@diffusionstudio/cli/channels";
import type { Engine } from "@/components/engine";
-function documentRootKeys(world: Engine["world"], document: WorldDocument): string[] {
- const keys: string[] = [];
- for (const node of document.stage.children) {
- if (node.eid === undefined) continue;
- const key = world.components.Key[node.eid];
- if (key !== undefined) keys.push(key);
- }
- return keys;
-}
-
/**
* `dapi mount` — evaluates a compiled project module and renders it directly into the ECS world
*/
export function handleMount(engine: Accessor<Engine>) {
- return async ({ code, live }: MountRequest): Promise<void> => {
+ return async ({ code }: MountRequest): Promise<void> => {
const e = engine();
const world = e.world;
const c = world.components;
let dispose = () => { };
- let persisted = false;
+ let registered = false;
try {
// Evaluate — top-level code (including top-level await) runs here.
@@ -41,7 +34,18 @@ export function handleMount(engine: Accessor<Engine>) {
const project = module.default as () => unknown;
assert(typeof project === "function", "The project module must default-export a Solid component");
- const document = new WorldDocument(e);
+ // Persist the compiled module as a content-addressed SCRIPT asset so any
+ // world (export, capture, reload) can re-run it in adopt mode. `mountId`
+ // ties every entity of this mount together for that re-run.
+ const scriptAsset = await createScriptAsset(world, code);
+ const mountId = nanoid();
+
+ const document = new WorldDocument(world, {
+ engine: e,
+ mode: "author",
+ mountId,
+ scriptAssetId: scriptAsset.id,
+ });
try {
world.history.startTransaction("Render project");
@@ -64,21 +68,23 @@ export function handleMount(engine: Accessor<Engine>) {
world.history.commitTransaction();
}
- if (live) {
- world.liveMounts.register({
- rootKeys: () => documentRootKeys(world, document),
- advance: () => document.advanceTicker(),
- dispose,
- });
- persisted = true;
- }
+ // A mount always stays live: its reactive graph keeps driving the
+ // entities until a later mount claims a root key or the app closes.
+ world.liveMounts.register({
+ mountId,
+ rootKeys: () => documentRootKeys(world, document),
+ advance: () => document.advanceTicker(),
+ dispose,
+ });
+ registered = true;
if (document.rootEid && hasComponent(world, document.rootEid, c.Scene)) {
switchActiveScene(world, document.rootEid);
e.camera.fitToActiveScene();
}
} finally {
- if (!persisted) dispose?.();
+ // Only the error path (before registration) needs to dispose the graph.
+ if (!registered) dispose?.();
}
};
}
@@ -102,7 +108,7 @@ export function handleNodeInsert(engine: Accessor<Engine>) {
const project = module.default as () => unknown;
assert(typeof project === "function", "The project module must default-export a Solid component");
- const document = new WorldDocument(e, { parentEid });
+ const document = new WorldDocument(e.world, { parentEid, engine: e });
try {
world.history.startTransaction("Insert nodes");
diff --git a/apps/web/src/context/editor-api/node.ts b/apps/web/src/context/editor-api/node.ts
index c2215bd2..747a25c3 100644
--- a/apps/web/src/context/editor-api/node.ts
+++ b/apps/web/src/context/editor-api/node.ts
@@ -386,7 +386,7 @@ export function handleNodePatch(engine: Accessor<Engine>) {
const results: NodePatchResult[] = [];
for (const patch of patches) {
- const doc = new WorldDocument(e);
+ const doc = new WorldDocument(e.world, { engine: e });
try {
world.history.startTransaction("patching node");
diff --git a/apps/web/src/utils/jsx.ts b/apps/web/src/utils/jsx.ts
index b839c4e8..b6675f15 100644
--- a/apps/web/src/utils/jsx.ts
+++ b/apps/web/src/utils/jsx.ts
@@ -68,6 +68,7 @@ type DocumentNode = {
host?: HtmlHost;
surfaceHost?: SurfaceHost;
ref?(target: unknown): void;
+ adopted?: boolean;
};
let nextNodeId = 1;
@@ -295,18 +296,59 @@ type GenaiQueueItem = {
type: "asset" | "caption" | "sync";
};
+export interface WorldDocumentOptions {
+ /** Mount into an existing parent entity (e.g. `dapi node insert`). */
+ parentEid?: number;
+ /** Only needed for `commit()`'s captioning phase (`author` mode). */
+ engine?: Engine;
+ /**
+ * `author` (default) mints entities and defines structure — an explicit
+ * `dapi mount`. `adopt` binds the re-run to already-persisted entities by
+ * their `MountPath`, rebuilding runtime hosts without re-authoring structure
+ * (restore, export, capture).
+ */
+ mode?: "author" | "adopt";
+ /** Identity shared by every entity of this mount (author stamps, adopt matches). */
+ mountId?: string;
+ /** SCRIPT asset holding the compiled module, stamped onto the mount root. */
+ scriptAssetId?: string;
+ /** `adopt` mode: MountPath -> existing entity id, built from the world. */
+ adoptIndex?: Map<string, number>;
+}
+
export class WorldDocument implements ProjectDocument<DocumentNode> {
public promises: Promise<void>[] = [];
public stage: DocumentNode;
public rootEid: number | null = null;
- public engine: Engine;
+ public world: EngineWorld;
+ public engine?: Engine;
+
+ private readonly mode: "author" | "adopt";
+ private readonly mountId?: string;
+ private readonly scriptAssetId?: string;
+ private readonly adoptIndex?: Map<string, number>;
+
+ // Runtime hosts this render created. Offline (export/capture) worlds are
+ // discarded without an entity-delete pass, so their hosts (an HtmlHost
+ // appends a canvas to document.body) must be freed explicitly on dispose.
+ private createdHosts: { dispose(): void }[] = [];
private queue: GenaiQueueItem[] = [];
- // Set once `commit()` finishes. A live mount (`dapi mount --live`) keeps
- // its reactive graph running past commit, so later writes flow through the
- // same paths, untracked; otherwise the undo stack would fill with one
- // entry per reactive update.
+ private trackHost<T extends { dispose(): void }>(host: T): T {
+ this.createdHosts.push(host);
+ return host;
+ }
+
+ /** Frees the runtime hosts this render created (paired with the graph dispose). */
+ public disposeHosts(): void {
+ for (const host of this.createdHosts) host.dispose();
+ this.createdHosts.length = 0;
+ }
+
+ // Set once `commit()` finishes. A mount keeps its reactive graph running
+ // past commit, so later writes flow through the same paths, untracked;
+ // otherwise the undo stack would fill with one entry per reactive update.
private committed = false;
private track<T>(fn: () => T): T {
@@ -318,9 +360,14 @@ export class WorldDocument implements ProjectDocument<DocumentNode> {
return result;
}
- public constructor(engine: Engine, target?: { parentEid: number }) {
- this.stage = makeNode({ tag: "#root", eid: target?.parentEid });
- this.engine = engine;
+ public constructor(world: EngineWorld, options: WorldDocumentOptions = {}) {
+ this.world = world;
+ this.engine = options.engine;
+ this.stage = makeNode({ tag: "#root", eid: options.parentEid });
+ this.mode = options.mode ?? "author";
+ this.mountId = options.mountId;
+ this.scriptAssetId = options.scriptAssetId;
+ this.adoptIndex = options.adoptIndex;
}
/**
@@ -407,6 +454,7 @@ export class WorldDocument implements ProjectDocument<DocumentNode> {
const sceneEid = getSceneAncestor(world, nodeEid);
if (!sceneEid || !hasAudioSources(world, sceneEid)) continue;
+ assert(this.engine, "captioning requires an engine (author-mode mount)");
const { asset, trim } = await transcribeScene(this.engine, sceneEid);
setComponent(world, nodeEid, c.AssetId, asset.id);
setComponent(world, nodeEid, c.Trim, trim);
@@ -417,10 +465,6 @@ export class WorldDocument implements ProjectDocument<DocumentNode> {
this.committed = true;
}
- private get world(): EngineWorld {
- return this.engine.world;
- }
-
private ticker = solid.createSignal<ProjectTick>(
{ time: 0, frame: 0, delta: 0, playing: false },
{ equals: (a, b) => a.time === b.time && a.frame === b.frame && a.delta === b.delta && a.playing === b.playing },
@@ -437,11 +481,22 @@ export class WorldDocument implements ProjectDocument<DocumentNode> {
* demand (content-cached in the library, so it collapses with the mount's own
* generation of the same spec).
*/
- public async loadFile(input: AssetInput): Promise<File> {
- const asset = isAssetRef(input)
- ? await resolveGeneratedAsset(this.world, input, new Map())
- : await resolveAsset(this.world, input);
- return await asset.handle.getFile();
+ public loadFile(input: AssetInput): Promise<File> {
+ const promise = (async () => {
+ const asset = isAssetRef(input)
+ ? await resolveGeneratedAsset(this.world, input, new Map())
+ : await resolveAsset(this.world, input);
+ return await asset.handle.getFile();
+ })();
+
+ // Let commit() await the initial resolution so the first exported/captured
+ // frame reflects a `useFile`-driven draw rather than rendering before the
+ // file lands. Post-commit refetches update reactively and aren't tracked.
+ if (!this.committed) {
+ this.promises.push(promise.then(() => undefined, () => undefined));
+ }
+
+ return promise;
}
/**
@@ -577,7 +632,7 @@ export class WorldDocument implements ProjectDocument<DocumentNode> {
"<htmlPaint> requires the html-in-canvas API; enable chrome://flags/#canvas-draw-element",
);
setComponent(world, eid, c.Paint, PaintType.HTML);
- const host = new HtmlHost();
+ const host = this.trackHost(new HtmlHost());
addComponent(world, eid, c.HtmlHost, false);
c.HtmlHost[eid] = host;
node.host = host;
@@ -593,7 +648,7 @@ export class WorldDocument implements ProjectDocument<DocumentNode> {
setComponent(world, eid, c.Name, getNextName(world, "HTML"));
const fid = createEntity(world);
setComponent(world, fid, c.Paint, PaintType.HTML);
- const host = new HtmlHost();
+ const host = this.trackHost(new HtmlHost());
addComponent(world, fid, c.HtmlHost, false);
c.HtmlHost[fid] = host;
appendChild(world, fid, eid);
@@ -601,7 +656,7 @@ export class WorldDocument implements ProjectDocument<DocumentNode> {
break;
} case "surfacePaint": {
setComponent(world, eid, c.Paint, PaintType.SURFACE);
- const host = new SurfaceHost();
+ const host = this.trackHost(new SurfaceHost());
addComponent(world, eid, c.SurfaceHost, false);
c.SurfaceHost[eid] = host;
node.surfaceHost = host;
@@ -613,7 +668,7 @@ export class WorldDocument implements ProjectDocument<DocumentNode> {
setComponent(world, eid, c.Name, getNextName(world, "Surface"));
const fid = createEntity(world);
setComponent(world, fid, c.Paint, PaintType.SURFACE);
- const host = new SurfaceHost();
+ const host = this.trackHost(new SurfaceHost());
addComponent(world, fid, c.SurfaceHost, false);
c.SurfaceHost[fid] = host;
appendChild(world, fid, eid);
@@ -1137,8 +1192,11 @@ export class WorldDocument implements ProjectDocument<DocumentNode> {
// only the empty placeholders Solid's control flow leaves behind pass.
if (node.text !== undefined) {
if (parent === this.stage) return;
- if (this.isTextEntity(parent)) this.assignChars(parent);
- else assert(node.text === "", `<${parent.tag}> cannot contain text`);
+ if (this.isTextEntity(parent)) {
+ if (!(parent.adopted === true && !this.committed)) this.assignChars(parent);
+ } else {
+ assert(node.text === "", `<${parent.tag}> cannot contain text`);
+ }
return;
}
@@ -1146,7 +1204,14 @@ export class WorldDocument implements ProjectDocument<DocumentNode> {
const eid = node.eid!;
if (parent !== this.stage) {
- this.attachEntity(eid, parent.eid!);
+ if (!node.adopted) this.attachEntity(eid, parent.eid!);
+ return;
+ }
+
+ // An adopted root is already placed and parented in the world; re-running
+ // placement/replace would overwrite its persisted position and delete it.
+ if (node.adopted) {
+ this.rootEid = eid;
return;
}
@@ -1174,6 +1239,15 @@ export class WorldDocument implements ProjectDocument<DocumentNode> {
}
}
+ // Stamp the mount's identity on its root so any world can re-run the
+ // module (export, capture, reload) in adopt mode.
+ if (this.mode === "author" && this.mountId !== undefined && this.scriptAssetId !== undefined) {
+ setComponent(world, eid, c.MountScript, {
+ mountId: this.mountId,
+ scriptAssetId: this.scriptAssetId,
+ });
+ }
+
this.rootEid = eid;
}
@@ -1245,9 +1319,29 @@ export class WorldDocument implements ProjectDocument<DocumentNode> {
* the stage), then recorded props in authored order.
*/
private materializeEcs(node: DocumentNode): void {
- node.eid = this.createEntityForTag(node);
+ const path = this.mountId !== undefined ? this.computeMountPath(node) : undefined;
+ const adoptedEid = this.mode === "adopt" && path !== undefined
+ ? this.adoptIndex?.get(path)
+ : undefined;
+
+ if (adoptedEid !== undefined) {
+ node.eid = adoptedEid;
+ node.adopted = true;
+ this.reattachRuntimeHostsForTag(node);
+ } else {
+ node.eid = this.createEntityForTag(node);
+ if (this.mountId !== undefined && path !== undefined) {
+ setComponent(this.world, node.eid, this.world.components.MountPath, { mountId: this.mountId, path });
+ }
+ }
+
for (const child of node.children) this.attach(node, child);
- for (const [name, value] of Object.entries(node.props)) this.applyEcsProperty(node, name, value);
+
+ // Adopted nodes keep their persisted (possibly hand-edited) values; only
+ // actively re-running effects write, via setProperty after eid is set.
+ if (!node.adopted) {
+ for (const [name, value] of Object.entries(node.props)) this.applyEcsProperty(node, name, value);
+ }
if (node.surfaceHost !== undefined) {
const box = this.resolveBoxSize(node.tag === "surfacePaint" ? node.parent ?? node : node);
@@ -1257,6 +1351,91 @@ export class WorldDocument implements ProjectDocument<DocumentNode> {
assert(node.ref === undefined, `\`ref\` is not supported on <${node.tag}>`);
}
+ /** Index of `node` among its parent's entity-bearing (non-text) children. */
+ private entitySiblingIndex(node: DocumentNode): number {
+ const parent = node.parent;
+ if (parent === undefined) return 0;
+ let index = 0;
+ for (const child of parent.children) {
+ if (child === node) break;
+ if (child.text === undefined) index++;
+ }
+ return index;
+ }
+
+ /**
+ * A node's stable structural key: the index path of entity-bearing siblings
+ * from the mount root down to the node. Computed identically at author and
+ * adopt time (deterministic tree → matching paths), so adopt can bind the
+ * re-run to the persisted entity carrying the same `MountPath`.
+ */
+ private computeMountPath(node: DocumentNode): string {
+ const parts: number[] = [];
+ let cursor: DocumentNode | undefined = node;
+ while (cursor !== undefined && cursor.parent !== undefined) {
+ parts.push(this.entitySiblingIndex(cursor));
+ if (cursor.parent === this.stage) break;
+ cursor = cursor.parent;
+ }
+ return parts.reverse().join("/");
+ }
+
+ /**
+ * Adopt mode: rebuild the runtime-only hosts a persisted entity can't carry,
+ * binding a fresh host to the existing (adopted) paint entity. Mirrors the
+ * host setup in `createEntityForTag` but never creates structural entities.
+ */
+ private reattachRuntimeHostsForTag(node: DocumentNode): void {
+ const world = this.world;
+ const c = world.components;
+ const eid = node.eid!;
+
+ switch (node.tag) {
+ case "surfacePaint": {
+ const host = this.trackHost(new SurfaceHost());
+ addComponent(world, eid, c.SurfaceHost, false);
+ c.SurfaceHost[eid] = host;
+ node.surfaceHost = host;
+ break;
+ }
+ case "surface": {
+ const fid = this.findPaintChild(eid, PaintType.SURFACE);
+ assert(fid !== undefined, "adopted <surface> has no surface paint child");
+ const host = this.trackHost(new SurfaceHost());
+ addComponent(world, fid, c.SurfaceHost, false);
+ c.SurfaceHost[fid] = host;
+ node.surfaceHost = host;
+ break;
+ }
+ case "htmlPaint": {
+ const host = this.trackHost(new HtmlHost());
+ addComponent(world, eid, c.HtmlHost, false);
+ c.HtmlHost[eid] = host;
+ node.host = host;
+ break;
+ }
+ case "html": {
+ const fid = this.findPaintChild(eid, PaintType.HTML);
+ assert(fid !== undefined, "adopted <html> has no html paint child");
+ const host = this.trackHost(new HtmlHost());
+ addComponent(world, fid, c.HtmlHost, false);
+ c.HtmlHost[fid] = host;
+ node.host = host;
+ break;
+ }
+ }
+ }
+
+ /** The child paint entity of `eid` carrying the given paint type, if any. */
+ private findPaintChild(eid: number, paint: PaintType): number | undefined {
+ const world = this.world;
+ const c = world.components;
+ for (const fid of query(world, [ChildOf(eid), c.Paint, Not(c.Deleted)])) {
+ if (c.Paint[fid] === paint) return fid;
+ }
+ return undefined;
+ }
+
/** Builds the DOM subtree for a node under an <htmlPaint>, props applied. */
private materializeDom(node: DocumentNode, svg: boolean): void {
if (node.text !== undefined) {
diff --git a/apps/web/src/utils/media.ts b/apps/web/src/utils/media.ts
index bfd20f62..a75f2330 100644
--- a/apps/web/src/utils/media.ts
+++ b/apps/web/src/utils/media.ts
@@ -57,6 +57,8 @@ export function mimeTypeToExtension(mimeType: string): string {
// Web files
'text/html': '.html',
+ 'text/javascript': '.js',
+ 'application/javascript': '.js',
'application/json': '.json',
'application/x-subrip': '.srt',
'text/vtt': '.vtt',
diff --git a/apps/web/src/utils/mount.ts b/apps/web/src/utils/mount.ts
new file mode 100644
index 00000000..97b14ee1
--- /dev/null
+++ b/apps/web/src/utils/mount.ts
@@ -0,0 +1,135 @@
+/* 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 { query, Not } from "bitecs";
+import { renderProject } from "@diffusionstudio/jsx";
+
+import { WorldDocument, importProjectModule } from "@/utils/jsx";
+import { getAssetFile } from "@/components/engine/api/assets";
+import { assert } from "@/utils";
+
+import type { Engine, EngineWorld } from "@/components/engine";
+
+export interface RenderMountOptions {
+ mode: "author" | "adopt";
+ mountId: string;
+ scriptAssetId: string;
+ adoptIndex?: Map<string, number>;
+ parentEid?: number;
+ engine?: Engine;
+}
+
+export interface RealizedMount {
+ document: WorldDocument;
+ /** Tears down the reactive graph AND frees the runtime hosts it created. */
+ dispose: () => void;
+}
+
+/** Root keys of a rendered mount (its top-level entities' `Key` values). */
+export function documentRootKeys(world: EngineWorld, document: WorldDocument): string[] {
+ const keys: string[] = [];
+ for (const node of document.stage.children) {
+ if (node.eid === undefined) continue;
+ const key = world.components.Key[node.eid];
+ if (key !== undefined) keys.push(key);
+ }
+ return keys;
+}
+
+/**
+ * Evaluates a compiled project module and renders it into `world` through a
+ * WorldDocument, then settles async work (asset loads, generation). Shared by
+ * the author path (`dapi mount`) and the adopt path (restore/export/capture).
+ * The returned `dispose` frees both the reactive graph and the hosts it made.
+ */
+export async function renderMount(
+ world: EngineWorld,
+ code: string,
+ options: RenderMountOptions,
+): Promise<RealizedMount> {
+ const module = await importProjectModule(code);
+ const project = module.default as () => unknown;
+ assert(typeof project === "function", "The project module must default-export a Solid component");
+
+ const document = new WorldDocument(world, options);
+ const disposeGraph = renderProject(project, document);
+ await document.commit();
+
+ return {
+ document,
+ dispose: () => {
+ disposeGraph();
+ document.disposeHosts();
+ },
+ };
+}
+
+/** MountPath -> entity id for one mount, so adopt can bind the re-run by key. */
+export function buildAdoptIndex(world: EngineWorld, mountId: string): Map<string, number> {
+ const c = world.components;
+ const index = new Map<string, number>();
+ for (const eid of query(world, [c.MountPath, Not(c.Deleted)])) {
+ if (c.MountPath.mountId[eid] !== mountId) continue;
+ index.set(c.MountPath.path[eid], eid);
+ }
+ return index;
+}
+
+/**
+ * Re-executes every mount recorded in `world` (via its `MountScript` root) in
+ * adopt mode: binds the re-run to the world's existing entities by `MountPath`,
+ * rebuilds the runtime-only hosts, and registers the graph so the per-frame
+ * `playbackSystem` drives it. This is how a cloned (export/capture) or restored
+ * (reload) world gets animated surfaces without host-sharing.
+ *
+ * A world's own re-entry is a no-op (`liveMounts.hasMount`). Every mount stays
+ * registered so the world's per-frame `playbackSystem` keeps driving it (live
+ * in the editor, per-frame during an offline export/capture render).
+ */
+export async function realizeMounts(
+ world: EngineWorld,
+ options: { engine?: Engine } = {},
+): Promise<{ disposeAll: () => void }> {
+ const c = world.components;
+ const seen = new Set<string>();
+
+ const roots = [...query(world, [c.MountScript, Not(c.Deleted)])].filter((eid) => {
+ const mountId = c.MountScript.mountId[eid];
+ if (seen.has(mountId) || world.liveMounts.hasMount(mountId)) return false;
+ seen.add(mountId);
+ return true;
+ });
+
+ for (const eid of roots) {
+ const mountId = c.MountScript.mountId[eid];
+ const scriptAssetId = c.MountScript.scriptAssetId[eid];
+
+ try {
+ const asset = world.assets.get(scriptAssetId);
+ assert(asset, `mount ${mountId}: SCRIPT asset ${scriptAssetId} not found`);
+ const code = await getAssetFile(asset).then((file) => file.text());
+
+ const adoptIndex = buildAdoptIndex(world, mountId);
+ const { document, dispose } = await renderMount(world, code, {
+ mode: "adopt",
+ mountId,
+ scriptAssetId,
+ adoptIndex,
+ engine: options.engine,
+ });
+
+ world.liveMounts.register({
+ mountId,
+ rootKeys: () => documentRootKeys(world, document),
+ advance: () => document.advanceTicker(),
+ dispose,
+ });
+ } catch (error) {
+ // A single malformed mount must not break loading/exporting the world.
+ console.error(`realizeMounts: failed to realize mount ${mountId}`, error);
+ }
+ }
+
+ return { disposeAll: () => world.liveMounts.disposeAll() };
+}
diff --git a/packages/jsx/src/renderer.ts b/packages/jsx/src/renderer.ts
index f8350989..9ba4b9f6 100644
--- a/packages/jsx/src/renderer.ts
+++ b/packages/jsx/src/renderer.ts
@@ -97,8 +97,9 @@ export type Ticker = {
* Subscribes to the project's timeline: the playhead of the scene the mount's
* root lives in (or is), pushed by the host once per playback tick. Each
* accessor only propagates when its value changes, so a paused scene re-runs
- * nothing and `frame()` consumers update at most once per frame. Values only
- * move while the reactive graph is alive, i.e. under `dapi mount --live`.
+ * nothing and `frame()` consumers update at most once per frame. Values move
+ * while the reactive graph is alive: a mount stays live, and export, capture,
+ * and reload each re-execute the module and drive the ticker themselves.
*/
export function useTicker(): Ticker {
const document = doc();
diff --git a/samples/reconciler/02-live-signals.tsx b/samples/reconciler/02-live-signals.tsx
index 3eeb92b5..8a2b374f 100644
--- a/samples/reconciler/02-live-signals.tsx
+++ b/samples/reconciler/02-live-signals.tsx
@@ -1,14 +1,14 @@
/* @jsxImportSource @diffusionstudio/jsx */
/* Live reactivity: post-commit updates flow through the materialized nodes.
*
- * dapi mount --live samples/reconciler/02-live-signals.tsx
+ * dapi mount samples/reconciler/02-live-signals.tsx
*
* Watch the stage:
* - the blue rect slides and recolors (reactive setProperty)
* - the counter text updates in place (replaceText into Chars)
* - the green badge blinks (Show insert/remove; its placeholder text node
* sits under the scene without crashing the ECS side)
- * Re-mount without --live to freeze and dispose the graph.
+ * Re-mount without to freeze and dispose the graph.
*/
import { Show, createSignal } from "solid-js";
diff --git a/samples/reconciler/03-live-list.tsx b/samples/reconciler/03-live-list.tsx
index 18781555..6117379b 100644
--- a/samples/reconciler/03-live-list.tsx
+++ b/samples/reconciler/03-live-list.tsx
@@ -1,7 +1,7 @@
/* @jsxImportSource @diffusionstudio/jsx */
/* Keyed list: <For> reorders, inserts, and removes materialized subtrees.
*
- * dapi mount --live samples/reconciler/03-live-list.tsx
+ * dapi mount samples/reconciler/03-live-list.tsx
*
* Every 1.2s the first card cycles to the back: Solid MOVES the existing
* nodes (reorder/reparent path, not delete + recreate; entity ids in
diff --git a/samples/reconciler/04-ticker.tsx b/samples/reconciler/04-ticker.tsx
index 20a13415..0d09f044 100644
--- a/samples/reconciler/04-ticker.tsx
+++ b/samples/reconciler/04-ticker.tsx
@@ -1,7 +1,7 @@
/* @jsxImportSource @diffusionstudio/jsx */
/* Timeline clock: useTicker drives props from the scene's playhead.
*
- * dapi mount --live samples/reconciler/04-ticker.tsx
+ * dapi mount samples/reconciler/04-ticker.tsx
*
* Values only move during playback: press play in the editor. The orange
* rect orbits with the frame, the readout shows time/frame, and the
diff --git a/samples/reconciler/05-html-paint.tsx b/samples/reconciler/05-html-paint.tsx
index 8e3567d1..ba7d3c24 100644
--- a/samples/reconciler/05-html-paint.tsx
+++ b/samples/reconciler/05-html-paint.tsx
@@ -1,7 +1,7 @@
/* @jsxImportSource @diffusionstudio/jsx */
/* Environment split: the same tags mean different things per context.
*
- * dapi mount --live samples/reconciler/05-html-paint.tsx
+ * dapi mount samples/reconciler/05-html-paint.tsx
*
* Requires the html-in-canvas API (chrome://flags/#canvas-draw-element;
* not available in Electron 35, so use a supporting build): without it the
diff --git a/samples/reconciler/06-anime-timeline.tsx b/samples/reconciler/06-anime-timeline.tsx
index 3de6859d..275966de 100644
--- a/samples/reconciler/06-anime-timeline.tsx
+++ b/samples/reconciler/06-anime-timeline.tsx
@@ -1,7 +1,7 @@
/* @jsxImportSource @diffusionstudio/jsx */
/* Anime.js timeline scrubbed by the playhead: one clock, two render worlds.
*
- * dapi mount --live samples/reconciler/06-anime-timeline.tsx
+ * dapi mount samples/reconciler/06-anime-timeline.tsx
*
* Needs the html-in-canvas API (see 05-html-paint.tsx). A paused anime.js
* timeline tweens plain-object targets; a createEffect seeks it to the
diff --git a/samples/reconciler/07-anime-mini.tsx b/samples/reconciler/07-anime-mini.tsx
index 412b3f39..a972a210 100644
--- a/samples/reconciler/07-anime-mini.tsx
+++ b/samples/reconciler/07-anime-mini.tsx
@@ -1,6 +1,6 @@
/* @jsxImportSource @diffusionstudio/jsx */
/* Anime.js timeline scrubbed by the playhead: canvas and DOM in lockstep.
- * dapi mount --live samples/reconciler/07-anime-mini.tsx
+ * dapi mount samples/reconciler/07-anime-mini.tsx
*/
import { createEffect, createSignal } from "solid-js";
import { createTimeline } from "animejs";
diff --git a/samples/reconciler/08-surface-paint.tsx b/samples/reconciler/08-surface-paint.tsx
index faf63b73..2dbbb0d8 100644
--- a/samples/reconciler/08-surface-paint.tsx
+++ b/samples/reconciler/08-surface-paint.tsx
@@ -2,7 +2,7 @@
/* Ref-provided canvas: the <surface> element hands its backing bitmap to the
* ref callback, which owns it from then on.
*
- * dapi mount --live samples/reconciler/08-surface-paint.tsx
+ * dapi mount samples/reconciler/08-surface-paint.tsx
*
* The ref runs once at materialization, inside the mount's reactive owner:
* the effect below redraws from a signal and the playhead ticker, and the
diff --git a/samples/reconciler/09-three-helmet.tsx b/samples/reconciler/09-three-helmet.tsx
index e3ac1f27..3d1c28e7 100644
--- a/samples/reconciler/09-three-helmet.tsx
+++ b/samples/reconciler/09-three-helmet.tsx
@@ -1,7 +1,7 @@
/* @jsxImportSource @diffusionstudio/jsx */
/* Three.js owning a <surface>: a glTF helmet spun by the playhead.
*
- * dapi mount --live samples/reconciler/09-three-helmet.tsx
+ * dapi mount samples/reconciler/09-three-helmet.tsx
*
* The <surface> ref hands three.js a detached HTMLCanvasElement to render into;
* the engine samples that bitmap into the node's box every frame, so a WebGL
diff --git a/samples/reconciler/README.md b/samples/reconciler/README.md
index 3786ce81..d21bd8e4 100644
--- a/samples/reconciler/README.md
+++ b/samples/reconciler/README.md
@@ -6,14 +6,14 @@ Run from the repo root with the editor open:
| Sample | Command | Exercises |
| --- | --- | --- |
| [01-static-tree.tsx](01-static-tree.tsx) | `dapi mount samples/reconciler/01-static-tree.tsx` | deferred materialization, prop replay, paints, text segments, timing |
-| [02-live-signals.tsx](02-live-signals.tsx) | `dapi mount --live samples/reconciler/02-live-signals.tsx` | reactive props, replaceText, Show insert/remove |
-| [03-live-list.tsx](03-live-list.tsx) | `dapi mount --live samples/reconciler/03-live-list.tsx` | \<For\> moves (reorder without recreate), list insert/remove |
-| [04-ticker.tsx](04-ticker.tsx) | `dapi mount --live samples/reconciler/04-ticker.tsx` | useTicker playhead reactivity (press play) |
-| [05-html-paint.tsx](05-html-paint.tsx) | `dapi mount --live samples/reconciler/05-html-paint.tsx` | DOM/SVG materialization under \<html\>; needs html-in-canvas |
-| [06-anime-timeline.tsx](06-anime-timeline.tsx) | `dapi mount --live samples/reconciler/06-anime-timeline.tsx` | anime.js timeline seeked from useTicker, driving an ECS node and \<html\> content in lockstep |
-| [07-anime-mini.tsx](07-anime-mini.tsx) | `dapi mount --live samples/reconciler/07-anime-mini.tsx` | minimal anime.js + useTicker sync, sized for a social post |
-| [08-surface-paint.tsx](08-surface-paint.tsx) | `dapi mount --live samples/reconciler/08-surface-paint.tsx` | ref-provided canvas: \<surface\> element and \<surfacePaint\> child, effect-driven redraws |
-| [09-three-helmet.tsx](09-three-helmet.tsx) | `dapi mount --live samples/reconciler/09-three-helmet.tsx` | three.js WebGL renderer owning a \<surface\>, glTF model loaded over the network, rotation seeked from useTicker |
+| [02-live-signals.tsx](02-live-signals.tsx) | `dapi mount samples/reconciler/02-live-signals.tsx` | reactive props, replaceText, Show insert/remove |
+| [03-live-list.tsx](03-live-list.tsx) | `dapi mount samples/reconciler/03-live-list.tsx` | \<For\> moves (reorder without recreate), list insert/remove |
+| [04-ticker.tsx](04-ticker.tsx) | `dapi mount samples/reconciler/04-ticker.tsx` | useTicker playhead reactivity (press play) |
+| [05-html-paint.tsx](05-html-paint.tsx) | `dapi mount samples/reconciler/05-html-paint.tsx` | DOM/SVG materialization under \<html\>; needs html-in-canvas |
+| [06-anime-timeline.tsx](06-anime-timeline.tsx) | `dapi mount samples/reconciler/06-anime-timeline.tsx` | anime.js timeline seeked from useTicker, driving an ECS node and \<html\> content in lockstep |
+| [07-anime-mini.tsx](07-anime-mini.tsx) | `dapi mount samples/reconciler/07-anime-mini.tsx` | minimal anime.js + useTicker sync, sized for a social post |
+| [08-surface-paint.tsx](08-surface-paint.tsx) | `dapi mount samples/reconciler/08-surface-paint.tsx` | ref-provided canvas: \<surface\> element and \<surfacePaint\> child, effect-driven redraws |
+| [09-three-helmet.tsx](09-three-helmet.tsx) | `dapi mount samples/reconciler/09-three-helmet.tsx` | three.js WebGL renderer owning a \<surface\>, glTF model loaded over the network, rotation seeked from useTicker |
Each root scene carries a stable key, so re-mounting a sample replaces its
scene in place. Inspect results with `dapi node tree`; entity ids in sample 03