@scenoco-three/editor 0.4.0 → 0.5.0

package/app/document.ts

@@ -1,500 +1,547 @@
-import { Color, Euler, Vector2, Vector3, type Object3D } from 'three';
-import {
-  Registry,
-  elementType,
-  getAttachmentDef,
-  isArrayType,
-  type Component,
-  type CompiledScene,
-  type EnumDef,
-  type PropType,
-  type PropertyType,
-  type SceneGraph,
-} from '@scenoco-three/core';
-import type { NodeOrigin, SceneProvenance } from '@scenoco-three/compiler';
-import type { EditOp, EditTarget } from '../dist/protocol.js';
-import { UndoStack } from './commands.js';
-
-export type TransformChannel = 'position' | 'rotation' | 'scale';
-type Scalar = number | boolean | string | number[];
-type AttrMap = Record<string, Scalar>;
-
-/** A node's attachment slot as the inspector needs it. */
-export interface AttachmentView {
-  slot: number;
+import type { Object3D, Vector3 } from 'three';
+import { provenanceOf, type Component, type Provenance } from '@scenoco-three/core';
+import type { ComponentInfo, ElementAt, ProjectModel, PropInfo, TagInfo, ValueShape } from '@scenoco-three/compiler';
+import { EditLog } from './editLog.js';
+import { formatValue, parseValue, type Scalar } from './values.js';
+
+/** A pending change, in the shape the server splices. */
+export type Edit =
+  | { op: 'setAttribute'; at: ElementAt; name: string; value: string | null }
+  | { op: 'removeElement'; at: ElementAt }
+  | { op: 'insertChild'; at: ElementAt; xml: string; index?: number }
+  | { op: 'moveElement'; at: ElementAt; parent: ElementAt; index?: number };
+
+/** The three placement channels a gizmo drives. */
+export type TransformChannel = 'position' | 'eulerAngles' | 'scale';
+
+/** One element of the open document, as the inspector needs it. */
+interface ElementView {
   tag: string;
-  attrs: AttrMap;
-  /** Inline attr props are editable (authored scene node, not src-loaded). */
-  editable: boolean;
-  /** `src=` file the attachment was loaded from (props read-only, src editable), else null. */
-  src: string | null;
+  at: ElementAt;
+  /** Byte range of the whole element in the document text — what a copy lifts. */
+  start: number;
+  end: number;
+  attributes: Map<string, string>;
 }
 
 /**
- * The editable model of the loaded scene and the single funnel for every change.
+ * The open document, and every change made to it since it was opened.
  *
- * Each mutator builds an undoable command that writes to **both** the live
- * Three.js object (so the viewport updates) **and** the compiled scene (the
- * serialization source of truth). Net edits to save are derived by diffing the
- * live compiled scene against a snapshot taken at load — so undo/redo, which
- * rewinds the compiled scene, is reflected automatically with no extra bookkeeping.
+ * ### What replaced what
+ *
+ * v1 held a compiled scene bundle and mirrored every edit into a copy-on-write shadow of it —
+ * `cowAttachments`, `srcEdits`, `removedComponents`, a structural op log, and index arithmetic to
+ * keep the shadow aligned with the live objects. That existed because the browser had a *bundle*
+ * and no way back to the source.
+ *
+ * Here the source **is** the model. A node knows which element built it, because the compiler
+ * stamped it; an edit is a splice addressed by that stamp; the file on disk is the only state.
+ * So this class holds the document text, the element index, and a list of pending splices.
+ *
+ * Edits are also applied to the live objects immediately, which is not redundant: the round trip
+ * through the server and a rebuild takes long enough to feel wrong under a gizmo drag, and an
+ * inspector that only updated after a save would be unusable.
  */
 export class SceneDocument {
-  private readonly compiled: CompiledScene;
-  /** Pristine copy at load — diffed against `compiled` to produce save edits. */
-  private original: CompiledScene;
-  private readonly undo: UndoStack;
-  private readonly listeners = new Set<() => void>();
-  /** Attachment pool indices this document created via copy-on-write (mutate in place). */
-  private readonly cowAttachments = new Set<number>();
-  /** `src` edits (prefab instance / material) — no compiled home, tracked explicitly. */
-  private readonly srcEdits = new Map<string, EditOp>();
-
-  constructor(
-    private readonly graph: SceneGraph,
-    private readonly provenance?: SceneProvenance,
-  ) {
-    this.compiled = graph.compiled;
-    this.original = structuredClone(graph.compiled);
-    this.undo = new UndoStack(() => this.emit());
-  }
-
-  // ── editability (driven by provenance) ─────────────────────────────────────────
-
-  /** Where a node came from — authored scene, a prefab instance root, or prefab-internal. */
-  nodeOrigin(node: Object3D): NodeOrigin {
-    const i = this.graph.nodeIndexOf.get(node);
-    return (i !== undefined && this.provenance?.nodes[i]) || { kind: 'scene' };
-  }
-  /** Transform is editable on authored nodes and prefab-instance roots (their own override). */
+  /** Project-relative path — and the `file` every editable node is stamped with. */
+  readonly path: string;
+
+  private text: string;
+  private readonly model: ProjectModel;
+  private elements: ElementView[] = [];
+  /** What has changed since the document was opened, and how to take it back. */
+  private readonly log = new EditLog();
+
+  constructor(path: string, text: string, elements: readonly RawElement[], model: ProjectModel) {
+    this.path = path;
+    this.text = text;
+    this.model = model;
+    this.adopt(elements);
+  }
+
+  // --- what may be edited ------------------------------------------------------------------
+
+  /**
+   * Where this node came from, or null if nothing authored it.
+   *
+   * Null covers two cases that look the same from here and are both correctly read-only: a node
+   * some component spawned at runtime, and a node from a *different* document — the inside of a
+   * spawned prefab, which is stamped with the prefab's own file.
+   */
+  originOf(node: Object3D): Provenance | null {
+    return provenanceOf(node);
+  }
+
+  /** True when this node belongs to the document being edited. */
+  private mine(node: Object3D): ElementAt | null {
+    const origin = provenanceOf(node);
+    if (!origin || origin.file !== this.path) return null;
+    return { line: origin.line, column: origin.column };
+  }
+
   canEditTransform(node: Object3D): boolean {
-    const k = this.nodeOrigin(node).kind;
-    return k === 'scene' || k === 'prefab-root';
+    return this.mine(node) !== null;
   }
-  /** Components are editable only on authored scene nodes. */
+
+  /**
+   * Whether this document can *declare* components on a node — what an "Add component" needs.
+   *
+   * A spawned prefab cannot take one. The compiler skips a `<Prefab>` element's children when it
+   * walks a document for components, so a `<Components>` block written inside one compiles to
+   * nothing: the button would appear to work and change nothing, which is worse than not
+   * offering it. The prefab's own file is where its components are declared.
+   */
   canEditComponents(node: Object3D): boolean {
-    return this.nodeOrigin(node).kind === 'scene';
+    return this.mine(node) !== null && this.tagNameOf(node) !== 'Prefab';
   }
-  /** The prefab `src` of a prefab-instance root, else undefined. */
-  prefabSrc(node: Object3D): string | undefined {
-    const o = this.nodeOrigin(node);
-    return o.kind === 'prefab-root' ? o.src : undefined;
+
+  /**
+   * Whether *this* document declares the component, as opposed to a prefab it spawns.
+   *
+   * A prefab instance is the case that needs it: the `<Prefab>` element is in this file, so the
+   * node is ours and its placement is editable — but the components came with the prefab and are
+   * declared in that file. Asking the node is the wrong question, and answering it with the node
+   * gave an inspector full of live-looking fields whose writes went nowhere: `setComponentProp`
+   * finds no element and returns, so typing into them did nothing at all.
+   */
+  canEditComponent(component: Component): boolean {
+    return this.componentElement(component) !== undefined;
+  }
+
+  canEditStructure(node: Object3D): boolean {
+    return this.mine(node) !== null;
   }
-  private attachmentSrcOf(poolIndex: number): string | null {
-    return this.provenance?.attachments[poolIndex] ?? null;
+
+  /** The document a node came from, when it is not this one — what to open to edit it. */
+  foreignSource(node: Object3D): string | null {
+    const origin = provenanceOf(node);
+    return origin && origin.file !== this.path ? origin.file : null;
   }
 
-  // ── subscription ───────────────────────────────────────────────────────────
+  // --- reading -----------------------------------------------------------------------------
 
-  onChange(cb: () => void): () => void {
-    this.listeners.add(cb);
-    return () => this.listeners.delete(cb);
+  /** The element that built this node. */
+  private elementOf(node: Object3D): ElementView | undefined {
+    const at = this.mine(node);
+    if (!at) return undefined;
+    return this.elements.find((e) => e.at.line === at.line && e.at.column === at.column);
   }
-  private emit(): void {
-    for (const cb of this.listeners) cb();
+
+  /** What the document says for one of a node's attributes, or undefined if it says nothing. */
+  nodeAttr(node: Object3D, attr: string): string | undefined {
+    return this.elementOf(node)?.attributes.get(attr);
   }
 
-  get canUndo(): boolean {
-    return this.undo.canUndo;
+  /** True when the document writes this attribute — as opposed to leaving it at its default. */
+  isNodeAttrSet(node: Object3D, attr: string): boolean {
+    return this.nodeAttr(node, attr) !== undefined;
   }
-  get canRedo(): boolean {
-    return this.undo.canRedo;
+
+  /** The element name the document wrote — `Panel`, not `Mesh`. */
+  tagNameOf(node: Object3D): string | undefined {
+    return this.elementOf(node)?.tag;
   }
-  /** Any unsaved change (cheap: scenes are small). */
-  get isDirty(): boolean {
-    return this.netEdits().length > 0;
+
+  /** The tag the compiler knows this node's element by, with its authorable attributes. */
+  tagOf(node: Object3D): TagInfo | undefined {
+    const tag = this.elementOf(node)?.tag;
+    return tag ? this.model.tags.find((t) => t.name === tag) : undefined;
   }
 
-  undoLast(): void {
-    this.undo.undo();
+  /** The components on a node, paired with what the compiler knows about each class. */
+  componentsOf(node: Object3D): Array<{ component: Component; info: ComponentInfo | undefined }> {
+    return node.components.map((component) => ({
+      component,
+      info: this.model.components.find((c) => c.name === component.constructor.name),
+    }));
   }
-  redoLast(): void {
-    this.undo.redo();
-  }
-
-  // ── transform edits ──────────────────────────────────────────────────────────
-
-  /** Set a node's position/scale (world units) or rotation (radians, XYZ). */
-  setTransform(node: Object3D, channel: TransformChannel, value: number[], opts?: { coalesce?: boolean }): void {
-    if (!this.canEditTransform(node)) return;
-    const i = this.graph.nodeIndexOf.get(node);
-    if (i === undefined) return;
-    const t = this.compiled.nodes[i]!.transform;
-    const prev = t[channel].slice();
-    const next = value.slice();
-    if (numbersEqual(prev, next)) return; // no-op (e.g. an unchanged channel after a drag)
-    this.undo.run({
-      label: `${channel} ${node.name || node.type}`,
-      coalesceKey: opts?.coalesce ? `node:${i}:${channel}` : undefined,
-      apply: () => {
-        t[channel] = next.slice();
-        applyTransform(node, channel, next);
-      },
-      invert: () => {
-        t[channel] = prev.slice();
-        applyTransform(node, channel, prev);
-      },
+
+  /** The element of one component — the Nth `<Type>` inside this node's `<Components>`. */
+  private componentElement(component: Component): ElementView | undefined {
+    const owner = this.elementOf(component.object3D);
+    if (!owner) return undefined;
+    const name = component.constructor.name;
+    const ordinal = component.object3D.components
+      .filter((c) => c.constructor.name === name)
+      .indexOf(component);
+    // Elements are in document order, so the components of a node are the ones that follow it
+    // before the next node's element — and the Nth of a name is the Nth match.
+    const start = this.elements.indexOf(owner);
+    const matches = this.elements.slice(start + 1).filter((e) => e.tag === name);
+    return matches[ordinal];
+  }
+
+  componentProp(component: Component, name: string): string | undefined {
+    return this.componentElement(component)?.attributes.get(name);
+  }
+
+  isComponentPropSet(component: Component, name: string): boolean {
+    return this.componentProp(component, name) !== undefined;
+  }
+
+  /**
+   * One attribute as a **value**, for the inspector's widgets.
+   *
+   * The document stores text and the widgets edit numbers, flags and axis lists; this pair is the
+   * only place the two meet, so a scrubbed number and a hand-typed one land in the file the same
+   * way. Undefined when the document does not write it — which is what the row needs in order to
+   * show the default, greyed.
+   */
+  nodeValue(node: Object3D, prop: PropInfo): Scalar | undefined {
+    return parseValue(prop.shape, this.nodeAttr(node, prop.name));
+  }
+
+  componentValue(component: Component, prop: PropInfo): Scalar | undefined {
+    return parseValue(prop.shape, this.componentProp(component, prop.name));
+  }
+
+  setNodeValue(node: Object3D, prop: PropInfo, value: Scalar, opts?: { coalesce?: boolean }): void {
+    this.setNodeAttr(node, prop.name, formatValue(prop.shape, value), { ...opts, shape: prop.shape });
+  }
+
+  setComponentValue(
+    component: Component,
+    prop: PropInfo,
+    value: Scalar,
+    opts?: { coalesce?: boolean },
+  ): void {
+    this.setComponentProp(component, prop.name, formatValue(prop.shape, value), {
+      ...opts,
+      shape: prop.shape,
     });
   }
 
-  setVisible(node: Object3D, value: boolean): void {
-    if (!this.canEditTransform(node)) return;
-    const i = this.graph.nodeIndexOf.get(node);
-    if (i === undefined) return;
-    const t = this.compiled.nodes[i]!.transform;
-    const prev = t.visible;
-    if (prev === value) return;
-    this.undo.run({
-      label: `visible ${node.name || node.type}`,
-      apply: () => {
-        t.visible = value;
-        node.visible = value;
+  // --- writing -----------------------------------------------------------------------------
+
+  /**
+   * Set or clear one of a node's own attributes.
+   *
+   * `null` clears it, which is a real instruction rather than "write the default": a document
+   * that says nothing inherits whatever the class decides later, and one that writes the current
+   * default is pinned to today's value.
+   */
+  setNodeAttr(
+    node: Object3D,
+    attr: string,
+    value: string | null,
+    opts?: { coalesce?: boolean; shape?: ValueShape; from?: unknown },
+  ): void {
+    const at = this.mine(node);
+    if (!at) return;
+    const before = this.nodeAttr(node, attr) ?? null;
+    // `from` when the caller knows the value from before the change — a gizmo does, because the
+    // drag it is reporting has already moved the object. Sampling here would be a frame late.
+    const live = opts?.from ?? snapshot(node, attr);
+    this.log.commit(
+      `${attr} on <${this.elementOf(node)?.tag ?? '?'}>`,
+      () => {
+        this.writeAttribute(at, attr, value);
+        this.applyLive(node, attr, value, opts?.shape, live);
       },
-      invert: () => {
-        t.visible = prev;
-        node.visible = prev;
+      () => {
+        this.writeAttribute(at, attr, before);
+        this.applyLive(node, attr, before, opts?.shape, live);
       },
-    });
+      opts?.coalesce === true,
+    );
   }
 
-  // ── component property edits ──────────────────────────────────────────────────
+  clearNodeAttr(node: Object3D, attr: string): void {
+    this.setNodeAttr(node, attr, null);
+  }
 
-  /** Set a scalar/vector/color/bool/string `@property` in compiled form. */
   setComponentProp(
     component: Component,
     name: string,
-    value: number | boolean | string | number[],
-    opts?: { coalesce?: boolean },
+    value: string | null,
+    opts?: { coalesce?: boolean; shape?: ValueShape },
   ): void {
-    const ci = this.graph.componentIndexOf.get(component);
-    if (ci === undefined) return;
-    const cc = this.compiled.components[ci]!;
-    if ((this.provenance?.nodes[cc.node]?.kind ?? 'scene') !== 'scene') return; // prefab content read-only
-    const meta = Registry.getComponent(cc.type)?.meta.properties.get(name);
-    if (!meta) return;
-    const elem = elementType(meta.type);
-
-    const field = component as unknown as Record<string, unknown>;
-    const had = name in cc.props;
-    if (had && valuesEqual(cc.props[name], value)) return; // no-op
-    const prevCompiled = had ? structuredClone(cc.props[name]!) : undefined;
-    const prevRuntime = cloneRuntime(field[name]);
-    const nextRuntime = toRuntime(meta.type, value);
-    this.undo.run({
-      label: `${cc.type}.${name}`,
-      coalesceKey: opts?.coalesce ? `comp:${ci}:${name}` : undefined,
-      apply: () => {
-        cc.props[name] = structuredClone(value);
-        field[name] = cloneRuntime(nextRuntime);
+    const element = this.componentElement(component);
+    if (!element) return;
+    const before = element.attributes.get(name) ?? null;
+    const live = snapshot(component, name);
+    this.log.commit(
+      `${name} on <${element.tag}>`,
+      () => {
+        this.writeAttribute(element.at, name, value);
+        this.applyLive(component, name, value, opts?.shape, live);
       },
-      invert: () => {
-        if (had) cc.props[name] = structuredClone(prevCompiled!);
-        else delete cc.props[name];
-        field[name] = cloneRuntime(prevRuntime);
+      () => {
+        this.writeAttribute(element.at, name, before);
+        this.applyLive(component, name, before, opts?.shape, live);
       },
-    });
-    void elem; // reserved: array-element handling lands with array editing
+      opts?.coalesce === true,
+    );
   }
 
-  // ── attachment edits (geometry / material / scene settings) ─────────────────────
+  clearComponentProp(component: Component, name: string): void {
+    this.setComponentProp(component, name, null);
+  }
 
-  /** The attachment slots on a node, with editability + src provenance for the inspector. */
-  attachmentsOf(node: Object3D): AttachmentView[] {
-    const i = this.graph.nodeIndexOf.get(node);
-    if (i === undefined) return [];
-    const sceneNode = this.nodeOrigin(node).kind === 'scene';
-    return this.compiled.nodes[i]!.attachments.map((idx, slot) => {
-      const asset = this.compiled.attachments[idx]!;
-      const src = this.attachmentSrcOf(idx);
-      return { slot, tag: asset.tag, attrs: asset.attrs as AttrMap, editable: sceneNode && src === null, src };
+  /**
+   * Write a transform channel from the live object — what a gizmo drag commits.
+   *
+   * In the document's own units, so `eulerAngles` is degrees, and in the document's own grammar,
+   * so a vector is `x: 1; y: 2; z: 3`. A gizmo produces a great many of these, which is what
+   * `coalesce` is for: one drag is one undo step.
+   */
+  setTransform(
+    node: Object3D,
+    channel: TransformChannel,
+    opts?: { coalesce?: boolean; from?: Vector3 },
+  ): void {
+    const vector = channel === 'eulerAngles' ? node.eulerAngles : node[channel];
+    this.setNodeAttr(node, channel, formatVector(vector.x, vector.y, vector.z), {
+      ...opts,
+      shape: channel === 'eulerAngles' ? 'euler' : 'vector3',
+      // Cloned: the gizmo reuses one vector per channel across drags, and this one has to hold
+      // still inside an undo step for as long as the step exists.
+      ...(opts?.from ? { from: opts.from.clone() } : {}),
     });
   }
 
-  /** Current compiled value of an attachment attr (fresh — editors read it per change). */
-  attachmentAttr(node: Object3D, slot: number, attr: string): Scalar | undefined {
-    const i = this.graph.nodeIndexOf.get(node);
-    if (i === undefined) return undefined;
-    const idx = this.compiled.nodes[i]!.attachments[slot];
-    return idx === undefined ? undefined : (this.compiled.attachments[idx]!.attrs[attr] as Scalar | undefined);
+  setVisible(node: Object3D, value: boolean): void {
+    node.visible = value;
+    this.setNodeAttr(node, 'visible', String(value));
+  }
+
+  /** Delete a node's element, and everything under it. */
+  removeNode(node: Object3D): void {
+    const at = this.mine(node);
+    if (!at) return;
+    this.log.push({ op: 'removeElement', at }, `remove <${this.elementOf(node)?.tag ?? 'node'}>`);
+  }
+
+  /** Reparent — what a drag in the tree produces. */
+  moveNode(node: Object3D, newParent: Object3D, index?: number): void {
+    const at = this.mine(node);
+    const parent = this.mine(newParent);
+    if (!at || !parent) return;
+    this.log.push(
+      { op: 'moveElement', at, parent, ...(index !== undefined ? { index } : {}) },
+      `move <${this.elementOf(node)?.tag ?? 'node'}>`,
+    );
   }
 
   /**
-   * Set an inline attachment attribute, **copy-on-write**: the first edit clones the
-   * pooled `CompiledAsset` into a private entry (so sibling nodes sharing it are
-   * untouched); later edits mutate the private copy in place. The live resource is
-   * rebuilt from the attachment's own builder, so it's unshared automatically.
+   * The source text of a node's element — what a copy puts on the clipboard.
+   *
+   * The authored text, not a re-serialization of the live objects: a paste should reproduce what
+   * was written, comments and formatting and all, and anything reconstructed from the runtime
+   * would have lost both.
    */
-  setAttachmentProp(node: Object3D, slot: number, attr: string, value: Scalar, opts?: { coalesce?: boolean }): void {
-    const i = this.graph.nodeIndexOf.get(node);
-    if (i === undefined) return;
-    const cnode = this.compiled.nodes[i]!;
-    const curIdx = cnode.attachments[slot];
-    if (curIdx === undefined) return;
-    const src = this.compiled.attachments[curIdx]!;
-    if (this.nodeOrigin(node).kind !== 'scene' || this.attachmentSrcOf(curIdx) !== null) return; // read-only
-    const tag = src.tag;
-    const reattach = (attrs: AttrMap) => getAttachmentDef(tag)?.make(attrs).attach({ node });
-
-    if (this.cowAttachments.has(curIdx)) {
-      // Already our private copy — mutate in place.
-      const asset = src;
-      const had = attr in asset.attrs;
-      if (had && valuesEqual(asset.attrs[attr], value)) return;
-      const prev = had ? structuredClone(asset.attrs[attr]!) : undefined;
-      this.undo.run({
-        label: `${tag}.${attr}`,
-        coalesceKey: opts?.coalesce ? `att:${curIdx}:${attr}` : undefined,
-        apply: () => {
-          asset.attrs[attr] = structuredClone(value);
-          reattach(asset.attrs as AttrMap);
-        },
-        invert: () => {
-          if (had) asset.attrs[attr] = structuredClone(prev!);
-          else delete asset.attrs[attr];
-          reattach(asset.attrs as AttrMap);
-        },
-      });
-      return;
-    }
+  sourceOf(node: Object3D): string | null {
+    const element = this.elementOf(node);
+    return element ? this.text.slice(element.start, element.end) : null;
+  }
 
-    if (valuesEqual(src.attrs[attr], value)) return; // no-op against the shared value
-    const newIdx = this.compiled.attachments.length;
-    const newAttrs = { ...structuredClone(src.attrs), [attr]: structuredClone(value) };
-    this.undo.run({
-      label: `${tag}.${attr}`,
-      coalesceKey: opts?.coalesce ? `att:slot:${i}:${slot}:${attr}` : undefined,
-      apply: () => {
-        this.compiled.attachments[newIdx] = { tag, attrs: newAttrs };
-        cnode.attachments[slot] = newIdx;
-        this.cowAttachments.add(newIdx);
-        reattach(newAttrs as AttrMap);
-      },
-      invert: () => {
-        cnode.attachments[slot] = curIdx;
-        this.cowAttachments.delete(newIdx);
-        reattach(src.attrs as AttrMap);
-      },
-    });
+  /** Paste a fragment under a node. */
+  insertNode(parent: Object3D, xml: string): void {
+    const at = this.mine(parent);
+    if (!at) return;
+    this.log.push({ op: 'insertChild', at, xml }, 'paste');
   }
 
-  /** Edit a prefab-instance node's `src` (save-only — reopen to see the swapped content). */
-  setNodeSrc(node: Object3D, src: string): void {
-    const i = this.graph.nodeIndexOf.get(node);
-    if (i === undefined || this.nodeOrigin(node).kind !== 'prefab-root') return;
-    const cnode = this.compiled.nodes[i]!;
-    this.recordSrcEdit(`node:${i}:src`, { kind: 'node', nodeIndex: i, ...(cnode.id ? { id: cnode.id } : {}) }, src);
-  }
-
-  /** Edit a src-loaded attachment's `src` (save-only — reopen to see the swapped content). */
-  setAttachmentSrc(node: Object3D, slot: number, src: string): void {
-    const i = this.graph.nodeIndexOf.get(node);
-    if (i === undefined) return;
-    const idx = this.compiled.nodes[i]!.attachments[slot];
-    if (idx === undefined || this.attachmentSrcOf(idx) === null) return;
-    this.recordSrcEdit(`att:${i}:${slot}:src`, this.attachmentTarget(i, slot, this.compiled.attachments[idx]!.tag), src);
-  }
-
-  private recordSrcEdit(key: string, target: EditTarget, src: string): void {
-    const prev = this.srcEdits.get(key);
-    this.undo.run({
-      label: `src ${key}`,
-      coalesceKey: `src:${key}`,
-      apply: () => void this.srcEdits.set(key, { target, attr: 'src', value: src }),
-      invert: () => {
-        if (prev) this.srcEdits.set(key, prev);
-        else this.srcEdits.delete(key);
-      },
-    });
+  /** Add a component to a node — a `<Type />` inside its `<Components>`. */
+  addComponent(node: Object3D, type: string): void {
+    const at = this.mine(node);
+    if (!at) return;
+    const components = this.componentsBlockOf(node);
+    if (components) {
+      this.log.push({ op: 'insertChild', at: components.at, xml: `<${type} />` }, `add <${type}>`);
+      return;
+    }
+    // No `<Components>` yet, so the block comes with it.
+    this.log.push(
+      { op: 'insertChild', at, xml: `<Components>\n  <${type} />\n</Components>` },
+      `add <${type}>`,
+    );
   }
 
-  // ── persistence ───────────────────────────────────────────────────────────────
-
-  /** The minimal set of changed attributes vs. the loaded source, for surgical save. */
-  netEdits(): EditOp[] {
-    const out: EditOp[] = [];
-    this.compiled.nodes.forEach((node, i) => {
-      const orig = this.original.nodes[i]!;
-      const target = (): EditTarget => ({ kind: 'node', nodeIndex: i, ...(node.id ? { id: node.id } : {}) });
-      if (!numbersEqual(node.transform.position, orig.transform.position))
-        out.push({ target: target(), attr: 'position', value: node.transform.position.slice() });
-      if (!numbersEqual(node.transform.rotation, orig.transform.rotation))
-        out.push({ target: target(), attr: 'rotation', value: node.transform.rotation.slice() });
-      if (!numbersEqual(node.transform.scale, orig.transform.scale))
-        out.push({ target: target(), attr: 'scale', value: node.transform.scale.slice() });
-      if (node.transform.visible !== orig.transform.visible)
-        out.push({ target: target(), attr: 'visible', value: node.transform.visible });
-    });
-    this.compiled.components.forEach((comp, ci) => {
-      const orig = this.original.components[ci]!;
-      for (const [name, value] of Object.entries(comp.props)) {
-        if (!isSavableScalar(value) || valuesEqual(value, orig.props[name])) continue;
-        out.push({ target: this.componentTarget(ci), attr: name, value: value as number | boolean | string | number[] });
-      }
-    });
-    // Attachment attrs: a slot whose pool index changed (copy-on-write) vs. its original asset.
-    this.compiled.nodes.forEach((node, i) => {
-      const orig = this.original.nodes[i]!;
-      node.attachments.forEach((attIdx, slot) => {
-        const origIdx = orig.attachments[slot];
-        if (origIdx === undefined || attIdx === origIdx) return;
-        const cur = this.compiled.attachments[attIdx]!;
-        const base = this.original.attachments[origIdx]!;
-        for (const [attr, val] of Object.entries(cur.attrs)) {
-          if (!isSavableScalar(val) || valuesEqual(val, base.attrs[attr])) continue;
-          out.push({ target: this.attachmentTarget(i, slot, cur.tag), attr, value: val as number | boolean | string | number[] });
-        }
-      });
-    });
-    // `src` edits (prefab instance / material) have no compiled home — tracked explicitly.
-    out.push(...this.srcEdits.values());
-    return out;
+  removeComponent(component: Component): void {
+    const element = this.componentElement(component);
+    if (!element) return;
+    this.log.push({ op: 'removeElement', at: element.at }, `remove <${element.tag}>`);
   }
 
-  /** Mark the current state as the saved baseline (keeps the undo stack). */
-  markSaved(): void {
-    this.original = structuredClone(this.compiled);
-    this.srcEdits.clear();
-    this.emit();
+  private componentsBlockOf(node: Object3D): ElementView | undefined {
+    const owner = this.elementOf(node);
+    if (!owner) return undefined;
+    const start = this.elements.indexOf(owner);
+    const next = this.elements[start + 1];
+    return next?.tag === 'Components' ? next : undefined;
   }
 
+  // --- the edit log ------------------------------------------------------------------------
+  //
+  // Kept by `EditLog`; the document supplies the pair of closures that make each step and takes
+  // it back. Everything below is the document's side of that contract.
+
   /**
-   * Re-apply a set of edits onto this (freshly loaded) document — used to preserve
-   * the user's unsaved changes after a `src=` dependency reload. Resolution is by
-   * id/tag/ordinal (best-effort): edits whose target no longer exists are dropped.
+   * Make the live scene agree with what the document now says about one attribute.
+   *
+   * The document is the model and the scene is the view, and until this existed nothing carried
+   * the model back to the view: typing a position in the inspector rewrote the XML and left the
+   * object where it was, and undoing a gizmo drag rewound the file while the object stayed
+   * dragged. Every write goes through here, so an edit, an undo and a redo all land the same
+   * way — which is the only reason undo can be trusted.
+   *
+   * `fallback` is the value the object had before this edit, used when the document has nothing
+   * left to say (the attribute was cleared, or was never authored). The class's own default is
+   * the more principled answer and is not knowable here: it lives in the compiled scene, and
+   * reading it back would mean rebuilding the node.
    */
-  applyEdits(ops: EditOp[]): void {
-    for (const op of ops) this.applyEdit(op);
-  }
-
-  private applyEdit(op: EditOp): void {
-    const t = op.target;
-    if (t.kind === 'node') {
-      const node = this.nodeById(t.id);
-      if (!node) return;
-      if (op.attr === 'src') this.setNodeSrc(node, op.value as string);
-      else if (op.attr === 'visible') this.setVisible(node, op.value as boolean);
-      else if (op.attr === 'position' || op.attr === 'rotation' || op.attr === 'scale')
-        this.setTransform(node, op.attr, op.value as number[]);
-    } else if (t.kind === 'component') {
-      const comp = this.componentByTarget(t.nodeId, t.type, t.ordinal);
-      if (comp) this.setComponentProp(comp, op.attr, op.value);
-    } else {
-      const node = t.root ? this.graph.nodeByIndex[this.compiled.root] : this.nodeById(t.nodeId);
-      if (!node) return;
-      const slot = this.attachmentSlot(node, t.tag, t.ordinal);
-      if (slot === undefined) return;
-      if (op.attr === 'src') this.setAttachmentSrc(node, slot, op.value as string);
-      else this.setAttachmentProp(node, slot, op.attr, op.value);
-    }
+  private applyLive(
+    target: Object3D | Component,
+    name: string,
+    text: string | null,
+    shape: ValueShape | undefined,
+    fallback: unknown,
+  ): void {
+    if (text === null || shape === undefined) return restore(target, name, fallback);
+    const value = parseValue(shape, text);
+    if (value === undefined) return restore(target, name, fallback);
+    write(target, name, value);
   }
 
-  private nodeById(id?: string): Object3D | undefined {
-    if (!id) return undefined;
-    const i = this.compiled.nodes.findIndex((n) => n.id === id);
-    return i >= 0 ? this.graph.nodeByIndex[i] : undefined;
-  }
-  private componentByTarget(nodeId: string | undefined, type: string, ordinal: number): Component | undefined {
-    if (!nodeId) return undefined;
-    const ni = this.compiled.nodes.findIndex((n) => n.id === nodeId);
-    if (ni < 0) return undefined;
-    const ci = this.compiled.nodes[ni]!.components.filter((x) => this.compiled.components[x]!.type === type)[ordinal];
-    if (ci === undefined) return undefined;
-    for (const [inst, idx] of this.graph.componentIndexOf) if (idx === ci) return inst;
-    return undefined;
-  }
-  private attachmentSlot(node: Object3D, tag: string, ordinal: number): number | undefined {
-    const ni = this.graph.nodeIndexOf.get(node);
-    if (ni === undefined) return undefined;
-    const atts = this.compiled.nodes[ni]!.attachments;
-    let count = 0;
-    for (let slot = 0; slot < atts.length; slot++) {
-      if (this.compiled.attachments[atts[slot]!]!.tag !== tag) continue;
-      if (count === ordinal) return slot;
-      count++;
-    }
-    return undefined;
-  }
-
-  private attachmentTarget(i: number, slot: number, tag: string): EditTarget {
-    const node = this.compiled.nodes[i]!;
-    const ordinal = node.attachments.slice(0, slot + 1).filter((idx) => this.compiled.attachments[idx]!.tag === tag).length - 1;
-    return {
-      kind: 'attachment',
-      nodeIndex: i,
-      ...(node.id ? { nodeId: node.id } : {}),
-      ...(i === this.compiled.root ? { root: true } : {}),
-      tag,
-      ordinal,
-    };
-  }
-
-  private componentTarget(ci: number): EditTarget {
-    const cc = this.compiled.components[ci]!;
-    const node = this.compiled.nodes[cc.node]!;
-    const sameType = node.components.filter((x) => this.compiled.components[x]!.type === cc.type);
-    return {
-      kind: 'component',
-      componentIndex: ci,
-      nodeIndex: cc.node,
-      ...(node.id ? { nodeId: node.id } : {}),
-      type: cc.type,
-      ordinal: sameType.indexOf(ci),
-    };
+  /** Queue the splice, and keep this document's own view of the element in step with it. */
+  private writeAttribute(at: ElementAt, name: string, value: string | null): void {
+    this.log.replaceAttribute({ op: 'setAttribute', at, name, value });
+
+    const element = this.elements.find((e) => e.at.line === at.line && e.at.column === at.column);
+    if (!element) return;
+    if (value === null) element.attributes.delete(name);
+    else element.attributes.set(name, value);
+  }
+
+  get canUndo(): boolean {
+    return this.log.canUndo;
+  }
+
+  get canRedo(): boolean {
+    return this.log.canRedo;
   }
-}
 
-// ── value helpers ────────────────────────────────────────────────────────────────
+  get isDirty(): boolean {
+    return this.log.isDirty;
+  }
+
+  /** Everything not yet written to disk. */
+  edits(): readonly Edit[] {
+    return this.log.edits;
+  }
 
-function applyTransform(node: Object3D, channel: TransformChannel, v: number[]): void {
-  if (channel === 'rotation') node.rotation.set(v[0]!, v[1]!, v[2]!);
-  else node[channel].fromArray(v);
+  undoLast(): void {
+    this.log.undo();
+  }
+
+  redoLast(): void {
+    this.log.redo();
+  }
+
+  /** Called once the server has written the file. */
+  markSaved(text: string, elements: readonly RawElement[]): void {
+    this.text = text;
+    this.log.clear();
+    this.adopt(elements);
+    this.log.emit();
+  }
+
+  onChange(listener: () => void): () => void {
+    return this.log.onChange(listener);
+  }
+
+  /**
+   * Take the element index the server built.
+   *
+   * Not parsed here on purpose. The positions have to be **the same numbers** the compiler
+   * stamped into the live objects, and the only way to guarantee that is for one parser to
+   * produce both. A second implementation in the browser drifted on the first long open tag it
+   * met, and the symptom — some nodes selectable and some not — pointed nowhere near the cause.
+   */
+  private adopt(elements: readonly RawElement[]): void {
+    this.elements = elements.map((e) => ({
+      tag: e.tag,
+      at: { line: e.line, column: e.column },
+      start: e.start,
+      end: e.end,
+      attributes: new Map(Object.entries(e.attributes)),
+    }));
+  }
 }
 
-/** Compiled scalar → the Three.js-typed value a component field holds (mirrors instantiate). */
-function toRuntime(type: PropertyType, value: number | boolean | string | number[]): unknown {
-  const elem = elementType(type);
-  if (isArrayType(type)) return (value as number[]).map((v) => toRuntimeScalar(elem, v));
-  return toRuntimeScalar(elem, value as number | boolean | string | number[]);
+/** One element, as the server's index reports it. */
+export interface RawElement {
+  tag: string;
+  line: number;
+  column: number;
+  start: number;
+  end: number;
+  attributes: Record<string, string>;
 }
-function toRuntimeScalar(elem: PropType | { new (): unknown } | EnumDef, value: unknown): unknown {
-  switch (elem) {
-    case 'vec2':
-      return new Vector2().fromArray(value as number[]);
-    case 'vec3':
-      return new Vector3().fromArray(value as number[]);
-    case 'euler': {
-      const e = value as number[];
-      return new Euler(e[0]!, e[1]!, e[2]!);
-    }
-    case 'color':
-      return new Color(value as number);
-    default:
-      return value;
-  }
+
+/** The default a document leaves unwritten, as the compiler read it from the source. */
+export function defaultOf(prop: PropInfo): string | undefined {
+  return prop.default;
 }
 
-/** Clone a runtime value so undo snapshots don't alias live Three.js objects. */
-function cloneRuntime(v: unknown): unknown {
-  if (v == null) return v;
-  const o = v as { isVector3?: boolean; isVector2?: boolean; isColor?: boolean; isEuler?: boolean; clone?: () => unknown };
-  if (o.isVector2 || o.isVector3 || o.isColor) return o.clone!();
-  if (o.isEuler) {
-    const e = v as Euler;
-    return new Euler(e.x, e.y, e.z, e.order);
-  }
-  return Array.isArray(v) ? v.map(cloneRuntime) : v;
+/** `x: 1; y: 2; z: 3` — the DSL's only vector spelling. */
+export function formatVector(x: number, y: number, z: number): string {
+  const round = (n: number): string => String(Math.round(n * 1000) / 1000);
+  return `x: ${round(x)}; y: ${round(y)}; z: ${round(z)}`;
 }
 
-const isSavableScalar = (v: unknown): boolean =>
-  typeof v === 'number' ||
-  typeof v === 'boolean' ||
-  typeof v === 'string' ||
-  (Array.isArray(v) && v.every((x) => typeof x === 'number'));
 
-function numbersEqual(a: number[], b: number[]): boolean {
-  return a.length === b.length && a.every((x, i) => x === b[i]);
+// --- the live half of an edit -----------------------------------------------------------------
+
+/**
+ * `eulerAngles` hands back a cached vector that is recomputed from `rotation` on every read, so
+ * writing *into* it sets a field the next read discards. Assigning the whole vector goes through
+ * the setter, which is the documented way to use it — and the reason this needs naming at all.
+ */
+const ASSIGN_WHOLE = new Set(['eulerAngles']);
+
+/** The live value of one attribute, detached so a later mutation cannot change it. */
+function snapshot(target: object, name: string): unknown {
+  const value = (target as Record<string, unknown>)[name];
+  const cloneable = value as { clone?: () => unknown } | null;
+  return cloneable && typeof cloneable.clone === 'function' ? cloneable.clone() : value;
+}
+
+/** Put a snapshot back where it came from. */
+function restore(target: object, name: string, snap: unknown): void {
+  const current = (target as Record<string, unknown>)[name] as { copy?: (v: unknown) => void } | null;
+  if (!ASSIGN_WHOLE.has(name) && current && snap && typeof current.copy === 'function') {
+    current.copy(snap);
+    return;
+  }
+  (target as Record<string, unknown>)[name] = snap;
 }
-function valuesEqual(a: unknown, b: unknown): boolean {
-  if (Array.isArray(a) && Array.isArray(b)) return numbersEqual(a as number[], b as number[]);
-  return a === b;
+
+/** Write a parsed attribute value onto the live object, in whatever form the field takes. */
+function write(target: object, name: string, value: Scalar): void {
+  const current = (target as Record<string, unknown>)[name] as
+    | { set?: (...args: number[]) => void; copy?: unknown }
+    | null;
+
+  if (Array.isArray(value)) {
+    // A vector or an Euler. Assign a fresh one where the field aliases, otherwise write in place
+    // so anything holding a reference to it — three does, everywhere — sees the change.
+    if (ASSIGN_WHOLE.has(name) && current && typeof current.set === 'function') {
+      const fresh = (current as { clone(): { set(...args: number[]): unknown } }).clone();
+      fresh.set(...value);
+      (target as Record<string, unknown>)[name] = fresh;
+      return;
+    }
+    if (current && typeof current.set === 'function') {
+      current.set(...value);
+      return;
+    }
+  }
+  // A colour is a number here, and `Color.set` takes one; everything else is a plain field.
+  if (typeof value === 'number' && current && typeof current.set === 'function') {
+    current.set(value);
+    return;
+  }
+  (target as Record<string, unknown>)[name] = value;
 }