Skip to content

The VS Code of video editing, built for agents.

TypeScript

Refactor editor integration and enhance editing capabilities

konstantin-paulus6b0b4d34b7eb
diff --git a/apps/desktop/src/edit.ts b/apps/desktop/src/edit.ts
index b443dcbb..da88225d 100644
--- a/apps/desktop/src/edit.ts
+++ b/apps/desktop/src/edit.ts
@@ -20,12 +20,12 @@ import { readdir, readFile, writeFile } from "node:fs/promises";
import { join } from "node:path";
import Sqids from "sqids";
-import { Project, SyntaxKind } from "ts-morph";
+import { IndentationText, Project, SyntaxKind } from "ts-morph";
import { ID_ATTR, formatSource, isCompositionTag, parseSource } from "@diffusionstudio/jsx";
import type { PropValue } from "@diffusionstudio/jsx";
-import type { JsxAttribute, JsxOpeningElement, JsxSelfClosingElement, Node, SourceFile } from "ts-morph";
+import type { JsxAttribute, JsxElement, JsxOpeningElement, JsxSelfClosingElement, Node, SourceFile } from "ts-morph";
export type { PropValue };
@@ -37,11 +37,30 @@ export interface SourceContext {
}
/** Overwrites props of the element named by `source` (a `SOURCE_ATTR` value). */
-export interface SourceEdit {
+export interface SourceSet {
+ kind: "set";
source: string;
props: Record<string, PropValue>;
}
+/**
+ * Adds `<tag {...props} />` under the element named by `parent`, in front of
+ * the child named by `before` or last. `source` is the pending name the canvas
+ * knows the new element by; the write answers with the real one in `ids`.
+ * A parent may itself be pending when it was inserted earlier in the same
+ * write.
+ */
+export interface SourceInsert {
+ kind: "insert";
+ source: string;
+ parent: string;
+ tag: string;
+ props: Record<string, PropValue>;
+ before?: string;
+}
+
+export type SourceEdit = SourceSet | SourceInsert;
+
export interface WriteResult {
/** Sources that could not be written, as `id` or `id (prop)`. */
skipped: string[];
@@ -178,6 +197,66 @@ function setProp(tag: JsxTag, name: string, value: PropValue): void {
else tag.addAttribute({ name, initializer: initializerText(value) });
}
+// ---------------------------------------------------------------------------
+// Layout
+
+/**
+ * ts-morph measures indentation in units of its `indentationText` setting and
+ * does not learn a file's from the file, so before it is asked about one the
+ * setting is matched to what the file's first indented line uses (two spaces
+ * when there is none to learn from).
+ */
+function matchIndentation(sourceFile: SourceFile): void {
+ const lead = /^([ \t]+)\S/m.exec(sourceFile.getFullText())?.[1] ?? "";
+ const indentationText = lead.startsWith("\t")
+ ? IndentationText.Tab
+ : lead.length >= 8
+ ? IndentationText.EightSpaces
+ : lead.length >= 4
+ ? IndentationText.FourSpaces
+ : IndentationText.TwoSpaces;
+ sourceFile.getProject().manipulationSettings.set({ indentationText });
+}
+
+/** The whole element a tag opens — the tag itself when it is self-closing. */
+const elementOf = (tag: JsxTag): JsxElement | JsxSelfClosingElement =>
+ tag.isKind(SyntaxKind.JsxOpeningElement) ? tag.getParentIfKindOrThrow(SyntaxKind.JsxElement) : tag;
+
+/**
+ * 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
+ * re-printing the parent's body, so these are text edits at positions it
+ * supplies; the child takes the indentation of its new neighbours and
+ * everything else in the file keeps its bytes.
+ */
+function insertChild(sourceFile: SourceFile, parent: JsxTag, child: string, before?: JsxTag): void {
+ matchIndentation(sourceFile);
+ const element = elementOf(parent);
+ const indent = element.getIndentationText();
+ const childIndent = element.getChildIndentationText();
+
+ // A self-closing parent is opened up around the child.
+ if (element.isKind(SyntaxKind.JsxSelfClosingElement)) {
+ const opening = element.getText().replace(/\s*\/>$/, ">");
+ sourceFile.replaceText(
+ [element.getStart(), element.getEnd()],
+ `${opening}\n${childIndent}${child}\n${indent}</${tagName(parent)}>`,
+ );
+ return;
+ }
+
+ if (before) {
+ const anchor = elementOf(before);
+ if (anchor.isFirstNodeOnLine()) sourceFile.insertText(anchor.getStartLinePos(), `${anchor.getIndentationText()}${child}\n`);
+ else sourceFile.insertText(anchor.getStart(), `${child} `);
+ return;
+ }
+
+ const closing = element.getClosingElement();
+ if (closing.isFirstNodeOnLine()) sourceFile.insertText(closing.getStartLinePos(), `${childIndent}${child}\n`);
+ else sourceFile.insertText(closing.getStart(), `\n${childIndent}${child}\n${indent}`);
+}
+
/** Whether an expression is a value rather than a way of computing one. */
function isLiteral(node: Node): boolean {
if (
@@ -256,18 +335,24 @@ interface OpenFile {
text: string;
}
-/** An edit resolved to the element it names within its file. */
-interface FileEdit {
- locator: number | string;
- edit: SourceEdit;
-}
-
/** What one file's edits came to. */
interface FileWrite {
skipped: string[];
ids: Record<string, string>;
}
+/**
+ * The element a source names, resolved through the names this write has
+ * already handed out: an insert answers with a real source, and anything
+ * addressed by the pending one from then on means the new element.
+ */
+function locate(
+ source: string,
+ ids: Record<string, string>,
+): { file: string; locator: number | string } | undefined {
+ return parseSource(ids[source] ?? source);
+}
+
/**
* One write against a project's sources. ts-morph parses into a file system of
* its own: bytes come off disk and go back to it here, and every file a write
@@ -400,18 +485,20 @@ class SourceWriter {
const ids: Record<string, string> = {};
// Grouped by file: one parse and one write per file, however many elements
- // of it an edit touched.
- const byFile = new Map<string, FileEdit[]>();
+ // 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.
+ const fileOf = new Map<string, string>();
+ const byFile = new Map<string, SourceEdit[]>();
for (const edit of edits) {
- const location = parseSource(edit.source);
- if (!location) {
+ const address = edit.kind === "insert" ? edit.parent : edit.source;
+ const file = parseSource(address)?.file ?? fileOf.get(address);
+ if (!file) {
skipped.push(edit.source);
continue;
}
- byFile.set(location.file, [
- ...(byFile.get(location.file) ?? []),
- { locator: location.locator, edit },
- ]);
+ if (edit.kind === "insert") fileOf.set(edit.source, file);
+ byFile.set(file, [...(byFile.get(file) ?? []), edit]);
}
for (const file of byFile.keys()) await this.load(file);
@@ -425,7 +512,7 @@ class SourceWriter {
// ts-morph will not vouch for is dropped rather than half written.
if (!written) {
this.discard(file);
- skipped.push(...entries.map((entry) => entry.edit.source));
+ skipped.push(...entries.map((entry) => entry.source));
continue;
}
@@ -442,13 +529,24 @@ class SourceWriter {
* the sources it would not write, or undefined if the file is to be left
* alone entirely.
*/
- private editFile(file: string, sourceFile: SourceFile, entries: FileEdit[]): FileWrite | undefined {
+ private editFile(file: string, sourceFile: SourceFile, entries: SourceEdit[]): FileWrite | undefined {
const nextId = idAllocator(idsIn(sourceFile));
const skipped: string[] = [];
const ids: Record<string, string> = {};
try {
- for (const { locator, edit } of entries) {
+ for (const edit of entries) {
+ if (edit.kind === "insert") {
+ if (!this.insertElement(file, sourceFile, edit, ids, nextId)) skipped.push(edit.source);
+ continue;
+ }
+
+ const locator = locate(edit.source, ids)?.locator;
+ if (locator === undefined) {
+ skipped.push(edit.source);
+ continue;
+ }
+
let wrote = false;
for (const [name, value] of Object.entries(edit.props)) {
@@ -486,6 +584,45 @@ class SourceWriter {
this.dropUnparsed([file]);
return this.files.has(file) ? { skipped, ids } : undefined;
}
+
+ /**
+ * Adds one element to the tree, named on the spot: the canvas is already
+ * showing it and will address it by that name with its next edit, so it
+ * cannot wait for a write to earn one. False when the parent (or the anchor)
+ * is not an element this file can be asked to hold a child under.
+ */
+ private insertElement(
+ file: string,
+ sourceFile: SourceFile,
+ edit: SourceInsert,
+ ids: Record<string, string>,
+ nextId: () => string,
+ ): boolean {
+ if (!isCompositionTag(edit.tag)) return false;
+
+ const parentLocator = locate(edit.parent, ids)?.locator;
+ const parent = parentLocator === undefined ? undefined : findTag(sourceFile, parentLocator);
+ if (!parent) return false;
+
+ let before: JsxTag | undefined;
+ if (edit.before !== undefined) {
+ const anchorLocator = locate(edit.before, ids)?.locator;
+ before = anchorLocator === undefined ? undefined : findTag(sourceFile, anchorLocator);
+ // "In front of" only means something for a child of the same parent.
+ if (!before || elementOf(before).getParent() !== elementOf(parent)) return false;
+ }
+
+ // Placed bare and named, then given its props the way any element is:
+ // one attribute at a time, re-found by name after each (editing one
+ // attribute forgets its siblings).
+ const id = nextId();
+ insertChild(sourceFile, parent, `<${edit.tag} ${ID_ATTR}="${id}" />`, before);
+ for (const [name, value] of Object.entries(edit.props)) {
+ setProp(findTag(sourceFile, id)!, name, value);
+ }
+ ids[edit.source] = formatSource(file, id);
+ return true;
+ }
}
/** Stamps every source file of the project. Writes nothing to a fully named project. */
diff --git a/apps/web/src/components/sidebar-right/inspector/background.tsx b/apps/web/src/components/sidebar-right/inspector/background.tsx
index 80515e69..92582308 100644
--- a/apps/web/src/components/sidebar-right/inspector/background.tsx
+++ b/apps/web/src/components/sidebar-right/inspector/background.tsx
@@ -18,11 +18,11 @@ import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip
import { createSignal } from "solid-js";
import { Background, DEFAULT_BACKGROUND, Root, colorToHex } from "@diffusionstudio/runtime";
import { useTrait, useWorld } from "@diffusionstudio/koota-solid";
-import { useDocument } from "@/engine/hooks/use-document";
+import { useEditor } from "@/engine/hooks/use-editor";
export function BackgroundSettings() {
const world = useWorld();
- const doc = useDocument();
+ const editor = useEditor();
const [isPickerOpen, setIsPickerOpen] = createSignal(false);
const background = useTrait(world.get(Root)!, Background);
@@ -34,7 +34,7 @@ export function BackgroundSettings() {
const assignColor = (value: number) => {
const root = world.get(Root)!;
const color = colorToHex(value);
- doc().editProperty(root, "background", color);
+ editor.editProperty(root, "background", color);
};
return (
diff --git a/apps/web/src/components/sidebar-right/inspector/inspector-header.tsx b/apps/web/src/components/sidebar-right/inspector/inspector-header.tsx
index 6154c57b..d77fb9e1 100644
--- a/apps/web/src/components/sidebar-right/inspector/inspector-header.tsx
+++ b/apps/web/src/components/sidebar-right/inspector/inspector-header.tsx
@@ -14,11 +14,11 @@ import { Button } from "@/components/ui/button";
import { useWorld } from "@diffusionstudio/koota-solid";
import { focusContent, getCameraMatrix, Root, setCameraZoom, zoomCameraBy } from "@diffusionstudio/runtime";
import { useCameraScale } from "@/engine";
-import { useDocument } from "@/engine/hooks/use-document";
+import { useEditor } from "@/engine/hooks/use-editor";
export function InspectorHeader() {
const world = useWorld();
- const doc = useDocument();
+ const editor = useEditor();
// Every operation here is anchored on the stage itself — its center, or its
// content — so the menu needs no canvas geometry of its own.
@@ -27,15 +27,15 @@ export function InspectorHeader() {
const zoomBy = (factor: number) => {
zoomCameraBy(world, factor);
- doc()?.reportEdit(world.get(Root)!, 'camera', getCameraMatrix(world));
+ editor.reportEdit(world.get(Root)!, 'camera', getCameraMatrix(world));
};
const zoomTo = (percent: number) => {
setCameraZoom(world, percent / 100);
- doc()?.reportEdit(world.get(Root)!, 'camera', getCameraMatrix(world));
+ editor.reportEdit(world.get(Root)!, 'camera', getCameraMatrix(world));
};
const zoomToFit = () => {
focusContent(world);
- doc()?.reportEdit(world.get(Root)!, 'camera', getCameraMatrix(world));
+ editor.reportEdit(world.get(Root)!, 'camera', getCameraMatrix(world));
};
return (
diff --git a/apps/web/src/engine/camera-controller.tsx b/apps/web/src/engine/camera-controller.tsx
index 5429dc2b..5ac2eaa6 100644
--- a/apps/web/src/engine/camera-controller.tsx
+++ b/apps/web/src/engine/camera-controller.tsx
@@ -5,7 +5,7 @@
import { createMemo, onCleanup, onMount } from 'solid-js';
import { useTrait, useWorld } from '@diffusionstudio/koota-solid';
import { panCamera, setCamera, zoomCameraAt, getCamera, RenderSurface, getCameraMatrix, Root } from '@diffusionstudio/runtime';
-import { useDocument } from './hooks/use-document';
+import { useEditor } from './hooks/use-editor';
import type { JSX } from 'solid-js';
@@ -28,7 +28,7 @@ function isEditable(target: EventTarget | null): boolean {
export function CameraController(): JSX.Element {
const world = useWorld();
const surface = useTrait(world, RenderSurface);
- const doc = useDocument();
+ const editor = useEditor();
const canvas = createMemo(() => {
const target = surface()?.canvas;
@@ -86,7 +86,7 @@ export function CameraController(): JSX.Element {
panCamera(world, event.deltaX * scale, event.deltaY * scale);
}
- doc()?.reportEdit(world.get(Root)!, 'camera', getCameraMatrix(world));
+ editor.reportEdit(world.get(Root)!, 'camera', getCameraMatrix(world));
};
const handlePointerDown = (event: PointerEvent): void => {
@@ -114,7 +114,7 @@ export function CameraController(): JSX.Element {
// a long drag can't accumulate rounding error.
const [x, y] = localPoint(event);
setCamera(world, { e: startE + (x - startX), f: startF + (y - startY) });
- doc()?.reportEdit(world.get(Root)!, 'camera', getCameraMatrix(world));
+ editor.reportEdit(world.get(Root)!, 'camera', getCameraMatrix(world));
};
const handlePointerUp = (event: PointerEvent): void => {
diff --git a/apps/web/src/engine/editor.ts b/apps/web/src/engine/editor.ts
new file mode 100644
index 00000000..f3963f8c
--- /dev/null
+++ b/apps/web/src/engine/editor.ts
@@ -0,0 +1,261 @@
+/* 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/. */
+
+/**
+ * The editing side of a mounted project: what an editor does to the document
+ * (change a prop, add an element) and how those changes are reported back in
+ * the vocabulary of the JSX, so whoever mounted the project can write them to
+ * the source. The document itself only knows how to be rendered into; this is
+ * where the commands live.
+ */
+
+import { getEntityChildren, getParentEntity, Source } from '@diffusionstudio/runtime';
+import { SOURCE_ATTR } from '@diffusionstudio/jsx';
+import { createRoot } from 'solid-js';
+
+import { getRuntimeDocument, insert, withDocument } from '@diffusionstudio/reconciler';
+
+import type { PropValue } from '@diffusionstudio/jsx';
+import type { Entity, World } from 'koota';
+import type { ProjectDocument, RuntimeDocument, SceneNode } from '@diffusionstudio/reconciler';
+
+/**
+ * A property the editor changed, in the vocabulary of the JSX rather than of
+ * the traits it was written to: `source` is the element it belongs to (its
+ * SOURCE_ATTR stamp) and `value` is what a project would have written there.
+ * Whoever mounts the document decides what to do with these — writing them
+ * back to disk is the point, but nothing here knows about a disk.
+ */
+export interface PropEdit {
+ kind: 'prop';
+ source: string;
+ name: string;
+ value: PropValue;
+}
+
+/**
+ * An element the editor added. The entity already exists in the world when
+ * this is reported, stamped with the pending `source`; whoever writes it to
+ * disk answers with the real one and re-stamps (see `isPendingSource`).
+ * `parent` is the source of the element it was inserted under and `before`,
+ * when present, the sibling it was placed in front of; without it, appended.
+ */
+export interface InsertEdit {
+ kind: 'insert';
+ source: string;
+ parent: string;
+ tag: string;
+ props: Record<string, PropValue>;
+ before?: string;
+}
+
+export type EntityEdit = PropEdit | InsertEdit;
+
+/**
+ * Sources of elements the editor created that no write has named yet. Shaped
+ * so `parseSource` rejects them (no `:`): they must never reach a file as an
+ * address, only as the key a write answers with the real source for.
+ */
+const PENDING_PREFIX = 'pending#';
+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;
+ }
+}
+
+/** What `insertElement` learns about each element while it renders. */
+interface Recorded {
+ tag: string;
+ props: Record<string, PropValue>;
+}
+
+export class DocumentEditor {
+ private readonly world: World;
+ private sink?: (edit: EntityEdit) => void;
+
+ public constructor(world: World) {
+ this.world = world;
+ }
+
+ /** The document of the current mount. */
+ private get document(): RuntimeDocument {
+ return getRuntimeDocument(this.world);
+ }
+
+ /**
+ * Listens for edits made through this editor. One sink at a time — a
+ * second call replaces the first. Returns an unsubscribe.
+ */
+ public onEdit(sink: (edit: EntityEdit) => void): () => void {
+ this.sink = sink;
+ return () => {
+ if (this.sink === sink) {
+ this.sink = undefined;
+ }
+ };
+ }
+
+ /** Writes a prop to the document and reports it. */
+ public editProperty(entity: Entity, name: string, value: PropValue): void {
+ this.document.setProperty({ entity }, name, value);
+ this.reportEdit(entity, name, value);
+ }
+
+ /** Reports an edit whose change the editor already made itself. */
+ public reportEdit(entity: Entity, name: string, value: PropValue): void {
+ const source = entity.get(Source)?.value;
+
+ if (source) {
+ this.sink?.({ kind: 'prop', source, name, value });
+ }
+ }
+
+ /**
+ * Adds elements the way a project would author them, under `parent` and in
+ * front of `anchor` (or last):
+ *
+ * editor.insertElement(scene, () => <Rect x={10} width={200} height={300} />)
+ *
+ * `element` is rendered like a piece of a project (the PascalCase
+ * components of "./elements", since an app's own JSX compiles for the DOM),
+ * so the entities are real from this call on: same recipe, traits, and
+ * ordering a compiled render gets. What they lack is a name in the file, so
+ * each is stamped with a pending source that `restamp` replaces once the
+ * write answers, and reported as an insert in creation order (parents
+ * before children, so a nested tree lands in one write). Returns the
+ * top-level entities created; nothing when the parent has no source to be
+ * written under.
+ */
+ public insertElement(parent: Entity, element: () => unknown, anchor?: Entity): Entity[] {
+ if (!parent.get(Source)?.value) return [];
+
+ const created = new Map<Entity, Recorded>();
+ const dispose = createRoot((dispose) => {
+ withDocument(this.recording(created), () =>
+ insert({ entity: parent }, element, anchor ? { entity: anchor } : null),
+ );
+ return dispose;
+ });
+ // Nothing here stays reactive: the values were the tool's, and the
+ // entities outlive the graph that produced them (as on unmount).
+ dispose();
+
+ for (const [entity, { tag, props }] of created) {
+ const parentEntity = getParentEntity(entity);
+ const parentSource = parentEntity?.get(Source)?.value;
+ if (!parentEntity || !parentSource) continue;
+
+ // Placed in front of the next sibling that was already there. New
+ // siblings are skipped: they are appended after this one, or share
+ // its anchor, and either way the order in the file comes out right.
+ const siblings = getEntityChildren(this.world, parentEntity);
+ const before = siblings
+ .slice(siblings.indexOf(entity) + 1)
+ .find((sibling) => !created.has(sibling))
+ ?.get(Source)?.value;
+
+ this.sink?.({
+ kind: 'insert',
+ source: entity.get(Source)!.value,
+ parent: parentSource,
+ tag,
+ props,
+ ...(before ? { before } : {}),
+ });
+ }
+
+ return [...created.keys()].filter((entity) => !created.has(getParentEntity(entity)!));
+ }
+
+ /**
+ * Re-stamps entities whose element earned a name, as `old source -> new`.
+ * Queried rather than remembered: the entities that survived are the ones
+ * the world still holds.
+ */
+ public restamp(ids: Record<string, string>): void {
+ for (const entity of this.world.query(Source)) {
+ const next = ids[entity.get(Source)!.value];
+ if (next) entity.set(Source, { value: next });
+ }
+ }
+
+ /**
+ * Takes back an element whose insert could not be written: it has no
+ * place in the file, so it has no place on the canvas either.
+ */
+ public discardPending(source: string): void {
+ if (!isPendingSource(source)) return;
+ const document = this.document;
+ // Snapshot: destroying cascades through the subtree, and a live query
+ // would hand back children that went with their parent.
+ const doomed = [...this.world.query(Source)].filter((entity) => entity.get(Source)?.value === source);
+ for (const entity of doomed) {
+ if (!entity.isAlive()) continue;
+ const parent = getParentEntity(entity);
+ document.removeNode({ entity: parent ?? document.stage.entity }, { entity });
+ }
+ }
+
+ /**
+ * The document as `insertElement` renders into it: the same host, with
+ * every element created stamped pending and its tag and literal props
+ * noted in `created`. The document itself never learns it was watched.
+ */
+ private recording(created: Map<Entity, Recorded>): ProjectDocument<SceneNode> {
+ const document = this.document;
+ return {
+ stage: document.stage,
+ createElement: (tag) => {
+ const node = document.createElement(tag);
+ if (node !== document.stage) {
+ document.setProperty(node, SOURCE_ATTR, `${PENDING_PREFIX}${++pendingCounter}`);
+ created.set(node.entity, { tag: tag.charAt(0).toLowerCase() + tag.slice(1), props: {} });
+ }
+ return node;
+ },
+ setProperty: (node, name, value) => {
+ const recorded = created.get(node.entity);
+ if (recorded && name !== SOURCE_ATTR && name !== 'children' && name !== 'ref' && isPropValue(value)) {
+ recorded.props[name] = value;
+ }
+ document.setProperty(node, name, value);
+ },
+ createTextNode: () => document.createTextNode(),
+ replaceText: () => document.replaceText(),
+ isTextNode: () => document.isTextNode(),
+ insertNode: (parent, node, anchor) => document.insertNode(parent, node, anchor),
+ removeNode: (parent, node) => document.removeNode(parent, node),
+ getParentNode: (node) => document.getParentNode(node),
+ getFirstChild: (node) => document.getFirstChild(node),
+ getNextSibling: (node) => document.getNextSibling(node),
+ };
+ }
+}
+
+const editors = new WeakMap<World, DocumentEditor>();
+
+/** The editor for `world`, created on first use. Outlives mounts: it reads the current document per call. */
+export function getDocumentEditor(world: World): DocumentEditor {
+ let editor = editors.get(world);
+ if (!editor) {
+ editor = new DocumentEditor(world);
+ editors.set(world, editor);
+ }
+ return editor;
+}
diff --git a/apps/web/src/engine/hooks/index.ts b/apps/web/src/engine/hooks/index.ts
index ed2aa6c6..3cd7b2f4 100644
--- a/apps/web/src/engine/hooks/index.ts
+++ b/apps/web/src/engine/hooks/index.ts
@@ -5,3 +5,4 @@
export * from './use-active-scene';
export * from './use-camera';
export * from './use-running';
+export * from './use-editor';
diff --git a/apps/web/src/engine/hooks/use-editor.ts b/apps/web/src/engine/hooks/use-editor.ts
new file mode 100644
index 00000000..71176c9f
--- /dev/null
+++ b/apps/web/src/engine/hooks/use-editor.ts
@@ -0,0 +1,13 @@
+/* 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 { useWorld } from "@diffusionstudio/koota-solid";
+import { getDocumentEditor } from "../editor";
+
+import type { DocumentEditor } from "../editor";
+
+/** The editor of the mounted project: prop edits and element inserts, reported back to the source. */
+export function useEditor(): DocumentEditor {
+ return getDocumentEditor(useWorld());
+}
diff --git a/apps/web/src/engine/index.ts b/apps/web/src/engine/index.ts
index 1eb3d6ec..5e91e211 100644
--- a/apps/web/src/engine/index.ts
+++ b/apps/web/src/engine/index.ts
@@ -7,3 +7,4 @@ export * from './context';
export * from './canvas';
export * from './camera-controller';
export * from './hooks';
+export * from './editor';
diff --git a/apps/web/src/pages/editor.tsx b/apps/web/src/pages/editor.tsx
index 98a07089..8e4579d4 100644
--- a/apps/web/src/pages/editor.tsx
+++ b/apps/web/src/pages/editor.tsx
@@ -10,18 +10,81 @@ import { FloatingProjectHeader, SidebarLeft } from "@/components/sidebar-left";
import { useLayout, MIN_TIMELINE_HEIGHT } from "@/context/layout";
import { useEditorApi } from "@/context/dapi";
import { RULER_HEIGHT } from "@/components/engine/timeline/config";
+import { createEffect, onCleanup } from 'solid-js';
+import { toast } from 'somoto';
+import { useWorld } from '@diffusionstudio/koota-solid';
+import { mount } from '@diffusionstudio/reconciler';
+import { getDocumentEditor } from '@/engine/editor';
+import { createEditWriter } from '@/projects/edits';
+import { compileProject, watchProject, projectDir } from '@/projects/host';
import { useProjectId } from "@/hooks/use-project-id";
-import { useProject } from "@/projects";
+
+import type { Mount } from '@diffusionstudio/reconciler';
+import type { EditWriter } from '@/projects/edits';
const MIN_CANVAS_HEIGHT = 200;
export function EditorPage() {
- // The project folder from the route, rendered into the koota world.
- useProject(useProjectId());
-
const { uiVisible, timelineMinimized, timelineHeight, setTimelineHeight } = useLayout();
const { isDesktop, isFullscreen } = useEditorApi();
const [resizing, setResizing] = createSignal(false);
+ const name = useProjectId();
+ const world = useWorld();
+
+ createEffect(() => {
+ const dir = projectDir(name());
+ if (!dir) return;
+
+ let mounted: Mount | undefined;
+ let writer: EditWriter | undefined;
+ let unlisten: (() => void) | undefined;
+ let disposed = false;
+ let generation = 0;
+
+ const unmount = (): void => {
+ // Before the entities go: what the editor changed is still owed to the
+ // file, whatever happens to the scene that showed it.
+ unlisten?.();
+ unlisten = undefined;
+ writer?.dispose();
+ writer = undefined;
+ mounted?.dispose();
+ mounted = undefined;
+ };
+
+ const load = async (): Promise<void> => {
+ const current = ++generation;
+ const result = await compileProject(dir);
+ if (disposed || current !== generation) return;
+
+ // A broken edit keeps the last good render on the canvas.
+ if (!result.ok) {
+ toast.error('Project failed to compile', { description: result.error });
+ return;
+ }
+
+ // The old render goes first: there is only one stage per world.
+ unmount();
+ try {
+ mounted = mount(result.code, world);
+ // The rendered scene knows which element every entity came from, so
+ // from here on an edit in the editor can find its way back.
+ writer = createEditWriter(dir, world);
+ unlisten = getDocumentEditor(world).onEdit((edit) => writer?.push(edit));
+ } catch (error) {
+ toast.error('Project failed to render', { description: (error as Error).message });
+ }
+ };
+
+ void load();
+ const unwatch = watchProject(dir, () => void load());
+
+ onCleanup(() => {
+ disposed = true;
+ unwatch();
+ unmount();
+ });
+ });
const timelineStyles = createMemo(() => {
if (!uiVisible()) return;
diff --git a/apps/web/src/projects/edits.ts b/apps/web/src/projects/edits.ts
index 29176cca..e32e1c6f 100644
--- a/apps/web/src/projects/edits.ts
+++ b/apps/web/src/projects/edits.ts
@@ -2,20 +2,13 @@
* 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/. */
-// The path from an edit made in the editor to the JSX that produced it.
-//
-// Nothing here changes the composition — the document did that before the edit
-// was reported, which is what makes writing cheap: no compile, no remount, and
-// a dragged rect can report a hundred positions on the way to the one that
-// ends up in the file. They collapse into a single write per element and prop,
-// so what reaches disk is where things ended up rather than how they got there.
-
-import { Source } from '@diffusionstudio/runtime';
+
+import { getDocumentEditor } from '@/engine/editor';
import { toast } from 'somoto';
import { writeProject } from './host';
-import type { EntityEdit } from '@diffusionstudio/reconciler';
+import type { EntityEdit, InsertEdit } from '@/engine/editor';
import type { SourceEdit, WriteResult } from './host';
import type { World } from 'koota';
@@ -26,45 +19,94 @@ import type { World } from 'koota';
*/
const DEBOUNCE = 120;
-export interface EditWriter {
+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 per element, per prop: the last value for a prop is the
+ // only one worth writing, and an element written twice is written once.
+ private inserts = new Map<string, InsertEdit>();
+ private pending = new Map<string, InsertEdit['props']>();
+ // Pending sources a write is out for: edits to them wait for the answer.
+ private inflight = new Set<string>();
+ private timer: ReturnType<typeof setTimeout> | undefined;
+ private disposed = false;
+
+ public constructor(dir: string, world: World) {
+ this.dir = dir;
+ this.world = world;
+ }
+
/** Records an edit; the write follows once edits stop arriving. */
- push(edit: EntityEdit): void;
+ public push(edit: EntityEdit): void {
+ if (this.disposed) return;
+
+ if (edit.kind === 'insert') {
+ this.inserts.set(edit.source, edit);
+ } else {
+ // A prop of an element still waiting to be inserted is part of how
+ // it is inserted.
+ const insert = this.inserts.get(edit.source);
+ if (insert) insert.props = { ...insert.props, [edit.name]: edit.value };
+ else this.pending.set(edit.source, { ...this.pending.get(edit.source), [edit.name]: edit.value });
+ }
+
+ this.schedule();
+ }
+
/** Writes what is pending and stops. */
- dispose(): void;
-}
+ public dispose(): void {
+ clearTimeout(this.timer);
+ // The last edits still belong in the file, even though the entities
+ // they came from are on their way out.
+ this.flush();
+ this.disposed = true;
+ }
-/**
- * Collects edits against the project in `dir` and writes them back.
- *
- * `world` is only read after a write returns, to answer the one thing a write
- * can tell the canvas: an element that had no `id` in the source has one now,
- * and the entity it produced has to be re-stamped with it. Without that, the
- * next edit to the same element would still address it by a position the
- * write itself may have invalidated.
- */
-export function createEditWriter(dir: string, world: World): EditWriter {
- // Per element, then per prop: the last value for a prop is the only one
- // worth writing, and an element written twice is written once.
- const pending = new Map<string, Record<string, unknown>>();
- let timer: ReturnType<typeof setTimeout> | undefined;
- let disposed = false;
-
- const flush = (): void => {
- timer = undefined;
- if (!pending.size) return;
-
- const edits: SourceEdit[] = [...pending].map(([source, props]) => ({
- source,
- props: props as SourceEdit['props'],
- }));
- pending.clear();
-
- writeProject(dir, edits).then(report).catch((error: unknown) => {
- toast.error('Could not write to the project', { description: message(error) });
- });
- };
-
- const report = (result: WriteResult): void => {
+ private schedule(): void {
+ clearTimeout(this.timer);
+ this.timer = setTimeout(() => this.flush(), DEBOUNCE);
+ }
+
+ private flush(): void {
+ this.timer = undefined;
+ if (!this.inserts.size && !this.pending.size) return;
+
+ // Anything addressed through an element whose insert is still out
+ // waits for its name: edits to it, and inserts under or beside it.
+ const waits = (source: string | undefined): boolean => source !== undefined && this.inflight.has(source);
+ const heldInserts = new Map([...this.inserts].filter(([, insert]) => waits(insert.parent) || waits(insert.before)));
+ const held = new Map([...this.pending].filter(([source]) => waits(source)));
+ const edits: SourceEdit[] = [
+ ...[...this.inserts.values()]
+ .filter((insert) => !heldInserts.has(insert.source))
+ .map(({ kind, source, parent, tag, props, before }): SourceEdit => ({
+ kind,
+ source,
+ parent,
+ tag,
+ props,
+ ...(before === undefined ? {} : { before }),
+ })),
+ ...[...this.pending]
+ .filter(([source]) => !held.has(source))
+ .map(([source, props]): SourceEdit => ({ kind: 'set', source, props })),
+ ];
+ if (!edits.length) return;
+
+ this.inflight = new Set([...this.inflight, ...this.inserts.keys()].filter((source) => !heldInserts.has(source)));
+ this.inserts = heldInserts;
+ this.pending = held;
+
+ writeProject(this.dir, edits)
+ .then((result) => this.report(result))
+ .catch((error: unknown) => {
+ toast.error('Could not write to the project', { description: message(error) });
+ });
+ }
+
+ private report(result: WriteResult): void {
if (result.error) {
toast.error('Could not write to the project', { description: result.error });
} else if (result.skipped.length) {
@@ -76,36 +118,57 @@ export function createEditWriter(dir: string, world: World): EditWriter {
});
}
- if (result.ids && !disposed) restamp(world, result.ids);
- };
-
- return {
- push(edit) {
- if (disposed) return;
- pending.set(edit.source, { ...pending.get(edit.source), [edit.name]: edit.value });
- clearTimeout(timer);
- timer = setTimeout(flush, DEBOUNCE);
- },
- dispose() {
- clearTimeout(timer);
- // The last edits still belong in the file, even though the entities
- // they came from are on their way out.
- flush();
- disposed = true;
- },
- };
+ if (this.disposed) return;
+ const ids = result.ids ?? {};
+ const editor = getDocumentEditor(this.world);
+ editor.restamp(ids);
+
+ // 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);
+ for (const source of [...this.pending.keys()]) {
+ const next = rename(source);
+ if (next === source) continue;
+ const props = this.pending.get(source)!;
+ this.pending.delete(source);
+ if (next) this.pending.set(next, { ...this.pending.get(next), ...props });
+ }
+ for (const [source, insert] of [...this.inserts]) {
+ const parent = rename(insert.parent);
+ if (parent === undefined) {
+ // Its parent never made it into the file, so neither can it.
+ this.inserts.delete(source);
+ editor.discardPending(source);
+ continue;
+ }
+ // An anchor that did not make it just means "last".
+ const before = insert.before === undefined ? undefined : rename(insert.before);
+ const { before: _, ...rest } = insert;
+ this.inserts.set(source, { ...rest, parent, ...(before === undefined ? {} : { before }) });
+ }
+ for (const source of this.inflight) {
+ if (!ids[source]) editor.discardPending(source);
+ }
+ this.inflight = new Set();
+
+ // What was held back has its names now.
+ if (this.inserts.size || this.pending.size) this.schedule();
+ }
}
+const message = (error: unknown): string => (error instanceof Error ? error.message : String(error));
+
/**
- * Re-stamps entities whose element earned a name, as `old id -> new id`.
- * Queried rather than remembered: the entities that survived the write are the
- * ones the world still holds.
+ * Collects edits against the project in `dir` and writes them back.
+ *
+ * `world` is only read after a write returns, to answer the one thing a write
+ * can tell the canvas: an element that had no `id` in the source has one now,
+ * and the entity it produced has to be re-stamped with it. Without that, the
+ * next edit to the same element would still address it by a position the
+ * write itself may have invalidated.
*/
-function restamp(world: World, ids: Record<string, string>): void {
- for (const entity of world.query(Source)) {
- const next = ids[entity.get(Source)!.value];
- if (next) entity.set(Source, { value: next });
- }
+export function createEditWriter(dir: string, world: World): EditWriter {
+ return new EditWriter(dir, world);
}
-const message = (error: unknown): string => (error instanceof Error ? error.message : String(error));
+export type { EditWriter };
diff --git a/apps/web/src/projects/index.ts b/apps/web/src/projects/index.ts
index 528f3d89..bf37a731 100644
--- a/apps/web/src/projects/index.ts
+++ b/apps/web/src/projects/index.ts
@@ -3,4 +3,3 @@
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
export * from './host';
-export * from './use-project';
diff --git a/apps/web/src/projects/use-project.ts b/apps/web/src/projects/use-project.ts
deleted file mode 100644
index 09c4f6fe..00000000
--- a/apps/web/src/projects/use-project.ts
+++ /dev/null
@@ -1,79 +0,0 @@
-/* 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 { createEffect, onCleanup } from 'solid-js';
-import { toast } from 'somoto';
-import { useWorld } from '@diffusionstudio/koota-solid';
-import { getRuntimeDocument, mount } from '@diffusionstudio/reconciler';
-
-import { createEditWriter } from './edits';
-import { compileProject, projectDir, watchProject } from './host';
-
-import type { Accessor } from 'solid-js';
-import type { Mount } from '@diffusionstudio/reconciler';
-import type { EditWriter } from './edits';
-
-/**
- * Loads the project folder `name` into the runtime world: compiles it, renders
- * its JSX, and re-renders on every change on disk. Call under the koota
- * EngineProvider; the mount follows `name` and is torn down with the owner.
- */
-export function useProject(name: Accessor<string>): void {
- const world = useWorld();
-
- createEffect(() => {
- const dir = projectDir(name());
- if (!dir) return;
-
- let mounted: Mount | undefined;
- let writer: EditWriter | undefined;
- let unlisten: (() => void) | undefined;
- let disposed = false;
- let generation = 0;
-
- const unmount = (): void => {
- // Before the entities go: what the editor changed is still owed to the
- // file, whatever happens to the scene that showed it.
- unlisten?.();
- unlisten = undefined;
- writer?.dispose();
- writer = undefined;
- mounted?.dispose();
- mounted = undefined;
- };
-
- const load = async (): Promise<void> => {
- const current = ++generation;
- const result = await compileProject(dir);
- if (disposed || current !== generation) return;
-
- // A broken edit keeps the last good render on the canvas.
- if (!result.ok) {
- toast.error('Project failed to compile', { description: result.error });
- return;
- }
-
- // The old render goes first: there is only one stage per world.
- unmount();
- try {
- mounted = mount(result.code, world);
- // The rendered scene knows which element every entity came from, so
- // from here on an edit in the editor can find its way back.
- writer = createEditWriter(dir, world);
- unlisten = getRuntimeDocument(world).onEdit((edit) => writer?.push(edit));
- } catch (error) {
- toast.error('Project failed to render', { description: (error as Error).message });
- }
- };
-
- void load();
- const unwatch = watchProject(dir, () => void load());
-
- onCleanup(() => {
- disposed = true;
- unwatch();
- unmount();
- });
- });
-}
diff --git a/packages/reconciler/src/document.ts b/packages/reconciler/src/document.ts
index 522b581b..7523396f 100644
--- a/packages/reconciler/src/document.ts
+++ b/packages/reconciler/src/document.ts
@@ -38,7 +38,6 @@ import {
} from '@diffusionstudio/runtime';
import { parseTime, SOURCE_ATTR } from '@diffusionstudio/jsx';
-import type { PropValue } from '@diffusionstudio/jsx';
import type { CameraMatrix } from '@diffusionstudio/runtime';
import type { Entity, World } from 'koota';
import type { ProjectDocument } from './host';
@@ -71,68 +70,29 @@ function toSeconds(value: unknown): number | undefined {
return parseTime(value);
}
-/**
- * A property the editor changed, in the vocabulary of the JSX rather than of
- * the traits it was written to: `source` is the element it belongs to (its
- * SOURCE_ATTR stamp) and `value` is what a project would have written there.
- * Whoever mounts the document decides what to do with these — writing them
- * back to disk is the point, but nothing here knows about a disk.
- */
-export interface EntityEdit {
- source: string;
- name: string;
- value: PropValue;
-}
-
export class RuntimeDocument implements ProjectDocument<SceneNode> {
/** The mount root. Both it and the <stage> element stand for the Stage entity. */
public readonly stage: SceneNode;
private readonly world: World;
- private sink?: (edit: EntityEdit) => void;
public constructor(world: World) {
this.world = world;
this.stage = { entity: world.get(Root)! };
}
- /**
- * Listens for edits the editor makes through `editProperty`. One sink at a
- * time — a second call replaces the first. Returns an unsubscribe.
- */
- public onEdit(sink: (edit: EntityEdit) => void): () => void {
- this.sink = sink;
- return () => {
- if (this.sink === sink) {
- this.sink = undefined;
- }
- };
- }
-
- /**
- * Writes an edit to the document and saves the changes to the source
- */
- public editProperty(entity: Entity, name: string, value: PropValue): void {
- this.setProperty({ entity }, name, value);
- this.reportEdit(entity, name, value);
- }
-
- /**
- * Reports an edit whose change the editor already made itself
- */
- public reportEdit(entity: Entity, name: string, value: PropValue): void {
- const source = entity.get(Source)?.value;
-
- if (source) {
- this.sink?.({ source, name, value });
- }
- }
-
public createElement(tag: string): SceneNode {
- switch (tag) {
+ // Composition elements arrive in either spelling: the camelCase
+ // intrinsics a project authors, or the PascalCase components the compile
+ // step (and an app inserting elements) uses.
+ const name = tag.charAt(0).toLowerCase() + tag.slice(1);
+ let entity: Entity;
+
+ switch (name) {
case 'stage':
- return this.stage;
+ entity = this.stage.entity;
+ break;
case 'scene': {
- const entity = createEntity(this.world);
+ entity = createEntity(this.world);
entity.add(Geometry);
entity.set(Geometry, { value: GeometryType.RECT });
entity.add(Position);
@@ -141,20 +101,22 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {
entity.add(ClipsContent);
entity.add(Playback);
resizeEntity(this.world, entity, { width: 1920, height: 1080 });
- return { entity };
+ break;
}
case 'rect': {
- const entity = createEntity(this.world);
+ entity = createEntity(this.world);
entity.add(Geometry);
entity.set(Geometry, { value: GeometryType.RECT });
entity.add(Position);
entity.set(Position, { x: 0, y: 0 });
resizeEntity(this.world, entity, { width: 100, height: 100 });
- return { entity };
+ break;
}
default:
throw new Error(`<${tag}> is not supported yet (only <stage>, <scene> and <rect>).`);
}
+
+ return { entity };
}
public createTextNode(): SceneNode {
diff --git a/packages/reconciler/src/index.ts b/packages/reconciler/src/index.ts
index 4689f3e0..cb44365a 100644
--- a/packages/reconciler/src/index.ts
+++ b/packages/reconciler/src/index.ts
@@ -3,9 +3,10 @@
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
export * from './document';
+export * from './elements';
export { evaluate } from './evaluate';
export { mount, type Mount } from './mount';
export { PATCH_PROP_KEYS } from './patch';
-export { renderProject } from './renderer';
+export { insert, renderProject, withDocument } from './renderer';
export { JSX_RUNTIME } from './runtime';
export type { ProjectDocument, ProjectTick } from './host';
diff --git a/packages/reconciler/src/renderer.ts b/packages/reconciler/src/renderer.ts
index f0e9ba94..02320774 100644
--- a/packages/reconciler/src/renderer.ts
+++ b/packages/reconciler/src/renderer.ts
@@ -124,25 +124,31 @@ export function useFile(src: AssetInput): ResourceReturn<File> {
}
/**
- * Host entry point: renders a project component directly into `document`.
- * Mounting is synchronous — the document is fully written when this returns.
+ * Runs `fn` with `document` as the one the static runtime exports write into.
+ * Anything creating elements outside a project render — a host inserting
+ * elements of its own — goes through here.
*/
-export function renderProject<N>(project: () => unknown, document: ProjectDocument<N>): () => void {
+export function withDocument<N, T>(document: ProjectDocument<N>, fn: () => T): T {
const previous = currentDocument;
currentDocument = document as ProjectDocument;
-
try {
- return render(
- () =>
- createComponent(DocumentContext.Provider, {
- value: document as ProjectDocument,
- get children() {
- return createComponent(project, {}) as JSX.Element;
- },
- }),
- document.stage,
- );
+ return fn();
} finally {
currentDocument = previous;
}
}
+
+/**
+ * Host entry point: renders a project component directly into `document`.
+ * Mounting is synchronous — the document is fully written when this returns.
+ */
+export function renderProject<N>(project: () => unknown, document: ProjectDocument<N>): () => void {
+ return withDocument(document, () =>
+ render(() => createComponent(DocumentContext.Provider, {
+ value: document as ProjectDocument,
+ get children() {
+ return createComponent(project, {}) as JSX.Element;
+ },
+ }), document.stage),
+ );
+}
diff --git a/packages/runtime/MIGRATION.md b/packages/runtime/MIGRATION.md
index 15e69d94..e1b22337 100644
--- a/packages/runtime/MIGRATION.md
+++ b/packages/runtime/MIGRATION.md
@@ -131,6 +131,8 @@ apps/web now depends on `@diffusionstudio/runtime` and `@diffusionstudio/koota-s
**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`. Not built yet: `<text>` in `createElement` (Text tool), and the DrawOverlay port itself.
+
**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)