Skip to content

The VS Code of video editing, built for agents.

TypeScript

Enhance project editing capabilities and integrate new JSX features

konstantin-paulusb2fc9a96191b
diff --git a/apps/desktop/package.json b/apps/desktop/package.json
index 13325a58..e34a0576 100644
--- a/apps/desktop/package.json
+++ b/apps/desktop/package.json
@@ -36,8 +36,10 @@
"@babel/core": "^7.29.7",
"@babel/preset-typescript": "^7.27.1",
"@diffusionstudio/cli": "*",
+ "@diffusionstudio/jsx": "*",
"babel-preset-solid": "^1.9.12",
"esbuild": "^0.28.1",
+ "sqids": "^0.3.0",
"update-electron-app": "^3.0.0"
}
}
diff --git a/apps/desktop/src/main-channels.ts b/apps/desktop/src/main-channels.ts
index cea7eb25..bc0c3b5a 100644
--- a/apps/desktop/src/main-channels.ts
+++ b/apps/desktop/src/main-channels.ts
@@ -10,6 +10,7 @@
// CLI traffic uses a separate wire pair (CLI_WIRE in @diffusionstudio/cli/protocol);
// main forwards it opaquely without inspecting channel names.
import type { LogEntry, ScreenshotResult } from "@diffusionstudio/cli/protocol";
+import type { SourceEdit, WriteResult } from "./source";
export const MAIN_WIRE = {
REQUEST: "main:request",
@@ -46,6 +47,7 @@ export const MAIN_CHANNELS = {
PROJECTS_DUPLICATE: "projects:duplicate",
PROJECTS_DELETE: "projects:delete",
PROJECTS_COMPILE: "projects:compile",
+ PROJECTS_WRITE: "projects:write",
PROJECTS_WATCH: "projects:watch",
PROJECTS_UNWATCH: "projects:unwatch",
@@ -81,6 +83,8 @@ export type CompileResult =
| { ok: true; code: string }
| { ok: false; error: string };
+export type { SourceEdit, WriteResult };
+
export type MainChannel = (typeof MAIN_CHANNELS)[keyof typeof MAIN_CHANNELS];
// Events fed by a `diffusion://` deep link. Main routes each link to exactly
@@ -131,6 +135,10 @@ export type MainRequestMap = {
[MAIN_CHANNELS.PROJECTS_DUPLICATE]: { request: { dir: string }; response: ProjectInfo };
[MAIN_CHANNELS.PROJECTS_DELETE]: { request: { dir: string }; response: void };
[MAIN_CHANNELS.PROJECTS_COMPILE]: { request: { dir: string }; response: CompileResult };
+ [MAIN_CHANNELS.PROJECTS_WRITE]: {
+ request: { dir: string; edits: SourceEdit[] };
+ response: WriteResult;
+ };
[MAIN_CHANNELS.PROJECTS_WATCH]: { request: { dir: string }; response: void };
[MAIN_CHANNELS.PROJECTS_UNWATCH]: { request: { dir: string }; response: void };
};
diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts
index 0f541b8d..367a0ffc 100644
--- a/apps/desktop/src/main.ts
+++ b/apps/desktop/src/main.ts
@@ -25,6 +25,7 @@ import {
unwatchAll,
unwatchProject,
watchProject,
+ writeProject,
} from "./projects";
import type { DeepLinkChannel } from "./main-channels";
import type { LogEntry } from "@diffusionstudio/cli/protocol";
@@ -269,6 +270,7 @@ if (app.requestSingleInstanceLock()) {
mainBridge.handle(MAIN_CHANNELS.PROJECTS_DUPLICATE, ({ dir }) => duplicateProject(dir));
mainBridge.handle(MAIN_CHANNELS.PROJECTS_DELETE, ({ dir }) => deleteProject(dir));
mainBridge.handle(MAIN_CHANNELS.PROJECTS_COMPILE, ({ dir }) => compileProject(dir));
+ mainBridge.handle(MAIN_CHANNELS.PROJECTS_WRITE, ({ dir, edits }) => writeProject(dir, edits));
mainBridge.handle(MAIN_CHANNELS.PROJECTS_WATCH, ({ dir }, event) =>
watchProject(BrowserWindow.fromWebContents(event.sender), dir),
);
diff --git a/apps/desktop/src/projects.ts b/apps/desktop/src/projects.ts
index 68325a5c..a2ab375c 100644
--- a/apps/desktop/src/projects.ts
+++ b/apps/desktop/src/projects.ts
@@ -24,7 +24,9 @@ import type { BuildOptions, Plugin } from "esbuild";
import { mainBridge } from "./main-manager";
import { MAIN_CHANNELS } from "./main-channels";
-import type { CompileResult, ProjectInfo } from "./main-channels";
+import { applyEdits, sourcePlugin, stampProject } from "./source";
+import type { CompileResult, ProjectInfo, SourceEdit, WriteResult } from "./main-channels";
+import type { SourceContext } from "./source";
/** Entry points looked up in a project folder, in order of preference. */
export const ENTRY_FILES = ["index.tsx", "index.ts", "index.jsx", "index.js"];
@@ -286,10 +288,13 @@ function preset(name: string): unknown {
return loaded.default ?? loaded;
}
-const babelOptions = (filename: string): TransformOptions => ({
+const babelOptions = (file: string, filename: string): TransformOptions => ({
filename,
babelrc: false,
configFile: false,
+ // Runs before the presets, which is what it needs: Solid's transform
+ // replaces the JSX trees this stamps.
+ plugins: [[sourcePlugin, { file }]],
presets: [
[preset("babel-preset-solid"), { generate: "universal", moduleName: RUNTIME_MODULE }],
[preset("@babel/preset-typescript"), { onlyRemoveTypeImports: true }],
@@ -308,13 +313,22 @@ function solidLoader(root: string): Plugin {
return undefined;
}
const source = await readFile(args.path, "utf8");
- const result = await transformAsync(source, babelOptions(args.path));
+ // The project-relative name is half of every element's id, so it is
+ // spelled the one way both directions of ./source spell it.
+ const result = await transformAsync(source, babelOptions(name.split(sep).join("/"), args.path));
return { contents: result?.code ?? "", loader: "js" };
});
},
};
}
+/** The `./source` context for a project folder, wired to the watcher's self-write log. */
+const sourceContext = (dir: string): SourceContext => ({
+ babel: load<Babel>("@babel/core"),
+ dir,
+ onWrite: (file) => markSelfWrite(dir, file),
+});
+
export async function compileProject(dir: string): Promise<CompileResult> {
const entry = await findEntry(dir);
if (!entry) return { ok: false, error: noEntryError() };
@@ -322,6 +336,10 @@ export async function compileProject(dir: string): Promise<CompileResult> {
// Fills in package.json/tsconfig for folders that predate the record.
await scaffold(dir);
+ // Names every element before it is numbered, so the ids this compile hands
+ // the canvas are durable ones. A fully keyed project is not written to.
+ await stampProject(sourceContext(dir));
+
// esbuild resolves symlinks, so the loader has to match on real paths.
const root = await realpath(dir);
@@ -338,11 +356,57 @@ export async function compileProject(dir: string): Promise<CompileResult> {
}
}
+// ---------------------------------------------------------------------------
+// Write
+
+/**
+ * Writes values the editor arrived at back into the JSX that produced them.
+ * Deliberately not a compile: the canvas already shows these values, so this
+ * is the file catching up with the scene rather than the other way round, and
+ * the watcher is told to keep quiet about it (see `markSelfWrite`).
+ */
+export async function writeProject(dir: string, edits: SourceEdit[]): Promise<WriteResult> {
+ try {
+ return await applyEdits(sourceContext(dir), edits);
+ } catch (error) {
+ return { skipped: edits.map((edit) => edit.source), error: error instanceof Error ? error.message : String(error) };
+ }
+}
+
// ---------------------------------------------------------------------------
// Watch
const watchers = new Map<string, FSWatcher>();
+/** How long a file we wrote ourselves stays exempt from the watcher. */
+const SELF_WRITE_GRACE = 1000;
+
+/**
+ * Writes made on behalf of the editor, by file and time. The watcher stays on
+ * — anything else may be editing these files, and should still reach the
+ * canvas — but our own writes must not come back as a change, or every key
+ * stamp and every dragged rect would cost a recompile and a remount of the
+ * scene the user is looking at.
+ */
+const selfWrites = new Map<string, number>();
+
+const writeKey = (dir: string, path: string): string => `${dir}\n${path}`;
+
+export function markSelfWrite(dir: string, path: string): void {
+ selfWrites.set(writeKey(dir, path), Date.now());
+}
+
+function isSelfWrite(dir: string, path: string): boolean {
+ const key = writeKey(dir, path);
+ const at = selfWrites.get(key);
+ if (at === undefined) return false;
+ if (Date.now() - at > SELF_WRITE_GRACE) {
+ selfWrites.delete(key);
+ return false;
+ }
+ return true;
+}
+
export function watchProject(window: BrowserWindow | null, dir: string): void {
if (watchers.has(dir)) return;
const watcher = watch(dir, { recursive: true }, (_event, filename) => {
@@ -350,6 +414,7 @@ export function watchProject(window: BrowserWindow | null, dir: string): void {
// Project-relative and `/`-separated; installs churn node_modules constantly.
const path = filename.split(sep).join("/");
if (path.startsWith("node_modules/") || path === "node_modules") return;
+ if (isSelfWrite(dir, path)) return;
mainBridge.emit(window, MAIN_CHANNELS.PROJECTS_CHANGED, { dir, path });
});
watcher.on("error", () => unwatchProject(dir));
diff --git a/apps/desktop/src/source.ts b/apps/desktop/src/source.ts
new file mode 100644
index 00000000..13ab7425
--- /dev/null
+++ b/apps/desktop/src/source.ts
@@ -0,0 +1,481 @@
+/* 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 two directions of a project's JSX, in one module.
+//
+// Reading: `sourcePlugin` stamps every composition element with where it came
+// from, so the entity the renderer builds from it knows its own origin.
+// Writing: `applyEdits` puts a value the editor arrived at back into the
+// attribute that produced it, and `stampProject` gives elements the durable
+// names that survive edits made to the file in between.
+//
+// Both directions number a file's JSX elements in document order, and an
+// element is known by its position there until it has an `id`. If the two ever
+// disagreed about the order, a drag would write to the wrong element — which
+// is why they are here together and share one traversal (`eachElement`) over
+// one parser, rather than agreeing by convention.
+
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import Sqids from "sqids";
+
+import { ID_ATTR, SOURCE_ATTR, formatSource, isCompositionTag, parseSource } from "@diffusionstudio/jsx";
+
+import type { PropValue } from "@diffusionstudio/jsx";
+import type { NodePath, PluginObj, TransformOptions, types as t } from "@babel/core";
+
+export type { PropValue };
+
+/** The parts of `@babel/core` this module needs; the caller owns loading it. */
+export type SourceBabel = Pick<typeof import("@babel/core"), "parseSync" | "traverse">;
+
+/** What babel hands a plugin factory. */
+type BabelApi = { types: typeof import("@babel/core").types };
+
+export interface SourceContext {
+ babel: SourceBabel;
+ /** Absolute path of the project folder. */
+ dir: string;
+ /** Called with the project-relative path of every file written. */
+ onWrite?: (file: string) => void;
+}
+
+/** Overwrites props of the element named by `source` (a `SOURCE_ATTR` value). */
+export interface SourceEdit {
+ source: string;
+ props: Record<string, PropValue>;
+}
+
+export interface WriteResult {
+ /** Sources that could not be written, as `id` or `id (prop)`. */
+ skipped: string[];
+ /**
+ * Elements that earned a name in this write, as `old source id -> new one`.
+ * The canvas re-stamps its entities with these, so identity does not have to
+ * wait for a recompile.
+ */
+ ids?: Record<string, string>;
+ error?: string;
+}
+
+const SOURCE_FILE = /\.[jt]sx?$/;
+
+const sqids = new Sqids({ minLength: 2 });
+
+// ---------------------------------------------------------------------------
+// The numbering
+
+/**
+ * Every JSX element a traversal reaches, in document order. Components and DOM
+ * tags are counted but not stamped: a position means "the nth element in this
+ * file", and skipping some would make that depend on which ones are
+ * composition elements today.
+ */
+function eachElement(
+ traverse: (visitor: { JSXElement(path: NodePath<t.JSXElement>): void }) => void,
+ visit: (node: t.JSXElement, index: number) => void,
+): void {
+ let index = 0;
+ traverse({
+ JSXElement(path) {
+ visit(path.node, index++);
+ },
+ });
+}
+
+/** The tag as written, or undefined for the member/namespaced forms no tag has. */
+function tagName(node: t.JSXElement): string | undefined {
+ const name = node.openingElement.name;
+ return name.type === "JSXIdentifier" ? name.name : undefined;
+}
+
+function attributeOf(node: t.JSXElement, name: string): t.JSXAttribute | undefined {
+ for (const attribute of node.openingElement.attributes) {
+ if (attribute.type !== "JSXAttribute") continue;
+ if (attribute.name.type === "JSXIdentifier" && attribute.name.name === name) return attribute;
+ }
+ return undefined;
+}
+
+function idOf(node: t.JSXElement): string | undefined {
+ const value = attributeOf(node, ID_ATTR)?.value;
+ return value?.type === "StringLiteral" ? value.value : undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Reading: the compile-time stamp
+
+/**
+ * Stamps every composition element with the location of its JSX source, so
+ * entities on the canvas can be traced back to the code that produced them.
+ * An element that names itself with `id` keeps that name; the position is the
+ * fallback for elements nothing has had to write to yet. The id is removed on
+ * the way through, so it never reaches a host as a prop.
+ */
+export function sourcePlugin({ types }: BabelApi, { file }: { file: string }): PluginObj {
+ return {
+ name: "jsx-source-location",
+ visitor: {
+ // Stamped up front: Solid's transform replaces whole JSX trees, so by the
+ // time a nested element would be visited normally it no longer exists.
+ Program(program) {
+ eachElement(
+ (visitor) => program.traverse(visitor),
+ (node, index) => {
+ const tag = tagName(node);
+ if (tag === undefined || !isCompositionTag(tag)) return;
+
+ const id = idOf(node);
+ const opening = node.openingElement;
+ opening.attributes = opening.attributes.filter(
+ (attribute) =>
+ !(
+ attribute.type === "JSXAttribute" &&
+ attribute.name.type === "JSXIdentifier" &&
+ attribute.name.name === ID_ATTR
+ ),
+ );
+ opening.attributes.push(
+ types.jsxAttribute(
+ types.jsxIdentifier(SOURCE_ATTR),
+ types.stringLiteral(formatSource(file, id ?? index)),
+ ),
+ );
+ },
+ );
+ },
+ },
+ };
+}
+
+// ---------------------------------------------------------------------------
+// Writing: values back into attributes
+
+const round = (value: number): number => Math.round(value * 100) / 100;
+
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+
+/** A prop value as the JavaScript that would have produced it. */
+function literalText(value: PropValue): string {
+ if (typeof value === "string") return JSON.stringify(value);
+ if (typeof value === "number") return String(round(value));
+ if (typeof value === "boolean" || value === null) return String(value);
+ if (Array.isArray(value)) return `[${value.map(literalText).join(", ")}]`;
+
+ const entries = Object.entries(value).map(
+ ([key, nested]) => `${IDENTIFIER.test(key) ? key : JSON.stringify(key)}: ${literalText(nested)}`,
+ );
+ return entries.length ? `{ ${entries.join(", ")} }` : "{}";
+}
+
+/** A prop value as it appears after `=` in a JSX attribute. */
+export function initializerText(value: PropValue): string {
+ return typeof value === "string" ? JSON.stringify(value) : `{${literalText(value)}}`;
+}
+
+/** `muted`, not `muted={true}` — an attribute as one would write it. */
+function attributeText(name: string, value: PropValue): string {
+ if (typeof value === "boolean") return value ? name : `${name}={false}`;
+ return `${name}=${initializerText(value)}`;
+}
+
+/** Whether an expression is a value rather than a way of computing one. */
+function isLiteral(node: t.Node): boolean {
+ switch (node.type) {
+ case "StringLiteral":
+ case "NumericLiteral":
+ case "BooleanLiteral":
+ case "NullLiteral":
+ return true;
+ case "UnaryExpression":
+ return (node.operator === "-" || node.operator === "+") && isLiteral(node.argument);
+ case "ArrayExpression":
+ return node.elements.every((element) => element !== null && isLiteral(element));
+ case "ObjectExpression":
+ return node.properties.every(
+ (property) =>
+ property.type === "ObjectProperty" && !property.computed && isLiteral(property.value),
+ );
+ default:
+ return false;
+ }
+}
+
+/**
+ * A prop is only written back when the source holds a plain literal. Anything
+ * else — a signal, a prop of the surrounding component, an expression — is
+ * someone's reactivity, and a drag has no business overwriting it.
+ */
+function isWritable(attribute: t.JSXAttribute): boolean {
+ const value = attribute.value;
+ if (!value) return true;
+ if (value.type === "StringLiteral") return true;
+ if (value.type !== "JSXExpressionContainer") return false;
+ return value.expression.type !== "JSXEmptyExpression" && isLiteral(value.expression);
+}
+
+// ---------------------------------------------------------------------------
+// Files
+
+/** Text edits over one file's source, applied together so ranges stay valid. */
+class Splices {
+ // Keyed by range, so writing the same attribute twice in one batch replaces
+ // it once rather than splicing over a range that is no longer there.
+ private readonly replacements = new Map<string, { start: number; end: number; text: string }>();
+ private readonly insertions = new Map<number, string[]>();
+
+ public replace(node: { start?: number | null; end?: number | null }, text: string): void {
+ if (typeof node.start !== "number" || typeof node.end !== "number") return;
+ this.replacements.set(`${node.start}:${node.end}`, { start: node.start, end: node.end, text });
+ }
+
+ /**
+ * Adds an attribute to an element, after the ones it already has — where one
+ * would have written it. That position is the end of an existing attribute
+ * rather than the inside of one, so it never lands within a replacement; and
+ * since edits apply back to front, an insertion sitting exactly on the end of
+ * an attribute being replaced still ends up after it.
+ */
+ public addAttribute(node: t.JSXElement, text: string): void {
+ const attributes = node.openingElement.attributes;
+ const at = attributes[attributes.length - 1]?.end ?? node.openingElement.name.end;
+ if (typeof at !== "number") return;
+ this.insertions.set(at, [...(this.insertions.get(at) ?? []), text]);
+ }
+
+ public get empty(): boolean {
+ return !this.replacements.size && !this.insertions.size;
+ }
+
+ /** Applies back to front, so earlier offsets are still the ones parsed. */
+ public apply(source: string): string {
+ const all = [
+ ...this.replacements.values(),
+ ...[...this.insertions].map(([at, texts]) => ({
+ start: at,
+ end: at,
+ text: texts.map((text) => ` ${text}`).join(""),
+ })),
+ ].sort((a, b) => b.start - a.start);
+
+ let text = source;
+ for (const splice of all) {
+ text = text.slice(0, splice.start) + splice.text + text.slice(splice.end);
+ }
+ return text;
+ }
+}
+
+/** One file, parsed, with its elements in the order both directions number them. */
+interface ParsedFile {
+ source: string;
+ elements: t.JSXElement[];
+}
+
+const absolute = (dir: string, file: string): string => join(dir, ...file.split("/"));
+
+async function parseFile(context: SourceContext, file: string): Promise<ParsedFile | undefined> {
+ let source: string;
+ try {
+ source = await readFile(absolute(context.dir, file), "utf8");
+ } catch {
+ return undefined;
+ }
+
+ const options: TransformOptions = {
+ filename: absolute(context.dir, file),
+ babelrc: false,
+ configFile: false,
+ sourceType: "module",
+ // JSX everywhere but in `.ts`, where `<T>value` is a type assertion
+ // instead — the same reading babel's TypeScript preset picks by extension.
+ parserOpts: { plugins: file.endsWith(".ts") ? ["typescript"] : ["jsx", "typescript"] },
+ };
+
+ let ast: ReturnType<SourceBabel["parseSync"]>;
+ try {
+ ast = context.babel.parseSync(source, options);
+ } catch {
+ // A file mid-edit does not parse; the next change brings another chance.
+ return undefined;
+ }
+ if (!ast) return undefined;
+
+ const elements: t.JSXElement[] = [];
+ eachElement(
+ (visitor) => context.babel.traverse(ast as t.Node, visitor),
+ (node) => elements.push(node),
+ );
+ return { source, elements };
+}
+
+async function save(context: SourceContext, file: string, text: string): Promise<void> {
+ // Claimed before the write lands: a watcher must never see this change
+ // arrive without knowing whose it was.
+ context.onWrite?.(file);
+ await writeFile(absolute(context.dir, file), text, "utf8");
+}
+
+/**
+ * Ids live in text, which can be copied, so two elements can end up claiming
+ * one. An ambiguous id resolves to nothing and the write is reported instead.
+ */
+function findElement(elements: t.JSXElement[], locator: number | string): t.JSXElement | undefined {
+ if (typeof locator === "number") return elements[locator];
+ const matches = elements.filter((element) => idOf(element) === locator);
+ return matches.length === 1 ? matches[0] : undefined;
+}
+
+function counterOf(id: string): number {
+ const decoded = sqids.decode(id);
+ return decoded.length === 1 && Number.isInteger(decoded[0]) ? decoded[0]! : 0;
+}
+
+function idAllocator(taken: Set<string>): () => string {
+ let counter = 0;
+
+ for (const id of taken) {
+ counter = Math.max(counter, counterOf(id));
+ }
+
+ return () => {
+ while (true) {
+ const id = sqids.encode([++counter]);
+ if (taken.has(id)) continue;
+ taken.add(id);
+ return id;
+ }
+ };
+}
+
+const idsIn = (elements: t.JSXElement[]): Set<string> =>
+ new Set(elements.flatMap((element) => idOf(element) ?? []));
+
+// ---------------------------------------------------------------------------
+// Naming
+
+/** Every project source file, project-relative and `/`-separated. */
+async function sourceFiles(dir: string, prefix = ""): Promise<string[]> {
+ let entries;
+ try {
+ entries = await readdir(prefix ? join(dir, ...prefix.split("/")) : dir, { withFileTypes: true });
+ } catch {
+ return [];
+ }
+
+ const files: string[] = [];
+ for (const entry of entries) {
+ if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+ const path = prefix ? `${prefix}/${entry.name}` : entry.name;
+ if (entry.isDirectory()) files.push(...(await sourceFiles(dir, path)));
+ else if (SOURCE_FILE.test(entry.name)) files.push(path);
+ }
+ return files;
+}
+
+/**
+ * Names every composition element in a file, so identity does not have to be
+ * earned one write at a time: without an id, an element is only a position,
+ * and any edit that adds an element above it moves it. Idempotent — a file
+ * where nothing is missing an id is not written to, which is what makes this
+ * safe to run before every compile.
+ */
+async function stampFile(context: SourceContext, file: string): Promise<void> {
+ const parsed = await parseFile(context, file);
+ if (!parsed) return;
+
+ const nextId = idAllocator(idsIn(parsed.elements));
+ const splices = new Splices();
+
+ for (const element of parsed.elements) {
+ const tag = tagName(element);
+ if (tag === undefined || !isCompositionTag(tag) || idOf(element)) continue;
+
+ splices.addAttribute(element, `${ID_ATTR}="${nextId()}"`);
+ }
+
+ if (splices.empty) return;
+ await save(context, file, splices.apply(parsed.source));
+}
+
+/** Stamps every source file of the project. Writes nothing to a fully named project. */
+export async function stampProject(context: SourceContext): Promise<void> {
+ for (const file of await sourceFiles(context.dir)) {
+ await stampFile(context, file);
+ }
+}
+
+// ---------------------------------------------------------------------------
+// Prop writes
+
+/**
+ * Writes prop values back into the JSX that produced them. Props whose source
+ * is an expression rather than a literal are reported as skipped and left
+ * alone; an element that is written to and has no id gets one, so that the
+ * next edit to renumber the file cannot strand it.
+ */
+export async function applyEdits(context: SourceContext, edits: SourceEdit[]): Promise<WriteResult> {
+ const skipped: string[] = [];
+ 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, { locator: number | string; edit: SourceEdit }[]>();
+ for (const edit of edits) {
+ const location = parseSource(edit.source);
+ if (!location) {
+ skipped.push(edit.source);
+ continue;
+ }
+ byFile.set(location.file, [
+ ...(byFile.get(location.file) ?? []),
+ { locator: location.locator, edit },
+ ]);
+ }
+
+ for (const [file, entries] of byFile) {
+ const parsed = await parseFile(context, file);
+ if (!parsed) {
+ skipped.push(...entries.map((entry) => entry.edit.source));
+ continue;
+ }
+
+ const nextId = idAllocator(idsIn(parsed.elements));
+ const splices = new Splices();
+
+ for (const { locator, edit } of entries) {
+ const element = findElement(parsed.elements, locator);
+ if (!element) {
+ skipped.push(edit.source);
+ continue;
+ }
+
+ let wrote = false;
+ for (const [name, value] of Object.entries(edit.props)) {
+ const attribute = attributeOf(element, name);
+ if (attribute && !isWritable(attribute)) {
+ skipped.push(`${edit.source} (${name})`);
+ continue;
+ }
+
+ if (attribute) splices.replace(attribute, attributeText(name, value));
+ else splices.addAttribute(element, attributeText(name, value));
+ wrote = true;
+ }
+
+ // Named only once something was written: failing to write to an element
+ // is no reason to touch the file.
+ if (!wrote || idOf(element)) continue;
+ const id = nextId();
+ splices.addAttribute(element, `${ID_ATTR}="${id}"`);
+ ids[edit.source] = formatSource(file, id);
+ }
+
+ if (splices.empty) continue;
+ await save(context, file, splices.apply(parsed.source));
+ }
+
+ return { skipped, ...(Object.keys(ids).length ? { ids } : {}) };
+}
diff --git a/apps/web/src/components/sidebar-right/inspector/background.tsx b/apps/web/src/components/sidebar-right/inspector/background.tsx
index 4602d22c..17de88cb 100644
--- a/apps/web/src/components/sidebar-right/inspector/background.tsx
+++ b/apps/web/src/components/sidebar-right/inspector/background.tsx
@@ -16,7 +16,7 @@ import { ColorOpacityRow } from "@/components/ui/color-opacity-row";
import { Button } from "@/components/ui/button";
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
import { createSignal } from "solid-js";
-import { Background, DEFAULT_BACKGROUND, Root } from "@diffusionstudio/runtime";
+import { Background, DEFAULT_BACKGROUND, Root, colorToHex } from "@diffusionstudio/runtime";
import { useTrait, useWorld } from "@diffusionstudio/koota-solid";
import { useDocument } from "@/engine/hooks/use-document";
@@ -32,8 +32,9 @@ export function BackgroundSettings() {
let anchorRef: HTMLDivElement | undefined;
const assignColor = (value: number) => {
- const doc = document();
- doc.setProperty(doc.stage, "background", value);
+ const root = world.get(Root)!;
+ const color = colorToHex(value);
+ document().editProperty(root, "background", color);
};
return (
diff --git a/apps/web/src/projects/edits.ts b/apps/web/src/projects/edits.ts
new file mode 100644
index 00000000..29176cca
--- /dev/null
+++ b/apps/web/src/projects/edits.ts
@@ -0,0 +1,111 @@
+/* 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 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 { toast } from 'somoto';
+
+import { writeProject } from './host';
+
+import type { EntityEdit } from '@diffusionstudio/reconciler';
+import type { SourceEdit, WriteResult } from './host';
+import type { World } from 'koota';
+
+/**
+ * How long edits pile up before they are written. Long enough that a drag is
+ * one write, short enough that letting go of a slider and looking at the file
+ * shows the value that is on the canvas.
+ */
+const DEBOUNCE = 120;
+
+export interface EditWriter {
+ /** Records an edit; the write follows once edits stop arriving. */
+ push(edit: EntityEdit): void;
+ /** Writes what is pending and stops. */
+ dispose(): void;
+}
+
+/**
+ * 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 => {
+ if (result.error) {
+ toast.error('Could not write to the project', { description: result.error });
+ } else if (result.skipped.length) {
+ // Not a failure: the source computes these, and overwriting an
+ // expression with the value it happened to produce would delete
+ // someone's work.
+ toast.warning('Some props are computed and stay as they are', {
+ description: result.skipped.join(', '),
+ });
+ }
+
+ if (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;
+ },
+ };
+}
+
+/**
+ * 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.
+ */
+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 });
+ }
+}
+
+const message = (error: unknown): string => (error instanceof Error ? error.message : String(error));
diff --git a/apps/web/src/projects/host.ts b/apps/web/src/projects/host.ts
index 538c5272..0a73ec39 100644
--- a/apps/web/src/projects/host.ts
+++ b/apps/web/src/projects/host.ts
@@ -13,9 +13,9 @@ import { mainBridge } from '@/lib/ipc';
import { store } from '@/init';
import { createStoredSignal } from '@/lib/store/signal';
-import type { CompileResult, ProjectInfo } from '@desktop/main-channels';
+import type { CompileResult, ProjectInfo, SourceEdit, WriteResult } from '@desktop/main-channels';
-export type { CompileResult, ProjectInfo };
+export type { CompileResult, ProjectInfo, SourceEdit, WriteResult };
const rootItem = store.define<string | null>('projects.root', null);
const [projectsRoot, setProjectsRoot] = createStoredSignal(rootItem);
@@ -92,6 +92,15 @@ export function compileProject(dir: string): Promise<CompileResult> {
return mainBridge.call(MAIN_CHANNELS.PROJECTS_COMPILE, { dir });
}
+/**
+ * Writes changed props back into the project's JSX. No compile follows: the
+ * canvas is already showing these values, and main keeps the write from
+ * reaching the watcher (see `markSelfWrite` in the desktop's projects.ts).
+ */
+export function writeProject(dir: string, edits: SourceEdit[]): Promise<WriteResult> {
+ return mainBridge.call(MAIN_CHANNELS.PROJECTS_WRITE, { dir, edits });
+}
+
/**
* Watches a project folder and calls `onChange` (debounced) when a file
* inside it changes. Returns the unwatch function.
diff --git a/apps/web/src/projects/use-project.ts b/apps/web/src/projects/use-project.ts
index d3dfa008..09c4f6fe 100644
--- a/apps/web/src/projects/use-project.ts
+++ b/apps/web/src/projects/use-project.ts
@@ -5,12 +5,14 @@
import { createEffect, onCleanup } from 'solid-js';
import { toast } from 'somoto';
import { useWorld } from '@diffusionstudio/koota-solid';
-import { mount } from '@diffusionstudio/reconciler';
+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
@@ -25,10 +27,18 @@ export function useProject(name: Accessor<string>): void {
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;
};
@@ -48,6 +58,10 @@ export function useProject(name: Accessor<string>): void {
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 });
}
diff --git a/package-lock.json b/package-lock.json
index 80aadabc..8cdf5409 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -49,8 +49,10 @@
"@babel/core": "^7.29.7",
"@babel/preset-typescript": "^7.27.1",
"@diffusionstudio/cli": "*",
+ "@diffusionstudio/jsx": "*",
"babel-preset-solid": "^1.9.12",
"esbuild": "^0.28.1",
+ "sqids": "^0.3.0",
"update-electron-app": "^3.0.0"
},
"devDependencies": {
diff --git a/packages/jsx/src/index.ts b/packages/jsx/src/index.ts
index 3aefc22e..a958fa69 100644
--- a/packages/jsx/src/index.ts
+++ b/packages/jsx/src/index.ts
@@ -21,6 +21,15 @@ export type {
GenerateVoiceOptions,
} from "./generate";
export { parseTime, TIME_FPS } from "./time";
+export {
+ COMPOSITION_TAGS,
+ ID_ATTR,
+ SOURCE_ATTR,
+ formatSource,
+ isCompositionTag,
+ parseSource,
+} from "./source";
+export type { CompositionTag, PropValue } from "./source";
export { useTicker, useFile } from "./hooks";
export type { Ticker } from "./hooks";
export type {
@@ -44,6 +53,7 @@ export type {
SequenceProps,
ShaderPaintProps,
SolidPaintProps,
+ SourceProps,
StageProps,
SurfacePaintProps,
SurfaceProps,
diff --git a/packages/jsx/src/jsx-runtime.ts b/packages/jsx/src/jsx-runtime.ts
index 64fa0894..0b92b73a 100644
--- a/packages/jsx/src/jsx-runtime.ts
+++ b/packages/jsx/src/jsx-runtime.ts
@@ -33,6 +33,7 @@ import type {
SequenceProps,
ShaderPaintProps,
SolidPaintProps,
+ SourceProps,
StageProps,
SurfacePaintProps,
SurfaceProps,
@@ -66,23 +67,23 @@ export declare namespace JSX {
export interface IntrinsicElements extends HtmlElementTags, SvgElementTags {
img: ImgTag;
- stage: StageProps;
- group: GroupProps;
- rect: RectProps | SolidJSX.SVGElementTags["rect"];
- video: VideoProps;
- image: ImageProps | SolidJSX.SVGElementTags["image"];
- audio: AudioProps;
- text: TextProps | SolidJSX.SVGElementTags["text"];
- sequence: SequenceProps;
- captions: CaptionsProps;
- solidPaint: SolidPaintProps;
- linearGradientPaint: GradientPaintProps;
- radialGradientPaint: GradientPaintProps;
- colorStop: ColorStopProps;
- htmlPaint: HtmlPaintProps;
- html: HtmlProps;
- shaderPaint: ShaderPaintProps;
- surfacePaint: SurfacePaintProps;
- surface: SurfaceProps;
+ stage: StageProps & SourceProps;
+ group: GroupProps & SourceProps;
+ rect: (RectProps & SourceProps) | SolidJSX.SVGElementTags["rect"];
+ video: VideoProps & SourceProps;
+ image: (ImageProps & SourceProps) | SolidJSX.SVGElementTags["image"];
+ audio: AudioProps & SourceProps;
+ text: (TextProps & SourceProps) | SolidJSX.SVGElementTags["text"];
+ sequence: SequenceProps & SourceProps;
+ captions: CaptionsProps & SourceProps;
+ solidPaint: SolidPaintProps & SourceProps;
+ linearGradientPaint: GradientPaintProps & SourceProps;
+ radialGradientPaint: GradientPaintProps & SourceProps;
+ colorStop: ColorStopProps & SourceProps;
+ htmlPaint: HtmlPaintProps & SourceProps;
+ html: HtmlProps & SourceProps;
+ shaderPaint: ShaderPaintProps & SourceProps;
+ surfacePaint: SurfacePaintProps & SourceProps;
+ surface: SurfaceProps & SourceProps;
}
}
diff --git a/packages/jsx/src/source.ts b/packages/jsx/src/source.ts
new file mode 100644
index 00000000..f6e16fc9
--- /dev/null
+++ b/packages/jsx/src/source.ts
@@ -0,0 +1,108 @@
+/* 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/. */
+
+/**
+ * How the compile step, the host and the editor agree to name the elements of
+ * a project's source. Everything here is data all three sides read; none of
+ * them import each other, and nothing here touches a file or a host.
+ *
+ * It exists so that a change made on the canvas can be written back to the JSX
+ * that produced it: the compile step stamps every composition element with
+ * where it came from, the host keeps that stamp on the entity it builds, and
+ * the editor hands it back when it wants the source changed.
+ */
+
+/**
+ * Attribute an element may carry to name itself. An id outlives edits that
+ * renumber the file, so it — not the element's position — is what an entity
+ * holds once its element has one.
+ *
+ * Yours to write: an id is any string, and `id="hero"` is worth more to read
+ * than anything generated. The editor only stamps elements that have none, and
+ * renaming one by hand is safe. Stripped at compile time, so it never reaches
+ * a host as a prop; what survives is `SOURCE_ATTR`, which carries it.
+ *
+ * Not to be confused with the `key` prop, which is a within-render label that
+ * `syncTo` references — a way for elements to point at each other, not a name
+ * that survives an edit.
+ */
+export const ID_ATTR = "id";
+
+/**
+ * Attribute the compile step stamps onto every composition element, carrying
+ * `<file relative to the project>:<id, or position in document order>`.
+ * It is what lets an entity be traced back to the JSX that produced it.
+ */
+export const SOURCE_ATTR = "__source";
+
+/**
+ * What a prop can be worth in a source file: JSON, essentially. It is the
+ * vocabulary an edit is expressed in — the value as a project would have
+ * written it, not as a host happens to store it, so a color travels as
+ * "#161616" rather than as the number the runtime packs it into.
+ */
+export type PropValue = number | string | boolean | null | PropValue[] | { [key: string]: PropValue };
+
+/**
+ * The composition elements — the tags that become entities. Everything else a
+ * project renders is either a user component or DOM content under
+ * `<htmlPaint>`, neither of which a stamp would mean anything for.
+ *
+ * Kept in step with the `IntrinsicElements` of "./jsx-runtime" by hand: that
+ * one declares types for a compiler, this one is read at runtime.
+ */
+export const COMPOSITION_TAGS = [
+ "stage",
+ "group",
+ "rect",
+ "video",
+ "image",
+ "audio",
+ "text",
+ "sequence",
+ "captions",
+ "solidPaint",
+ "linearGradientPaint",
+ "radialGradientPaint",
+ "colorStop",
+ "htmlPaint",
+ "html",
+ "shaderPaint",
+ "surfacePaint",
+ "surface",
+] as const;
+
+export type CompositionTag = (typeof COMPOSITION_TAGS)[number];
+
+const TAGS: ReadonlySet<string> = new Set(COMPOSITION_TAGS);
+
+/**
+ * Whether a tag names a composition element, in either spelling: the camelCase
+ * intrinsics a project is authored in, and the PascalCase components the
+ * compile step canonicalizes them into (see @diffusionstudio/reconciler's
+ * "elements"). Both are the same element, so both are stamped.
+ */
+export function isCompositionTag(tag: string): boolean {
+ return TAGS.has(tag) || TAGS.has(tag.charAt(0).toLowerCase() + tag.slice(1));
+}
+
+/**
+ * A source id is `file:locator`, where a numeric locator is the element's
+ * position in document order and anything else is its id. The file is where the
+ * element was last seen: an id that moved to another file reads as gone rather
+ * than as some other element, which is the safe way to be wrong.
+ */
+export function parseSource(id: string): { file: string; locator: number | string } | undefined {
+ const at = id.lastIndexOf(":");
+ if (at < 0) return undefined;
+
+ const suffix = id.slice(at + 1);
+ if (!suffix) return undefined;
+
+ const index = Number(suffix);
+ return { file: id.slice(0, at), locator: Number.isInteger(index) ? index : suffix };
+}
+
+/** The inverse of `parseSource`. */
+export const formatSource = (file: string, locator: number | string): string => `${file}:${locator}`;
diff --git a/packages/jsx/src/types.ts b/packages/jsx/src/types.ts
index 9e3f679d..b95b0d7d 100644
--- a/packages/jsx/src/types.ts
+++ b/packages/jsx/src/types.ts
@@ -246,6 +246,15 @@ type CommonProps = TimingProps &
| "opacity" | "cornerRadius" | "transition" | "animations"
>;
+/**
+ * What every composition element accepts on top of its own props. Read by the
+ * compile step and never seen by a host, so it is not part of `PatchProps`:
+ * nothing patches an id, because an id is not a property of the composition.
+ */
+export type SourceProps = {
+ id?: string;
+};
+
/** The infinite canvas every project renders into; only allowed as the root element. */
export type StageProps = {
/** Canvas color, any CSS color. */
diff --git a/packages/reconciler/src/document.ts b/packages/reconciler/src/document.ts
index 30c06938..28fa1cc9 100644
--- a/packages/reconciler/src/document.ts
+++ b/packages/reconciler/src/document.ts
@@ -2,21 +2,6 @@
* 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 JSX host over the runtime world: Solid's universal renderer (via
-// @diffusionstudio/jsx) writes project JSX straight into runtime entities, so
-// a rendered project IS the composition, with no intermediate tree. This is
-// the only file in the reconciler that knows how the runtime models nodes.
-//
-// It is also the single write router into a world: the editor UI reaches its
-// document with `getRuntimeDocument(world)` and edits through the same
-// `setProperty` a rendering project goes through, so front and backend share
-// one vocabulary and one translation to traits.
-//
-// Supported tags for now:
-// - <stage>: the infinite canvas, i.e. the world's document root. It has no
-// size or position; `background` sets the canvas color.
-// - <rect>: a rect entity with x, y, width, height and fill (the entity's
-// own Color trait, so a filled rect needs no paint sub-entities).
import {
Background,
@@ -33,17 +18,14 @@ import {
getEntityChildren,
DocumentRoot,
Root,
+ Source,
} from '@diffusionstudio/runtime';
+import { SOURCE_ATTR } from '@diffusionstudio/jsx';
+import type { PropValue } from '@diffusionstudio/jsx';
import type { Entity, World } from 'koota';
import type { ProjectDocument } from './host';
-/**
- * A host node: a handle around an element's entity. Koota entities are plain
- * numbers, which Solid's universal renderer would take for text (`insert()`
- * turns numbers into text nodes), so nodes wrap them. One handle per entity,
- * so node identity is stable across getParentNode/getFirstChild/getNextSibling.
- */
export interface SceneNode {
readonly entity: Entity;
}
@@ -57,16 +39,63 @@ function toNumber(value: unknown) {
return Number.isFinite(number) ? number : undefined;
}
+/**
+ * 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 document root 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;
+ }
+ };
+ }
+
+ /**
+ * The editor's door into the composition, as opposed to `setProperty`,
+ * which is the rendering project's. Both change the same traits the same
+ * way; the difference is where the value came from, and so whether the
+ * source already says it. A project's own render must never be reported as
+ * an edit, or every reactive update would write the file it came from.
+ *
+ * The value is the one a project would have written — "#161616", not the
+ * number the runtime packs a color into — because it is on its way to being
+ * spelled out in a JSX attribute.
+ */
+ public editProperty(entity: Entity, name: string, value: PropValue): void {
+ this.setProperty({ entity }, name, value);
+ const source = entity.get(Source)?.value;
+
+ if (source) {
+ this.sink?.({ source, name, value });
+ }
+ }
+
public createElement(tag: string): SceneNode {
if (tag === 'stage') {
return this.stage;
@@ -97,6 +126,16 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {
public setProperty({ entity }: SceneNode, name: string, value: unknown): void {
switch (name) {
+ case SOURCE_ATTR: {
+ if (typeof value !== 'string' || !value) {
+ entity.remove(Source);
+ return;
+ }
+
+ entity.add(Source);
+ entity.set(Source, { value });
+ return;
+ }
case 'x':
case 'y': {
entity.add(Position);
@@ -153,6 +192,7 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {
this.removeNode(node, child);
}
node.entity.set(Background, { value: DEFAULT_BACKGROUND });
+ node.entity.remove(Source);
return;
}
// ChildOf auto-destroys orphans, so paints go with it.
diff --git a/packages/runtime/src/traits/node.ts b/packages/runtime/src/traits/node.ts
index 548e60e7..394f75bb 100644
--- a/packages/runtime/src/traits/node.ts
+++ b/packages/runtime/src/traits/node.ts
@@ -56,6 +56,13 @@ export const Name = trait({ value: '' });
// Stable identity for entities.
export const Key = trait({ value: '' });
+// Where this entity's JSX element is, as `<file>:<key or position>` (see
+// SOURCE_ATTR in @diffusionstudio/jsx). Set by the host while a project
+// renders; it is what lets a change made in the editor be written back to the
+// source that produced the entity. Deliberately not serialized: a copy of an
+// entity is not the element it was copied from.
+export const Source = trait({ value: '' });
+
export const AssetId = trait({ value: '' });
// Sibling order under a ChildOf parent.