[breadboard] Support [graphurl]#module:{moduleId} URL syntax.

- **Teach loader and runner about `[graphurl]#module:{id}` URLs.**
- **docs(changeset): Support `[graphurl]#module:{moduleId}` URL
syntax.**

Fixes #3977 and #3843.

.changeset/orange-toes-decide.md

@@ -0,0 +1,6 @@
+---
+"@google-labs/breadboard": minor
+"@breadboard-ai/shared-ui": minor
+---
+
+Support `[graphurl]#module:{moduleId}` URL syntax.

packages/breadboard/src/loader/loader.ts

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { ModuleIdentifier } from "@breadboard-ai/types";
 import type { GraphDescriptor, GraphToRun } from "../types.js";
 import type {
   GraphProvider,
@@ -17,7 +18,13 @@ export const SENTINEL_BASE_URL = new URL("sentinel://sentinel/sentinel");
 export { resolveGraph };
 
 function resolveGraph(graphToRun: GraphToRun): GraphDescriptor {
-  const { graph, subGraphId } = graphToRun;
+  const { graph, subGraphId, moduleId } = graphToRun;
+  if (moduleId) {
+    const url = graph.url?.startsWith("module:")
+      ? graph.url
+      : `module:${moduleId}:${graph.url}`;
+    return { ...graph, main: moduleId, url };
+  }
   return subGraphId ? graph.graphs![subGraphId] : graph;
 }
 
@@ -39,6 +46,8 @@ export const baseURLFromContext = (context: GraphLoaderContext) => {
   return SENTINEL_BASE_URL;
 };
 
+const MODULE_PREFIX = "module:";
+
 export class Loader implements GraphLoader {
   #graphProviders: GraphProvider[];
 
@@ -76,6 +85,24 @@ export class Loader implements GraphLoader {
     hash: string,
     supergraph: GraphDescriptor
   ): GraphLoaderResult {
+    const isModule = hash.startsWith(MODULE_PREFIX);
+    if (isModule) {
+      const modules = supergraph.modules;
+      const moduleId: ModuleIdentifier = hash.slice(MODULE_PREFIX.length);
+      if (!modules) {
+        const error = `No modules to load "${moduleId}" from`;
+        console.warn(error);
+        return { success: false, error };
+      }
+      const module = modules[moduleId];
+      if (!module) {
+        const error = `No module found for module ID: ${moduleId}`;
+        console.warn(error);
+        return { success: false, error };
+      }
+      return { success: true, graph: supergraph, moduleId };
+    }
+
     const subgraphs = supergraph.graphs;
     if (!subgraphs) {
       const error = `No subgraphs to load "#${hash}" from`;

packages/breadboard/src/run/run-graph.ts

@@ -42,6 +42,7 @@ export async function* runGraph(
 
   if (isImperativeGraph(graph)) {
     graph = toDeclarativeGraph(graph);
+    graphToRun = { graph };
   }
 
   const lifecycle = state?.lifecycle();

packages/breadboard/src/types.ts

@@ -20,6 +20,7 @@ import type {
   TraversalResult,
   Probe,
   GraphIdentifier,
+  ModuleIdentifier,
 } from "@breadboard-ai/types";
 import { GraphLoader } from "./loader/types.js";
 import { DataStore } from "./data/types.js";
@@ -729,4 +730,5 @@ export type ConfigOrGraph =
 export type GraphToRun = {
   graph: GraphDescriptor;
   subGraphId?: GraphIdentifier;
+  moduleId?: ModuleIdentifier;
 };

packages/shared-ui/src/elements/editor/editor.ts

@@ -359,8 +359,10 @@ export class Editor extends LitElement implements DragConnectorReceiver {
     const pushReference = (
       nodeId: NodeIdentifier,
       portId: PortIdentifier,
-      reference: string | BreadboardCapability
+      reference: string | BreadboardCapability | null
     ) => {
+      if (!reference) return;
+
       if (typeof reference === "object") {
         if (isGraphDescriptorCapability(reference)) {
           return;