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.tsindex 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.tsxindex 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/tooltipimport { 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.tsxindex 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.tsxindex 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsxindex 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.tsindex 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.tsindex 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.tsdeleted file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.mdindex 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)