@particle-academy/fancy-flow 0.10.1 → 0.12.0

package/dist/{chunk-2DMBJN2O.js → chunk-D6W5FMCT.js}

@@ -1,5 +1,5 @@
 import { resolveNodePorts } from './chunk-TITD5W4Y.js';
-import { getNodeKind, defaultConfigFor, validateConfig } from './chunk-CPSOC27D.js';
+import { getNodeKind, defaultConfigFor, validateConfig } from './chunk-U5F22BHV.js';
 
 // src/schema/workflow-schema.ts
 var WORKFLOW_SCHEMA_VERSION = 1;
@@ -72,12 +72,13 @@ function importWorkflow(schema, options = {}) {
         issues.push({ level: "warning", nodeId: n.id, message: `${iss.key}: ${iss.message}` });
       }
     }
+    const kindId = kind?.name ?? n.kind;
     return {
       id: n.id,
-      type: n.kind,
+      type: kindId,
       position: { x: n.position?.x ?? 0, y: n.position?.y ?? 0 },
       data: {
-        kind: n.kind,
+        kind: kindId,
         label: n.label ?? kind?.label ?? n.kind,
         description: n.description,
         config,
@@ -115,5 +116,5 @@ function workflowToBlob(schema) {
 }
 
 export { WORKFLOW_SCHEMA_URL, WORKFLOW_SCHEMA_VERSION, exportWorkflow, importWorkflow, workflowToBlob };
-//# sourceMappingURL=chunk-2DMBJN2O.js.map
-//# sourceMappingURL=chunk-2DMBJN2O.js.map
+//# sourceMappingURL=chunk-D6W5FMCT.js.map
+//# sourceMappingURL=chunk-D6W5FMCT.js.map

package/dist/chunk-D6W5FMCT.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema/workflow-schema.ts"],"names":[],"mappings":"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","file":"chunk-D6W5FMCT.js","sourcesContent":["import type { FlowEdge, FlowGraph, FlowNode, PortDescriptor } from \"../types\";\nimport { defaultConfigFor, getNodeKind, validateConfig } from \"../registry/registry\";\nimport { resolveNodePorts } from \"../registry/ports\";\n\n/** Schema version. Bump on breaking shape changes; add migrations as needed. */\nexport const WORKFLOW_SCHEMA_VERSION = 1 as const;\nexport const WORKFLOW_SCHEMA_URL = \"https://particle.academy/schemas/workflow/v1.json\";\n\nexport type WorkflowSchema = {\n  $schema: typeof WORKFLOW_SCHEMA_URL;\n  version: typeof WORKFLOW_SCHEMA_VERSION;\n  metadata?: WorkflowMetadata;\n  graph: {\n    nodes: WorkflowSchemaNode[];\n    edges: WorkflowSchemaEdge[];\n  };\n  view?: {\n    viewport?: { x: number; y: number; zoom: number };\n  };\n};\n\nexport type WorkflowMetadata = {\n  id?: string;\n  name?: string;\n  description?: string;\n  createdAt?: number;\n  updatedAt?: number;\n  author?: string;\n  tags?: string[];\n};\n\nexport type WorkflowSchemaNode = {\n  id: string;\n  /** Registry kind name (e.g. \"memory_store\"). */\n  kind: string;\n  position: { x: number; y: number };\n  label?: string;\n  description?: string;\n  config?: Record<string, unknown>;\n  /**\n   * Resolved ports, written on export.\n   *\n   * A kind may derive its ports from config (`switch_case` cases,\n   * `llm_branch` routes), and that derivation is a JavaScript function — a\n   * runtime in another language cannot execute it. Without the resolved ports\n   * in the document, the PHP twin sees no declared outputs and falls back to a\n   * single `out`, so every branch edge in an exported flow silently stops\n   * firing. Serializing them keeps the schema self-describing and preserves\n   * the cross-runtime guarantee: same JSON in, same routing out.\n   *\n   * Optional and additive — a hand-written schema may omit them, and each\n   * runtime then falls back to its own kind registry.\n   */\n  inputs?: PortDescriptor[];\n  outputs?: PortDescriptor[];\n};\n\nexport type WorkflowSchemaEdge = {\n  id: string;\n  source: string;\n  target: string;\n  sourceHandle?: string;\n  targetHandle?: string;\n  label?: string;\n};\n\nexport type ImportIssue = {\n  level: \"error\" | \"warning\";\n  nodeId?: string;\n  edgeId?: string;\n  message: string;\n};\n\nexport type ImportResult = {\n  graph: FlowGraph;\n  issues: ImportIssue[];\n  /** True when the import produced a usable graph (errors may have been\n   *  rewritten to warnings via `lenient: true`). */\n  ok: boolean;\n};\n\n/** Snapshot the in-memory graph as a portable WorkflowSchema. */\nexport function exportWorkflow(\n  graph: FlowGraph,\n  metadata?: WorkflowMetadata,\n  view?: WorkflowSchema[\"view\"],\n): WorkflowSchema {\n  return {\n    $schema: WORKFLOW_SCHEMA_URL,\n    version: WORKFLOW_SCHEMA_VERSION,\n    metadata: metadata ? { ...metadata, updatedAt: Date.now() } : undefined,\n    graph: {\n      nodes: graph.nodes.map(toSchemaNode),\n      edges: graph.edges.map(toSchemaEdge),\n    },\n    view,\n  };\n}\n\nfunction toSchemaNode(n: FlowNode): WorkflowSchemaNode {\n  const data: any = n.data ?? {};\n  const kindName = data.kind ?? n.type ?? \"custom\";\n  // Resolve through the same helper the canvas and runtime use, so a\n  // config-driven kind writes its ACTUAL ports into the document instead of\n  // leaving another language's runtime to guess at them.\n  const ports = resolveNodePorts(n, getNodeKind(kindName) ?? undefined);\n  return {\n    id: n.id,\n    kind: kindName,\n    position: { x: n.position.x, y: n.position.y },\n    label: data.label,\n    description: data.description,\n    config: data.config,\n    inputs: ports.inputs,\n    outputs: ports.outputs,\n  };\n}\n\nfunction toSchemaEdge(e: FlowEdge): WorkflowSchemaEdge {\n  return {\n    id: e.id,\n    source: e.source,\n    target: e.target,\n    sourceHandle: e.sourceHandle ?? undefined,\n    targetHandle: e.targetHandle ?? undefined,\n    label: typeof e.label === \"string\" ? e.label : undefined,\n  };\n}\n\nexport type ImportOptions = {\n  /** When true, unknown kinds become warnings + a \"custom\" placeholder\n   *  instead of errors. Default false. */\n  lenient?: boolean;\n};\n\n/**\n * Hydrate a schema into runtime FlowGraph + validate kinds/configs against\n * the registry. Reports issues for unknown kinds, missing required config,\n * and dangling edges.\n */\nexport function importWorkflow(schema: unknown, options: ImportOptions = {}): ImportResult {\n  const issues: ImportIssue[] = [];\n  const lenient = options.lenient === true;\n\n  if (!schema || typeof schema !== \"object\") {\n    return { ok: false, graph: { nodes: [], edges: [] }, issues: [{ level: \"error\", message: \"Schema is not an object.\" }] };\n  }\n  const s = schema as Partial<WorkflowSchema>;\n  if (s.version !== WORKFLOW_SCHEMA_VERSION) {\n    issues.push({\n      level: lenient ? \"warning\" : \"error\",\n      message: `Unsupported workflow schema version: ${s.version} (expected ${WORKFLOW_SCHEMA_VERSION})`,\n    });\n    if (!lenient) return { ok: false, graph: { nodes: [], edges: [] }, issues };\n  }\n\n  const rawNodes = s.graph?.nodes ?? [];\n  const rawEdges = s.graph?.edges ?? [];\n\n  const nodes: FlowNode[] = rawNodes.map((n) => {\n    const kind = getNodeKind(n.kind);\n    if (!kind) {\n      issues.push({\n        level: lenient ? \"warning\" : \"error\",\n        nodeId: n.id,\n        message: `Unknown kind \"${n.kind}\" — register it before importing.`,\n      });\n    }\n    const config = n.config ?? (kind ? defaultConfigFor(kind) : {});\n    if (kind) {\n      for (const iss of validateConfig(kind, config)) {\n        issues.push({ level: \"warning\", nodeId: n.id, message: `${iss.key}: ${iss.message}` });\n      }\n    }\n    // Canonicalise on the way in: a document may carry a pre-namespace id, and\n    // rewriting it here means the graph converges on the canonical id the next\n    // time it is saved, rather than carrying the ambiguous name forever.\n    const kindId = kind?.name ?? n.kind;\n    return {\n      id: n.id,\n      type: kindId,\n      position: { x: n.position?.x ?? 0, y: n.position?.y ?? 0 },\n      data: {\n        kind: kindId,\n        label: n.label ?? kind?.label ?? n.kind,\n        description: n.description,\n        config,\n        // Carry serialized ports back onto the node so a round-trip is stable\n        // and an unknown kind still routes the way the document described.\n        ...(n.inputs ? { inputs: n.inputs } : {}),\n        ...(n.outputs ? { outputs: n.outputs } : {}),\n      } as any,\n    };\n  });\n\n  const nodeIds = new Set(nodes.map((n) => n.id));\n  const edges: FlowEdge[] = rawEdges\n    .map((e) => {\n      if (!nodeIds.has(e.source)) {\n        issues.push({ level: \"warning\", edgeId: e.id, message: `Edge source \"${e.source}\" not found.` });\n        return null;\n      }\n      if (!nodeIds.has(e.target)) {\n        issues.push({ level: \"warning\", edgeId: e.id, message: `Edge target \"${e.target}\" not found.` });\n        return null;\n      }\n      return {\n        id: e.id,\n        source: e.source,\n        target: e.target,\n        sourceHandle: e.sourceHandle,\n        targetHandle: e.targetHandle,\n        label: e.label,\n      } as FlowEdge;\n    })\n    .filter((e): e is FlowEdge => e !== null);\n\n  const ok = issues.every((i) => i.level !== \"error\");\n  return { ok, graph: { nodes, edges }, issues };\n}\n\n/** Convenience: serialize a schema as a downloadable JSON Blob. */\nexport function workflowToBlob(schema: WorkflowSchema): Blob {\n  return new Blob([JSON.stringify(schema, null, 2)], { type: \"application/json\" });\n}\n"]}

