Skip to content

The VS Code of video editing, built for agents.

TypeScript

Enhance loop handling and editing capabilities in the editor

konstantin-paulus1bc0d852425c
diff --git a/apps/desktop/src/edit.ts b/apps/desktop/src/edit.ts
index 712b96e9..05b55f6e 100644
--- a/apps/desktop/src/edit.ts
+++ b/apps/desktop/src/edit.ts
@@ -9,10 +9,20 @@ import { join } from "node:path";
import Sqids from "sqids";
import { IndentationText, Project, SyntaxKind } from "ts-morph";
-import { ID_ATTR, formatSource, isCompositionTag, parseSource } from "@diffusionstudio/jsx";
+import { ID_ATTR, formatSource, isCompositionTag, isLoopTag, parseSource } from "@diffusionstudio/jsx";
import type { PropValue } from "@diffusionstudio/jsx";
-import type { JsxAttribute, JsxElement, JsxOpeningElement, JsxSelfClosingElement, Node, SourceFile } from "ts-morph";
+import type {
+ ArrowFunction,
+ FunctionExpression,
+ JsxAttribute,
+ JsxElement,
+ JsxFragment,
+ JsxOpeningElement,
+ JsxSelfClosingElement,
+ Node,
+ SourceFile,
+} from "ts-morph";
export type { PropValue };
@@ -74,7 +84,31 @@ export interface SourceRemove {
source: string;
}
-export type SourceEdit = SourceSet | SourceInsert | SourceMove | SourceRemove;
+/**
+ * One iteration of a loop as the canvas rendered it: for every composition
+ * element of the loop body, by its source, the props it came out with and (for
+ * a `<text>`) its literal content — the values that were computed from the
+ * item, spelled as literals. `pending` is the name the canvas already knows
+ * that iteration's copy of the element by; the write answers with the real
+ * one in `ids`. The first iteration keeps the body's own names, so it carries
+ * none.
+ */
+export type SourceIteration = Record<string, { props: Record<string, PropValue>; text?: string; pending?: string }>;
+
+/**
+ * Replaces the `<For>`/`<Index>` around the element named by `source` with
+ * one copy of its body per iteration, each spelling out what that iteration
+ * rendered. Nothing that comes after this in the same write can address a
+ * looped element (see `inLoop`): the loop is a recipe for elements, and a
+ * change to one of them means writing them down first.
+ */
+export interface SourceUnroll {
+ kind: "unroll";
+ source: string;
+ iterations: SourceIteration[];
+}
+
+export type SourceEdit = SourceSet | SourceInsert | SourceMove | SourceRemove | SourceUnroll;
export interface WriteResult {
/** Sources that could not be written, as `id` or `id (prop)`. */
@@ -85,6 +119,12 @@ export interface WriteResult {
* wait for a recompile.
*/
ids?: Record<string, string>;
+ /**
+ * The loops this write unrolled, by the `source` of the `SourceUnroll` that
+ * asked. An unroll not listed here was declined, and the canvas takes its
+ * loop back (see the edit writer).
+ */
+ unrolled?: string[];
error?: string;
}
@@ -107,11 +147,18 @@ const absolute = (dir: string, file: string): string => join(dir, ...file.split(
* to find the handful that are elements.
*/
function tags(sourceFile: SourceFile): JsxTag[] {
+ return tagsIn(sourceFile);
+}
+
+/** The JSX elements at and under `node`, in document order. */
+function tagsIn(node: Node): JsxTag[] {
const found: JsxTag[] = [];
- sourceFile.forEachDescendant((node: Node) => {
- if (node.isKind(SyntaxKind.JsxSelfClosingElement)) found.push(node);
- else if (node.isKind(SyntaxKind.JsxElement)) found.push(node.getOpeningElement());
- });
+ const visit = (candidate: Node): void => {
+ if (candidate.isKind(SyntaxKind.JsxSelfClosingElement)) found.push(candidate);
+ else if (candidate.isKind(SyntaxKind.JsxElement)) found.push(candidate.getOpeningElement());
+ };
+ visit(node);
+ node.forEachDescendant(visit);
return found;
}
@@ -255,6 +302,85 @@ function matchIndentation(sourceFile: SourceFile): void {
const elementOf = (tag: JsxTag): JsxElement | JsxSelfClosingElement =>
tag.isKind(SyntaxKind.JsxOpeningElement) ? tag.getParentIfKindOrThrow(SyntaxKind.JsxElement) : tag;
+// ---------------------------------------------------------------------------
+// Loops
+
+type JsxBody = JsxElement | JsxSelfClosingElement | JsxFragment;
+type LoopCallback = ArrowFunction | FunctionExpression;
+
+const isLoopElement = (node: Node): node is JsxElement =>
+ node.isKind(SyntaxKind.JsxElement) && isLoopTag(tagName(node.getOpeningElement()));
+
+/**
+ * The nearest `<For>`/`<Index>` an element sits in the body of, if any. An
+ * element there is rendered once per item, so a write to it — a prop, a child,
+ * a move, a cut — would reach every iteration at once; the writer refuses
+ * those, and unrolls the loop instead when asked to (see `SourceUnroll`).
+ */
+const loopOf = (element: Node): JsxElement | undefined => element.getAncestors().find(isLoopElement);
+
+const inLoop = (tag: JsxTag): boolean => loopOf(elementOf(tag)) !== undefined;
+
+const isBlankText = (node: Node): boolean =>
+ node.isKind(SyntaxKind.JsxText) && node.containsOnlyTriviaWhiteSpaces();
+
+/**
+ * What a loop renders per item: the JSX its callback returns, when the
+ * callback is written out and returns nothing but JSX. Anything else — a
+ * reference to a function declared elsewhere, a body with statements of its
+ * own — computes its element in a way the source cannot be asked to spell out.
+ */
+function loopBody(loop: JsxElement): { callback: LoopCallback; body: JsxBody } | undefined {
+ const children = loop.getJsxChildren().filter((child) => !isBlankText(child));
+ if (children.length !== 1) return undefined;
+
+ const expression = children[0]!.asKind(SyntaxKind.JsxExpression)?.getExpression();
+ const callback = expression?.asKind(SyntaxKind.ArrowFunction) ?? expression?.asKind(SyntaxKind.FunctionExpression);
+ if (!callback) return undefined;
+
+ let returned: Node | undefined = callback.getBody();
+ if (returned.isKind(SyntaxKind.Block)) {
+ const statements = returned.getStatements();
+ if (statements.length !== 1) return undefined;
+ returned = statements[0]!.asKind(SyntaxKind.ReturnStatement)?.getExpression();
+ }
+ while (returned?.isKind(SyntaxKind.ParenthesizedExpression)) returned = returned.getExpression();
+
+ const body =
+ returned?.asKind(SyntaxKind.JsxElement) ??
+ returned?.asKind(SyntaxKind.JsxSelfClosingElement) ??
+ returned?.asKind(SyntaxKind.JsxFragment);
+ return body === undefined ? undefined : { callback, body };
+}
+
+/**
+ * The names a loop's callback binds — the item, the index, whatever it
+ * destructured (over-approximated: every identifier in the parameter list).
+ * These are what an unrolled copy no longer has a value for.
+ */
+function boundNames(callback: LoopCallback): Set<string> {
+ const names = new Set<string>();
+ for (const parameter of callback.getParameters()) {
+ const name = parameter.getNameNode();
+ if (name.isKind(SyntaxKind.Identifier)) names.add(name.getText());
+ for (const identifier of name.getDescendantsOfKind(SyntaxKind.Identifier)) names.add(identifier.getText());
+ }
+ return names;
+}
+
+/** Whether an attribute's value mentions any of `names`. */
+function mentions(attribute: JsxAttribute, names: Set<string>): boolean {
+ const initializer = attribute.getInitializer();
+ if (!initializer) return false;
+ if (initializer.isKind(SyntaxKind.Identifier) && names.has(initializer.getText())) return true;
+ return initializer.getDescendantsOfKind(SyntaxKind.Identifier).some((identifier) => names.has(identifier.getText()));
+}
+
+const isTextTag = (tag: JsxTag): boolean => {
+ const name = tagName(tag);
+ return name === "text" || name === "Text";
+};
+
/**
* Puts `child` (element text) under `parent`, in front of `before` (a direct
* child of it) or last. ts-morph has no operation for either without
@@ -408,6 +534,7 @@ interface OpenFile {
interface FileWrite {
skipped: string[];
ids: Record<string, string>;
+ unrolled: string[];
}
/**
@@ -552,11 +679,13 @@ class SourceWriter {
public async applyEdits(edits: SourceEdit[]): Promise<WriteResult> {
const skipped: string[] = [];
const ids: Record<string, string> = {};
+ const unrolled: string[] = [];
// Grouped by file: one parse and one write per file, however many elements
// of it an edit touched. An insert lives in its parent's file, and a
- // pending source in the file of the insert that made it; edits arrive in
- // the order they were made, so a parent is filed before its children.
+ // pending source in the file of the insert (or the unroll) that made it;
+ // edits arrive in the order they were made, so a parent is filed before
+ // its children.
const fileOf = new Map<string, string>();
const byFile = new Map<string, SourceEdit[]>();
for (const edit of edits) {
@@ -567,6 +696,13 @@ class SourceWriter {
continue;
}
if (edit.kind === "insert") fileOf.set(edit.source, file);
+ if (edit.kind === "unroll") {
+ for (const iteration of edit.iterations) {
+ for (const { pending } of Object.values(iteration)) {
+ if (pending) fileOf.set(pending, file);
+ }
+ }
+ }
byFile.set(file, [...(byFile.get(file) ?? []), edit]);
}
@@ -587,10 +723,15 @@ class SourceWriter {
skipped.push(...written.skipped);
Object.assign(ids, written.ids);
+ unrolled.push(...written.unrolled);
}
await this.save();
- return { skipped, ...(Object.keys(ids).length ? { ids } : {}) };
+ return {
+ skipped,
+ ...(Object.keys(ids).length ? { ids } : {}),
+ ...(unrolled.length ? { unrolled } : {}),
+ };
}
/**
@@ -602,6 +743,7 @@ class SourceWriter {
const nextId = idAllocator(idsIn(sourceFile));
const skipped: string[] = [];
const ids: Record<string, string> = {};
+ const unrolled: string[] = [];
try {
for (const edit of entries) {
@@ -620,6 +762,12 @@ class SourceWriter {
continue;
}
+ if (edit.kind === "unroll") {
+ if (this.unrollLoop(file, sourceFile, edit, ids, nextId)) unrolled.push(edit.source);
+ else skipped.push(`${edit.source} (loop)`);
+ continue;
+ }
+
const locator = locate(edit.source, ids)?.locator;
if (locator === undefined) {
skipped.push(edit.source);
@@ -636,6 +784,14 @@ class SourceWriter {
break;
}
+ // One element of a loop cannot take a value the others do not:
+ // the loop has to be unrolled first (and would have been, in this
+ // same write, had the canvas been able to spell it out).
+ if (inLoop(tag)) {
+ skipped.push(`${edit.source} (loop)`);
+ break;
+ }
+
const attribute = attributeOf(tag, name);
if (attribute && !isWritable(attribute)) {
skipped.push(`${edit.source} (${name})`);
@@ -661,7 +817,7 @@ class SourceWriter {
// The tree an edit leaves behind answers for itself before it is printed.
this.dropUnparsed([file]);
- return this.files.has(file) ? { skipped, ids } : undefined;
+ return this.files.has(file) ? { skipped, ids, unrolled } : undefined;
}
/**
@@ -681,7 +837,8 @@ class SourceWriter {
const parentLocator = locate(edit.parent, ids)?.locator;
const parent = parentLocator === undefined ? undefined : findTag(sourceFile, parentLocator);
- if (!parent) return false;
+ // A child of a looped element would be a child of every iteration's.
+ if (!parent || inLoop(parent)) return false;
let before: JsxTag | undefined;
if (edit.before !== undefined) {
@@ -727,7 +884,8 @@ class SourceWriter {
// element here that has nothing to do with it.
const locator = address?.file === file ? address.locator : undefined;
const tag = locator === undefined ? undefined : findTag(sourceFile, locator);
- if (!tag) return undefined;
+ // Nothing in a loop moves, or is moved into: it is every iteration's.
+ if (!tag || inLoop(tag)) return undefined;
const id = idOf(tag);
if (id) return id;
@@ -789,12 +947,167 @@ class SourceWriter {
const address = locate(edit.source, ids);
const locator = address?.file === file ? address.locator : undefined;
const tag = locator === undefined ? undefined : findTag(sourceFile, locator);
- if (!tag) return false;
+ // Cutting a looped element would cut it from every iteration.
+ if (!tag || inLoop(tag)) return false;
matchIndentation(sourceFile);
cutElement(sourceFile, elementOf(tag));
return true;
}
+
+ /**
+ * Replaces the loop around one element with its iterations written out.
+ * The body — the JSX the loop's callback returns — is copied once per
+ * iteration, keeping the author's layout; then each copy's elements take
+ * the props that iteration rendered, spelled as literals, and lose the
+ * spreads those props came from. The first copy keeps the body's ids, the
+ * rest are named afresh and answered for in `ids`.
+ *
+ * False when the loop is not one the source can be asked to spell out: no
+ * loop around the element, a loop within a loop, a callback that computes
+ * rather than returns JSX, a body with anything but composition elements in
+ * it (a component's props are its own, and control flow renders on its own
+ * terms), an attribute that leans on the item and that the canvas did not
+ * report a value for, or an iteration the canvas knows less about than the
+ * body asks.
+ */
+ private unrollLoop(
+ file: string,
+ sourceFile: SourceFile,
+ edit: SourceUnroll,
+ ids: Record<string, string>,
+ nextId: () => string,
+ ): boolean {
+ const locator = locate(edit.source, ids)?.locator;
+ const tag = locator === undefined ? undefined : findTag(sourceFile, locator);
+ const loop = tag === undefined ? undefined : loopOf(elementOf(tag));
+ if (!tag || !loop || loopOf(loop)) return false;
+
+ const shape = loopBody(loop);
+ if (!shape) return false;
+ const bound = boundNames(shape.callback);
+
+ // What the canvas said, by id: every key must name an element of this file.
+ const iterations: Map<string, SourceIteration[string]>[] = [];
+ for (const iteration of edit.iterations) {
+ const byId = new Map<string, SourceIteration[string]>();
+ for (const [source, record] of Object.entries(iteration)) {
+ const address = parseSource(source);
+ if (address?.file !== file || typeof address.locator !== "string") return false;
+ byId.set(address.locator, record);
+ }
+ iterations.push(byId);
+ }
+ if (!iterations.length) return false;
+
+ // The body's top-level elements: the copies are their text.
+ const roots: (JsxElement | JsxSelfClosingElement)[] = [];
+ for (const child of shape.body.isKind(SyntaxKind.JsxFragment) ? shape.body.getJsxChildren() : [shape.body]) {
+ if (isBlankText(child)) continue;
+ if (child.isKind(SyntaxKind.JsxElement) || child.isKind(SyntaxKind.JsxSelfClosingElement)) roots.push(child);
+ else return false;
+ }
+ if (!roots.length) return false;
+
+ // Checked before anything is touched: every element of the body is a named
+ // composition element every iteration accounts for, holds only what a copy
+ // can hold, and keeps no attribute that would be left pointing at the item.
+ const bodyTags = roots.flatMap(tagsIn);
+ const bodyIds: string[] = [];
+ for (const bodyTag of bodyTags) {
+ const id = idOf(bodyTag);
+ if (!isCompositionTag(tagName(bodyTag)) || !id || bodyIds.includes(id)) return false;
+ if (!iterations.every((iteration) => iteration.has(id))) return false;
+ bodyIds.push(id);
+
+ for (const attribute of bodyTag.getAttributes()) {
+ if (!attribute.isKind(SyntaxKind.JsxAttribute)) continue;
+ const name = attribute.getNameNode().getText();
+ if (name === ID_ATTR) continue;
+ if (iterations.every((iteration) => name in iteration.get(id)!.props)) continue;
+ if (mentions(attribute, bound)) return false;
+ }
+
+ const element = elementOf(bodyTag);
+ if (element.isKind(SyntaxKind.JsxSelfClosingElement)) continue;
+ const text = isTextTag(bodyTag);
+ for (const child of element.getJsxChildren()) {
+ if (isBlankText(child)) continue;
+ if (child.isKind(SyntaxKind.JsxText) || child.isKind(SyntaxKind.JsxExpression)) {
+ if (!text) return false;
+ } else if (child.isKind(SyntaxKind.JsxElement) || child.isKind(SyntaxKind.JsxSelfClosingElement)) {
+ if (text) return false;
+ } else {
+ return false;
+ }
+ }
+ }
+
+ // Before any indentation is measured: ts-morph counts it in units of a
+ // setting it does not learn from the file on its own.
+ matchIndentation(sourceFile);
+ const indent = loop.getIndentationText();
+
+ // Each copy: the roots' text at the loop's indentation, with the ids of
+ // every copy but the first swapped for fresh ones — by span, so the copies
+ // read exactly as the body does otherwise.
+ const minted: Map<string, string>[] = iterations.map(() => new Map());
+ const copies = iterations.map((iteration, index) =>
+ roots
+ .map((root) => {
+ let text = root.getText();
+ if (index > 0) {
+ const swaps = tagsIn(root)
+ .map((bodyTag) => {
+ const id = idOf(bodyTag)!;
+ const initializer = attributeOf(bodyTag, ID_ATTR)!.getInitializer()!;
+ const fresh = nextId();
+ minted[index]!.set(id, fresh);
+ const pending = iteration.get(id)!.pending;
+ if (pending) ids[pending] = formatSource(file, fresh);
+ return { start: initializer.getStart() - root.getStart(), end: initializer.getEnd() - root.getStart(), fresh };
+ })
+ .sort((a, b) => b.start - a.start);
+ for (const swap of swaps) text = `${text.slice(0, swap.start)}"${swap.fresh}"${text.slice(swap.end)}`;
+ }
+ return reindent(text, root.getIndentationText(), indent);
+ })
+ .join(`\n${indent}`),
+ );
+ sourceFile.replaceText([loop.getStart(), loop.getEnd()], copies.join(`\n${indent}`));
+
+ // Now every copy's elements answer to a name of their own: give each what
+ // its iteration rendered, one attribute at a time and re-found after each
+ // (editing one attribute forgets its siblings).
+ for (const [index, iteration] of iterations.entries()) {
+ for (const bodyId of bodyIds) {
+ const id = minted[index]!.get(bodyId) ?? bodyId;
+ const record = iteration.get(bodyId)!;
+ const found = (): JsxTag => {
+ const copy = findTag(sourceFile, id);
+ if (!copy) throw new Error(`the copy of ${bodyId} for iteration ${index} is gone`);
+ return copy;
+ };
+
+ // The spreads are what the recorded props stand in for.
+ for (let spread = found().getAttributes().find((a) => a.isKind(SyntaxKind.JsxSpreadAttribute)); spread; ) {
+ spread.remove();
+ spread = found().getAttributes().find((a) => a.isKind(SyntaxKind.JsxSpreadAttribute));
+ }
+ for (const [name, value] of Object.entries(record.props)) {
+ setProp(found(), name, value);
+ }
+
+ const element = elementOf(found());
+ if (element.isKind(SyntaxKind.JsxElement) && isTextTag(element.getOpeningElement())) {
+ const content = record.text ? jsxText(record.text) : "";
+ sourceFile.replaceText([element.getOpeningElement().getEnd(), element.getClosingElement().getStart()], content);
+ }
+ }
+ }
+
+ return true;
+ }
}
/** Stamps every source file of the project. Writes nothing to a fully named project. */
diff --git a/apps/desktop/src/source.ts b/apps/desktop/src/source.ts
index a8ac2880..991b6e0b 100644
--- a/apps/desktop/src/source.ts
+++ b/apps/desktop/src/source.ts
@@ -11,16 +11,23 @@
// disagreed, a drag would write to the wrong element; that invariant is why
// these two modules are read together.
-import { ID_ATTR, SOURCE_ATTR, formatSource, isCompositionTag } from "@diffusionstudio/jsx";
+import { ID_ATTR, LOOP_ATTR, SOURCE_ATTR, formatSource, isCompositionTag, isLoopTag } from "@diffusionstudio/jsx";
-import type { PluginObj } from "@babel/core";
+import type { PluginObj, types as t } from "@babel/core";
/** What babel hands a plugin factory. */
type BabelApi = { types: typeof import("@babel/core").types };
+const jsxTagName = (element: t.JSXElement): string | undefined => {
+ const name = element.openingElement.name;
+ return name.type === "JSXIdentifier" ? name.name : undefined;
+};
+
/**
* Stamps every composition element with the location of its JSX source, so
* entities on the canvas can be traced back to the code that produced them.
+ * An element in the body of a `<For>`/`<Index>` is also stamped with the
+ * location of that loop (see LOOP_ATTR).
*/
export function sourcePlugin({ types }: BabelApi, { file }: { file: string }): PluginObj {
return {
@@ -33,15 +40,24 @@ export function sourcePlugin({ types }: BabelApi, { file }: { file: string }): P
// "the nth element in this file", and skipping some would make that
// depend on which ones are composition elements today.
let index = 0;
+ // Loops are addressed by their position too, since nothing else names
+ // them; visited before what they contain, so it is known by then.
+ const positions = new WeakMap<t.JSXElement, number>();
program.traverse({
JSXElement(path) {
const position = index++;
+ positions.set(path.node, position);
const opening = path.node.openingElement;
const name = opening.name;
if (name.type !== "JSXIdentifier" || !isCompositionTag(name.name)) return;
+ const loop = path.findParent(
+ (parent) => parent.isJSXElement() && isLoopTag(jsxTagName(parent.node) ?? ""),
+ );
+ const loopPosition = loop ? positions.get(loop.node as t.JSXElement) : undefined;
+
// An element that names itself keeps that name; the position is the
// fallback for elements nothing has had to write to yet. The id is
// removed on the way through, so it never reaches a host as a prop.
@@ -64,6 +80,15 @@ export function sourcePlugin({ types }: BabelApi, { file }: { file: string }): P
types.stringLiteral(formatSource(file, locator)),
),
);
+
+ if (loopPosition !== undefined) {
+ opening.attributes.push(
+ types.jsxAttribute(
+ types.jsxIdentifier(LOOP_ATTR),
+ types.stringLiteral(formatSource(file, loopPosition)),
+ ),
+ );
+ }
},
});
},
diff --git a/apps/web/src/engine/editor.ts b/apps/web/src/engine/editor.ts
index 9330d56c..7fd57001 100644
--- a/apps/web/src/engine/editor.ts
+++ b/apps/web/src/engine/editor.ts
@@ -10,11 +10,11 @@
* where the commands live.
*/
-import { Active, Chars, getActiveEntity, getEntityChildren, getEntityTree, getParentEntity, isText, Selected, setActive, Source, Stage } from '@diffusionstudio/runtime';
-import { SOURCE_ATTR } from '@diffusionstudio/jsx';
+import { Active, Chars, getActiveEntity, getEntityChildren, getEntityTree, getParentEntity, isText, Loop, Selected, setActive, Source, Stage } from '@diffusionstudio/runtime';
+import { isPropValue, SOURCE_ATTR } from '@diffusionstudio/jsx';
import { createRoot } from 'solid-js';
-import { getRuntimeDocument, insert, isSceneNode, withDocument } from '@diffusionstudio/reconciler';
+import { authoredElement, getRuntimeDocument, insert, isSceneNode, withDocument } from '@diffusionstudio/reconciler';
import type { PropValue } from '@diffusionstudio/jsx';
import type { Entity, World } from 'koota';
@@ -77,7 +77,31 @@ export interface RemoveEdit {
source: string;
}
-export type EntityEdit = PropEdit | InsertEdit | MoveEdit | RemoveEdit;
+/**
+ * One iteration of a loop as the canvas rendered it: for every element of the
+ * loop body, by source, the props it came out with and (for a text) its
+ * content, plus — for every iteration but the first, which keeps the body's
+ * own names — the pending source its entity has been re-stamped with, so the
+ * write can answer with the real one (see `isPendingSource`).
+ */
+export type LoopIteration = Record<string, { props: Record<string, PropValue>; text?: string; pending?: string }>;
+
+/**
+ * A `<For>`/`<Index>` the editor needs written out as its iterations, so that
+ * one of them can be edited without the others: `source` is any element of
+ * the loop's body (the writer finds the loop from it) and `iterations` what
+ * each rendering of that body came to. Reported before the edit that needed
+ * it; the entities are already re-stamped when it is. `loop` is the stamp
+ * they carried (see `Loop`), for `unsettle` to give back if the write declines.
+ */
+export interface UnrollEdit {
+ kind: 'unroll';
+ source: string;
+ loop: string;
+ iterations: LoopIteration[];
+}
+
+export type EntityEdit = PropEdit | InsertEdit | MoveEdit | RemoveEdit | UnrollEdit;
/**
* Sources of elements the editor created that no write has named yet. Shaped
@@ -89,22 +113,10 @@ let pendingCounter = 0;
export const isPendingSource = (source: string): boolean => source.startsWith(PENDING_PREFIX);
-/** Whether a value is one a source file could spell: JSON, essentially. */
-function isPropValue(value: unknown): value is PropValue {
- if (value === null) return true;
- switch (typeof value) {
- case 'string':
- case 'number':
- case 'boolean':
- return true;
- case 'object':
- return Array.isArray(value)
- ? value.every(isPropValue)
- : Object.values(value as object).every(isPropValue);
- default:
- return false;
- }
-}
+const nextPendingSource = (): string => `${PENDING_PREFIX}${++pendingCounter}`;
+
+/** Whether an entity was rendered by a loop the source has not been asked to unroll yet. */
+export const isLooped = (entity: Entity): boolean => entity.isAlive() && entity.has(Loop);
/** What `insertElement` learns about each element while it renders. */
interface Recorded {
@@ -144,8 +156,14 @@ export class DocumentEditor {
this.reportEdit(entity, name, value);
}
- /** Reports an edit whose change the editor already made itself. */
+ /**
+ * Reports an edit whose change the editor already made itself. An entity a
+ * loop rendered is settled first (see `settle`): its element is every
+ * iteration's until the loop is unrolled, and the file hears about that
+ * before it hears the value.
+ */
public reportEdit(entity: Entity, name: string, value: PropValue): void {
+ this.settle(entity);
const source = entity.get(Source)?.value;
if (source) {
@@ -195,15 +213,125 @@ export class DocumentEditor {
const current = getActiveEntity(this.world);
if (current === entity) return;
setActive(this.world, entity);
- if (current?.isAlive()) this.reportEdit(current, 'active', false);
- if (entity) this.reportEdit(entity, 'active', true);
+ if (current?.isAlive() && !isLooped(current)) this.reportEdit(current, 'active', false);
+ if (entity && !isLooped(entity)) this.reportEdit(entity, 'active', true);
}
+ /**
+ * Selection and activation of a looped entity stay on the canvas: pointing
+ * at one iteration is not a reason to write the loop out, and the loop
+ * body cannot say which iteration is meant. Once an edit has settled the
+ * loop, they travel like anyone's.
+ */
private setSelected(entity: Entity, selected: boolean): void {
if (!entity.isAlive() || entity.has(Stage) || entity.has(Selected) === selected) return;
if (selected) entity.add(Selected);
else entity.remove(Selected);
- this.reportEdit(entity, 'selected', selected);
+ if (!isLooped(entity)) this.reportEdit(entity, 'selected', selected);
+ }
+
+ /**
+ * Makes `entity` one the file can address on its own. An entity a loop
+ * rendered shares its element — and so its source — with every other
+ * iteration, so a write to it would be a write to all of them; before the
+ * first edit reaches one, the loop is reported for unrolling with what each
+ * iteration rendered, so the writer can spell the iterations out as
+ * elements of their own and land the edit on the right one.
+ *
+ * The iterations are read off the canvas: the loop's entities are the
+ * children of one parent that carry its stamp, in order, and the body
+ * repeats through them (`a b a b` for a body of two elements). Every
+ * iteration but the first is re-stamped with a pending source on the spot,
+ * so anything the editor does to it from here on is addressed to its own
+ * copy and waits for that copy's name (see the edit writer). The stamps
+ * come off every entity of the loop, so this happens once; if the write
+ * declines, `unsettle` puts everything back and the loop stays as it was.
+ *
+ * Left alone, with nothing reported, when the loop is not one the canvas
+ * can spell out: an iteration that rendered something different from the
+ * others, a loop within a loop, an element with no source. The writer
+ * refuses to write into a loop, so such an edit is reported as skipped
+ * rather than reaching every iteration.
+ */
+ private settle(entity: Entity): void {
+ if (!isLooped(entity)) return;
+ const loop = entity.get(Loop)!.value;
+ const stamped = (candidate: Entity | null): boolean => candidate !== null && candidate.get(Loop)?.value === loop;
+
+ // Up to the top of this iteration, and to the element the loop rendered into.
+ let top = entity;
+ while (stamped(getParentEntity(top))) top = getParentEntity(top)!;
+ const container = getParentEntity(top);
+ if (container === null || isLooped(container)) return;
+
+ const roots = getEntityChildren(this.world, container).filter(stamped);
+ const first = roots[0]?.get(Source)?.value;
+ if (!first) return;
+
+ // The body's top-level sources repeat once per iteration.
+ const width = roots.findIndex((root, index) => index > 0 && root.get(Source)?.value === first);
+ const stride = width === -1 ? roots.length : width;
+ if (roots.length % stride !== 0) return;
+ const count = roots.length / stride;
+ if (!roots.every((root, index) => root.get(Source)?.value === roots[index % stride]!.get(Source)?.value)) return;
+
+ // What each iteration rendered, element by element, and the entities
+ // to re-stamp once it is all known to be spellable.
+ const iterations: LoopIteration[] = [];
+ const restamp: [Entity, string][] = [];
+ for (let index = 0; index < count; index++) {
+ const iteration: LoopIteration = {};
+ for (const root of roots.slice(index * stride, (index + 1) * stride)) {
+ for (const member of getEntityTree(this.world, root)) {
+ // Only what the project authored: the runtime's own
+ // sub-entities are derived from that, not written.
+ const authored = authoredElement(member);
+ if (!authored) continue;
+ const source = member.get(Source)?.value;
+ // A loop within the loop, or an element the file does not
+ // know, or one the body renders twice: not spellable.
+ if (!source || !stamped(member) || source in iteration) return;
+ const pending = index > 0 ? nextPendingSource() : undefined;
+ iteration[source] = { props: authored.props, ...(authored.text === undefined ? {} : { text: authored.text }), ...(pending ? { pending } : {}) };
+ if (pending) restamp.push([member, pending]);
+ }
+ }
+ iterations.push(iteration);
+ }
+
+ for (const [member, pending] of restamp) member.set(Source, { value: pending });
+ for (const root of roots) {
+ for (const member of getEntityTree(this.world, root)) member.remove(Loop);
+ }
+
+ this.sink?.({ kind: 'unroll', source: first, loop, iterations });
+ }
+
+ /**
+ * Takes back an unroll the write declined: the entities go back to the
+ * sources they had and to being the loop's, so that pointing at them stays
+ * on the canvas and the next edit asks again. Nothing is destroyed — the
+ * loop still renders them, it just cannot be written to.
+ */
+ public unsettle(edit: UnrollEdit): void {
+ const originals = new Map<string, string>();
+ const members = new Set<string>();
+ for (const iteration of edit.iterations) {
+ for (const [source, { pending }] of Object.entries(iteration)) {
+ members.add(source);
+ if (pending) originals.set(pending, source);
+ }
+ }
+
+ for (const entity of this.world.query(Source)) {
+ const current = entity.get(Source)!.value;
+ const original = originals.get(current);
+ if (original) entity.set(Source, { value: original });
+ if (original || members.has(current)) {
+ entity.add(Loop);
+ entity.set(Loop, { value: edit.loop });
+ }
+ }
}
/**
@@ -224,6 +352,9 @@ export class DocumentEditor {
*/
public insertElement(parent: Entity, element: () => unknown, anchor?: Entity): Entity[] {
if (!parent.get(Source)?.value) return [];
+ // A child of one iteration's element, not of every iteration's.
+ this.settle(parent);
+ if (anchor) this.settle(anchor);
const created = new Map<Entity, Recorded>();
const dispose = createRoot((dispose) => {
@@ -275,15 +406,20 @@ export class DocumentEditor {
* way would have put it (ordering included).
*/
public reparent(entity: Entity, parent: Entity, anchor?: Entity): boolean {
- const source = entity.get(Source)?.value;
- const parentSource = parent.get(Source)?.value;
- if (!source || !parentSource) return false;
+ if (!entity.get(Source)?.value || !parent.get(Source)?.value) return false;
if (getParentEntity(entity) === parent && anchor === undefined) return false;
// Checked here rather than left to the document: a move into itself is
// a no-op there (nothing to report), and one into its own subtree is
// caught only after the node has already left the parent it had.
if (entity === parent || getEntityTree(this.world, entity).includes(parent)) return false;
+ // Each end of the move has to be one element, not every iteration's.
+ this.settle(entity);
+ this.settle(parent);
+ if (anchor) this.settle(anchor);
+ const source = entity.get(Source)!.value;
+ const parentSource = parent.get(Source)!.value;
+
const wasActive = entity.has(Active);
try {
@@ -336,6 +472,8 @@ export class DocumentEditor {
const document = this.document;
for (const entity of roots) {
if (!entity.isAlive()) continue;
+ // Cut from the file as one iteration's element, not the body's.
+ this.settle(entity);
const source = entity.get(Source)!.value;
document.removeNode({ entity: getParentEntity(entity) ?? document.stage.entity }, { entity });
this.sink?.({ kind: 'remove', source });
@@ -385,7 +523,7 @@ export class DocumentEditor {
createElement: (tag) => {
const node = document.createElement(tag);
if (node !== document.stage) {
- document.setProperty(node, SOURCE_ATTR, `${PENDING_PREFIX}${++pendingCounter}`);
+ document.setProperty(node, SOURCE_ATTR, nextPendingSource());
created.set(node.entity, { tag: tag.charAt(0).toLowerCase() + tag.slice(1), props: {} });
}
return node;
diff --git a/apps/web/src/engine/hooks/use-running.ts b/apps/web/src/engine/hooks/use-running.ts
new file mode 100644
index 00000000..57e22fd9
--- /dev/null
+++ b/apps/web/src/engine/hooks/use-running.ts
@@ -0,0 +1,17 @@
+/* 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 { createSignal, onCleanup, type Accessor } from 'solid-js';
+
+import { useEngineContext } from '../context';
+
+/** Reactive read of whether the engine's tick loop is running. */
+export function useRunning(): Accessor<boolean> {
+ const engine = useEngineContext();
+ const [running, setRunning] = createSignal(engine.running);
+
+ onCleanup(engine.onRunningChange(setRunning));
+
+ return running;
+}
diff --git a/apps/web/src/projects/edits.ts b/apps/web/src/projects/edits.ts
index 6525a14b..dc9c2a5a 100644
--- a/apps/web/src/projects/edits.ts
+++ b/apps/web/src/projects/edits.ts
@@ -8,7 +8,7 @@ import { toast } from 'somoto';
import { writeProject } from './host';
-import type { EntityEdit, InsertEdit, MoveEdit, RemoveEdit } from '@/engine/editor';
+import type { EntityEdit, InsertEdit, MoveEdit, RemoveEdit, UnrollEdit } from '@/engine/editor';
import type { SourceEdit, WriteResult } from './host';
import type { World } from 'koota';
@@ -23,18 +23,25 @@ class EditWriter {
private readonly dir: string;
private readonly world: World;
- // Inserts first, in the order they were made (a child's parent may be one
- // of them), then the moves, then per element, per prop: the last value for
- // a prop is the only one worth writing, an element written twice is
- // written once, and only where an element ended up is worth moving it to.
- // Removes last: nothing else addressed to a removed element is worth
- // writing, and once cut, an unnamed element's neighbours are elsewhere.
+ // Unrolls first: everything else addressed to what a loop rendered is
+ // addressed to the copies the unroll makes. Then inserts, in the order
+ // they were made (a child's parent may be one of them), then the moves,
+ // then per element, per prop: the last value for a prop is the only one
+ // worth writing, an element written twice is written once, and only where
+ // an element ended up is worth moving it to. Removes last: nothing else
+ // addressed to a removed element is worth writing, and once cut, an
+ // unnamed element's neighbours are elsewhere.
+ private unrolls = new Map<string, UnrollEdit>();
private inserts = new Map<string, InsertEdit>();
private moves = new Map<string, MoveEdit>();
private pending = new Map<string, InsertEdit['props']>();
private removes = new Set<string>();
// Pending sources a write is out for: edits to them wait for the answer.
private inflight = new Set<string>();
+ // The unrolls a write is out for. One the write declines is taken back
+ // (its entities go back to the loop) rather than discarded like a failed
+ // insert: the loop still renders them, it just cannot be written to.
+ private sent: UnrollEdit[] = [];
private timer: ReturnType<typeof setTimeout> | undefined;
private disposed = false;
@@ -47,7 +54,9 @@ class EditWriter {
public push(edit: EntityEdit): void {
if (this.disposed) return;
- if (edit.kind === 'insert') {
+ if (edit.kind === 'unroll') {
+ this.unrolls.set(edit.source, edit);
+ } else if (edit.kind === 'insert') {
this.inserts.set(edit.source, edit);
} else if (edit.kind === 'remove') {
this.remove(edit);
@@ -138,7 +147,7 @@ class EditWriter {
private flush(): void {
this.timer = undefined;
- if (!this.inserts.size && !this.moves.size && !this.pending.size && !this.removes.size) return;
+ if (!this.unrolls.size && !this.inserts.size && !this.moves.size && !this.pending.size && !this.removes.size) return;
// Anything addressed through an element whose insert is still out
// waits for its name: edits to it, and inserts or moves under or
@@ -149,6 +158,8 @@ class EditWriter {
const held = new Map([...this.pending].filter(([source]) => waits(source)));
const heldRemoves = new Set([...this.removes].filter(waits));
const edits: SourceEdit[] = [
+ // First: the copies an unroll makes are what the rest is addressed to.
+ ...[...this.unrolls.values()].map(({ kind, source, iterations }): SourceEdit => ({ kind, source, iterations })),
...[...this.inserts.values()]
.filter((insert) => !heldInserts.has(insert.source))
.map(({ kind, source, parent, tag, props, before, text }): SourceEdit => ({
@@ -181,7 +192,13 @@ class EditWriter {
];
if (!edits.length) return;
- this.inflight = new Set([...this.inflight, ...this.inserts.keys()].filter((source) => !heldInserts.has(source)));
+ // The names an unroll handed out are out with it.
+ this.sent = [...this.unrolls.values()];
+ this.unrolls = new Map();
+ this.inflight = new Set([
+ ...[...this.inflight, ...this.inserts.keys()].filter((source) => !heldInserts.has(source)),
+ ...this.sent.flatMap((unroll) => pendingsOf(unroll)),
+ ]);
this.inserts = heldInserts;
this.moves = heldMoves;
this.pending = held;
@@ -197,13 +214,6 @@ class EditWriter {
private report(result: WriteResult): void {
if (result.error) {
toast.error('Could not write to the project', { description: result.error });
- } else if (result.skipped.length) {
- // Not a failure: the source computes these, and overwriting an
- // expression with the value it happened to produce would delete
- // someone's work.
- toast.warning('Some props are computed and stay as they are', {
- description: result.skipped.join(', '),
- });
}
if (this.disposed) return;
@@ -211,6 +221,18 @@ class EditWriter {
const editor = getDocumentEditor(this.world);
editor.restamp(ids);
+ // An unroll the write declined: the loop's entities go back to being the
+ // loop's, and to the source they had (which the writer refuses to write
+ // into, so nothing owed to them below reaches the loop body).
+ const restored = new Set<string>();
+ const unrolled = new Set(result.unrolled ?? []);
+ for (const unroll of this.sent) {
+ if (unrolled.has(unroll.source)) continue;
+ editor.unsettle(unroll);
+ for (const pending of pendingsOf(unroll)) restored.add(pending);
+ }
+ this.sent = [];
+
// What piled up under a pending name while its write was out now
// belongs to the real one, or to nothing if the file would not have it.
const rename = (source: string): string | undefined => (this.inflight.has(source) ? ids[source] : source);
@@ -255,7 +277,7 @@ class EditWriter {
if (next) this.removes.add(next);
}
for (const source of this.inflight) {
- if (!ids[source]) editor.discardPending(source);
+ if (!ids[source] && !restored.has(source)) editor.discardPending(source);
}
this.inflight = new Set();
@@ -266,6 +288,13 @@ class EditWriter {
const message = (error: unknown): string => (error instanceof Error ? error.message : String(error));
+/** The pending sources an unroll stamped on the iterations it wrote out. */
+const pendingsOf = (unroll: UnrollEdit): string[] => {
+ return unroll.iterations
+ .flatMap((iteration) => Object.values(iteration)
+ .flatMap(({ pending }) => (pending ? [pending] : [])));
+}
+
/**
* Collects edits against the project in `dir` and writes them back.
*
diff --git a/packages/jsx/src/index.ts b/packages/jsx/src/index.ts
index 721531c4..173b682f 100644
--- a/packages/jsx/src/index.ts
+++ b/packages/jsx/src/index.ts
@@ -24,9 +24,13 @@ export { parseTime, TIME_FPS } from "./time";
export {
COMPOSITION_TAGS,
ID_ATTR,
+ LOOP_ATTR,
+ LOOP_TAGS,
SOURCE_ATTR,
formatSource,
isCompositionTag,
+ isLoopTag,
+ isPropValue,
parseSource,
} from "./source";
export type { CompositionTag, PropValue } from "./source";
diff --git a/packages/jsx/src/source.ts b/packages/jsx/src/source.ts
index be50778c..20645000 100644
--- a/packages/jsx/src/source.ts
+++ b/packages/jsx/src/source.ts
@@ -33,6 +33,23 @@ export const ID_ATTR = "id";
*/
export const SOURCE_ATTR = "__source";
+/**
+ * Attribute the compile step stamps onto every composition element that sits
+ * in the body of a `<For>` or `<Index>`, carrying the source of that loop
+ * (`<file>:<position of the loop element>`). Every iteration renders the same
+ * element, so its entities share one `SOURCE_ATTR` and cannot be written to
+ * one at a time; the loop stamp is what lets the editor tell that, gather the
+ * loop's entities, and have the source unrolled into one element per
+ * iteration before it writes. Only the nearest loop is named: an element in a
+ * loop within a loop is that inner loop's business.
+ */
+export const LOOP_ATTR = "__loop";
+
+/** The Solid control-flow components whose children render once per item. */
+export const LOOP_TAGS: readonly string[] = ["For", "Index"];
+
+export const isLoopTag = (tag: string): boolean => LOOP_TAGS.includes(tag);
+
/**
* What a prop can be worth in a source file: JSON, essentially. It is the
* vocabulary an edit is expressed in — the value as a project would have
@@ -41,6 +58,28 @@ export const SOURCE_ATTR = "__source";
*/
export type PropValue = number | string | boolean | null | PropValue[] | { [key: string]: PropValue };
+/**
+ * Whether a value is one a source file could spell — a `PropValue`. An
+ * instance of a class (an `AssetRef`, say) is not, however plain its fields:
+ * spelled as an object literal it would read back as something else.
+ */
+export function isPropValue(value: unknown): value is PropValue {
+ if (value === null) return true;
+ switch (typeof value) {
+ case "string":
+ case "number":
+ case "boolean":
+ return true;
+ case "object": {
+ if (Array.isArray(value)) return value.every(isPropValue);
+ const prototype = Object.getPrototypeOf(value);
+ return (prototype === Object.prototype || prototype === null) && Object.values(value as object).every(isPropValue);
+ }
+ default:
+ return false;
+ }
+}
+
/**
* The composition elements — the tags that become entities. Everything else a
* project renders is either a user component or DOM content under
diff --git a/packages/reconciler/src/document.ts b/packages/reconciler/src/document.ts
index 95928cd8..17184963 100644
--- a/packages/reconciler/src/document.ts
+++ b/packages/reconciler/src/document.ts
@@ -15,6 +15,7 @@ import {
End,
FontStyle,
FrameRate,
+ Loop,
Geometry,
GeometryType,
getEntityTree,
@@ -45,9 +46,10 @@ import {
TextBaseline,
TextStyle,
} from '@diffusionstudio/runtime';
-import { parseTime, SOURCE_ATTR } from '@diffusionstudio/jsx';
+import { isPropValue, LOOP_ATTR, parseTime, SOURCE_ATTR } from '@diffusionstudio/jsx';
import type { CameraMatrix } from '@diffusionstudio/runtime';
+import type { PropValue } from '@diffusionstudio/jsx';
import { trait, type Entity, type World } from 'koota';
import type { ProjectDocument } from './host';
@@ -79,6 +81,40 @@ export type HostNode = SceneNode | TextNode;
*/
const TextParts = trait(() => new Set<TextNode>());
+/**
+ * What the project wrote on an entity's element, in the vocabulary of the JSX
+ * rather than of the traits it became: the tag, and every prop worth a value a
+ * source file could spell (see `PropValue`), as last set. Kept so an editor
+ * can spell an entity back out as an element — which is how a loop's
+ * iterations get written down one by one — without reading the traits
+ * backwards. `children` is not a prop here: an element's text is `Chars`, and
+ * its element children are the entity's.
+ */
+const Authored = trait(() => ({ tag: '', props: {} as Record<string, PropValue> }));
+
+/** Props that address or wire an element rather than describe it. */
+const UNAUTHORED_PROPS: ReadonlySet<string> = new Set([SOURCE_ATTR, LOOP_ATTR, 'children', 'ref']);
+
+export interface AuthoredElement {
+ /** The camelCase tag the project used. */
+ tag: string;
+ props: Record<string, PropValue>;
+ /** The literal text of a `<text>`, when it holds any. */
+ text?: string;
+}
+
+/**
+ * The element `entity` was rendered from, as a project would author it, or
+ * undefined for an entity no document created (the stage included).
+ */
+export function authoredElement(entity: Entity): AuthoredElement | undefined {
+ const authored = entity.get(Authored);
+ if (authored === undefined) return undefined;
+
+ const text = isText(entity) ? entity.get(Chars)?.value : undefined;
+ return { tag: authored.tag, props: { ...authored.props }, ...(text ? { text } : {}) };
+}
+
export function isSceneNode(node: HostNode): node is SceneNode {
return 'entity' in node;
}
@@ -214,6 +250,11 @@ export class RuntimeDocument implements ProjectDocument<HostNode> {
throw new Error(`<${tag}> is not supported yet (only <stage>, <scene>, <rect> and <text>).`);
}
+ if (entity !== this.stage.entity) {
+ entity.add(Authored);
+ entity.set(Authored, { tag: name, props: {} });
+ }
+
return { entity };
}
@@ -237,7 +278,25 @@ export class RuntimeDocument implements ProjectDocument<HostNode> {
if (!isSceneNode(node)) return;
const { entity } = node;
+ // Noted before it is interpreted: what the project wrote is what an
+ // editor spelling the element back out needs, however the traits pack it.
+ const authored = entity.get(Authored);
+ if (authored && !UNAUTHORED_PROPS.has(name)) {
+ if (isPropValue(value)) authored.props[name] = value;
+ else delete authored.props[name];
+ }
+
switch (name) {
+ case LOOP_ATTR: {
+ if (typeof value !== 'string' || !value) {
+ entity.remove(Loop);
+ return;
+ }
+
+ entity.add(Loop);
+ entity.set(Loop, { value });
+ return;
+ }
case SOURCE_ATTR: {
if (typeof value !== 'string' || !value) {
entity.remove(Source);
diff --git a/packages/runtime/MIGRATION.md b/packages/runtime/MIGRATION.md
new file mode 100644
index 00000000..fc19afab
--- /dev/null
+++ b/packages/runtime/MIGRATION.md
@@ -0,0 +1,156 @@
+# bitecs → koota migration status
+
+Working doc for migrating the editor engine from bitecs (in `apps/web/src/components/engine/`) into this headless runtime package, and for tracking how far `apps/web` has gotten consuming it. 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`.
+- `EntityRecord` (`src/world/serialize.ts`) is an in-memory clone/snapshot format for copy/paste, duplicate, and split-on-overlap — not a persisted format. Persistence to IndexedDB is not required for now and isn't built here; `EntityRecord`'s shape is free to change with no backward-compat constraint.
+- Breaking API/type changes inside the codebase are fine (established convention).
+- 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, Camera, Background, Time (was timestamp), FrameRate, RenderSurface (canvas+ctx+resolution), AudioEngine (injected, no ctor arg), Fonts, Mounts, FramePromises (was world.promises), Stage |
+| `createRuntimeWorld(projectId)` | `src/world/create-world.ts` | Side-effect free except spawning the stage. No AudioContext/window access |
+| Stage model | everywhere | See below, this replaced "parentless = top-level" |
+| Entity clone/snapshot | `src/world/serialize.ts` | serializeEntity / deserializeEntity / cloneFromRecords / stripMountIdentity / cloneSubtree. Backs copy/paste, duplicate, split-on-overlap, not persistence. 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)`). `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(world.get(Root))`. 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, `getTimelineOrigin`/`getSourceFrameAt`/`getSourceWindow` (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; resolveDuration/recomputeEntityTimeRange, propagate/bubble, pinEndToCurrentBounds, trimEntityIn/Out, reactTo* hooks |
+| Actions: resize, keyframe, overlap | `src/actions/{resize,keyframe,overlap}.ts` | Constraint seeding = ConstraintCache trait presence (was undefined store slots). Overlap uses cloneSubtree + trimEntityIn/Out |
+| 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 |
+| Observers (runtime half) | `src/world/observers.ts` | koota subscriptions wiring cache upkeep, Computed mirrors, and time-range reactions; auto-registered by `createRuntimeWorld` (returns a disposer). See semantic notes |
+| Media: decoders + audio bus | `src/media/*` | frame-cache, keyframe-index, time-stretcher, surface, html, audio-peaks moved verbatim; image, video, sequence, audio, shader with entity-based resolvers; audio-bus koota-ported; dispose walkers in `src/media/dispose.ts` and wired as observers |
+| Media: caption family | `src/media/caption/*` | types, subtitles, utils (incl. `setChars`), position, seven presets, resolver. See semantic notes on sparse TextStyle |
+| Text rendering | `src/utils/text.ts` (full port) | tokenize/shape/render joined the Token seed; reads RenderSurface.ctx + Camera; no-ops without a surface. Gradient construction split into `src/systems/gradients.ts` (render system reuses it) |
+| Fonts | `src/fonts/{fixtures,utils}.ts` | WebFonts fixtures verbatim; `loadWebFont` uses the Fonts world trait, resolves the FontFaceSet via globalThis (worker-capable), guards on missing FontFace (headless), and drops db persistence (app wraps it). `getLocalFonts` + `restoreFonts` stay app-side |
+| Support utils | `src/utils/{color,async}.ts`, `clamp` in math | parseColor/colorToHex/rgbToColor (colord dep), AsyncMutex/attempt |
+| Playback system | `src/systems/playback.ts`, `src/utils/transition.ts` | Playhead advance, visibility/local-time recursion, decoder forwarding, transitions, solo muting, live mounts step; `resolveAudioBus` exported from here. See semantic notes |
+| Render system | `src/systems/render.ts`, `HitRegions` world trait | Full traversal port: paints (solid/gradient/media/waveform/shader/html/surface), shadows/strokes/effects, masks, ClipsContent, transitions, Generating pulse. No-op without a RenderSurface. See semantic notes |
+| System schedule | `src/systems/schedule.ts` | `runSystems(world)`: playback → motion → transform → render, shared by the realtime tick and the capture loop |
+| Encoders | `packages/encoder` (`@diffusionstudio/encoder`) | `engine/encode/*` extracted into its OWN package, not `src/capture/`: createEncoder + createImageEncoder as pure consumers of the runtime's public API. See semantic notes |
+| Timecode helpers | `src/utils/time.ts` | `formatTimecode`/`formatTimestamp` (from `utils/transcode.ts`; the image encoder stamps captures with them) |
+| Audio sync | `src/media/audio-sync.ts` | Moved near-verbatim (FFT cross-correlation over RMS envelopes; pure math + mediabunny) |
+| Transcode + previews | `src/media/transcode.ts` | transcodeForTranscription/ForAnalysis, filmstripAsset, waveformAsset, stampTimestampLabel. Preview canvases became OffscreenCanvas + convertToBlob (worker-capable) instead of document.createElement + toDataURL |
+| Contact sheets | `packages/encoder/src/contact-sheet.ts` | Sheets compose image-encoder captures, so they live in the encoder package. It now OWNS `MAX_FRAMES_PER_SHEET` (was `@diffusionstudio/cli/channels`; the CLI imports it from here once rewired). composeSheet is async (OffscreenCanvas) |
+| Interaction reads | `src/queries/interaction.ts` | `entityWorldMat`/`entityLocalMat`/`entityQuad`/`entityAnchor`/`entityOffset` (device pixels, from the SoA stores), `isPointerInEntity`, `getSelectionMask`/`getMaskSelection` (was `utils/interaction.ts` + `utils/coordinates.ts`). `entityWorldMat` of the stage (a top-level node's `getParentEntity`, where bitecs had null) is the view matrix, so parent-space math for roots works unchanged |
+| Interactive upkeep | `src/actions/interactive.ts` | `syncInteractiveState` (was `api/utils.ts`; roots = `ChildOf(stage)`, diffed against the current tags so it fires no redundant events), `enterEntity` (double-click drill-down), `findChildAt` |
+| 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.
+
+## Stage model
+
+Every world spawns one entity tagged `Stage` (`createRuntimeWorld`). All rendered entities are its descendants; "top-level" means "direct child of the stage", never "has no parent".
+
+- `world.get(Root)` returns it; `isStage(entity)` tests for it; `getParentNode(entity)` returns the parent or null when the parent is the stage (use wherever top-level matters); `getParentEntity` returns the raw parent including the stage.
+- Clone contract: the stage id is per-session, so `serializeEntity` omits `ChildOf` when the parent is the stage, and `cloneFromRecords` attaches parentless records to the target world's stage.
+- `cloneSubtree` still keeps an outside-the-subtree parent (records with `ChildOf` are not rehomed).
+- `ChildOf = relation({ exclusive: true, autoDestroy: 'orphan' })`, so `world.get(Root).destroy()` tears down the whole document; clearing a project = destroy + respawn the stage.
+- Actions honor this: `createEntity` spawns as a stage child; `appendChild` asserts `getParentNode(entity) === null` ("already has a parent" = has a non-stage parent) and relies on exclusive re-targeting; `removeChild` re-parents to the stage instead of dropping ChildOf. `cloneFromRecords` attaches parentless records to the stage, so paste/duplicate roots land there too.
+
+## Authored time model
+
+`Delay` and `Trim` were replaced by four one-value traits carrying the vocabulary the JSX authors in, all frames: `Start`, `End`, `SourceIn`, `SourceOut`. Start/End place the node on its parent's timeline (parent-relative), SourceIn/SourceOut pick the slice of its own source that plays there. `PlaybackRate` is unchanged and stays authored.
+
+One trait per value rather than one trait with four fields, because a clip rarely says more than one of these things: they are separate answers to separate questions, and absence is the answer most nodes give. A razor cut authors an `End` and nothing else; a clip dropped at the playhead authors a `Start` and nothing else.
+
+- **Defaults** (`resolveDuration` in `actions/timing.ts`): absent Start is 0, absent SourceIn is 0, and an absent bound means the node runs for its whole source, or 16s (`DEFAULT_DURATION_FRAMES`) when it has no source. Scenes and groups without an End still fit their children.
+- **Every bound caps, so the shortest wins.** With more than one present, none silently overrides another: an End that reaches past the source runs out of frames, a SourceOut past the asset does too, and the asset length caps both. Source-side spans divide by the rate to become timeline frames. The asset length only participates when there is an asset: a shape or a text has nothing to run out of, so its 16s is a default rather than a cap.
+- Because the caps are read at resolve time, nothing rewrites authored values behind the user's back. `clampTrimToAssetDuration` is gone: swapping in a shorter asset shortens the clip on its own, and swapping a longer one back in gives the authored bounds their reach again.
+- `Computed.delay` was renamed `Computed.origin` (the scene frame carrying source frame 0, which is what the field always held) and `Computed.playbackRate` joined it as a mirror, so the per-frame path reads the rate from the same record as the bounds it scales. `Computed.start/end` land on whole frames; `origin` keeps its fraction so audio scheduled against it doesn't inherit a half-frame of slip.
+- Editing helpers replaced the old frame-math ones: `trimEntityIn/Out(world, entity, frame)` move an in/out point at a scene frame (`computeTrimStart/End` only produced the local frame and left callers to write the trait). `trimEntityIn` pins the implied End first, so trimming the head no longer drags the tail along, and writes SourceIn since a head trim is what defines one. `trimEntityOut` writes SourceOut only when the node already carries one, keeping the common case down to a single trait. Overlap resolution (trim/split on drop) is the only runtime caller so far.
+- The five traits share one observer loop (add/change/remove all propagate through the subtree, since a child is placed against its parent's origin). Removal passes the trait being removed down to `recomputeEntityTimeRange` as `ignore`, because koota fires onRemove *before* it clears the trait: without that, `entity.remove(End)` would compute against the End that is going away. Same koota quirk `rebuildCaches`'s `exclude` param exists for.
+
+## 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.
+- There is no Deleted tombstone: `deleteEntity` is `entity.destroy()`; ChildOf is autoDestroy 'orphan' so the subtree cascades. Undo re-creates entities from history (entity ids are not stable across delete/undo — key external refs by `Key`).
+- 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.
+- Observers: the runtime half of `api/observers.ts` became koota subscriptions in `world/observers.ts` (`observeWorld`, auto-registered by `createRuntimeWorld`). appendChild/removeChild are assert + re-target only; cache/size/constraint/time-range fixups ride the ChildOf add/remove events, so `cloneFromRecords`/restore prime Cache, Computed, and time ranges through the same path as actions. `rebuildCaches`/`aggregateKeyframeTracks` take an `exclude` param because koota fires relation remove events while the departing child is still in the old parent's queries.
+- Observer-driven behavior faithful to bitecs: Sequential onAdd group-ifies and strips spatial traits; Group/Scene/Audio onAdd and Paint/AssetId onChange run the timing recomputes; Start/End/SourceIn/SourceOut/PlaybackRate add/change/remove propagate them through the subtree; Keyframe/ItemIndex onChange resort caches; ChildOf onRemove rebuilds caches (+ `reactToChildDetached`, skipped when the parent is already destroyed). Authored→Computed mirrors register on add and change; trait removal does not reset Computed (same as bitecs).
+- Not faithful on purpose: keyframe auto-sync on authored edits did not move into observers. koota change events don't say which field changed, and syncing every field of a trait would mint spurious keyframes on untouched properties. Editing surfaces call `syncKeyframeTrack` for the property they changed (resizeEntity already does for width/height).
+- Size propagation is a Size observer now (`propagateSize` on add/change): bitecs restored sizes through `resizeEntity`, koota deserialization is a plain set. `resizeEntity` no longer calls propagateSize itself.
+- Still app-side from `api/observers.ts`: persistence scheduling, timeline index rebuilds, `syncInteractiveState`, Selected waveform show/hide, ClipHeight/Expanded, ExportSettings defaults, drag-origin traits.
+- Media handle traits renamed with a `Handle` suffix (`VideoDecoderHandle`, `AudioBusHandle`, ...) and typed to the concrete classes via type-only imports, so the trait and the class it stores (`AudioDecoder`, `HtmlHost`, ...) share one export surface without colliding. Resolvers are entity-based (`resolveVideoDecoder(world, entity)`), read Assets/Mode world traits, and store instances with add+set on the handle trait.
+- Dispose hooks are observers now: every `*Handle` trait disposes its value onRemove (destroy removes all traits, so deletion is covered without a subtree walk), Culled onAdd disposes decoders, ChildOf add/remove disconnects audio buses, and `reactToAssetChange`'s Caption branch drops the caption decoder. `src/media/dispose.ts` keeps only `disposeDecoders`/`disconnectAudioBus` for the still-alive cases.
+- TextStyle became all-undefined defaults: a range override carries ONLY its explicitly set fields (sparse store slot = inherit from the node), which is what the bitecs set-observer's TextRange special case enforced. Node-level fallbacks (16px/Inter/400/leading 1) live in the text renderer's accessors, restoring the bitecs `?? 1` leading semantics the earlier trait defaults had drifted from.
+- Caption presets write playhead-driven text via `setChars` (raw store write, no change events) so per-frame caption content never reaches app persistence, same as the bitecs raw array writes. Preset fills/ranges go through createEntity/appendChild, so caches prime via the observers.
+- DOM caveats, all lazy (nothing touches DOM at import time): HtmlHost/SurfaceHost create elements at construction (html-in-canvas is Chromium-flag-only anyway), ShaderHost needs WebGPU, `loadWebFont` no-ops without FontFace. tsconfig gained `DOM.Iterable` + `@webgpu/types`.
+- `SequenceDecoder` iterates the structural `AssetDirectoryHandle` (entries with `getFile`) instead of concrete FileSystemFileHandle, so node hosts can feed frame directories.
+- Playback: the bitecs top-level query `Not(ChildOf('*'))` became `ChildOf(document)`. Playhead advance, auto-stop, and visibility/localTime writes stay raw store writes (no change events, same as bitecs), and `AudioPlayback` is lazily added to playback roots on first tick. `resolveAudioBus` returns null when the world has no AudioEngine context (headless-without-audio; `AudioDecoder.playTo(null, ...)` already no-ops), and the context/offset reads guard the same way. The transition-cleanup `removeComponent(..., false)` became a plain `entity.remove(Transition)`; the app's history layer must treat Transition onRemove during a tick as system-driven, not undoable.
+- Render: `world.hitRegions` became the `HitRegions` world trait. The render system pushes CALLBACK-LESS entries ({ kind: 'entity', id } for Interactive entities, { kind: 'hud', id: 'canvas', quad } for the stage in realtime); the bitecs handleGeometryInteraction/handleCanvasInteraction bindings are the app's: its input system clears the list each frame, pushes HUD controls with handlers attached, and maps callback-less targets to its default handlers. In headless worlds nothing pushes (Interactive is app-added, the canvas region is realtime-only), so the list cannot grow unbounded without an input system draining it.
+- Render's top-level query `Not(ChildOf('*'))` became `ChildOf(document)`, like playback's. `getScaledImageProps` reads the ScaleMode trait against the ScaleModeType enum. `drawRectPath`, `renderFills`, and `renderNode` stay exported (HUD and thumbnail code consume them app-side).
+- Encoders live in `@diffusionstudio/encoder` (deps: runtime, mediabunny, koota), which imports ONLY the runtime's public API — the boundary that motivated the extraction. `ContainerFormat` stays in the runtime (`src/capture/format.ts`) because the ExportSettings trait persists it; the encoder re-exports the type. Nothing inside the runtime may import the encoder (cycle), so encoder-driven utilities like `utils/captions.ts` stay app-side or move into the encoder package.
+- Encoder API changes vs `engine/encode`: `config.scene`/`config.entity` are Entities; `realizeMounts` is injected via config (mount realization needs the host app's module loader + @diffusionstudio/jsx); the hardcoded "Made with Diffusion v..." metadata tag became `config.comment`; the bitecs `Hierarchy(ChildOf)` two-pass rescale walks became `recomputeAllTimeRanges` (exported) over `propagateTimeRangeDown` from the document's top-level nodes; and both encoders now dispose decoders and `world.destroy()` their throwaway offline worlds in `render()`'s finally (koota caps live worlds at 16 — bitecs could just drop them). Offline-world wiring is world traits (`Mode`/`Assets` shared by reference/`Fonts` copied/`RenderSurface`/`AudioEngine`/`FrameRate`/`FramePromises`) instead of the context bag; playhead/Playback/AudioPlayback writes stay raw store writes, matching the systems.
+- The encoder package's tsconfig must mirror the runtime's (`DOM.Iterable`, `@webgpu/types`, plus `@types/audioworklet`): runtime exports point at TS sources, so consumers compile them with their own compiler settings.
+- The active scene is the `Active` tag trait on the entity (`traits/interaction.ts`), not a world trait: `getActiveEntity(world)` / `setActive(world, entity | null)` in `actions/frame.ts` (was `ActiveScene` + `switchActiveScene`). 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.
+- Events: `world.onAdd/onChange/onRemove(trait | ChildOf('*'), cb)` exist; relation callbacks get `(entity, target)`. Exclusive re-target fires remove(old) then add(new); a redundant same-pair add fires nothing; remove events fire while the departing child is still in the old target's queries (hence rebuildCaches' `exclude` param). onAdd fires after initial values are applied (`spawn(Trait({...}))` included) and handlers may set traits on the entity. onChange fires even when the written value is unchanged. Destroy cascades and `world.destroy()` fire remove events with still-usable entities.
+
+## App integration progress (apps/web)
+
+apps/web now depends on `@diffusionstudio/runtime` and `@diffusionstudio/koota-solid` (plus `koota` directly) and has started consuming them, in parallel with the still-fully-intact bitecs engine — nothing in `apps/web/src/components/engine/` has been touched or deleted.
+
+- **Engine shell** (`apps/web/src/engine/`, not in this package — it's browser/DOM-coupled, which this package deliberately isn't): `Engine` (`create-engine.ts`) is a class wrapping `createRuntimeWorld` + `runSystems`; it owns canvas mount/resize/DPR, an AudioContext (created or injected, closed on `dispose()` only if it created it), and its own `requestAnimationFrame` loop (`start`/`stop`, plus a public `step(timestamp)` escape hatch for a future host to drive the tick itself and interleave app-side input/HUD systems around it). `context.tsx` (`EngineProvider`/`useEngineContext`) composes koota-solid's `WorldProvider` around `engine.world`, so trait state is read via `useTrait`/`useQuery` directly against the world, not funneled through a context bag. `canvas.tsx` (`EngineCanvas`) is the reusable mount/resize/start component. `hooks/` has a few illustrative per-trait wrappers so far: `useCamera`, `useActiveScene`, `useRunning`.
+- **Wired into the live app**: `KootaEngineProvider` (the new `EngineProvider`, aliased) is mounted in `pages/home.tsx` at the same level and lifetime as the old bitecs `EngineProvider` (both keyed on `projectId`), so anything under `EditorPage` can reach the koota world as more gets migrated. In `components/canvas/canvas.tsx`, the koota `EngineCanvas` now occupies the visible `z-1` canvas slot. The old bitecs `<canvas id="engine-canvas">` stays mounted at the same DOM id (so its `EngineProvider`'s `init()` still finds it and keeps initializing, and everything still on `useEngine()`/`useECS()` — Toolbar, drag/drop, sidebars, timeline — keeps working) but is `opacity-0 pointer-events-none`: no longer visible or interactive. Drag/drop handlers moved from the canvas element to its wrapping div so `pointer-events-none` didn't silently kill them.
+- **Projects on disk (desktop only)**: `apps/web/src/projects/` loads real content into the koota world. A project is a folder under a user-picked root (persisted in `dspro.ui.projects.root`) holding an `index.tsx` whose default export renders `<stage>`; the electron main process (`apps/desktop/src/projects.ts`) scans the root, scaffolds new folders (`index.tsx`, `package.json`, `tsconfig.json`, generated `jsx.d.ts`), bundles with esbuild + babel-preset-solid (universal, moduleName `@diffusionstudio/jsx`) and watches for changes. The new `@diffusionstudio/reconciler` package (`packages/reconciler`, modeled on ds-next's `src/reconciler/`) evaluates the CJS bundle against the app's solid-js and `@diffusionstudio/jsx`, and its `RuntimeDocument` implements `ProjectDocument` over the world (`mount(code, world)` wraps both): `<stage>` = the infinite canvas, i.e. the Stage entity itself (`background` sets the Background world trait; no size, no camera fitting), `<scene>` = a top-level clipped, playable frame (the `frameSelection` recipe: RECT geometry + `Scene`/`ClipsContent`/`Playback`, minus the solid fill child, since `fill` is the entity's own trait), `<rect>` = a RECT entity (x/y/width/height; `fill` is the entity's own `Color` trait — an intrinsic solid fill rendered first, beneath any Paint children — so a filled rect needs no sub-entities). `start`/`end`/`sourceIn`/`sourceOut` are the authored time traits of the same name: `parseTime` turns seconds, `"30f"`, and clock strings into seconds, and the host converts to project frames against the `FrameRate` trait (so `"30f"` is one second of the canonical 30fps unit, 60 frames in a 60fps project). Absence is meaningful on all four, so an unset or unparsable prop removes its trait instead of writing a zero, which is also what a reactive prop going undefined does. Host nodes wrap entities in objects because Solid's universal renderer treats numbers as text. `useProject(name)` (`apps/web/src/projects/use-project.ts`, called from `pages/editor.tsx`) compiles → renders → re-renders on disk changes. Routes: `/` is the full-screen dashboard (`pages/home.tsx`, no longer a dialog), `/projects/*name` is the editor with the project folder `name` loaded (`useProjectId()` reads it from the route); the old default project id is gone, so there is no editor without a project. Only those three tags so far, handling `name`, `x`/`y`, `width`/`height`, `fill`, `background`, `camera`, and the four time props; no write-back from canvas edits to source yet (`editProperty`/`reportEdit` exist and the sink is wired, but nothing on the canvas calls them; an editor moving a clip converts frames back to seconds itself with `framesToSeconds`).
+
+ **The `<scene>` slice.** The `scene="id"` prop that promoted a `<rect>` is gone (dropped from `PatchProps`, `CommonProps`, and the `PATCH_PROP_KEYS` allowlist): it existed to give a mount root an identity across partial mounts, and with `<stage>` standing for the whole document and `id`/`SOURCE_ATTR` carrying identity, nothing was left for it to do. What the tag added beyond the entity recipe:
+ - **`x`/`y` on a scene are authored.** The old reference model made canvas placement an editor concern with no JSX spelling. That cannot hold once the source is the document: a scene dragged on the canvas has nowhere to be written back to. Same reasoning as `<stage camera>`.
+ - **`insertNode` re-parents.** It previously only rewrote `ItemIndex`, so every element landed under the stage regardless of nesting. Harmless while `<stage>`/`<rect>` were the whole vocabulary; fatal for a frame that has to contain its children. A move between two non-stage parents goes back through the stage, because `appendChild` asserts top-level.
+ - **Ordering compares entities, not handles.** `children()` mints a fresh `{ entity }` per lookup, so the old `siblings.indexOf(node)` in `insertNode`/`getNextSibling` never matched: anchors were ignored (every insert appended) and `getNextSibling` always returned the first child. Only reachable through `<Show>`/`<For>` reordering, which nothing exercised yet.
+ - **`ActiveScene`**: the first scene a render produces claims it if no live scene holds it; `removeNode` clears it when the holder goes. The timeline has to point somewhere, and which scene is being worked on afterwards is the editor's state, not the document's.
+ - Nested `<scene>` throws (the runtime forbids it); `name` joined the handled props.
+
+ **The `key` prop went with it**, for the same reason: it was a within-render label letting elements point at each other (`syncTo` named a clip's `key`), which is the job `id` already does, and unlike `key` an id survives an edit that renumbers the file. So `syncTo` now names an `id`. Dropped from `PatchProps`, `CommonProps`, and `PATCH_PROP_KEYS`. The runtime's `Key` trait is untouched and unrelated: it is the ECS-side stable identity that clone/paste external refs key off (entity ids do not survive delete/undo), and nothing on the JSX path ever wrote it.
+
+ **Element insertion (write-back of new elements).** Editing commands live app-side in `DocumentEditor` (`apps/web/src/engine/editor.ts`, one per world via `getDocumentEditor(world)`, hook `useEditor()`; the reconciler exports `insert`/`withDocument` for it), not in `RuntimeDocument`, which stays a plain `ProjectDocument` host: `onEdit`, `editProperty`, `reportEdit`, `insertElement`, `restamp`, `discardPending`. `editor.insertElement(parent, () => <Rect x={10} width={200} height={300} />, anchor?)` renders the thunk through Solid's universal `insert` under `withDocument` with a recording proxy of the document (same host, every `createElement` stamped pending and `setProperty` noted; the document never learns it was watched), so it goes through the document's own `createElement`/`setProperty`/`insertNode` and is a first-class node on the canvas at once, no remount. The app's JSX compiles for the DOM, so lowercase `<rect>` is unusable there; the PascalCase components (`Rect`, `Scene`, ... now exported from the reconciler index) compile identically in both modes and are the spelling to use. `createElement` lowercases the first letter, so both spellings reach the same recipe. While the thunk renders, every element created is stamped with a pending source (`pending#n`, colon-free so `parseSource` rejects it as an address) and its tag + literal props recorded; afterwards one `InsertEdit` per element is reported in creation order (`EntityEdit` is now `PropEdit | InsertEdit`, discriminated by `kind`), a nested `<Scene><Rect/></Scene>` naming its parent by pending source, and `before` set to the next pre-existing sibling. Returns the top-level entities created. The desktop `applyEdits` grew a matching `SourceInsert` (`SourceEdit = SourceSet | SourceInsert`): it appends `<tag {...props} id="…" />` under the parent (or in front of `before`, which must be a direct child) as text edits at positions ts-morph supplies (`getIndentationText`/`getChildIndentationText`/`isFirstNodeOnLine`, with `manipulationSettings.indentationText` matched to the file first since ts-morph does not detect it; it has no insert-child or open-self-closing operation short of re-printing the body), props via the same `setProp`/`addAttribute` path as prop edits, allocates the id on the spot, and answers with `ids[pending] = real`. A pending parent earlier in the same batch resolves through that map, so a rect drawn into a just-drawn scene lands in one write. The `EditWriter` class (`apps/web/src/projects/edits.ts`) sends inserts first, folds prop edits into a not-yet-flushed insert, holds back edits (and child inserts) addressed through an in-flight pending name until the answer arrives, then re-keys them and re-stamps entities via `DocumentEditor.restamp`; an insert the file would not take (`skipped`) is undone on the canvas via `DocumentEditor.discardPending`. `<text>` is hosted too: the recipe is TEXT geometry + `Chars` + `TextStyle` and no `Size` (a text without one sizes itself to its glyphs, which is what a click-inserted text wants); `color` writes the entity's `Color` (the intrinsic fill the text renderer already draws glyphs with, so no paint child), and `fontSize`/`fontFamily`/`fontWeight`/`fontStyle`/`textAlign`/`textBaseline` write `TextStyle` (an unset or invalid value clears the field to `undefined`, i.e. the renderer's default). Text content travels as Solid text nodes, and the runtime has no node for those, so a plain `TextNode` object (`{ text, parent }`, `HostNode = SceneNode | TextNode`, `isSceneNode` narrows) stands in for the DOM text node the way the original bitecs host's `{ kind: "text" }` did: held by identity (Solid compares handles with `===` and calls `replaceText(getFirstChild(parent))`), kept per text entity in an ordered list, and the list's join is the entity's `Chars`, so `<Text>Hello {name()}</Text>` reconciles through `replaceText`/`insertNode`/`removeNode` on the text nodes alone. Text under anything but a text entity throws, as does an entity under a text. `insertElement`'s recording proxy passes text nodes through untouched (only `SceneNode`s are stamped/recorded). Not built yet: the DrawOverlay port itself.
+
+ **Draw tools (`components/canvas/draw-overlay.tsx`) and Toolbar are on the koota world.** The armed tool is the `Tool` world trait (`traits/interaction.ts`, attached by `createRuntimeWorld`; read with the app's `useTool()`, written with `world.set(Tool, { value })`). Toolbar and the sidebar ToolMenu write it; the bitecs keyboard system's V/H/F/R/T shortcuts still target the old world and stay dead for the new tools until it migrates. Drawing goes through `DocumentEditor.insertElement` with the reconciler's `Scene`/`Rect`/`Text` components (`fill`/`color` instead of a `SolidPaint` child), so a drawn element is written to the source like any authored one; a draw with no mounted project is a no-op. `InsertEdit`/`SourceInsert` gained `text` for a text element's literal content (`Chars` after render), which the desktop writer emits as `<text id="…">Hello</text>` (bare when JSX reads it back verbatim, `{"…"}` otherwise). Runtime gained `findSceneAt`/`worldToLocal` (`queries/hit-test.ts`), reading `LocalTransform` from the store like `getEntityBounds`. Not carried over: `world.history.transaction` — there is no undo layer yet.
+
+ **Selection is a document property.** `selected?: boolean` joined `PatchProps` (picked into `CommonProps` and `SceneProps`, listed in `PATCH_PROP_KEYS`), for the same reason `<stage camera>` and `<scene x y>` exist: the source is the document, so a click on the canvas has nowhere else to be written to, and it means the selection survives the unmount/remount every recompile does. `RuntimeDocument.setProperty('selected')` adds the runtime's `Selected` trait for `true` and removes it for anything else (a bare attribute, a reactive prop going undefined; the stage is never selectable). The editor direction is `DocumentEditor.select(entities, { extend? })` / `deselect` / `clearSelection` (`apps/web/src/engine/editor.ts`): they write the trait and report a `selected` prop edit per entity that changed, `false` for the ones deselected. Selection surfaces go through these rather than touching `Selected` directly (DrawOverlay and SceneInitOverlay do), so nothing else has to know it is a source prop; not an observer on the trait, because a mount adding `Selected` from the file, or an unmount destroying selected entities, must not report as edits. The desktop `setProp` writes `false` as the attribute's absence (`attribute.remove()`), so deselection never leaves `selected={false}` behind, and the same now holds for any boolean prop (`muted`). Not carried over: the bitecs `selectStage/Parent/ChildEntities` helpers and the input system's click/marquee selection, which are still on the old world.
+
+ **The active entity is a document property too.** `active?: boolean` in `PatchProps` (picked into `SceneProps` only for now; the scene restriction is a single assertion in `setActive` and goes when it goes), listed in `PATCH_PROP_KEYS`. The `ActiveScene` world trait is gone; `Active` is a tag on the entity, so it dies with the entity (no clearing in `removeNode`) and comes back from `<scene active>` on remount. Two invariants live in `world/observers.ts`, so they hold whichever path adds the tag: `onAdd(Active)` strips it from every other holder (last wins), and `onAdd(ChildOf('*'))` strips it when the new parent is not the stage (root only). The ChildOf half is what catches a nested `<rect active>` from a file, because Solid sets props before insertion while the entity is still a stage child; the cost is that such a rect first steals the tag and then loses it, so a file saying `active` on a scene and on something nested inside it ends with nothing active until the mount fallback below. `DocumentEditor.activate(entity | null)` is the editor route (trait via `setActive`, `active: false` reported for the one it left, `true` for the new one); overlays use it, the encoder calls `setActive` directly (headless, nothing to report), `useActiveScene()` reads `useQuery(Active)[0]`. `pages/editor.tsx` activates the first root scene through the editor after a mount that produced no active entity, so a project without one gets it written into the file and it sticks. A file naming two active scenes keeps both until the next `activate` cleans up; the document does not report edits.
+
+ **Left stale on purpose** (deferred to a docs/examples pass): all eight `examples/*.tsx` still open with `<rect scene="...">` and no `<stage>`, so `tsc -p examples --noEmit` fails on them; `reference/jsx/{scene,roots}.md` still describes the pre-`<stage>` model where a mount grafts roots into an existing document; and `reference/jsx/{audio-sync,video,audio,elements}.md` still document `key` as the `syncTo` target. Deliberately not half-migrated: `reference/jsx` is stale as a whole, and patching the `key` rows alone would hide that.
+
+## Remaining work (suggested order)
+
+1. **App rewrite** (`apps/web`): app-side world traits (store, timelineIndex signal; input/HUD are done), history via koota events (undo/redo; persistence to IndexedDB is explicitly not required for now, see ground rules, so skip the Dexie-writes/font-persistence wrapping that would otherwise imply), re-adding the editing-surface `syncKeyframeTrack` calls the observers slice dropped, UI to `packages/koota-solid` hooks (only `useCamera`/`useActiveScene`/`useRunning` exist so far), timeline UI consumes new `TimelineNode.entity`. `utils/captions.ts` (trpc/upload/encoder-driven) stays app-side, rewired to `@diffusionstudio/encoder`. Once real content loads into the koota world, delete the now-hidden bitecs canvas and `engine/components`, `engine/api` progressively.
+2. **CLI**: point node capture at the runtime + encoder packages (incl. importing `MAX_FRAMES_PER_SHEET` from the encoder instead of defining it in `cli-channels.ts`).
+
+## 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), colord (parseColor). Dev: @webgpu/types (shader host).
+- AoS handle traits accept class instances and null through plain `entity.set(trait, value)`; `getStore` returns the value array.
diff --git a/packages/runtime/src/traits/node.ts b/packages/runtime/src/traits/node.ts
index 394f75bb..b39ab3f4 100644
--- a/packages/runtime/src/traits/node.ts
+++ b/packages/runtime/src/traits/node.ts
@@ -63,6 +63,14 @@ export const Key = trait({ value: '' });
// entity is not the element it was copied from.
export const Source = trait({ value: '' });
+// On entities a `<For>`/`<Index>` body produced: the source of that loop (see
+// LOOP_ATTR in @diffusionstudio/jsx). Every iteration shares one Source, so
+// this is what tells the editor an element cannot be written to alone and
+// which entities are its fellow iterations. Set by the host while a project
+// renders and taken off once the loop has been unrolled in the source; not
+// serialized, for the same reason Source is not.
+export const Loop = trait({ value: '' });
+
export const AssetId = trait({ value: '' });
// Sibling order under a ChildOf parent.