Consolidate duplicated editor code, trim comments, refresh README

Split GraphCanvas (1076 -> 831 lines) into EdgeLayer and graphMenus;
the port and marker menus were the same list and are now one function.
Value specs of the inspector and the list tab share valueSpecs.ts, and
the remaining copies (compound commands, type glyphs, typed asset
lookup, name rule, play/editor world setup, marquee) are merged.

Four copies had already drifted apart; merging them fixes:
- "Disconnect N links" in the port menu is one undo step, not N
- "+ Add collider" is hidden on a placed container instance, as in
  the hierarchy menu, instead of always failing
- a bool property coerced from the text "false" becomes false
- a port command on an unknown node type reports instead of crashing

Comment-only edits leave the bundle byte-identical. README corrected in
35 places (step limit, jump-run clock, suite duration, 409 body, ...).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

src/core/commands/CompoundCommand.ts

@@ -28,3 +28,8 @@ export class CompoundCommand implements Command {
     for (let i = this.commands.length - 1; i >= 0; i--) this.commands[i]!.undo(project);
   }
 }
+
+/** A lone command stays itself, so the undo step keeps its own label. */
+export function oneStep(label: string, commands: readonly Command[]): Command {
+  return commands.length === 1 ? commands[0]! : new CompoundCommand(label, commands);
+}

src/core/commands/containerCommands.ts

