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.tsindex 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.tsindex 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 }): Ptypes.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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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 underdiff --git a/packages/reconciler/src/document.ts b/packages/reconciler/src/document.tsindex 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.mdnew file mode 100644index 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.tsindex 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.