@field/cascade 0.10.0 → 0.11.0

package/dist/cli/Graph-ZJJTRQTM.js

@@ -0,0 +1,2975 @@
+import {
+  loadEmbeddedModule,
+  loadProjectModule
+} from "./chunk-2KXB47FP.js";
+import {
+  moduleNodeFunction
+} from "./chunk-RLCAJBVR.js";
+import "./chunk-53NMBJAO.js";
+import "./chunk-SGJAET2L.js";
+import {
+  Node,
+  canConnect,
+  getNodeClass,
+  getNodeDisplayName,
+  isColorValue,
+  isStandardLibraryNode,
+  normalizeColor,
+  normalizeType,
+  packagePathToType
+} from "./chunk-FCDXJ6EK.js";
+import "./chunk-RUU3YWXU.js";
+import {
+  bundleSchemasCompatible,
+  unknownFieldMessage
+} from "./chunk-GFS6W3C5.js";
+import "./chunk-HFHWYL55.js";
+import {
+  parseBundleFieldPath,
+  remoteBundlePath
+} from "./chunk-CO22XHNG.js";
+import "./chunk-A4OAMOZH.js";
+import "./chunk-J7VK7MNF.js";
+import "./chunk-BIJO5OFS.js";
+
+// src/nodes/annotations/Annotation.ts
+var Annotation = class extends Node {
+  constructor(id, type, graph) {
+    super(id, type, graph);
+    // Marker property for reliable type checking (survives HMR and serialization)
+    this.isAnnotation = true;
+  }
+  /**
+   * Annotations always have exactly one output at index 0
+   */
+  getOutput() {
+    return this.getOutputPort(0);
+  }
+  /**
+   * Annotations don't execute - override to no-op
+   */
+  async execute() {
+  }
+};
+
+// src/nodes/annotations/Image.ts
+var ImageAnnotation = class extends Annotation {
+  constructor(id, graph) {
+    super(id, "Image", graph);
+  }
+};
+
+// src/nodes/annotations/Text.ts
+var TextAnnotation = class extends Annotation {
+  constructor(id, graph) {
+    super(id, "Text", graph);
+  }
+};
+
+// src/nodes/annotations/Group.ts
+var GroupAnnotation = class extends Annotation {
+  constructor(id, graph) {
+    super(id, "Group", graph);
+  }
+};
+
+// src/nodes/annotations/Line.ts
+var LineAnnotation = class extends Annotation {
+  constructor(id, graph) {
+    super(id, "Line", graph);
+  }
+};
+
+// src/nodes/annotations/Polyline.ts
+var PolylineAnnotation = class extends Annotation {
+  constructor(id, graph) {
+    super(id, "Polyline", graph);
+  }
+};
+
+// src/engine/AssetManager.ts
+var BrowserAssetLoader = class {
+  async loadImage(path) {
+    return new Promise((resolve, reject) => {
+      if (typeof Image === "undefined") {
+        reject(new Error("Image API not available (not in browser environment)"));
+        return;
+      }
+      const img = new Image();
+      img.onload = () => resolve(img);
+      img.onerror = () => reject(new Error(`Failed to load image: ${path}`));
+      img.src = path;
+    });
+  }
+  async loadJSON(path) {
+    if (typeof fetch === "undefined") {
+      throw new Error("fetch API not available (not in browser environment)");
+    }
+    const response = await fetch(path);
+    if (!response.ok) {
+      throw new Error(`Failed to load JSON: ${path} - ${response.statusText}`);
+    }
+    return response.json();
+  }
+  async loadText(path) {
+    if (typeof fetch === "undefined") {
+      throw new Error("fetch API not available (not in browser environment)");
+    }
+    const response = await fetch(path);
+    if (!response.ok) {
+      throw new Error(`Failed to load text: ${path} - ${response.statusText}`);
+    }
+    return response.text();
+  }
+  async loadBinary(path) {
+    if (typeof fetch === "undefined") {
+      throw new Error("fetch API not available (not in browser environment)");
+    }
+    const response = await fetch(path);
+    if (!response.ok) {
+      throw new Error(`Failed to load binary: ${path} - ${response.statusText}`);
+    }
+    return response.arrayBuffer();
+  }
+};
+var AssetManager = class {
+  constructor(projectRoot = "", loader) {
+    this.cache = /* @__PURE__ */ new Map();
+    this.projectRoot = projectRoot;
+    this.loader = loader ?? new BrowserAssetLoader();
+  }
+  async load(path) {
+    if (this.cache.has(path)) {
+      return this.cache.get(path);
+    }
+    const absolutePath = this.resolve(path);
+    const type = this.getAssetType(path);
+    let data;
+    switch (type) {
+      case "image":
+        data = await this.loader.loadImage(absolutePath);
+        break;
+      case "json":
+        data = await this.loader.loadJSON(absolutePath);
+        break;
+      case "text":
+        data = await this.loader.loadText(absolutePath);
+        break;
+      default:
+        throw new Error(`Unsupported asset type: ${type}`);
+    }
+    const asset = {
+      id: this.generateId(path),
+      path,
+      type,
+      data,
+      size: 0,
+      metadata: {}
+    };
+    this.cache.set(path, asset);
+    return asset;
+  }
+  resolve(path) {
+    if (path.startsWith("http://") || path.startsWith("https://")) {
+      return path;
+    }
+    if (path.startsWith("/")) {
+      return path;
+    }
+    return `${this.projectRoot}${path}`;
+  }
+  getAssetType(path) {
+    const ext = path.split(".").pop()?.toLowerCase();
+    if (["jpg", "jpeg", "png", "gif", "webp", "svg"].includes(ext || "")) return "image";
+    if (["mp3", "wav", "ogg", "m4a"].includes(ext || "")) return "audio";
+    if (["mp4", "webm", "mov"].includes(ext || "")) return "video";
+    if (ext === "json") return "json";
+    if (["txt", "md", "csv"].includes(ext || "")) return "text";
+    return "binary";
+  }
+  generateId(path) {
+    return path.replace(/[^a-zA-Z0-9]/g, "_");
+  }
+  getAsset(path) {
+    return this.cache.get(path);
+  }
+  clearCache() {
+    this.cache.clear();
+  }
+  removeAsset(path) {
+    this.cache.delete(path);
+  }
+  /**
+   * Reload an asset from its path (useful for hot reload)
+   */
+  async reloadAsset(path) {
+    this.cache.delete(path);
+    return this.load(path);
+  }
+  /**
+   * Reload all cached assets (useful for hot reload)
+   */
+  async reloadAll() {
+    const paths = Array.from(this.cache.keys());
+    this.cache.clear();
+    await Promise.all(paths.map((path) => this.load(path).catch((err) => {
+      console.warn(`Failed to reload asset ${path}:`, err);
+    })));
+  }
+  list() {
+    return Array.from(this.cache.values());
+  }
+};
+
+// src/engine/PackageManager.ts
+var PackageManager = class {
+  constructor() {
+    this.cache = /* @__PURE__ */ new Map();
+    this.loadingPromises = /* @__PURE__ */ new Map();
+    this.cdnBaseUrl = "https://esm.sh";
+  }
+  /**
+   * Load an NPM package from CDN
+   * @param packageName Package name (e.g., 'three', 'lodash', '@tensorflow/tfjs')
+   * @param version Optional version (defaults to 'latest')
+   * @returns The loaded module
+   */
+  async load(packageName, version = "latest") {
+    const key = `${packageName}@${version}`;
+    if (this.cache.has(key)) {
+      return this.cache.get(key);
+    }
+    if (this.loadingPromises.has(key)) {
+      return this.loadingPromises.get(key);
+    }
+    const loadPromise = this.loadPackage(key, packageName, version);
+    this.loadingPromises.set(key, loadPromise);
+    try {
+      const module = await loadPromise;
+      this.cache.set(key, module);
+      return module;
+    } catch (error) {
+      this.loadingPromises.delete(key);
+      throw error;
+    }
+  }
+  async loadPackage(key, packageName, version) {
+    const versionPart = version === "latest" ? "" : `@${version}`;
+    const url = `${this.cdnBaseUrl}/${packageName}${versionPart}`;
+    try {
+      const module = await import(
+        /* @vite-ignore */
+        url
+      );
+      if (module.default && typeof module.default === "object") {
+        return module.default;
+      }
+      if (module.default !== void 0) {
+        return module.default;
+      }
+      return module;
+    } catch (error) {
+      throw new Error(
+        `Failed to load package ${key}: ${error.message || "Unknown error"}
+URL: ${url}`
+      );
+    }
+  }
+  /**
+   * Search for packages in the NPM registry
+   * @param query Search query
+   * @param limit Maximum number of results (default: 20)
+   * @returns Array of package search results
+   */
+  async search(query, limit = 20) {
+    try {
+      const url = `https://registry.npmjs.org/-/v1/search?text=${encodeURIComponent(query)}&size=${limit}`;
+      const response = await fetch(url, {
+        method: "GET",
+        headers: {
+          "Accept": "application/json"
+        }
+      });
+      if (!response.ok) {
+        if (response.status === 0 || response.status === 403 || response.status === 404) {
+          console.warn("NPM registry search may be blocked by CORS. Using fallback.");
+          return [];
+        }
+        throw new Error(`Search failed: ${response.statusText}`);
+      }
+      const data = await response.json();
+      return data.objects?.map((result) => ({
+        name: result.package.name,
+        version: result.package.version,
+        description: result.package.description,
+        keywords: result.package.keywords || [],
+        author: result.package.author,
+        homepage: result.package.links?.homepage,
+        repository: result.package.links?.repository ? { url: result.package.links.repository } : void 0
+      })) || [];
+    } catch (error) {
+      if (error.message?.includes("CORS") || error.message?.includes("Failed to fetch")) {
+        console.warn("NPM registry search unavailable:", error.message);
+        return [];
+      }
+      throw new Error(`Failed to search packages: ${error.message || "Unknown error"}`);
+    }
+  }
+  /**
+   * Get package information from NPM registry
+   * @param packageName Package name
+   * @returns Package metadata
+   */
+  async getPackageInfo(packageName) {
+    try {
+      const url = `https://registry.npmjs.org/${encodeURIComponent(packageName)}`;
+      const response = await fetch(url);
+      if (!response.ok) {
+        if (response.status === 404) {
+          return null;
+        }
+        throw new Error(`Failed to fetch package info: ${response.statusText}`);
+      }
+      const data = await response.json();
+      const latestVersion = data["dist-tags"]?.latest || Object.keys(data.versions).pop();
+      const versionData = data.versions[latestVersion];
+      return {
+        name: data.name,
+        version: latestVersion,
+        description: versionData.description,
+        keywords: versionData.keywords || [],
+        author: versionData.author,
+        homepage: data.homepage || versionData.homepage,
+        repository: versionData.repository
+      };
+    } catch (error) {
+      throw new Error(`Failed to get package info: ${error.message || "Unknown error"}`);
+    }
+  }
+  /**
+   * Clear the package cache
+   */
+  clearCache() {
+    this.cache.clear();
+    this.loadingPromises.clear();
+  }
+  /**
+   * Remove a specific package from cache
+   */
+  removeFromCache(packageName, version) {
+    if (version) {
+      const key = `${packageName}@${version}`;
+      this.cache.delete(key);
+      this.loadingPromises.delete(key);
+    } else {
+      for (const key of this.cache.keys()) {
+        if (key.startsWith(`${packageName}@`)) {
+          this.cache.delete(key);
+          this.loadingPromises.delete(key);
+        }
+      }
+    }
+  }
+  /**
+   * Get list of cached packages
+   */
+  getCachedPackages() {
+    return Array.from(this.cache.keys());
+  }
+};
+
+// src/engine/ModuleResolver.ts
+var ModuleResolver = class {
+  constructor(config) {
+    this.config = config;
+  }
+  /**
+   * Set file system functions for reading external files
+   * These are injected to allow different implementations (browser vs Node.js)
+   */
+  setFileSystemFunctions(readFn, existsFn) {
+    this.fileReadFn = readFn;
+    this.fileExistsFn = existsFn;
+  }
+  /**
+   * Resolve a module path to its source code and metadata
+   */
+  async resolve(modulePath) {
+    if (modulePath.startsWith("cascade.")) {
+      return this.resolveStdlib(modulePath);
+    }
+    if (modulePath.startsWith("local.")) {
+      return this.resolveEmbedded(modulePath);
+    }
+    for (const pkg of this.config.projectPackages) {
+      if (modulePath.startsWith(`${pkg.alias}.`)) {
+        return this.resolveProject(modulePath, pkg);
+      }
+    }
+    if (this.config.embeddedModules.has(modulePath)) {
+      return this.resolveEmbedded(modulePath);
+    }
+    return null;
+  }
+  /**
+   * Resolve a standard library module
+   * Class-based stdlib nodes don't have editable code
+   */
+  resolveStdlib(modulePath) {
+    const NodeClass = getNodeClass(modulePath);
+    if (!NodeClass) {
+      return null;
+    }
+    const source = {
+      type: "stdlib",
+      module: modulePath
+    };
+    const parts = modulePath.split(".");
+    const displayPath = `<cascade>/${parts.slice(1).join("/")}.ts`;
+    return {
+      source,
+      code: "",
+      // Class-based nodes don't have editable code
+      displayPath,
+      editable: false
+    };
+  }
+  /**
+   * Resolve an embedded module
+   */
+  resolveEmbedded(modulePath) {
+    const embedded = this.config.embeddedModules.get(modulePath);
+    if (!embedded) {
+      return null;
+    }
+    const source = {
+      type: "embedded",
+      module: modulePath,
+      code: embedded.code,
+      history: embedded.history || []
+    };
+    return {
+      source,
+      code: embedded.code,
+      displayPath: "<embedded>",
+      editable: true
+    };
+  }
+  /**
+   * Resolve a project module from an external file
+   */
+  async resolveProject(modulePath, pkg) {
+    const relativeParts = modulePath.replace(`${pkg.alias}.`, "").split(".");
+    const filePath = `${pkg.path}/${relativeParts.join("/")}.ts`;
+    const external = this.config.externalModules.get(modulePath);
+    let code = null;
+    let status = "synced";
+    if (this.fileReadFn && this.fileExistsFn) {
+      const fullPath = this.resolvePath(filePath);
+      const exists = await this.fileExistsFn(fullPath);
+      if (exists) {
+        code = await this.fileReadFn(fullPath);
+        if (code !== null) {
+          if (external && external.cachedCode !== code) {
+            status = "modified-external";
+          }
+        }
+      } else {
+        status = "missing";
+        code = external?.cachedCode || null;
+      }
+    } else if (external) {
+      code = external.cachedCode;
+    }
+    if (code === null) {
+      return null;
+    }
+    const source = {
+      type: "project",
+      module: modulePath,
+      file: filePath,
+      cachedCode: code,
+      lastSync: (/* @__PURE__ */ new Date()).toISOString(),
+      status
+    };
+    return {
+      source,
+      code,
+      displayPath: filePath,
+      editable: true
+    };
+  }
+  /**
+   * Resolve a relative path to an absolute path
+   */
+  resolvePath(relativePath) {
+    if (!this.config.basePath) {
+      return relativePath;
+    }
+    if (relativePath.startsWith("./")) {
+      return `${this.config.basePath}/${relativePath.slice(2)}`;
+    }
+    if (relativePath.startsWith("/")) {
+      return relativePath;
+    }
+    return `${this.config.basePath}/${relativePath}`;
+  }
+  /**
+   * Determine the source type for a given module path
+   */
+  getSourceType(modulePath) {
+    if (modulePath.startsWith("cascade.")) {
+      return "stdlib";
+    }
+    if (modulePath.startsWith("local.")) {
+      return "embedded";
+    }
+    for (const pkg of this.config.projectPackages) {
+      if (modulePath.startsWith(`${pkg.alias}.`)) {
+        return "project";
+      }
+    }
+    if (this.config.embeddedModules.has(modulePath)) {
+      return "embedded";
+    }
+    return null;
+  }
+  /**
+   * Create a new embedded module with the given code
+   * Use this when creating custom nodes from scratch
+   */
+  createEmbeddedModule(modulePath, code, author = "user") {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const initialVersion = {
+      code,
+      timestamp: now,
+      author
+    };
+    const module = {
+      code,
+      history: [initialVersion],
+      created: now,
+      modified: now
+    };
+    this.config.embeddedModules.set(modulePath, module);
+    return { modulePath, module };
+  }
+  /**
+   * Create a new embedded module from stdlib (duplicate)
+   */
+  duplicateToEmbedded(stdlibPath, newName) {
+    const resolution = this.resolveStdlib(stdlibPath);
+    if (!resolution) {
+      return null;
+    }
+    const typeName = stdlibPath.split(".").pop() || "Custom";
+    const baseName = newName || typeName;
+    let modulePath = `local.${baseName}`;
+    let counter = 1;
+    while (this.config.embeddedModules.has(modulePath)) {
+      modulePath = `local.${baseName}${counter}`;
+      counter++;
+    }
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const initialVersion = {
+      code: resolution.code,
+      timestamp: now,
+      author: "user"
+    };
+    const module = {
+      code: resolution.code,
+      history: [initialVersion],
+      created: now,
+      modified: now
+    };
+    this.config.embeddedModules.set(modulePath, module);
+    return { modulePath, module };
+  }
+  /**
+   * Create an external file from an embedded module (extract)
+   */
+  async extractToProject(embeddedPath, pkg, fileName) {
+    const embedded = this.config.embeddedModules.get(embeddedPath);
+    if (!embedded) {
+      return null;
+    }
+    const filePath = `${pkg.path}/${fileName}.ts`;
+    const modulePath = `${pkg.alias}.${fileName.replace(/\//g, ".")}`;
+    const external = {
+      file: filePath,
+      cachedCode: embedded.code,
+      lastSync: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    this.config.externalModules.set(modulePath, external);
+    return { modulePath, filePath };
+  }
+  /**
+   * Update embedded module code and record in history
+   */
+  updateEmbeddedCode(modulePath, newCode, author = "user", prompt) {
+    const embedded = this.config.embeddedModules.get(modulePath);
+    if (!embedded) {
+      return false;
+    }
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const version = {
+      code: newCode,
+      timestamp: now,
+      author,
+      prompt
+    };
+    embedded.history.push(version);
+    embedded.code = newCode;
+    embedded.modified = now;
+    return true;
+  }
+  /**
+   * Restore embedded module to a previous version
+   */
+  restoreVersion(modulePath, versionIndex) {
+    const embedded = this.config.embeddedModules.get(modulePath);
+    if (!embedded || versionIndex < 0 || versionIndex >= embedded.history.length) {
+      return false;
+    }
+    const version = embedded.history[versionIndex];
+    embedded.code = version.code;
+    embedded.modified = (/* @__PURE__ */ new Date()).toISOString();
+    embedded.history.push({
+      code: version.code,
+      timestamp: embedded.modified,
+      author: "user"
+    });
+    return true;
+  }
+  /**
+   * Get all registered project packages
+   */
+  getProjectPackages() {
+    return [...this.config.projectPackages];
+  }
+  /**
+   * Add a project package
+   */
+  addProjectPackage(pkg) {
+    const existing = this.config.projectPackages.find((p) => p.alias === pkg.alias);
+    if (existing) {
+      existing.path = pkg.path;
+    } else {
+      this.config.projectPackages.push(pkg);
+    }
+  }
+  /**
+   * Remove a project package
+   */
+  removeProjectPackage(alias) {
+    const index = this.config.projectPackages.findIndex((p) => p.alias === alias);
+    if (index >= 0) {
+      this.config.projectPackages.splice(index, 1);
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Sync an external module with its file
+   */
+  async syncExternalModule(modulePath) {
+    const external = this.config.externalModules.get(modulePath);
+    if (!external || !this.fileReadFn || !this.fileExistsFn) {
+      return "missing";
+    }
+    const fullPath = this.resolvePath(external.file);
+    const exists = await this.fileExistsFn(fullPath);
+    if (!exists) {
+      return "missing";
+    }
+    const code = await this.fileReadFn(fullPath);
+    if (code === null) {
+      return "missing";
+    }
+    external.cachedCode = code;
+    external.lastSync = (/* @__PURE__ */ new Date()).toISOString();
+    return "synced";
+  }
+  /**
+   * Export configuration for serialization
+   */
+  exportConfig() {
+    return {
+      projectPackages: [...this.config.projectPackages],
+      embeddedModules: Object.fromEntries(this.config.embeddedModules),
+      externalModules: Object.fromEntries(this.config.externalModules)
+    };
+  }
+  /**
+   * Import configuration from deserialization
+   */
+  importConfig(config) {
+    if (config.projectPackages) {
+      this.config.projectPackages = [...config.projectPackages];
+    }
+    if (config.embeddedModules) {
+      this.config.embeddedModules = new Map(Object.entries(config.embeddedModules));
+    }
+    if (config.externalModules) {
+      this.config.externalModules = new Map(Object.entries(config.externalModules));
+    }
+  }
+};
+function createModuleResolver(basePath) {
+  return new ModuleResolver({
+    projectPackages: [],
+    embeddedModules: /* @__PURE__ */ new Map(),
+    externalModules: /* @__PURE__ */ new Map(),
+    basePath
+  });
+}
+
+// src/engine/GraphValidator.ts
+var GraphValidator = class {
+  /**
+   * Detect cycles in the graph using DFS
+   * Returns array of node IDs involved in cycles
+   */
+  static detectCycles(graph) {
+    const cycles = [];
+    const visited = /* @__PURE__ */ new Set();
+    const recStack = /* @__PURE__ */ new Set();
+    const path = [];
+    const dfs = (nodeId) => {
+      if (recStack.has(nodeId)) {
+        const cycleStart = path.indexOf(nodeId);
+        if (cycleStart !== -1) {
+          cycles.push([...path.slice(cycleStart), nodeId]);
+        }
+        return true;
+      }
+      if (visited.has(nodeId)) {
+        return false;
+      }
+      visited.add(nodeId);
+      recStack.add(nodeId);
+      path.push(nodeId);
+      const node = graph.getNode(nodeId);
+      if (node) {
+        for (const output of node.outputs) {
+          for (const conn of output.connections) {
+            dfs(conn.to.nodeId);
+          }
+        }
+      }
+      recStack.delete(nodeId);
+      path.pop();
+      return false;
+    };
+    const nodes = graph.nodes;
+    for (const node of nodes) {
+      if (!visited.has(node.id)) {
+        dfs(node.id);
+      }
+    }
+    return cycles;
+  }
+  /**
+   * Check if adding a connection would create a cycle
+   */
+  static wouldCreateCycle(graph, fromNodeId, toNodeId) {
+    if (fromNodeId === toNodeId) {
+      return true;
+    }
+    const visited = /* @__PURE__ */ new Set();
+    const hasPath = (startId, targetId) => {
+      if (startId === targetId) return true;
+      if (visited.has(startId)) return false;
+      visited.add(startId);
+      const node = graph.getNode(startId);
+      if (!node) return false;
+      for (const output of node.outputs) {
+        for (const conn of output.connections) {
+          if (hasPath(conn.to.nodeId, targetId)) {
+            return true;
+          }
+        }
+      }
+      return false;
+    };
+    return hasPath(toNodeId, fromNodeId);
+  }
+  /**
+   * Perform topological sort of nodes
+   * Returns sorted node IDs, or throws if cycles exist
+   */
+  static topologicalSort(graph) {
+    const cycles = this.detectCycles(graph);
+    if (cycles.length > 0) {
+      throw new Error(
+        `Graph contains cycles: ${cycles.map((c) => c.join(" -> ")).join(", ")}`
+      );
+    }
+    const sorted = [];
+    const visited = /* @__PURE__ */ new Set();
+    const tempMark = /* @__PURE__ */ new Set();
+    const visit = (nodeId) => {
+      if (tempMark.has(nodeId)) {
+        throw new Error(`Cycle detected involving node ${nodeId}`);
+      }
+      if (visited.has(nodeId)) {
+        return;
+      }
+      tempMark.add(nodeId);
+      const node = graph.getNode(nodeId);
+      if (node) {
+        for (const input of node.inputs) {
+          for (const conn of input.connections) {
+            visit(conn.from.nodeId);
+          }
+        }
+      }
+      tempMark.delete(nodeId);
+      visited.add(nodeId);
+      sorted.push(nodeId);
+    };
+    const nodes = graph.nodes;
+    for (const node of nodes) {
+      if (!visited.has(node.id)) {
+        visit(node.id);
+      }
+    }
+    return sorted;
+  }
+  /**
+   * Validate a connection before it's added
+   */
+  static validateConnection(graph, fromNodeId, toNodeId, fromPortId, toPortId) {
+    const fromNode = graph.getNode(fromNodeId);
+    const toNode = graph.getNode(toNodeId);
+    if (!fromNode || !toNode) {
+      return {
+        type: "invalid_connection",
+        message: `Invalid connection: node not found`,
+        nodeIds: [fromNodeId, toNodeId]
+      };
+    }
+    const fromPort = fromNode.outputs.find((p) => p.id === fromPortId);
+    const toPort = toNode.inputs.find((p) => p.id === toPortId);
+    if (!fromPort || !toPort) {
+      return {
+        type: "invalid_connection",
+        message: `Invalid connection: port not found`,
+        nodeIds: [fromNodeId, toNodeId]
+      };
+    }
+    if (fromPort.portType !== toPort.portType) {
+      return {
+        type: "invalid_connection",
+        message: `Port type mismatch: cannot connect ${fromPort.portType} to ${toPort.portType}`,
+        nodeIds: [fromNodeId, toNodeId]
+      };
+    }
+    if (this.wouldCreateCycle(graph, fromNodeId, toNodeId)) {
+      return {
+        type: "cycle",
+        message: `Connection would create a cycle: ${fromNodeId} -> ${toNodeId}`,
+        nodeIds: [fromNodeId, toNodeId]
+      };
+    }
+    return null;
+  }
+  /**
+   * Validate the entire graph
+   */
+  static validateGraph(graph) {
+    const errors = [];
+    const warnings = [];
+    const cycles = this.detectCycles(graph);
+    if (cycles.length > 0) {
+      cycles.forEach((cycle) => {
+        errors.push({
+          type: "cycle",
+          message: `Cycle detected: ${cycle.join(" -> ")}`,
+          nodeIds: cycle
+        });
+      });
+    }
+    for (const conn of graph.connections) {
+      const fromNode = graph.getNode(conn.from.nodeId);
+      const toNode = graph.getNode(conn.to.nodeId);
+      if (!fromNode || !toNode) {
+        errors.push({
+          type: "invalid_connection",
+          message: `Connection references non-existent node`,
+          connectionId: conn.id,
+          nodeIds: [conn.from.nodeId, conn.to.nodeId]
+        });
+        continue;
+      }
+      const fromPort = fromNode.outputs.find((p) => p.id === conn.from.portId);
+      const toPort = toNode.inputs.find((p) => p.id === conn.to.portId);
+      if (!fromPort || !toPort) {
+        errors.push({
+          type: "invalid_connection",
+          message: `Connection references non-existent port`,
+          connectionId: conn.id,
+          nodeIds: [conn.from.nodeId, conn.to.nodeId]
+        });
+        continue;
+      }
+      if (fromPort.portType !== toPort.portType) {
+        errors.push({
+          type: "invalid_connection",
+          message: `Port type mismatch in connection`,
+          connectionId: conn.id,
+          nodeIds: [conn.from.nodeId, conn.to.nodeId]
+        });
+      }
+    }
+    const connectedNodes = /* @__PURE__ */ new Set();
+    for (const conn of graph.connections) {
+      connectedNodes.add(conn.from.nodeId);
+      connectedNodes.add(conn.to.nodeId);
+    }
+    const nodes = graph.nodes;
+    const orphanedNodes = nodes.filter((n) => {
+      const hasNoConnections = !connectedNodes.has(n.id);
+      const isEntryPoint = n.inputs.every((p) => p.connections.length === 0);
+      return hasNoConnections && !isEntryPoint;
+    });
+    if (orphanedNodes.length > 0) {
+      warnings.push({
+        type: "orphaned_node",
+        message: `Found ${orphanedNodes.length} orphaned node(s) with no connections`,
+        nodeIds: orphanedNodes.map((n) => n.id)
+      });
+    }
+    const entryPoints = nodes.filter(
+      (node) => node.inputs.every((p) => p.connections.length === 0)
+    );
+    if (entryPoints.length === 0 && nodes.length > 0) {
+      warnings.push({
+        type: "invalid_entry_point",
+        message: "No entry points found (all nodes have input connections)"
+      });
+    }
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings
+    };
+  }
+};
+
+// src/nodes/CookScheduler.ts
+var COOK_SIGNAL_KEY = "__cascadeCookSignal";
+var CookScheduler = class {
+  constructor(graph, debounceMs = 50) {
+    this.graph = graph;
+    this.debounceMs = debounceMs;
+    this.timer = null;
+    this.activeRun = null;
+    this.rerunRequested = false;
+    this.listeners = /* @__PURE__ */ new Set();
+    this.idleResolvers = /* @__PURE__ */ new Set();
+    this.backgroundAbort = null;
+    /** Set when something is invalidated while a run is active: the pass in
+     *  progress stops after the node it is on, so the edit is cooked next rather
+     *  than after everything that happened to be queued before it. */
+    this.invalidatedDuringRun = false;
+    /** Nodes on display, by id, counted because two Viewers can show one node. */
+    this.watched = /* @__PURE__ */ new Map();
+    this._status = {
+      phase: "idle",
+      pass: 0,
+      superseded: 0,
+      total: 0,
+      completed: 0,
+      currentNode: null,
+      startedAt: null,
+      elapsed: 0
+    };
+  }
+  get status() {
+    return this._status;
+  }
+  get isRunning() {
+    return this.activeRun !== null;
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    listener(this._status);
+    return () => this.listeners.delete(listener);
+  }
+  /**
+   * Declare that a node is on display, so it and everything it depends on cook
+   * before anything else in a pass. Returns the release.
+   *
+   * Viewer-first order: a pass used to run strictly in topological order, so a
+   * sink nobody was looking at (an export, a plot plan) could sit in front of
+   * the node on screen. With a node watched, its upstream closure goes first
+   * and the unwatched remainder runs after it in the same pass, still in
+   * topological order. The closure is upstream-closed, so the order stays
+   * valid. With nothing watched — the CLI, a test, cook-all — nothing changes.
+   */
+  watch(node) {
+    const id = node.id;
+    this.watched.set(id, (this.watched.get(id) ?? 0) + 1);
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      const count = (this.watched.get(id) ?? 1) - 1;
+      if (count <= 0) this.watched.delete(id);
+      else this.watched.set(id, count);
+    };
+  }
+  /** The ids of nodes currently on display. */
+  get watchedNodeIds() {
+    return new Set(this.watched.keys());
+  }
+  /** @internal Called by Node whenever its sole cook state changes. */
+  notifyNodeStateChange() {
+    this.emit();
+  }
+  markStale(node, origin = "self") {
+    if (origin === "self") node.markSelfDirty();
+    const visited = /* @__PURE__ */ new Set();
+    const visit = (candidate) => {
+      if (visited.has(candidate.id)) return;
+      visited.add(candidate.id);
+      if (candidate.cookState !== "stale") candidate.invalidateCook();
+      for (const output of candidate.outputs) {
+        for (const connection of output.connections) {
+          const downstream = this.graph.getNode(connection.to.nodeId);
+          if (downstream) visit(downstream);
+        }
+      }
+    };
+    visit(node);
+    if (this.activeRun) this.invalidatedDuringRun = true;
+    if (this.graph.getNode(node.id) === node) this.schedule();
+  }
+  markDownstreamStale(node) {
+    for (const output of node.outputs) {
+      for (const connection of output.connections) {
+        const downstream = this.graph.getNode(connection.to.nodeId);
+        if (downstream) this.markStale(downstream, "upstream");
+      }
+    }
+  }
+  schedule() {
+    this.preemptBackground("interactive work arrived");
+    if (this.activeRun) {
+      this.rerunRequested = true;
+      return;
+    }
+    if (this.timer) clearTimeout(this.timer);
+    const total = this.graph.nodes.filter((node) => node.cookState === "stale" || node.cookState === "queued").length;
+    this.setStatus({ phase: "scheduled", total, completed: 0, currentNode: null, pass: 0, superseded: 0, startedAt: null, elapsed: 0 });
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      void this.flushScheduled();
+    }, this.debounceMs);
+  }
+  async flush(entryNode) {
+    await this.flushInternal(entryNode, true);
+  }
+  async flushScheduled() {
+    await this.flushInternal(void 0, false);
+  }
+  async flushInternal(entryNode, retryErrors) {
+    this.preemptBackground("interactive work arrived");
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    if (retryErrors) this.prepareErrorRetry(entryNode);
+    if (this.activeRun) {
+      this.rerunRequested = true;
+      await this.activeRun;
+      return;
+    }
+    this.activeRun = this.run(entryNode).finally(() => {
+      this.activeRun = null;
+    });
+    await this.activeRun;
+  }
+  /** Explicit execution retries failed nodes once; debounced invalidation does not. */
+  prepareErrorRetry(entryNode) {
+    const allowed = entryNode ? this.collectDownstream(entryNode) : null;
+    for (const node of this.graph.nodes) {
+      if (node.cookState === "error" && (!allowed || allowed.has(node.id))) {
+        node.invalidateCook();
+      }
+    }
+  }
+  async whenIdle() {
+    if (!this.activeRun && !this.timer) return;
+    await new Promise((resolve) => this.idleResolvers.add(resolve));
+  }
+  dispose() {
+    this.preemptBackground("the graph went away");
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = null;
+    this.listeners.clear();
+    for (const resolve of this.idleResolvers) resolve();
+    this.idleResolvers.clear();
+  }
+  async run(entryNode) {
+    let restrictTo = entryNode ? this.collectDownstream(entryNode) : null;
+    let pass = 0;
+    let supersededCount = 0;
+    let cutOffCount = 0;
+    do {
+      this.rerunRequested = false;
+      this.invalidatedDuringRun = false;
+      const stale = this.graph.nodes.filter(
+        (node) => (node.cookState === "stale" || node.cookState === "queued") && (!restrictTo || restrictTo.has(node.id))
+      );
+      restrictTo = null;
+      if (stale.length === 0) break;
+      const staleIds = new Set(stale.map((node) => node.id));
+      const ordered = this.graph.getTopologicalOrder().map((id) => this.graph.getNode(id)).filter((node) => !!node && staleIds.has(node.id));
+      const orderedIds = new Set(ordered.map((node) => node.id));
+      for (const node of stale) if (!orderedIds.has(node.id)) ordered.push(node);
+      this.viewerFirst(ordered);
+      for (const node of ordered) node.setCookState("queued");
+      const startedAt = performance.now();
+      pass += 1;
+      this.setStatus({
+        phase: "cooking",
+        total: ordered.length,
+        completed: 0,
+        currentNode: null,
+        pass,
+        superseded: supersededCount,
+        startedAt,
+        elapsed: 0
+      });
+      const blocked = /* @__PURE__ */ new Set();
+      const notReady = this.graph.pendingConnectionTargets();
+      let superseded = false;
+      for (const node of ordered) {
+        if (notReady.has(node.id)) {
+          node.setCookState("stale");
+          blocked.add(node.id);
+          this.setStatus({
+            ...this._status,
+            completed: this._status.completed + 1,
+            currentNode: null,
+            elapsed: performance.now() - startedAt
+          });
+          continue;
+        }
+        const upstreamBlocked = node.inputs.some((input) => input.connections.some(
+          (connection) => staleIds.has(connection.from.nodeId) && (blocked.has(connection.from.nodeId) || this.graph.getNode(connection.from.nodeId)?.cookState === "error")
+        ));
+        if (upstreamBlocked) {
+          node.setCookState("stale");
+          blocked.add(node.id);
+          this.setStatus({
+            ...this._status,
+            completed: this._status.completed + 1,
+            currentNode: null,
+            elapsed: performance.now() - startedAt
+          });
+          continue;
+        }
+        if (node.canSkipCook()) {
+          node.skipCook();
+          cutOffCount += 1;
+          this.setStatus({
+            ...this._status,
+            completed: this._status.completed + 1,
+            currentNode: null,
+            cutOff: cutOffCount,
+            elapsed: performance.now() - startedAt
+          });
+          continue;
+        }
+        node.setCookState("cooking");
+        this.setStatus({ ...this._status, currentNode: node, elapsed: performance.now() - startedAt });
+        await this.executeInteractive(node);
+        if (node.cookState === "error") blocked.add(node.id);
+        if (node.cookState === "stale") {
+          blocked.add(node.id);
+          superseded = true;
+          supersededCount += 1;
+        }
+        this.setStatus({
+          ...this._status,
+          completed: this._status.completed + 1,
+          currentNode: null,
+          superseded: supersededCount,
+          elapsed: performance.now() - startedAt
+        });
+        if (this.invalidatedDuringRun) {
+          this.rerunRequested = true;
+          break;
+        }
+      }
+      if (superseded) this.rerunRequested = true;
+    } while (this.rerunRequested);
+    this.setStatus({ phase: "idle", total: 0, completed: 0, currentNode: null, pass: 0, superseded: 0, startedAt: null, elapsed: 0 });
+    for (const resolve of this.idleResolvers) resolve();
+    this.idleResolvers.clear();
+  }
+  /**
+   * Cook one node with its signal published as the ambient cook signal, so a
+   * stage it starts can be withdrawn when the cook is superseded even if the
+   * node never passes `context.signal` along. Safe as a single global because
+   * this lane runs one node at a time; restored rather than cleared in case a
+   * host nests a run.
+   */
+  async executeInteractive(node) {
+    const globals = globalThis;
+    const previous = globals[COOK_SIGNAL_KEY];
+    const read = () => node.inFlightCookSignal;
+    globals[COOK_SIGNAL_KEY] = read;
+    try {
+      await node.execute();
+    } finally {
+      if (globals[COOK_SIGNAL_KEY] === read) globals[COOK_SIGNAL_KEY] = previous;
+    }
+  }
+  // ============ The background lane ============
+  /**
+   * Work that must never delay the thing being looked at.
+   *
+   * Marcus's rule for an auto-updating series, 2026-09-09: *"i want the series
+   * to auto-update ... however the single live node has priority."* That cannot
+   * be expressed in the interactive queue, which is one FIFO with no priority
+   * in it — measured by MW-OBSERVATORY-ART as 91 of 91 downstream cooks queued
+   * behind their upstream with zero overlap and nothing ever superseded. A
+   * series auto-updating through that queue would sit in front of the next
+   * edit: twelve instances at ~220 ms each is 2.6 seconds between Marcus and
+   * the slider he is dragging.
+   *
+   * So background is a second lane with three properties, and all three are
+   * load-bearing:
+   *
+   *   - it **starts only when the graph is quiet** — `phase === 'idle'` plus a
+   *     settling interval, because otherwise a drag becomes a chain of
+   *     started-and-cancelled passes, which is worse than not starting;
+   *   - it is **abandoned the moment interactive work arrives**, at `schedule`
+   *     rather than at the run, so the debounce window is not spent on it;
+   *   - it is abandoned **through a signal the work can see**, so an expensive
+   *     task can bail before committing rather than after. That is the fault
+   *     this lane exists to avoid rather than relocate: an abandoned cook on
+   *     `cloud-volumes` had already encoded and uploaded a 1.55 MB PNG before
+   *     anything noticed it was superseded.
+   *
+   * **The trap for whoever builds the first client.** Mutating the graph from
+   * inside a background task — which is what applying a parameter set does —
+   * reaches `markStale`, and `markStale` calls `schedule`, which preempts the
+   * background lane. A task that invalidates the graph therefore cancels
+   * itself. The way out is to drive nodes directly rather than through the
+   * interactive queue, not to weaken the preemption; the preemption is the
+   * only thing making the lane honest.
+   */
+  async runBackground(task, options = {}) {
+    this.preemptBackground("superseded by a newer background task");
+    await this.whenSettled(options.settleMs ?? this.debounceMs * 4);
+    const abort = new AbortController();
+    this.backgroundAbort = abort;
+    try {
+      await task(abort.signal);
+      return abort.signal.aborted ? "preempted" : "completed";
+    } finally {
+      if (this.backgroundAbort === abort) this.backgroundAbort = null;
+    }
+  }
+  /** Whether background work is in flight. Distinct from `isRunning`, which is
+   *  the interactive lane — a panel showing one as the other would report the
+   *  series as though Marcus's own edit were still cooking. */
+  get isRunningBackground() {
+    return this.backgroundAbort !== null;
+  }
+  /** @internal Abandon the background lane. Public so a client can stand down
+   *  without waiting for an invalidation to do it. */
+  preemptBackground(reason) {
+    const abort = this.backgroundAbort;
+    if (!abort) return;
+    this.backgroundAbort = null;
+    if (!abort.signal.aborted) abort.abort(new Error(reason));
+  }
+  /**
+   * Resolve once the graph has been idle for `settleMs` without interruption.
+   *
+   * Deliberately not `whenIdle()` plus a timer: `whenIdle` resolves the instant
+   * the queue drains, and a drag drains it between every keystroke. The
+   * settling interval is what turns *momentarily idle* into *finished*, and it
+   * restarts whenever work reappears — so under sustained invalidation this
+   * never resolves, which is correct. Background work has no business starting
+   * while the graph is still moving.
+   */
+  whenSettled(settleMs) {
+    return new Promise((resolve) => {
+      let timer = null;
+      const stop = this.subscribe((status) => {
+        if (status.phase === "idle") {
+          if (timer === null) {
+            timer = setTimeout(() => {
+              stop();
+              resolve();
+            }, settleMs);
+          }
+          return;
+        }
+        if (timer !== null) {
+          clearTimeout(timer);
+          timer = null;
+        }
+      });
+    });
+  }
+  /** Stable-partition `ordered` in place: what a watched node needs, first. */
+  viewerFirst(ordered) {
+    if (this.watched.size === 0) return;
+    const needed = /* @__PURE__ */ new Set();
+    const visit = (id) => {
+      if (needed.has(id)) return;
+      const node = this.graph.getNode(id);
+      if (!node) return;
+      needed.add(id);
+      for (const input of node.inputs) {
+        for (const connection of input.connections) visit(connection.from.nodeId);
+      }
+    };
+    for (const id of this.watched.keys()) visit(id);
+    if (needed.size === 0) return;
+    const first = ordered.filter((node) => needed.has(node.id));
+    if (first.length === 0 || first.length === ordered.length) return;
+    const rest = ordered.filter((node) => !needed.has(node.id));
+    ordered.splice(0, ordered.length, ...first, ...rest);
+  }
+  collectDownstream(entryNode) {
+    const result = /* @__PURE__ */ new Set();
+    const visit = (node) => {
+      if (result.has(node.id)) return;
+      result.add(node.id);
+      for (const output of node.outputs) {
+        for (const connection of output.connections) {
+          const downstream = this.graph.getNode(connection.to.nodeId);
+          if (downstream) visit(downstream);
+        }
+      }
+    };
+    visit(entryNode);
+    return result;
+  }
+  setStatus(status) {
+    this._status = Object.freeze(status);
+    this.emit();
+  }
+  emit() {
+    for (const listener of this.listeners) listener(this._status);
+  }
+};
+
+// src/nodes/Graph.ts
+var GRAPH_FORMAT_VERSION = "0.2";
+function parsePortId(portId) {
+  const parts = portId.split("_");
+  if (parts.length < 3) {
+    throw new Error(`Invalid port ID format: ${portId}`);
+  }
+  const portType = parts[parts.length - 2];
+  const index = parseInt(parts[parts.length - 1], 10);
+  if (isNaN(index)) {
+    throw new Error(`Invalid port index in port ID: ${portId}`);
+  }
+  const elementId = parts.slice(0, -2).join("_");
+  return { elementId, portType, index };
+}
+function createPortId(elementId, portType, index) {
+  return `${elementId}_${portType}_${index}`;
+}
+var Graph = class _Graph {
+  constructor(assetManager, packageManager, moduleResolver) {
+    this._elements = [];
+    this._elementMap = /* @__PURE__ */ new Map();
+    // O(1) lookup cache
+    this.connections = [];
+    this._connectionMap = /* @__PURE__ */ new Map();
+    // O(1) connection lookup
+    this.connectionIdCounter = 0;
+    // Project configuration (v0.2)
+    this.project = { packages: [] };
+    this.createdAt = (/* @__PURE__ */ new Date()).toISOString();
+    // Execution Control
+    this.cookingNodes = /* @__PURE__ */ new Set();
+    // Execution state
+    this.executionState = "idle";
+    // Cached topological order (invalidated when graph structure changes)
+    this.cachedTopologicalOrder = null;
+    this.restoringHierarchy = false;
+    /**
+     * Whether the load-time connection restore has stopped making progress.
+     *
+     * Set by whoever drives the warm-up passes — Studio's `cookGraph`, the CLI's
+     * runner — when the pending list stops shrinking. The pending list itself is
+     * kept, so a connection can still bind later if a bypass is lifted or a
+     * module finally compiles; what ends is treating it as a reason to hold a
+     * node back.
+     */
+    this.connectionsSettled = false;
+    this.assetManager = assetManager || new AssetManager();
+    this.packageManager = packageManager || new PackageManager();
+    this.moduleResolver = moduleResolver || createModuleResolver();
+    this.scheduler = new CookScheduler(this);
+  }
+  get created() {
+    return this.createdAt;
+  }
+  /**
+   * Unified elements array (computations and annotations)
+   */
+  get elements() {
+    return this._elements;
+  }
+  set elements(value) {
+    this._elements = value;
+    this._elementMap.clear();
+    for (const el of value) {
+      this._elementMap.set(el.id, el);
+    }
+  }
+  /**
+   * Helper to check if an element is an annotation
+   * Uses marker property for reliability (survives HMR and serialization)
+   */
+  isAnnotation(element) {
+    return element.isAnnotation === true;
+  }
+  /**
+   * Get all computations (non-annotation nodes)
+   */
+  get nodes() {
+    return this._elements.filter((e) => !this.isAnnotation(e));
+  }
+  /**
+   * Set computations (triggers Svelte reactivity)
+   */
+  set nodes(value) {
+    this._elements = [...this._elements.filter((e) => this.isAnnotation(e)), ...value];
+  }
+  /**
+   * Get all annotations
+   */
+  get annotations() {
+    return this._elements.filter((e) => this.isAnnotation(e));
+  }
+  /**
+   * Set annotations (triggers Svelte reactivity)
+   */
+  set annotations(value) {
+    this._elements = [...this._elements.filter((e) => !this.isAnnotation(e)), ...value];
+  }
+  /**
+   * Generates a unique element ID based on a base ID.
+   * If the base ID ends in a number (e.g., "Checkers1"), strips it and increments.
+   * Always appends a number starting from 1 (e.g., "Checkers1", "Checkers2").
+   * Ensures the ID has no spaces.
+   * @param baseId The base ID to use (typically the element type or existing node ID)
+   * @param excludeElementId Optional element ID to exclude from uniqueness check (useful when renaming)
+   * @returns A unique element ID with no spaces
+   */
+  generateUniqueNodeId(baseId, excludeElementId) {
+    const sanitizedBaseId = baseId.replace(/\s+/g, "");
+    const match = sanitizedBaseId.match(/^(.+?)(\d+)?$/);
+    const baseName = match ? match[1] : sanitizedBaseId;
+    let counter = 1;
+    let candidateId = `${baseName}${counter}`;
+    while (this._elements.some(
+      (element) => element.id === candidateId && (!excludeElementId || element.id !== excludeElementId)
+    )) {
+      counter++;
+      candidateId = `${baseName}${counter}`;
+    }
+    return candidateId;
+  }
+  /**
+   * Get any element by ID (O(1) using Map cache)
+   */
+  getElement(id) {
+    return this._elementMap.get(id) || null;
+  }
+  /**
+   * Get a computation by ID (type-safe)
+   */
+  getNode(nodeId) {
+    const element = this.getElement(nodeId);
+    return element && !this.isAnnotation(element) ? element : null;
+  }
+  /**
+   * Get an annotation by ID (type-safe)
+   */
+  getAnnotation(id) {
+    const element = this.getElement(id);
+    return element && this.isAnnotation(element) ? element : null;
+  }
+  /**
+   * Return the live members of a group in authored order.
+   *
+   * Group membership is an annotation relationship, separate from subnet
+   * parenting. Only elements in the group's current network are visible, and
+   * recursive traversal is guarded against duplicate references and malformed
+   * cycles in loaded documents.
+   */
+  getGroupMembers(groupId, recursive = true) {
+    const group = this.getElement(groupId);
+    if (!this.isGroupAnnotation(group)) return [];
+    const members = [];
+    const seen = /* @__PURE__ */ new Set([group.id]);
+    const visitingGroups = /* @__PURE__ */ new Set([group.id]);
+    const visit = (owner) => {
+      for (const memberId of owner.containedElements ?? []) {
+        if (seen.has(memberId)) continue;
+        const member = this.getElement(memberId);
+        if (!member || member === owner || member.parent !== owner.parent) continue;
+        seen.add(memberId);
+        members.push(memberId);
+        if (recursive && this.isGroupAnnotation(member) && !visitingGroups.has(member.id)) {
+          visitingGroups.add(member.id);
+          visit(member);
+          visitingGroups.delete(member.id);
+        }
+      }
+    };
+    visit(group);
+    return members;
+  }
+  /**
+   * Assign existing elements to one group, or remove their group ownership.
+   * Validation completes before any annotation is changed, so failures leave
+   * every membership list untouched. Assignment never changes subnet parents.
+   */
+  assignToGroup(elementIds, groupId) {
+    const ids = [...new Set(elementIds)];
+    const elements = ids.map((id) => this.getElement(id));
+    if (elements.some((element) => !element)) return false;
+    const targetElement = groupId === null ? null : this.getElement(groupId);
+    if (groupId !== null && !this.isGroupAnnotation(targetElement)) return false;
+    const target = this.isGroupAnnotation(targetElement) ? targetElement : null;
+    if (target) {
+      for (const element of elements) {
+        if (element === target || element.parent !== target.parent) return false;
+        if (this.isGroupAnnotation(element) && this.groupContains(element, target.id)) return false;
+      }
+    }
+    const selected = new Set(ids);
+    for (const group of this.groupAnnotations()) {
+      const current = group.containedElements ?? [];
+      group.containedElements = current.filter((id) => !selected.has(id));
+    }
+    if (target) {
+      target.containedElements = [
+        .../* @__PURE__ */ new Set([...target.containedElements ?? [], ...ids])
+      ];
+    }
+    return true;
+  }
+  /**
+   * Get a node by absolute path (e.g., "/effects/blur1")
+   */
+  nodeByPath(path) {
+    if (!path.startsWith("/")) return null;
+    const segments = path.slice(1).split("/").filter((s) => s.length > 0);
+    if (segments.length === 0) return null;
+    let current = this.nodes.find((node) => !node.parent && node.id === segments[0]) ?? null;
+    for (let index = 1; current && index < segments.length; index++) {
+      if (!current.isNetwork()) return null;
+      current = current.children().find((child) => child.id === segments[index]) ?? null;
+    }
+    return current;
+  }
+  /**
+   * Add an element to the graph
+   */
+  addElement(element) {
+    this._elements.push(element);
+    this._elementMap.set(element.id, element);
+    this.invalidateTopologicalOrder();
+  }
+  /**
+   * Move an element between networks while keeping both sides of the parent
+   * relationship consistent. Structural editor code must use this instead of
+   * mutating `parent` or `_children` directly.
+   */
+  reparentElement(element, parent) {
+    if (parent) {
+      if (!parent.isNetwork() || parent === element) return false;
+      for (let ancestor = parent; ancestor; ancestor = ancestor.parent) {
+        if (ancestor === element) return false;
+      }
+    }
+    if (element.parent === parent) return true;
+    const previous = element.parent;
+    if (previous) {
+      const removeChild = previous.removeChild;
+      if (typeof removeChild === "function") removeChild.call(previous, element);
+      else {
+        previous._children = previous.children().filter((child) => child !== element);
+        element.parent = null;
+      }
+    }
+    if (parent) {
+      const addChild = parent.addChild;
+      if (typeof addChild === "function") addChild.call(parent, element);
+      else {
+        element.parent = parent;
+        parent._children.push(element);
+      }
+    }
+    if (!this.restoringHierarchy) this.pruneInvalidGroupMemberships();
+    this.invalidateTopologicalOrder();
+    return true;
+  }
+  /**
+   * Remove an element from the graph
+   */
+  removeElement(id) {
+    const element = this._elementMap.get(id);
+    if (!element) return;
+    const removed = [];
+    const visited = /* @__PURE__ */ new Set();
+    const collect = (candidate) => {
+      if (visited.has(candidate)) return;
+      visited.add(candidate);
+      candidate.children().forEach(collect);
+      removed.push(candidate);
+    };
+    collect(element);
+    const removedIds = new Set(removed.map((candidate) => candidate.id));
+    this.connections.filter((connection) => removedIds.has(connection.from.nodeId) || removedIds.has(connection.to.nodeId)).forEach((connection) => this.disconnect(connection.id));
+    const pending = this._connectionsToRestore;
+    if (Array.isArray(pending)) {
+      this._connectionsToRestore = pending.filter((connection) => {
+        const fromId = Array.isArray(connection?.[0]) ? connection[0][0] : void 0;
+        const toId = Array.isArray(connection?.[1]) ? connection[1][0] : void 0;
+        return !removedIds.has(fromId) && !removedIds.has(toId);
+      });
+    }
+    this._elements = this._elements.filter((candidate) => !removedIds.has(candidate.id));
+    for (const candidate of removed) {
+      this._elementMap.delete(candidate.id);
+      this.cookingNodes.delete(candidate);
+    }
+    for (const group of this.groupAnnotations()) {
+      group.containedElements = (group.containedElements ?? []).filter((memberId) => !removedIds.has(memberId));
+    }
+    for (const candidate of removed) {
+      const parent = candidate.parent;
+      if (parent) {
+        const removeChild = parent.removeChild;
+        if (typeof removeChild === "function") removeChild.call(parent, candidate);
+        else candidate.parent = null;
+      }
+    }
+    this.invalidateTopologicalOrder();
+    for (const candidate of removed) candidate.onDestroy?.();
+  }
+  isGroupAnnotation(element) {
+    return !!element && this.isAnnotation(element) && element.type === "Group";
+  }
+  groupAnnotations() {
+    return this.annotations.filter((annotation) => this.isGroupAnnotation(annotation));
+  }
+  groupContains(group, soughtId) {
+    const visited = /* @__PURE__ */ new Set();
+    const visit = (candidate) => {
+      if (visited.has(candidate.id)) return false;
+      visited.add(candidate.id);
+      for (const memberId of candidate.containedElements ?? []) {
+        if (memberId === soughtId) return true;
+        const member = this.getElement(memberId);
+        if (this.isGroupAnnotation(member) && member.parent === candidate.parent && visit(member)) return true;
+      }
+      return false;
+    };
+    return visit(group);
+  }
+  pruneInvalidGroupMemberships() {
+    for (const group of this.groupAnnotations()) {
+      const seen = /* @__PURE__ */ new Set();
+      group.containedElements = (group.containedElements ?? []).filter((memberId) => {
+        const member = this.getElement(memberId);
+        if (!member || member === group || member.parent !== group.parent || seen.has(memberId)) return false;
+        seen.add(memberId);
+        return true;
+      });
+    }
+  }
+  /**
+   * Rename an element's ID, updating internal maps
+   */
+  renameElement(oldId, newId) {
+    const element = this._elementMap.get(oldId);
+    if (!element || !newId || oldId !== newId && this._elementMap.has(newId)) return false;
+    if (oldId === newId) return true;
+    const renamedPorts = element.renameId(newId);
+    this._elementMap.delete(oldId);
+    this._elementMap.set(newId, element);
+    for (const connection of this.connections) {
+      if (connection.from.nodeId === oldId) connection.from.nodeId = newId;
+      if (connection.to.nodeId === oldId) connection.to.nodeId = newId;
+      connection.from.portId = renamedPorts.get(connection.from.portId) ?? connection.from.portId;
+      connection.to.portId = renamedPorts.get(connection.to.portId) ?? connection.to.portId;
+    }
+    const pending = this._connectionsToRestore;
+    if (Array.isArray(pending)) {
+      for (const connection of pending) {
+        for (const endpoint of Array.isArray(connection) ? connection : []) {
+          if (Array.isArray(endpoint) && endpoint[0] === oldId) endpoint[0] = newId;
+        }
+      }
+    }
+    for (const annotation of this.annotations) {
+      if (Array.isArray(annotation.containedElements)) {
+        annotation.containedElements = annotation.containedElements.map((id) => id === oldId ? newId : id);
+      }
+    }
+    this.invalidateTopologicalOrder();
+    return true;
+  }
+  addNode(type, position) {
+    const displayName = getNodeDisplayName(type);
+    const baseId = displayName.toLowerCase().replace(/\s+/g, "_");
+    const id = this.generateUniqueNodeId(baseId);
+    const NodeClass = getNodeClass(type);
+    let node;
+    if (NodeClass) {
+      node = new NodeClass(id, this);
+    } else {
+      node = new Node(id, packagePathToType(type), this);
+    }
+    node.modulePath = type;
+    if (isStandardLibraryNode(type)) {
+      node.sourceType = "stdlib";
+    } else if (type.startsWith("local.")) {
+      node.sourceType = "embedded";
+    } else {
+      const sourceType = this.moduleResolver.getSourceType(type);
+      node.sourceType = sourceType || "embedded";
+    }
+    node.position = position;
+    this.addElement(node);
+    return node;
+  }
+  /**
+   * Point an existing node instance at a different module.
+   *
+   * Duplicating a built-in into an editable copy, and promoting an embedded
+   * node to a file, both keep the node where it is on the canvas with its
+   * connections and parameter values intact and only change which module
+   * supplies `execute`. The compiled module is captured once when a node is
+   * loaded, so swapping the path alone would leave the old code running.
+   *
+   * Ports and parameters are untouched on purpose: both callers move IDENTICAL
+   * code, so the ports and settings the next cook declares are the ones already
+   * there, and reconciling them would only be a chance to be wrong.
+   *
+   * Switching to a different VERSION of a definition is a different move — use
+   * retargetDefinition, which reconciles and reports.
+   */
+  retargetModule(nodeId, modulePath, source, code) {
+    return this.retargetDefinition(nodeId, modulePath, source, code, {
+      preserveParameters: false
+    }).ok;
+  }
+  /**
+   * Point a node at a different definition and carry its settings across.
+   *
+   * The general form of retargetModule. One code path: the module swap is
+   * identical, and what differs is whether a reconciliation is asked for.
+   * retargetModule is the case where it is not — identical code drops nothing,
+   * so its report would be empty anyway, and skipping it keeps a working path
+   * working. Everything else goes through the reconciler.
+   *
+   * Policy (see ParameterCarryOverReport in Node.ts):
+   *   - a parameter surviving by NAME and TYPE keeps its value, and its
+   *     expression with it
+   *   - one the new definition adds takes its declared default
+   *   - one the new definition no longer has is dropped AND REPORTED, with the
+   *     value it held, so a caller can offer it back
+   *   - same name, different type is a conflict: the new type wins with its
+   *     default and the conflict is reported. No coercion is attempted
+   *
+   * Pass `options.parameters` when the new definition's declarations are known
+   * (a Definition panel has them) and the result is complete on return. Without
+   * them the result is `deferred: true` — a module's parameters are only known
+   * once its code declares them, which happens on the next cook.
+   */
+  retargetDefinition(nodeId, modulePath, source, code, options = {}) {
+    const blank = () => ({ kept: [], defaulted: [], dropped: [], retyped: [] });
+    const node = this.getNode(nodeId);
+    if (!node) {
+      return { ok: false, deferred: false, ...blank(), error: `no node with id ${nodeId}` };
+    }
+    const preserve = options.preserveParameters !== false;
+    if (preserve) node.beginParameterCarryOver();
+    node.modulePath = modulePath;
+    node.sourceType = source;
+    if (source === "embedded" && code !== void 0) node.code = code;
+    const modulePromise = source === "project" ? loadProjectModule(modulePath) : loadEmbeddedModule(code ?? node.code);
+    node.setFunction(moduleNodeFunction(node, modulePath, modulePromise));
+    modulePromise.catch((error) => {
+      node.abandonParameterCarryOver();
+      console.warn("Failed to compile " + modulePath + ":", error);
+    });
+    node.markDirty();
+    if (preserve && options.parameters) {
+      const report = node.applyParameterDeclarations(options.parameters) ?? blank();
+      return { ok: true, deferred: false, ...report };
+    }
+    return { ok: true, deferred: preserve, ...blank() };
+  }
+  /** The report from a deferred retarget, once its cook has run. Null until
+   *  then, and null for a node that was never retargeted. */
+  getRetargetReport(nodeId) {
+    return this.getNode(nodeId)?.lastCarryOverReport ?? null;
+  }
+  removeNode(nodeId) {
+    this.removeElement(nodeId);
+  }
+  /**
+   * Validate a connection before creating it
+   * Works with any element type (nodes and annotations)
+   */
+  validateConnection(fromPort, toPort) {
+    let fromElementId;
+    let toElementId;
+    try {
+      const fromParsed = parsePortId(fromPort.id);
+      const toParsed = parsePortId(toPort.id);
+      fromElementId = fromParsed.elementId;
+      toElementId = toParsed.elementId;
+    } catch (err) {
+      return { valid: false, error: `Invalid port ID format: ${err}` };
+    }
+    const fromElement = this.getElement(fromElementId);
+    const toElement = this.getElement(toElementId);
+    if (!fromElement || !toElement) {
+      return { valid: false, error: "Element not found" };
+    }
+    if (!this.isAnnotation(fromElement) && !this.isAnnotation(toElement)) {
+      const error = GraphValidator.validateConnection(
+        this,
+        fromElementId,
+        toElementId,
+        fromPort.id,
+        toPort.id
+      );
+      if (error) {
+        return { valid: false, error: error.message };
+      }
+    }
+    return { valid: true };
+  }
+  /**
+   * Check data type compatibility between ports
+   * Returns a warning message if types don't match, or null if compatible
+   */
+  checkDataTypeCompatibility(fromPort, toPort) {
+    const fromType = normalizeType(fromPort.dataType);
+    const toType = normalizeType(toPort.dataType);
+    if (canConnect(fromType, toType)) {
+      if (fromType === "bundle" && toType === "bundle" && !bundleSchemasCompatible(fromPort.options?.schema, toPort.options?.schema)) {
+        return `Schema mismatch: connecting a ${fromPort.options.schema} bundle to an input that takes ${toPort.options.schema}`;
+      }
+      return null;
+    }
+    const legacy = {
+      number: ["number[]", "string"],
+      float: ["number[]"],
+      int: ["number[]"],
+      string: ["number", "float", "int"]
+    };
+    if (legacy[fromType]?.includes(toType)) return null;
+    return `Type mismatch: connecting ${fromType} to ${toType}`;
+  }
+  /**
+   * Update type mismatch warnings on a node based on its input connections
+   */
+  updateTypeMismatchWarnings(nodeId) {
+    const node = this.getNode(nodeId);
+    if (!node) return;
+    const warnings = [];
+    for (const inputPort of node.inputs) {
+      for (const conn of inputPort.connections) {
+        const fromNode = this.getNode(conn.from.nodeId);
+        if (!fromNode) continue;
+        const fromPort = fromNode.outputs.find((p) => p.id === conn.from.portId);
+        if (!fromPort) continue;
+        const warning = this.checkDataTypeCompatibility(fromPort, inputPort);
+        if (warning) {
+          warnings.push(warning);
+        }
+      }
+    }
+    if (warnings.length > 0) {
+      node.warning = warnings.join("; ");
+    } else if (node.warning?.startsWith("Type mismatch")) {
+      node.warning = null;
+    }
+  }
+  connect(fromPort, toPort) {
+    const validation = this.validateConnection(fromPort, toPort);
+    if (!validation.valid) {
+      throw new Error(`Invalid connection: ${validation.error}`);
+    }
+    if (!toPort.variadic && toPort.connections && toPort.connections.length > 0) {
+      const connectionsToRemove = [...toPort.connections];
+      for (const conn of connectionsToRemove) {
+        this.disconnect(conn.id);
+      }
+    }
+    const fromParsed = parsePortId(fromPort.id);
+    const toParsed = parsePortId(toPort.id);
+    const connection = {
+      id: `conn_${Date.now()}_${++this.connectionIdCounter}`,
+      from: {
+        nodeId: fromParsed.elementId,
+        portId: fromPort.id
+      },
+      to: {
+        nodeId: toParsed.elementId,
+        portId: toPort.id
+      },
+      type: fromPort.portType
+    };
+    const existing = fromPort.connections.find(
+      (c) => c.to.nodeId === connection.to.nodeId && c.to.portId === connection.to.portId
+    );
+    if (existing) {
+      return existing;
+    }
+    this.connections.push(connection);
+    this._connectionMap.set(connection.id, connection);
+    fromPort.connections.push(connection);
+    toPort.connections.push(connection);
+    this.invalidateTopologicalOrder();
+    if (fromPort.value !== void 0 && fromPort.value !== null) {
+      toPort.value = fromPort.value;
+      if (toPort.onChange) {
+        try {
+          toPort.onChange(fromPort.value);
+        } catch (err) {
+          console.error(`Error in onChange callback for port ${toPort.name}:`, err);
+        }
+      }
+    }
+    this.syncVariadicPortsOnNode(toParsed.elementId);
+    this.updateTypeMismatchWarnings(toParsed.elementId);
+    this.getNode(toParsed.elementId)?.markDirty();
+    return connection;
+  }
+  disconnect(connectionId) {
+    const conn = this._connectionMap.get(connectionId);
+    if (!conn) return;
+    const sourceNode = this.getElement(conn.from.nodeId);
+    const targetNode = this.getElement(conn.to.nodeId);
+    if (sourceNode) {
+      const sourcePort = sourceNode.getPort(conn.from.portId);
+      if (sourcePort) {
+        sourcePort.connections = sourcePort.connections.filter((c) => c.id !== connectionId);
+      }
+    }
+    if (targetNode) {
+      const targetPort = targetNode.getPort(conn.to.portId);
+      if (targetPort) {
+        targetPort.connections = targetPort.connections.filter((c) => c.id !== connectionId);
+        if (targetPort.connections.length === 0) {
+          targetPort.value = targetPort.defaultValue;
+          try {
+            targetPort.onChange?.(targetPort.defaultValue);
+          } catch (err) {
+            console.error(`Error in onChange callback for port ${targetPort.name}:`, err);
+          }
+        }
+      }
+    }
+    const index = this.connections.findIndex((c) => c.id === connectionId);
+    if (index >= 0) {
+      this.connections.splice(index, 1);
+    }
+    this._connectionMap.delete(connectionId);
+    this.invalidateTopologicalOrder();
+    this.syncVariadicPortsOnNode(conn.to.nodeId);
+    this.updateTypeMismatchWarnings(conn.to.nodeId);
+    this.getNode(conn.to.nodeId)?.markDirty();
+  }
+  /**
+   * Sync variadic ports on a node after connection changes
+   */
+  syncVariadicPortsOnNode(nodeId) {
+    const node = this.getNode(nodeId);
+    if (node) {
+      node.syncVariadicPorts();
+    }
+  }
+  /**
+   * Validate the entire graph
+   */
+  validate() {
+    return GraphValidator.validateGraph(this);
+  }
+  /**
+   * Execute graph using topological sort for proper ordering
+   */
+  async execute(entryNode) {
+    this.executionState = "running";
+    try {
+      await this.scheduler.flush(entryNode);
+    } finally {
+      this.executionState = "idle";
+    }
+  }
+  /**
+   * Get or compute topological order for the entire graph
+   * Caches the result until graph structure changes
+   */
+  getTopologicalOrder() {
+    if (this.cachedTopologicalOrder) {
+      return this.cachedTopologicalOrder;
+    }
+    this.cachedTopologicalOrder = GraphValidator.topologicalSort(this);
+    return this.cachedTopologicalOrder;
+  }
+  /**
+   * Invalidate cached topological order (call when graph structure changes)
+   */
+  invalidateTopologicalOrder() {
+    this.cachedTopologicalOrder = null;
+  }
+  stop() {
+    this.executionState = "stopped";
+  }
+  reset() {
+    this.nodes.forEach((node) => {
+      node.error = null;
+      node.warning = null;
+      node.markDirty();
+    });
+    this.cookingNodes.clear();
+    this.executionState = "idle";
+  }
+  // Behavior Control (v1.2)
+  clearCookingNodes(except) {
+    if (except) {
+      this.cookingNodes.forEach((comp) => {
+        if (comp !== except) {
+          comp.setCook(false);
+        }
+      });
+    } else {
+      this.cookingNodes.forEach((comp) => {
+        comp.setCook(false);
+      });
+    }
+  }
+  isDownstreamOfCooking(node) {
+    const visited = /* @__PURE__ */ new Set();
+    const checkUpstream = (n) => {
+      if (visited.has(n.id)) return false;
+      visited.add(n.id);
+      if (this.cookingNodes.has(n)) {
+        return true;
+      }
+      for (const input of n.inputs) {
+        for (const conn of input.connections) {
+          const upstreamNode = this.getNode(conn.from.nodeId);
+          if (upstreamNode && checkUpstream(upstreamNode)) {
+            return true;
+          }
+        }
+      }
+      return false;
+    };
+    return checkUpstream(node);
+  }
+  addAnnotation(annotation) {
+    let annotationInstance;
+    if (this.isAnnotation(annotation)) {
+      annotationInstance = annotation;
+    } else {
+      const annData = annotation;
+      const normalizedType = annData.type.charAt(0).toUpperCase() + annData.type.slice(1).toLowerCase();
+      switch (normalizedType) {
+        case "Image":
+          annotationInstance = new ImageAnnotation(annData.id, this);
+          annotationInstance.src = annData.src;
+          break;
+        case "Text":
+          annotationInstance = new TextAnnotation(annData.id, this);
+          annotationInstance.content = annData.content;
+          break;
+        case "Group":
+          annotationInstance = new GroupAnnotation(annData.id, this);
+          annotationInstance.content = annData.content;
+          break;
+        case "Line":
+          annotationInstance = new LineAnnotation(annData.id, this);
+          if (annData.endPosition) {
+            annotationInstance.endPosition = annData.endPosition;
+          }
+          break;
+        case "Polyline":
+          annotationInstance = new PolylineAnnotation(annData.id, this);
+          if (annData.points) {
+            annotationInstance.points = annData.points;
+          }
+          break;
+        default:
+          annotationInstance = new Annotation(annData.id, annData.type, this);
+          if (annData.content !== void 0) annotationInstance.content = annData.content;
+          if (annData.src !== void 0) annotationInstance.src = annData.src;
+          if (annData.endPosition) annotationInstance.endPosition = annData.endPosition;
+          if (annData.points) annotationInstance.points = annData.points;
+      }
+      annotationInstance.position = annData.position || { x: 0, y: 0 };
+      if (annData.size) annotationInstance.size = annData.size;
+      if (annData.style) annotationInstance.style = { ...annData.style };
+      if (annData.caption !== void 0) annotationInstance.caption = annData.caption;
+      if (annData.containedElements) annotationInstance.containedElements = annData.containedElements;
+    }
+    this.addElement(annotationInstance);
+    this.initializeAnnotationPorts(annotationInstance).catch((err) => {
+      console.error(`Failed to initialize ports for annotation ${annotationInstance.id}:`, err);
+    });
+  }
+  removeAnnotation(id) {
+    this.removeElement(id);
+  }
+  /**
+   * Initialize output ports for an annotation based on its type
+   * Annotations always have exactly one output at index 0
+   */
+  async initializeAnnotationPorts(annotation) {
+    annotation.outputs = [];
+    if (annotation.type === "Image") {
+      const imageAnnotation = annotation;
+      const portId = createPortId(annotation.id, "output", 0);
+      const port = {
+        id: portId,
+        name: "image",
+        portType: "param",
+        dataType: "asset",
+        value: null,
+        connections: [],
+        setValue: (value) => {
+          port.value = value;
+          port.connections.forEach((conn) => {
+            const toParsed = parsePortId(conn.to.portId);
+            const targetElement = this.getElement(toParsed.elementId);
+            if (targetElement && !this.isAnnotation(targetElement)) {
+              const targetPort = targetElement.getInputPort(toParsed.index);
+              if (targetPort) {
+                targetPort.value = value;
+                targetPort.onChange?.(value);
+              }
+            }
+          });
+        },
+        trigger: (props) => {
+          port.connections.forEach((conn) => {
+            const toParsed = parsePortId(conn.to.portId);
+            const targetElement = this.getElement(toParsed.elementId);
+            if (targetElement && !this.isAnnotation(targetElement)) {
+              const targetPort = targetElement.getInputPort(toParsed.index);
+              targetPort?.onTrigger?.(props);
+            }
+          });
+        }
+      };
+      annotation.outputs.push(port);
+      const imageSrc = imageAnnotation.src;
+      if (imageSrc) {
+        try {
+          const img = new Image();
+          img.crossOrigin = "anonymous";
+          await new Promise((resolve, reject) => {
+            img.onload = () => {
+              port.setValue(img);
+              resolve();
+            };
+            img.onerror = reject;
+            img.src = imageSrc.startsWith("/") || imageSrc.startsWith("http") || imageSrc.startsWith("data:") ? imageSrc : `/${imageSrc}`;
+          });
+        } catch (error) {
+          console.error(`Failed to load image for annotation ${annotation.id}:`, error);
+        }
+      }
+    } else if (annotation.type === "Text") {
+      const textAnnotation = annotation;
+      if (textAnnotation.content !== void 0) {
+        const portId = createPortId(annotation.id, "output", 0);
+        const port = {
+          id: portId,
+          name: "text",
+          portType: "param",
+          dataType: "string",
+          value: textAnnotation.content,
+          connections: [],
+          setValue: (value) => {
+            port.value = value;
+            port.connections.forEach((conn) => {
+              const toParsed = parsePortId(conn.to.portId);
+              const targetElement = this.getElement(toParsed.elementId);
+              if (targetElement && !this.isAnnotation(targetElement)) {
+                const targetPort = targetElement.getInputPort(toParsed.index);
+                if (targetPort) {
+                  targetPort.value = value;
+                  targetPort.onChange?.(value);
+                }
+              }
+            });
+          },
+          trigger: (props) => {
+            port.connections.forEach((conn) => {
+              const toParsed = parsePortId(conn.to.portId);
+              const targetElement = this.getElement(toParsed.elementId);
+              if (targetElement && !this.isAnnotation(targetElement)) {
+                const targetPort = targetElement.getInputPort(toParsed.index);
+                targetPort?.onTrigger?.(props);
+              }
+            });
+          }
+        };
+        annotation.outputs.push(port);
+      }
+    }
+  }
+  // ============ Path Validation ============
+  /**
+   * Validate all expressions in the graph for broken paths
+   * Returns warnings for any expressions referencing non-existent nodes or parameters
+   */
+  validateExpressionPaths() {
+    const warnings = [];
+    const pathRefPattern = /\b(?:ch|chs|chv)\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+    for (const node of this.nodes) {
+      for (const [propName, prop] of Object.entries(node.props)) {
+        if (!prop.expression) continue;
+        const location = `${node.path()}/${propName}`;
+        const matches = prop.expression.matchAll(pathRefPattern);
+        for (const match of matches) {
+          const referencedPath = match[1];
+          const bundleWarning = this.bundlePathWarning(node, referencedPath);
+          if (bundleWarning !== void 0) {
+            if (bundleWarning) warnings.push({ location, expression: prop.expression, brokenPath: referencedPath, suggestion: bundleWarning });
+            continue;
+          }
+          const resolvedNode = this.resolvePathFromNode(node, referencedPath);
+          if (!resolvedNode.node) {
+            warnings.push({
+              location,
+              expression: prop.expression,
+              brokenPath: referencedPath,
+              suggestion: this.suggestPathFix(node, referencedPath)
+            });
+          } else if (resolvedNode.parmName && !resolvedNode.node.props[resolvedNode.parmName]) {
+            warnings.push({
+              location,
+              expression: prop.expression,
+              brokenPath: referencedPath,
+              suggestion: `Parameter "${resolvedNode.parmName}" not found on node "${resolvedNode.node.id}"`
+            });
+          }
+        }
+      }
+    }
+    return {
+      valid: warnings.length === 0,
+      warnings
+    };
+  }
+  /**
+   * A bundle field path in an expression: undefined when the path is not one,
+   * null when it is and reads a field the producer declares (or one that
+   * cannot be checked), and the problem otherwise.
+   */
+  bundlePathWarning(node, path) {
+    const remote = remoteBundlePath(path);
+    if (remote) {
+      const owner = this.getNode(remote.node);
+      const output = owner?.outputs.find((port) => port.name === remote.port);
+      if (output?.dataType !== "bundle") return void 0;
+      return `Expressions read bundle fields through a wire: connect ${remote.node}.${remote.port} to a bundle input here and read "${remote.port}.${remote.field}"`;
+    }
+    const reference = parseBundleFieldPath(path);
+    if (!reference) return void 0;
+    const input = node.inputs.find((port) => port.name === reference.port);
+    if (!input || input.dataType !== "bundle") return void 0;
+    const known = this.bundleFieldsFeeding(input);
+    if (!known || known.includes(reference.field)) return null;
+    return unknownFieldMessage(reference.field, known, `${node.id}.${reference.port}`);
+  }
+  /** The field names declared by whatever feeds a bundle input, or null. */
+  bundleFieldsFeeding(input) {
+    const connection = input.connections[0];
+    if (!connection) return null;
+    const port = this.getNode(connection.from.nodeId)?.getPort(connection.from.portId);
+    const fields = port?.options?.bundleFields;
+    return fields ? Object.keys(fields) : null;
+  }
+  /**
+   * Resolve a path from a node's context, returning both the node and optional parameter name
+   */
+  resolvePathFromNode(fromNode, path) {
+    const lastSlash = path.lastIndexOf("/");
+    let nodePath;
+    let parmName;
+    if (lastSlash > 0) {
+      const possibleParm = path.substring(lastSlash + 1);
+      const possibleNodePath = path.substring(0, lastSlash);
+      const asNode = fromNode.node(path);
+      if (asNode) {
+        return { node: asNode };
+      }
+      const parentNode = fromNode.node(possibleNodePath);
+      if (parentNode) {
+        return { node: parentNode, parmName: possibleParm };
+      }
+    }
+    return { node: fromNode.node(path) };
+  }
+  /**
+   * Try to suggest a fix for a broken path
+   */
+  suggestPathFix(fromNode, brokenPath) {
+    const segments = brokenPath.replace(/^\.?\.?\//, "").split("/");
+    const targetName = segments[segments.length - 1];
+    const allNodes = this.nodes;
+    const similar = allNodes.filter(
+      (n) => n.id.toLowerCase().includes(targetName.toLowerCase()) || targetName.toLowerCase().includes(n.id.toLowerCase())
+    );
+    if (similar.length > 0) {
+      const suggestion = similar[0];
+      return `Did you mean "${suggestion.path()}"?`;
+    }
+    return void 0;
+  }
+  toJSON() {
+    const result = {
+      version: GRAPH_FORMAT_VERSION,
+      metadata: {
+        name: this.project.name || "Cascade Graph",
+        created: this.createdAt,
+        modified: (/* @__PURE__ */ new Date()).toISOString(),
+        ...this.project.description ? { description: this.project.description } : {},
+        ...this.project.author ? { author: this.project.author } : {}
+      }
+    };
+    if (this.project.packages.length > 0) {
+      result.project = {
+        packages: this.project.packages.map((pkg) => ({
+          path: pkg.path,
+          alias: pkg.alias
+        }))
+      };
+    }
+    const resolverConfig = this.moduleResolver.exportConfig();
+    if (Object.keys(resolverConfig.embeddedModules).length > 0) {
+      result.embeddedModules = resolverConfig.embeddedModules;
+    }
+    if (Object.keys(resolverConfig.externalModules).length > 0) {
+      result.externalModules = resolverConfig.externalModules;
+    }
+    const packages = this.packageManager.getCachedPackages().map((pkg) => {
+      const [name, version] = pkg.split("@");
+      return { name, version: version || "latest" };
+    });
+    if (packages.length > 0) {
+      result.packages = packages;
+    }
+    const assets = this.assetManager.list().map((asset) => ({
+      id: asset.id,
+      path: asset.path,
+      type: asset.type,
+      size: asset.size
+    }));
+    if (assets.length > 0) {
+      result.assets = { manifest: assets };
+    }
+    const annotations = this.annotations;
+    const nodes = this.nodes;
+    if (annotations.length > 0) {
+      result.annotations = annotations.map((ann) => {
+        const serialized = {
+          id: ann.id,
+          type: ann.type,
+          position: [ann.position.x, ann.position.y]
+        };
+        const annAny = ann;
+        if (annAny.content !== void 0) serialized.content = annAny.content;
+        if (annAny.src !== void 0) serialized.src = annAny.src;
+        if (ann.size) serialized.size = ann.size;
+        if (annAny.points) serialized.points = annAny.points.map((p) => [p.x, p.y]);
+        if (annAny.endPosition) serialized.endPosition = [annAny.endPosition.x, annAny.endPosition.y];
+        if (ann.style) serialized.style = ann.style;
+        if (ann.caption !== void 0) serialized.caption = ann.caption;
+        if (ann.containedElements) serialized.containedElements = [...ann.containedElements];
+        if (ann.parent) serialized.parent = ann.parent.id;
+        return serialized;
+      });
+    }
+    result.nodes = nodes.map((n) => this.nodeToJSON(n));
+    const connections = this.connections.map((conn) => {
+      try {
+        const fromParsed = parsePortId(conn.from.portId);
+        const toParsed = parsePortId(conn.to.portId);
+        const fromElement = this.getElement(fromParsed.elementId);
+        const toElement = this.getElement(toParsed.elementId);
+        if (!fromElement || !toElement) return null;
+        const fromPort = fromElement.outputs?.[fromParsed.index];
+        const toPort = toElement.inputs?.[toParsed.index];
+        if (!fromPort || !toPort) return null;
+        return [
+          [fromParsed.elementId, fromParsed.index, fromPort.name],
+          [toParsed.elementId, toParsed.index, toPort.name]
+        ];
+      } catch (err) {
+        console.warn(`Failed to parse port ID in connection: ${err}`);
+        return null;
+      }
+    }).filter((conn) => conn !== null);
+    if (connections.length > 0) {
+      result.connections = connections;
+    }
+    if (this.editor) result.editor = this.editor;
+    if (this.seed !== void 0) result.seed = this.seed;
+    if (this.timeline) result.timeline = this.timeline;
+    return result;
+  }
+  /**
+   * Serialize a node with v0.2 source information
+   */
+  nodeToJSON(node) {
+    const nodeAny = node;
+    const fullType = nodeAny.modulePath || (node.type.includes(".") ? node.type : `cascade.image.${node.type}`);
+    let sourceType = nodeAny.sourceType;
+    if (!sourceType) {
+      if (isStandardLibraryNode(fullType)) {
+        sourceType = "stdlib";
+      } else if (fullType.startsWith("local.")) {
+        sourceType = "embedded";
+      } else {
+        sourceType = this.moduleResolver.getSourceType(fullType) || "embedded";
+      }
+    }
+    const result = {
+      id: node.id,
+      module: fullType,
+      position: [node.position.x, node.position.y],
+      source: sourceType
+    };
+    if (sourceType === "project") {
+      const config = this.moduleResolver.exportConfig();
+      const external = config.externalModules[fullType];
+      if (external) {
+        result.file = external.file;
+      }
+    }
+    if (result.source === "embedded" && node.code) {
+      result.code = node.code;
+    }
+    if (node.comment && node.comment.trim()) {
+      result.comment = node.comment;
+    }
+    if (node.color) {
+      result.color = node.color;
+    }
+    if (node.parent) {
+      result.parent = node.parent.id;
+    }
+    const rawParameterValue = (p) => node.rawParameterValue(p.name);
+    const changedParameters = (node.parameters ?? []).filter(
+      (p) => p.promoted || node.preservesPlainProp(p.name) || JSON.stringify(rawParameterValue(p)) !== JSON.stringify(p.defaultValue)
+    );
+    const parameters = changedParameters.filter((p) => p.documentField !== "props").map((p) => p.promoted ? { name: p.name, value: rawParameterValue(p), promoted: true } : { name: p.name, value: rawParameterValue(p) });
+    if (parameters.length > 0) {
+      result.params = parameters;
+    }
+    if (node.promotions?.length) {
+      result.promotions = node.promotions.map((entry) => ({
+        nodeId: entry.nodeId,
+        param: entry.param,
+        ...entry.label ? { label: entry.label } : {}
+      }));
+    }
+    const inputValues = node.inputs.filter((port) => (port.connections?.length ?? 0) === 0).filter((port) => port.value !== void 0 && port.value !== null).filter((port) => typeof port.value !== "function").map((port) => ({ name: port.name, defaultValue: port.value, dataType: port.dataType })).filter((port) => port.defaultValue !== "" || port.dataType === "string");
+    if (inputValues.length > 0) {
+      result.inputs = inputValues;
+    }
+    const props = Object.entries(node.props).reduce((acc, [key, prop]) => {
+      const keyed = (prop.channel?.keys?.length ?? 0) > 0;
+      if (prop.fromParameter && !prop.expression && !keyed) return acc;
+      let value = prop.value;
+      if (prop.type === "color" && isColorValue(value)) {
+        const normalized = normalizeColor(value);
+        value = [normalized.r, normalized.g, normalized.b, normalized.a ?? 1];
+      }
+      acc[key] = node.serializePropValue(key, value);
+      return acc;
+    }, {});
+    for (const parameter of changedParameters) {
+      if (parameter.documentField !== "props") continue;
+      props[parameter.name] = node.serializePropValue(
+        parameter.name,
+        node.rawParameterValue(parameter.name)
+      );
+    }
+    if (Object.keys(props).length > 0) {
+      result.props = props;
+    }
+    if (node.bypass) {
+      result.bypass = true;
+    }
+    if (node.cook) {
+      result.cook = true;
+    }
+    if (typeof node.serialize === "function") {
+      const nodeState = node.serialize();
+      if (nodeState && Object.keys(nodeState).length > 0) {
+        result.state = nodeState;
+      }
+    }
+    return result;
+  }
+  static fromJSON(json, assetManager, packageManager) {
+    const graph = new _Graph(assetManager, packageManager);
+    const version = json.version || "0.1";
+    if (typeof json.metadata?.created === "string") graph.createdAt = json.metadata.created;
+    if (json.editor && typeof json.editor === "object") graph.editor = json.editor;
+    if (Number.isInteger(json.seed)) graph.seed = json.seed;
+    if (json.timeline && typeof json.timeline === "object") graph.timeline = json.timeline;
+    graph.project = {
+      ...graph.project,
+      ...typeof json.metadata?.name === "string" ? { name: json.metadata.name } : {},
+      ...typeof json.metadata?.description === "string" ? { description: json.metadata.description } : {},
+      ...typeof json.metadata?.author === "string" ? { author: json.metadata.author } : {}
+    };
+    if (json.project) {
+      graph.project = {
+        ...graph.project,
+        name: json.metadata?.name ?? graph.project.name,
+        description: json.metadata?.description ?? graph.project.description,
+        author: json.metadata?.author ?? graph.project.author,
+        packages: json.project.packages || []
+      };
+      json.project.packages?.forEach((pkg) => {
+        graph.moduleResolver.addProjectPackage(pkg);
+      });
+    }
+    if (json.embeddedModules) {
+      graph.moduleResolver.importConfig({
+        embeddedModules: json.embeddedModules
+      });
+    }
+    if (json.externalModules) {
+      graph.moduleResolver.importConfig({
+        externalModules: json.externalModules
+      });
+    }
+    if (json.packages && Array.isArray(json.packages)) {
+    }
+    json.nodes.forEach((nodeData) => {
+      let nodeId = nodeData.id;
+      if (!nodeId) {
+        const baseId = nodeData.name || nodeData.type || nodeData.module;
+        nodeId = graph.generateUniqueNodeId(baseId);
+      } else {
+        let counter = 1;
+        let candidateId = nodeId;
+        while (graph.elements.some((e) => e.id === candidateId)) {
+          counter++;
+          candidateId = `${nodeId}${counter}`;
+        }
+        nodeId = candidateId;
+      }
+      const nodeType = nodeData.module || nodeData.type;
+      if (!nodeType || !nodeType.includes(".")) {
+        console.warn(`Invalid node type format: ${nodeType}. Expected package path (e.g., "cascade.image.Color"). Skipping node.`);
+        return;
+      }
+      const shortType = packagePathToType(nodeType);
+      const source = nodeData.source || (isStandardLibraryNode(nodeType) ? "stdlib" : "embedded");
+      let nodeCode = "";
+      if (source === "embedded") {
+        const embeddedModule = json.embeddedModules?.[nodeType];
+        nodeCode = embeddedModule?.code || nodeData.code || "";
+      } else if (source === "project") {
+        const externalModule = json.externalModules?.[nodeType];
+        nodeCode = externalModule?.cachedCode || nodeData.code || "";
+      }
+      const NodeClass = getNodeClass(nodeType);
+      let node;
+      if (NodeClass) {
+        node = new NodeClass(nodeId, graph);
+      } else if (nodeType.startsWith("cascade.")) {
+        throw new Error(`Unknown Cascade node type: ${nodeType}`);
+      } else {
+        node = new Node(nodeId, shortType, graph);
+      }
+      node.modulePath = nodeType;
+      node.sourceType = source;
+      if (Array.isArray(nodeData.position)) {
+        node.position = { x: nodeData.position[0] || 0, y: nodeData.position[1] || 0 };
+      } else if (nodeData.position && typeof nodeData.position === "object") {
+        node.position = { x: nodeData.position.x || 0, y: nodeData.position.y || 0 };
+      } else {
+        node.position = { x: 0, y: 0 };
+      }
+      node.code = nodeCode;
+      node.comment = nodeData.comment || "";
+      if (nodeData.color) node.color = nodeData.color;
+      if (Array.isArray(nodeData.params)) {
+        nodeData.params.forEach((saved) => {
+          if (!saved?.name) return;
+          const declared = node.parameters.find((parameter) => parameter.name === saved.name);
+          if (declared) {
+            declared.value = saved.value;
+            declared.promoted = Boolean(saved.promoted);
+          } else {
+            node.parameters.push({
+              name: saved.name,
+              value: saved.value,
+              defaultValue: saved.value,
+              dataType: "any",
+              promoted: Boolean(saved.promoted),
+              options: {}
+            });
+          }
+          if (saved.promoted) {
+            const port = node.in(saved.name, saved.value);
+            port.fromParameter = saved.name;
+          }
+        });
+      }
+      if (Array.isArray(nodeData.promotions)) {
+        node.promotions = nodeData.promotions.filter((entry) => entry?.nodeId && entry?.param).map((entry) => ({
+          nodeId: String(entry.nodeId),
+          param: String(entry.param),
+          ...entry.label ? { label: String(entry.label) } : {}
+        }));
+      }
+      graph.addElement(node);
+      const restoreInput = (name, value, hasValue, saved = {}) => {
+        if (!name) return;
+        const declared = node.inputs.find((port2) => port2.name === name);
+        const port = declared ?? node.in(
+          name,
+          hasValue ? value : void 0,
+          saved.dataType ? { type: saved.dataType } : {}
+        );
+        if (declared && hasValue) declared.value = value;
+        if (saved.id && port.id !== saved.id) port.id = saved.id;
+      };
+      if (Array.isArray(nodeData.inputs)) {
+        nodeData.inputs.forEach((saved) => {
+          if (!saved || typeof saved !== "object") return;
+          const hasDefault = Object.prototype.hasOwnProperty.call(saved, "defaultValue");
+          const hasValue = Object.prototype.hasOwnProperty.call(saved, "value");
+          restoreInput(
+            saved.name,
+            hasDefault ? saved.defaultValue : saved.value,
+            hasDefault || hasValue,
+            saved
+          );
+        });
+      } else if (nodeData.inputs && typeof nodeData.inputs === "object") {
+        Object.entries(nodeData.inputs).forEach(([name, value]) => {
+          restoreInput(name, value, true);
+        });
+      }
+      if (nodeData.outputs && Array.isArray(nodeData.outputs)) {
+        nodeData.outputs.forEach((portData) => {
+          const port = node.out(portData.name, portData.portType || "param");
+          if (portData.id && port.id !== portData.id) {
+            port.id = portData.id;
+          }
+        });
+      }
+      if (nodeData.props) {
+        Object.entries(nodeData.props).forEach(([key, propData]) => {
+          let value;
+          let expression;
+          if (propData && typeof propData === "object" && "value" in propData) {
+            value = propData.value;
+            expression = propData.expression;
+          } else {
+            value = propData;
+          }
+          let normalizedValue = value;
+          const declaredColor = node.props[key]?.type === "color";
+          if (isColorValue(value) && (declaredColor || !Array.isArray(value))) {
+            const normalized = normalizeColor(value);
+            normalizedValue = normalized.a !== void 0 && normalized.a !== 1 ? { r: normalized.r, g: normalized.g, b: normalized.b, a: normalized.a } : { r: normalized.r, g: normalized.g, b: normalized.b };
+          }
+          const definitionProp = node.parameters.find(
+            (parameter) => parameter.name === key && parameter.documentField === "props"
+          );
+          if (definitionProp) {
+            definitionProp.value = value;
+          } else if (!node.props[key]) {
+            node.props[key] = { value: normalizedValue };
+          } else {
+            node.props[key].value = normalizedValue;
+          }
+          if (expression && node.props[key]) {
+            node.props[key].expression = expression;
+          } else {
+            node.preservePlainProp(key);
+          }
+          if (!expression && node.props[key]?.expression) {
+            delete node.props[key].expression;
+            node.props[key] = { ...node.props[key] };
+          }
+          if (propData?.channel && node.props[key]) {
+            node.restorePropChannel(key, propData.channel);
+          }
+        });
+      }
+      if (nodeData.bypass !== void 0) {
+        node.setBypass(nodeData.bypass);
+      }
+      if (nodeData.cook !== void 0) {
+        node.setCook(nodeData.cook);
+      }
+      if (!NodeClass && (source === "project" || node.code)) {
+        const modulePromise = source === "project" ? loadProjectModule(nodeType) : loadEmbeddedModule(node.code);
+        node.setFunction(moduleNodeFunction(node, nodeType, modulePromise));
+        modulePromise.catch((err) => {
+          console.warn("Failed to compile node " + node.id + ":", err);
+        });
+      }
+      if (nodeData.state && typeof node.deserialize === "function") {
+        try {
+          node.deserialize(nodeData.state);
+        } catch (err) {
+          console.warn("Failed to deserialize state for node " + node.id + ":", err);
+        }
+      }
+    });
+    const connectionsToRestore = json.connections || [];
+    if (json.annotations && Array.isArray(json.annotations)) {
+      const annotations = json.annotations.map((annData) => {
+        let annotation;
+        const position = Array.isArray(annData.position) ? { x: annData.position[0] || 0, y: annData.position[1] || 0 } : { x: annData.position?.x || 0, y: annData.position?.y || 0 };
+        const normalizedType = annData.type.charAt(0).toUpperCase() + annData.type.slice(1).toLowerCase();
+        switch (normalizedType) {
+          case "Image":
+            annotation = new ImageAnnotation(annData.id, graph);
+            annotation.src = annData.src;
+            break;
+          case "Text":
+            annotation = new TextAnnotation(annData.id, graph);
+            annotation.content = annData.content;
+            break;
+          case "Group":
+            annotation = new GroupAnnotation(annData.id, graph);
+            annotation.content = annData.content;
+            break;
+          case "Line":
+            annotation = new LineAnnotation(annData.id, graph);
+            if (annData.endPosition) {
+              annotation.endPosition = Array.isArray(annData.endPosition) ? { x: annData.endPosition[0] || 0, y: annData.endPosition[1] || 0 } : { x: annData.endPosition.x || 0, y: annData.endPosition.y || 0 };
+            }
+            break;
+          case "Polyline":
+            annotation = new PolylineAnnotation(annData.id, graph);
+            if (annData.points) {
+              annotation.points = annData.points.map(
+                (p) => Array.isArray(p) ? { x: p[0] || 0, y: p[1] || 0 } : { x: p.x || 0, y: p.y || 0 }
+              );
+            }
+            break;
+          default:
+            annotation = new Annotation(annData.id, annData.type, graph);
+        }
+        annotation.position = position;
+        if (annData.size) annotation.size = { width: annData.size.width, height: annData.size.height };
+        if (annData.style) annotation.style = { ...annData.style };
+        if (annData.caption !== void 0) annotation.caption = annData.caption;
+        if (annData.containedElements) annotation.containedElements = annData.containedElements;
+        return annotation;
+      });
+      annotations.forEach((ann) => graph.addElement(ann));
+      graph._annotationPortsInitialized = Promise.all(
+        annotations.map((ann) => graph.initializeAnnotationPorts(ann))
+      ).catch((err) => {
+        console.error("Failed to initialize some annotation ports:", err);
+      });
+    } else {
+      graph._annotationPortsInitialized = Promise.resolve();
+    }
+    const authoredElements = [
+      ...Array.isArray(json.nodes) ? json.nodes : [],
+      ...Array.isArray(json.annotations) ? json.annotations : []
+    ];
+    graph.restoringHierarchy = true;
+    for (const elementData of authoredElements) {
+      if (typeof elementData?.parent !== "string") continue;
+      const child = graph.getElement(elementData.id);
+      const parent = graph.getElement(elementData.parent);
+      const warn = (reason) => console.warn(
+        `Parent link for "${elementData.id}" to "${elementData.parent}" ignored: ${reason}; element loaded at root.`
+      );
+      if (!child) continue;
+      if (!parent) {
+        warn("parent does not exist");
+        continue;
+      }
+      if (child === parent) {
+        warn("self-parenting is invalid");
+        continue;
+      }
+      if (!parent.isNetwork()) {
+        warn("parent is not a network");
+        continue;
+      }
+      let ancestor = parent;
+      let closesCycle = false;
+      const visited = /* @__PURE__ */ new Set();
+      while (ancestor && !visited.has(ancestor)) {
+        if (ancestor === child) {
+          closesCycle = true;
+          break;
+        }
+        visited.add(ancestor);
+        ancestor = ancestor.parent;
+      }
+      if (closesCycle) {
+        warn("parent cycle detected");
+        continue;
+      }
+      graph.reparentElement(child, parent);
+    }
+    graph.restoringHierarchy = false;
+    graph.pruneInvalidGroupMemberships();
+    const depth = (node) => {
+      let value = 0;
+      let parent = node.parent;
+      const visited = /* @__PURE__ */ new Set();
+      while (parent && !visited.has(parent)) {
+        visited.add(parent);
+        value++;
+        parent = parent.parent;
+      }
+      return value;
+    };
+    graph.nodes.filter((node) => node.isNetwork()).sort((left, right) => depth(right) - depth(left)).forEach((node) => node.syncPorts?.());
+    graph._connectionsToRestore = connectionsToRestore;
+    connectionsToRestore.forEach((connData) => {
+      graph.tryRestoreConnection(connData, false);
+    });
+    return graph;
+  }
+  async waitForAnnotationPorts() {
+    const initPromise = this._annotationPortsInitialized;
+    if (initPromise) {
+      await initPromise;
+    }
+  }
+  /**
+   * Try to restore a single connection from serialized data
+   * @internal
+   */
+  tryRestoreConnection(connData, checkDuplicates = false) {
+    if (!Array.isArray(connData) || !Array.isArray(connData[0]) || !Array.isArray(connData[1])) {
+      return false;
+    }
+    const [fromNodeId, fromPortIndex, fromPortName] = connData[0];
+    const [toNodeId, toPortIndex, toPortName] = connData[1];
+    if (typeof fromPortIndex !== "number" || typeof toPortIndex !== "number") {
+      return false;
+    }
+    const fromElement = this.getElement(fromNodeId);
+    const toElement = this.getElement(toNodeId);
+    if (!fromElement || !toElement) return false;
+    const byName = (ports, name) => typeof name === "string" ? ports?.find((p) => p.name === name) : void 0;
+    const resolve = (ports, name, index) => typeof name === "string" ? byName(ports, name) : ports?.[index];
+    const fromPort = resolve(fromElement.outputs, fromPortName, fromPortIndex);
+    const toPort = resolve(toElement.inputs, toPortName, toPortIndex);
+    if (!fromPort || !toPort) return false;
+    if (checkDuplicates) {
+      const exists = this.connections.some(
+        (c) => c.from.nodeId === fromNodeId && c.from.portId === fromPort.id && c.to.nodeId === toNodeId && c.to.portId === toPort.id
+      );
+      if (exists) return true;
+    }
+    try {
+      this.connect(fromPort, toPort);
+      return true;
+    } catch (err) {
+      console.warn(`[connect] ${fromNodeId}[${fromPortIndex}] -> ${toNodeId}[${toPortIndex}] rejected:`, err);
+      return false;
+    }
+  }
+  /**
+   * Restore connections that were stored during fromJSON
+   */
+  /**
+   * Bind the connections a loaded file described, and KEEP the ones that could
+   * not bind yet.
+   *
+   * A node's ports are created by running its code, so on load a connection
+   * into a node that hasn't executed has no port to attach to. This used to
+   * drop those connections on the floor — the pending list was deleted after
+   * one pass — which meant a graph of code-defined nodes came up almost
+   * entirely unwired, and nothing downstream of a source ever ran. Anything
+   * still unresolved stays pending, so calling this again after another cook
+   * finishes the job.
+   */
+  /**
+   * Node ids that a loaded file wires an input to, and whose connection has
+   * not bound yet.
+   *
+   * The reason this is public: **an input that is about to be connected is not
+   * an input that is missing**, and until now nothing could tell the two
+   * apart. On load a node's ports only exist once its code has run, so the
+   * first cook passes reach a node whose upstream edge has no port to attach
+   * to — the node runs with `undefined` on that input, throws whatever its
+   * author wrote for the unwired case, and a later pass then succeeds.
+   *
+   * The graph ends up correct and the log does not: those warm-up throws are
+   * real errors from the node's point of view, they are recorded, and they
+   * never clear. A user reported `volume-field` as broken on exactly this,
+   * having verified from the cache files that the output was in fact right.
+   *
+   * So the scheduler asks this before cooking, and treats a node with a
+   * pending inbound edge as *not ready* rather than as failed.
+   */
+  pendingConnectionTargets() {
+    const pending = this._connectionsToRestore;
+    const targets = /* @__PURE__ */ new Set();
+    if (this.connectionsSettled) return targets;
+    if (!Array.isArray(pending)) return targets;
+    for (const connection of pending) {
+      const target = Array.isArray(connection?.[1]) ? connection[1][0] : void 0;
+      if (typeof target === "string") targets.add(target);
+    }
+    return targets;
+  }
+  /** Called when the warm-up passes stop making progress. */
+  markConnectionsSettled() {
+    this.connectionsSettled = true;
+  }
+  restoreConnections() {
+    const connectionsToRestore = this._connectionsToRestore || [];
+    if (connectionsToRestore.length === 0) return;
+    const stillPending = connectionsToRestore.filter(
+      (connData) => !this.tryRestoreConnection(connData, true)
+    );
+    if (stillPending.length < connectionsToRestore.length) this.connectionsSettled = false;
+    if (stillPending.length > 0) {
+      this._connectionsToRestore = stillPending;
+    } else {
+      delete this._connectionsToRestore;
+    }
+  }
+};
+export {
+  GRAPH_FORMAT_VERSION,
+  Graph
+};
+//# sourceMappingURL=Graph-ZJJTRQTM.js.map