package/dist/{chunk-NCPQDVUE.js → chunk-IK5DS5JP.js}

@@ -1,10 +1,162 @@
 import { Handle, Position } from './chunk-NF6NPY5N.js';
+import { runFlow } from './chunk-L4AX73Q6.js';
 import { resolveNodePorts, nodeConfig } from './chunk-TITD5W4Y.js';
-import { getNodeKind, categoryAccent, registerNodeKind, listNodeKinds } from './chunk-CPSOC27D.js';
+import { getNodeKind, categoryAccent, registerNodeKind, listNodeKinds, kindIds } from './chunk-U5F22BHV.js';
 import { RichInputPreview } from './chunk-F5RPRB7A.js';
 import { memo, useMemo, createElement } from 'react';
 import { jsxs, jsx } from 'react/jsx-runtime';
 
+// src/registry/capabilities.ts
+var llmClient = null;
+function registerLlmClient(client) {
+  llmClient = client;
+  return () => {
+    if (llmClient === client) llmClient = null;
+  };
+}
+function getLlmClient() {
+  return llmClient;
+}
+var workflowResolver = null;
+function registerWorkflowResolver(resolver) {
+  workflowResolver = resolver;
+  return () => {
+    if (workflowResolver === resolver) workflowResolver = null;
+  };
+}
+function getWorkflowResolver() {
+  return workflowResolver;
+}
+function capabilityStatus() {
+  let documentReady = false;
+  try {
+    documentReady = Boolean(globalThis.__fancyFlowDocumentAdapter);
+  } catch {
+    documentReady = false;
+  }
+  return {
+    llm: llmClient !== null,
+    workflow_resolver: workflowResolver !== null,
+    document: documentReady
+  };
+}
+
+// src/registry/subflow.ts
+var DEFAULT_MAX_DEPTH = 8;
+function subflowMode(config) {
+  const mode = config.mode;
+  return mode === "stream" || mode === "both" ? mode : "output";
+}
+function subflowPorts(config) {
+  const mode = subflowMode(config);
+  const ports = [{ id: "out", label: "result" }];
+  if (mode === "stream" || mode === "both") ports.unshift({ id: "stream", label: "stream" });
+  return ports;
+}
+var subflowExecutor = async (ctx) => {
+  const config = ctx.node.data?.config ?? {};
+  const ref = String(config.workflow ?? "").trim();
+  if (!ref) ctx.abort("subflow has no workflow reference configured");
+  const resolver = getWorkflowResolver();
+  if (!resolver) {
+    ctx.abort(
+      "No workflow resolver registered. Call registerWorkflowResolver() so subflow can find the workflow it references."
+    );
+  }
+  const maxDepth = Number.isFinite(config.maxDepth) ? Number(config.maxDepth) : DEFAULT_MAX_DEPTH;
+  const depth = ctx.depth ?? 0;
+  if (depth + 1 > maxDepth) {
+    ctx.abort(
+      `subflow depth limit reached (${maxDepth}) at "${ref}" \u2014 a workflow is referencing itself, directly or through a chain.`
+    );
+  }
+  const child = await resolver(ref);
+  if (!child) ctx.abort(`subflow could not resolve workflow "${ref}"`);
+  const mode = subflowMode(config);
+  const streaming = mode === "stream" || mode === "both";
+  const forward = (event) => {
+    if (!streaming) return;
+    const detail = event.type === "node-status" ? `${event.nodeId} ${event.status}` : event.type === "run-end" ? `finished (${event.ok ? "ok" : "failed"})` : event.type;
+    ctx.emit({
+      type: "log",
+      nodeId: ctx.node.id,
+      level: "info",
+      message: `[${ref}] ${detail}`
+    });
+  };
+  const result = await runFlow(
+    child,
+    config.executors ?? {},
+    forward,
+    {
+      initialInputs: config.inputs ?? {
+        // With no explicit mapping, hand the parent's inputs to the child's
+        // entry points — the obvious default, and it makes the simple case
+        // require no configuration at all.
+        __parent: ctx.inputs
+      },
+      depth: depth + 1
+    }
+  );
+  if (!result.ok) {
+    ctx.abort(`subflow "${ref}" failed: ${result.error ?? "unknown error"}`);
+  }
+  if (mode === "stream") {
+    return { __port: "stream", value: result.outputs };
+  }
+  if (mode === "both") {
+    return result.outputs;
+  }
+  return { __port: "out", value: result.outputs };
+};
+
+// src/registry/llm-branch.ts
+function declaredRoutes(config) {
+  const raw = config.routes;
+  if (!Array.isArray(raw)) return [];
+  return raw.map((r) => ({ port: String(r?.port ?? "").trim(), description: r?.description })).filter((r) => r.port !== "");
+}
+function resolveFallbackPort(routes, fallbackEnabled) {
+  if (fallbackEnabled) return "fallback";
+  return routes[0]?.port ?? "out";
+}
+var llmBranchExecutor = async (ctx) => {
+  const config = ctx.node.data?.config ?? {};
+  const routes = declaredRoutes(config);
+  if (routes.length === 0) {
+    ctx.abort("llm_branch has no routes configured");
+  }
+  const client = getLlmClient();
+  if (!client) {
+    ctx.abort(
+      "No LLM client registered. Call registerLlmClient() with your provider adapter \u2014 fancy-flow ships the routing, not the model call."
+    );
+  }
+  const fallbackEnabled = config.fallback !== false;
+  const choice = await client.chooseRoute({
+    system: typeof config.system === "string" ? config.system : void 0,
+    prompt: String(config.prompt ?? ctx.inputs ?? ""),
+    routes,
+    provider: typeof config.provider === "string" ? config.provider : void 0,
+    model: typeof config.model === "string" ? config.model : void 0,
+    credential: typeof config.credential === "string" ? config.credential : void 0
+  });
+  const offered = new Set(routes.map((r) => r.port));
+  let port = choice?.port ?? "";
+  let reason = choice?.reason;
+  if (!offered.has(port)) {
+    const safe = resolveFallbackPort(routes, fallbackEnabled);
+    ctx.emit({
+      type: "log",
+      nodeId: ctx.node.id,
+      level: "warn",
+      message: `llm_branch: model returned "${port || "(nothing)"}", which is not a declared route. Routing to "${safe}".`
+    });
+    reason = reason ?? `unrecognised route "${port}"`;
+    port = safe;
+  }
+  return { __port: port, value: { route: port, reason, input: ctx.inputs } };
+};
 function RegistryNodeInner(props) {
   const kindName = props.data.kind ?? props.type;
   const kind = useMemo(() => getNodeKind(kindName), [kindName]);
@@ -163,7 +315,8 @@ var HTTP_METHODS = [
 var KINDS = [
   // ───────────── Triggers ─────────────
   {
-    name: "manual_trigger",
+    name: "@particle-academy/manual_trigger",
+    aliases: ["manual_trigger", "@fancy/manual_trigger"],
     category: "trigger",
     label: "Manual",
     description: "Entry point fired when the user clicks Run.",
@@ -172,7 +325,8 @@ var KINDS = [
     outputs: [{ id: "out" }]
   },
   {
-    name: "webhook_trigger",
+    name: "@particle-academy/webhook_trigger",
+    aliases: ["webhook_trigger", "@fancy/webhook_trigger"],
     category: "trigger",
     label: "Webhook",
     description: "Triggered by an inbound HTTP request to a host-provided URL.",
@@ -189,7 +343,8 @@ var KINDS = [
     ]
   },
   {
-    name: "schedule_trigger",
+    name: "@particle-academy/schedule_trigger",
+    aliases: ["schedule_trigger", "@fancy/schedule_trigger"],
     category: "trigger",
     label: "Schedule",
     description: "Fires on a cron schedule (host-implemented).",
@@ -209,7 +364,8 @@ var KINDS = [
     ]
   },
   {
-    name: "user_input",
+    name: "@particle-academy/user_input",
+    aliases: ["user_input", "@fancy/user_input"],
     category: "human",
     label: "User Input",
     description: "Pause the flow until the user submits the configured form.",
@@ -249,7 +405,8 @@ var KINDS = [
     ]
   },
   {
-    name: "rich_user_input",
+    name: "@particle-academy/rich_user_input",
+    aliases: ["rich_user_input", "@fancy/rich_user_input"],
     category: "human",
     label: "Rich User Input",
     description: "Pause the flow on a fully authored page \u2014 content, required reading, multi-section forms.",
@@ -272,9 +429,61 @@ var KINDS = [
     // what the person hitting this step will actually see.
     renderBody: (ctx) => createElement(RichInputPreview, { config: ctx.config ?? {} })
   },
+  {
+    name: "@particle-academy/subflow",
+    aliases: ["subflow", "@fancy/subflow"],
+    category: "logic",
+    label: "SubFlow",
+    description: "Run another workflow and bring its result \u2014 or its live progress \u2014 back into this one.",
+    icon: "\u29C9",
+    inputs: [{ id: "in" }],
+    // The stream port only exists when something actually streams.
+    outputs: (config) => subflowPorts(config ?? {}),
+    // Core, not marketplace: it runs a child graph through this same engine and
+    // needs nothing from outside except where workflows live.
+    executor: subflowExecutor,
+    configSchema: [
+      {
+        type: "text",
+        key: "workflow",
+        label: "Workflow",
+        required: true,
+        placeholder: "onboarding-v2",
+        description: "Reference resolved by the host's registerWorkflowResolver()."
+      },
+      {
+        type: "select",
+        key: "mode",
+        label: "Return",
+        default: "output",
+        options: [
+          { value: "output", label: "Output when it finishes" },
+          { value: "stream", label: "Stream progress as it runs" },
+          { value: "both", label: "Both \u2014 stream, then output" }
+        ],
+        description: "Streaming adds a second port so a parent can show progress instead of a spinner."
+      },
+      {
+        type: "json",
+        key: "inputs",
+        label: "Input mapping",
+        description: "Entry-point inputs for the child run. Omit to pass this node's inputs straight through."
+      },
+      {
+        type: "number",
+        key: "maxDepth",
+        label: "Max nesting depth",
+        default: DEFAULT_MAX_DEPTH,
+        min: 1,
+        max: 32,
+        description: "Guards against a workflow referencing itself."
+      }
+    ]
+  },
   // ───────────── Logic ─────────────
   {
-    name: "branch",
+    name: "@particle-academy/branch",
+    aliases: ["branch", "@fancy/branch"],
     category: "logic",
     label: "Branch",
     description: "Multi-way branch on a condition or value.",
@@ -286,7 +495,8 @@ var KINDS = [
     ]
   },
   {
-    name: "switch_case",
+    name: "@particle-academy/switch_case",
+    aliases: ["switch_case", "@fancy/switch_case"],
     category: "logic",
     label: "Switch",
     description: "Route to one of N labelled outputs based on a key.",
@@ -313,7 +523,8 @@ var KINDS = [
     ]
   },
   {
-    name: "for_each",
+    name: "@particle-academy/for_each",
+    aliases: ["for_each", "@fancy/for_each"],
     category: "logic",
     label: "For Each",
     description: "Iterate over a list, emitting each item on `item`.",
@@ -326,7 +537,8 @@ var KINDS = [
     ]
   },
   {
-    name: "merge",
+    name: "@particle-academy/merge",
+    aliases: ["merge", "@fancy/merge"],
     category: "logic",
     label: "Merge",
     description: "Combine multiple inputs into one object or array.",
@@ -344,7 +556,8 @@ var KINDS = [
     ]
   },
   {
-    name: "wait",
+    name: "@particle-academy/wait",
+    aliases: ["wait", "@fancy/wait"],
     category: "logic",
     label: "Wait",
     description: "Sleep or wait for an external event.",
@@ -361,7 +574,8 @@ var KINDS = [
     ]
   },
   {
-    name: "transform",
+    name: "@particle-academy/transform",
+    aliases: ["transform", "@fancy/transform"],
     category: "logic",
     label: "Transform",
     description: "Reshape data with an expression.",
@@ -378,7 +592,8 @@ var KINDS = [
   },
   // ───────────── Data ─────────────
   {
-    name: "memory_store",
+    name: "@particle-academy/memory_store",
+    aliases: ["memory_store", "@fancy/memory_store"],
     category: "data",
     label: "Memory Store",
     description: "Read or write per-conversation memory.",
@@ -398,7 +613,8 @@ var KINDS = [
     ]
   },
   {
-    name: "data_store",
+    name: "@particle-academy/data_store",
+    aliases: ["data_store", "@fancy/data_store"],
     category: "data",
     label: "Data Store",
     description: "Key-value or table read/write against a host store.",
@@ -426,7 +642,8 @@ var KINDS = [
     ]
   },
   {
-    name: "variable",
+    name: "@particle-academy/variable",
+    aliases: ["variable", "@fancy/variable"],
     category: "data",
     label: "Variable",
     description: "Workflow-scoped value used by other nodes.",
@@ -438,7 +655,8 @@ var KINDS = [
   },
   // ───────────── AI ─────────────
   {
-    name: "llm_call",
+    name: "@particle-academy/llm_call",
+    aliases: ["llm_call", "@fancy/llm_call"],
     category: "ai",
     label: "LLM Call",
     description: "Send a prompt + context to a model and receive a response.",
@@ -465,7 +683,8 @@ var KINDS = [
     ]
   },
   {
-    name: "llm_branch",
+    name: "@particle-academy/llm_branch",
+    aliases: ["llm_branch", "@fancy/llm_branch"],
     category: "ai",
     label: "LLM Router",
     description: "Let a model choose which route the flow takes.",
@@ -474,6 +693,10 @@ var KINDS = [
     // Each declared route is a port. The executor returns `{ __port: id }`
     // (or `Port.only(id)` on the PHP runtime) to pick one.
     outputs: (config) => routePorts(config?.routes, config?.fallback),
+    // A shuttle, not an engine: it carries the routes out to whatever LLM
+    // client the host registered and carries the choice back. No provider SDK
+    // reaches core, so this stays a builtin without adding a dependency.
+    executor: llmBranchExecutor,
     configSchema: [
       {
         type: "textarea",
@@ -535,7 +758,8 @@ var KINDS = [
     ]
   },
   {
-    name: "tool_use",
+    name: "@particle-academy/tool_use",
+    aliases: ["tool_use", "@fancy/tool_use"],
     category: "ai",
     label: "Tool Use",
     description: "Hand control to a host-registered tool by name.",
@@ -546,7 +770,8 @@ var KINDS = [
     ]
   },
   {
-    name: "embed_search",
+    name: "@particle-academy/embed_search",
+    aliases: ["embed_search", "@fancy/embed_search"],
     category: "ai",
     label: "Embed & Search",
     description: "Embed a query and search a vector store.",
@@ -559,7 +784,8 @@ var KINDS = [
   },
   // ───────────── IO ─────────────
   {
-    name: "api_request",
+    name: "@particle-academy/api_request",
+    aliases: ["api_request", "@fancy/api_request"],
     category: "io",
     label: "API Request",
     description: "HTTP request to any URL.",
@@ -573,7 +799,8 @@ var KINDS = [
     ]
   },
   {
-    name: "webhook_out",
+    name: "@particle-academy/webhook_out",
+    aliases: ["webhook_out", "@fancy/webhook_out"],
     category: "io",
     label: "Send Webhook",
     description: "POST a payload to a configured URL.",
@@ -586,7 +813,8 @@ var KINDS = [
   },
   // ───────────── Human ─────────────
   {
-    name: "human_approval",
+    name: "@particle-academy/human_approval",
+    aliases: ["human_approval", "@fancy/human_approval"],
     category: "human",
     label: "Human Approval",
     description: "Pause until a human approves or denies.",
@@ -600,7 +828,8 @@ var KINDS = [
     ]
   },
   {
-    name: "notify",
+    name: "@particle-academy/notify",
+    aliases: ["notify", "@fancy/notify"],
     category: "human",
     label: "Notify",
     description: "Send a message via Slack / email / SMS / etc.",
@@ -624,7 +853,8 @@ var KINDS = [
   },
   // ───────────── Output ─────────────
   {
-    name: "output",
+    name: "@particle-academy/output",
+    aliases: ["output", "@fancy/output"],
     category: "output",
     label: "Output",
     description: "Terminal node \u2014 captures the workflow's result.",
@@ -633,7 +863,8 @@ var KINDS = [
     outputs: []
   },
   {
-    name: "log",
+    name: "@particle-academy/log",
+    aliases: ["log", "@fancy/log"],
     category: "output",
     label: "Log",
     description: "Send to the run feed.",
@@ -660,10 +891,12 @@ var BUILTIN_KINDS = KINDS;
 // src/registry/index.ts
 function buildNodeTypes() {
   const map = {};
-  for (const k of listNodeKinds()) map[k.name] = RegistryNode;
+  for (const k of listNodeKinds()) {
+    for (const id of kindIds(k)) map[id] = RegistryNode;
+  }
   return map;
 }
 
-export { BUILTIN_KINDS, RegistryNode, buildNodeTypes, registerBuiltinKinds };
-//# sourceMappingURL=chunk-NCPQDVUE.js.map
-//# sourceMappingURL=chunk-NCPQDVUE.js.map
+export { BUILTIN_KINDS, DEFAULT_MAX_DEPTH, RegistryNode, buildNodeTypes, capabilityStatus, declaredRoutes, getLlmClient, getWorkflowResolver, llmBranchExecutor, registerBuiltinKinds, registerLlmClient, registerWorkflowResolver, resolveFallbackPort, subflowExecutor, subflowMode, subflowPorts };
+//# sourceMappingURL=chunk-IK5DS5JP.js.map
+//# sourceMappingURL=chunk-IK5DS5JP.js.map