@@ -20,11 +20,8 @@ import { nextAssetName } from './naming';
 import { requireObject, requireHolder, requireStructural } from './require';
 
 /**
- * Turns the selected objects, with everything parented below them, into a container asset placed
- * in their stead. The origin is the centre of the selection's bounding box (z = 0), so the template
- * is centred around (0, 0, 0). The objects themselves leave the holder – the placed container
- * shows them again, resolved from the template. It goes below the roots' shared parent, or at the
- * top level when they do not share one.
+ * Turns the selected objects and their descendants into a container asset placed in their stead, the
+ * template centred on the selection's bounding box (z = 0).
  */
 export class CreateContainerCommand implements Command {
   readonly label = 'Create container';

src/core/commands/portCommands.ts

@@ -9,14 +9,14 @@ import {
   type GraphNode,
   isTerminalNode,
   isValidPortName,
-  requireNodeDef,
   RUN_BEHAVIOR,
 } from '../graph';
 import type { PropertyValue } from '../model/Properties';
 import type { Project } from '../model/Project';
 import { type Removed, removeFirst, removeWhere, restoreAt } from '../util/list';
 import { type Command, CommandError } from './Command';
-import { requireBehavior } from './require';
+import { nextFieldName } from './naming';
+import { requireBehavior, requireNode, requireNodeDef } from './require';
 
 interface PortSite {
   graph: Graph;
@@ -52,19 +52,17 @@ function edgesOnPort(site: PortSite, key: string): (edge: GraphEdge) => boolean
       : edge.from.node === site.nodeId && edge.from.port === key;
 }
 
-/** The node whose declaration is being edited; a terminal is addressed by id like any other. */
-function requirePortNode(project: Project, assetId: string, nodeId: string): GraphNode {
-  const node = findNode(requireBehavior(project, assetId).graph, nodeId);
-  if (!node) throw new CommandError(`Node ${nodeId} not found`);
-  return node;
-}
-
 function nodeAt(site: PortSite): GraphNode | undefined {
-  return site.graph.nodes.find((n) => n.id === site.nodeId);
+  return findNode(site.graph, site.nodeId);
 }
 
-function renameParam(site: PortSite, from: string, to: string): void {
-  const node = nodeAt(site);
+/** The port's edges follow its new key, and so does an input's typed-in value, which lives under it. */
+function carryPort(site: PortSite, from: string, to: string): void {
+  for (const edge of site.graph.edges.filter(edgesOnPort(site, from))) {
+    if (site.asInput) edge.to.port = to;
+    else edge.from.port = to;
+  }
+  const node = site.asInput ? nodeAt(site) : undefined;
   const value = node?.params[from];
   if (!node || value === undefined) return;
   node.params[to] = value;
@@ -90,7 +88,7 @@ export class AddPortsCommand implements Command {
   }
 
   execute(project: Project): void {
-    const node = requirePortNode(project, this.assetId, this.nodeId);
+    const node = requireNode(project, this.assetId, this.nodeId);
     const keys = new Set((node.ports ?? []).map((p) => p.key));
     for (const port of this.ports) {
       if (!isValidPortName(port.key)) throw new CommandError(INVALID_NAME);
@@ -101,7 +99,7 @@ export class AddPortsCommand implements Command {
   }
 
   undo(project: Project): void {
-    const node = requirePortNode(project, this.assetId, this.nodeId);
+    const node = requireNode(project, this.assetId, this.nodeId);
     const added = new Set(this.ports.map((p) => p.key));
     node.ports = (node.ports ?? []).filter((p) => !added.has(p.key));
   }
@@ -129,7 +127,7 @@ export class RemovePortCommand implements Command {
   }
 
   execute(project: Project): void {
-    const node = requirePortNode(project, this.assetId, this.nodeId);
+    const node = requireNode(project, this.assetId, this.nodeId);
     const sites = portSites(project, this.assetId, node);
     const ports = [...(node.ports ?? [])];
     const removed = removeFirst(ports, (p) => p.key === this.key);
@@ -152,7 +150,7 @@ export class RemovePortCommand implements Command {
 
   undo(project: Project): void {
     if (!this.removed) return;
-    const node = requirePortNode(project, this.assetId, this.nodeId);
+    const node = requireNode(project, this.assetId, this.nodeId);
     const ports = [...(node.ports ?? [])];
     restoreAt(ports, [this.removed]);
     node.ports = ports;
@@ -187,22 +185,14 @@ export class RenamePortCommand implements Command {
 
   private rename(project: Project, from: string, to: string): void {
     if (from === to) return;
-    const node = requirePortNode(project, this.assetId, this.nodeId);
+    const node = requireNode(project, this.assetId, this.nodeId);
     const sites = portSites(project, this.assetId, node);
     if (!isValidPortName(to)) throw new CommandError(INVALID_NAME);
     const ports = node.ports ?? [];
     if (!ports.some((p) => p.key === from)) throw new CommandError(`Port "${from}" not found`);
     if (ports.some((p) => p.key === to)) throw new CommandError(`"${to}" already exists`);
     node.ports = ports.map((p) => (p.key === from ? { ...p, key: to } : p));
-    for (const site of sites) {
-      for (const edge of site.graph.edges.filter(edgesOnPort(site, from))) {
-        if (site.asInput) edge.to.port = to;
-        else edge.from.port = to;
-      }
-      // An input keeps its typed-in value under the port key, so a rename has to carry it along
-      // or the value silently falls back to the default.
-      if (site.asInput) renameParam(site, from, to);
-    }
+    for (const site of sites) carryPort(site, from, to);
   }
 }
 
@@ -210,17 +200,12 @@ export class RenamePortCommand implements Command {
 function renamePortOn(graph: Graph, node: GraphNode, from: string, to: string): void {
   const ports = node.ports ?? [];
   if (from === to || !ports.some((p) => p.key === from)) return;
-  const site: PortSite = {
-    graph,
-    nodeId: node.id,
-    asInput: requireNodeDef(node.type).declaresPorts === 'inputs',
-  };
   node.ports = ports.map((p) => (p.key === from ? { ...p, key: to } : p));
-  for (const edge of graph.edges.filter(edgesOnPort(site, from))) {
-    if (site.asInput) edge.to.port = to;
-    else edge.from.port = to;
-  }
-  if (site.asInput) renameParam(site, from, to);
+  carryPort(
+    { graph, nodeId: node.id, asInput: requireNodeDef(node.type).declaresPorts === 'inputs' },
+    from,
+    to,
+  );
 }
 
 /**
@@ -242,7 +227,7 @@ export class SetVariablePortCommand implements Command {
   }
 
   execute(project: Project): void {
-    const node = requirePortNode(project, this.assetId, this.nodeId);
+    const node = requireNode(project, this.assetId, this.nodeId);
     const ports = node.ports ?? [];
     const current = ports.find((p) => p.key === this.from);
     if (!current) throw new CommandError(`Port "${this.from}" not found`);
@@ -254,7 +239,7 @@ export class SetVariablePortCommand implements Command {
 
   undo(project: Project): void {
     if (!this.previous) return;
-    this.swap(project, requirePortNode(project, this.assetId, this.nodeId), this.port.key, this.previous);
+    this.swap(project, requireNode(project, this.assetId, this.nodeId), this.port.key, this.previous);
   }
 
   private swap(project: Project, node: GraphNode, from: string, to: DeclaredPort): void {
@@ -273,6 +258,5 @@ export function renameVariablePorts(graph: Graph, from: string, to: string): voi
 
 /** "in1", "in2", … – the first port name the terminal node does not use yet. */
 export function nextPortName(node: GraphNode, base: string): string {
-  const taken = new Set((node.ports ?? []).map((p) => p.key));
-  for (let i = 1; ; i++) if (!taken.has(`${base}${i}`)) return `${base}${i}`;
+  return nextFieldName(node.ports ?? [], base);
 }

src/core/commands/require.ts

@@ -4,7 +4,7 @@ import { type NodeDef, nodeDef } from '../graph/NodeRegistry';
 import type { Asset, BehaviorAsset } from '../model/Asset';
 import { findObject, type ObjectTree } from '../model/hierarchy';
 import { isTemplateContent, objectRef, type ObjectRef } from '../model/instance';
-import { findAsset, findObjectHolder, type ObjectHolder, type Project } from '../model/Project';
+import { findAsset, findAssetOf, findObjectHolder, type ObjectHolder, type Project } from '../model/Project';
 import type { SceneObject } from '../model/SceneObject';
 import { propDef, type PropertyDef } from '../properties/PropertySchema';
 import { CommandError } from './Command';
@@ -51,8 +51,8 @@ export function requireStructural(project: Project, holder: ObjectTree, objectId
 }
 
 export function requireBehavior(project: Project, assetId: string): BehaviorAsset {
-  const asset = findAsset(project, assetId);
-  if (!asset || asset.type !== 'behavior') throw new CommandError(`Behavior ${assetId} not found`);
+  const asset = findAssetOf(project, assetId, 'behavior');
+  if (!asset) throw new CommandError(`Behavior ${assetId} not found`);
   return asset;
 }
 

src/core/commands/sceneObjectCommands.ts

@@ -214,10 +214,6 @@ export class ClearOverrideCommand extends OverrideCommand {
   }
 }
 
-/**
- * Re-parents an object ('' = top level). It keeps its world position: the local one is recomputed
- * for the new parent.
- */
 /**
  * Moves an object among its siblings. Sibling order is the order the stored list happens to have
  * (`treeOrder`), so the move is a splice – and because objects sharing a `z` fall back to that
@@ -262,6 +258,10 @@ export class ReorderObjectCommand implements Command {
   }
 }
 
+/**
+ * Re-parents an object ('' = top level). It keeps its world position: the local one is recomputed
+ * for the new parent.
+ */
 export class SetParentCommand implements Command {
   readonly label = 'Set parent';
   private previous: { parentId: string; position: Position } = {

src/core/commands/variableCommands.ts

@@ -12,7 +12,8 @@ import type { Project } from '../model/Project';
 import {
   coerceValue,
   emptyFieldValue,
-  isCommonProp,
+  isValidFieldName,
+  isValidVariableName,
   type ListItemKind,
   type PrimitiveFieldDef,
   primitiveFieldsOf,
@@ -146,16 +147,6 @@ export class RenameVariableCommand implements Command {
 const INVALID_NAME = 'Variable names must start with a letter and contain only letters, digits or _';
 const INVALID_FIELD = 'Field names must start with a letter and contain only letters, digits or _';
 
-/** Identifier-like, and not a common property key – a variable "enabled" would shadow the switch. */
-export function isValidVariableName(name: string): boolean {
-  return isValidFieldName(name) && !isCommonProp(name);
-}
-
-/** A field lives inside its struct, so the reserved property keys do not apply to it. */
-export function isValidFieldName(name: string): boolean {
-  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name);
-}
-
 /** Where declared fields live: on a struct variable, or on the struct items of a list variable. */
 interface FieldOwner {
   /** True for a list of structs, where a field may not itself be a list (`ListFieldDef`). */
@@ -164,8 +155,12 @@ interface FieldOwner {
   setFields(next: readonly StructFieldDef[]): void;
 }
 
+function variableOf(project: Project, assetId: string, key: string): PropertyDef | undefined {
+  return requireBehavior(project, assetId).variables.find((v) => v.key === key);
+}
+
 function requireFieldOwner(project: Project, assetId: string, key: string): FieldOwner {
-  const def = requireBehavior(project, assetId).variables.find((v) => v.key === key);
+  const def = variableOf(project, assetId, key);
   if (def?.kind === 'struct')
     return {
       inList: false,
@@ -182,10 +177,8 @@ function requireFieldOwner(project: Project, assetId: string, key: string): Fiel
 }
 
 /**
- * Every value of one variable that carries a struct: the declared default, the behavior's own, and
- * each instance override – and for a list of structs, every item of each of those. A field is added
- * to or taken from all of them at once, so no value keeps a shape its declaration no longer
- * promises. The `id` is what pairs a site up again when the change is undone.
+ * One struct-carrying value of a variable (default, own, override, or list item); a field change hits
+ * all of them at once so none keeps a stale shape. `id` pairs a site up again on undo.
  */
 interface StructSite {
   id: string;
@@ -194,7 +187,7 @@ interface StructSite {
 }
 
 function structSites(project: Project, assetId: string, key: string): StructSite[] {
-  const def = requireBehavior(project, assetId).variables.find((v) => v.key === key);
+  const def = variableOf(project, assetId, key);
   const holders = valueHolders(project, assetId, key).filter(
     // An override the object does not have stays absent: writing one here would invent a deviation.
     (h) => !h.optional || (def?.kind === 'list' ? isList(h.read()) : isStruct(h.read())),
@@ -440,7 +433,7 @@ function requireListDef(
   assetId: string,
   key: string,
 ): Extract<PropertyDef, { kind: 'list' }> {
-  const def = requireBehavior(project, assetId).variables.find((v) => v.key === key);
+  const def = variableOf(project, assetId, key);
   if (def?.kind !== 'list') throw new CommandError(`Variable "${key}" is not a list`);
   return def;
 }