@particle-academy/fancy-flow 0.24.0 → 0.26.0

package/dist/index.cjs

@@ -1870,6 +1870,8 @@ function categoryAccent(category) {
       return "#a855f7";
     case "layout":
       return "#64748b";
+    case "annotation":
+      return "#eab308";
     default:
       return "#71717a";
   }
@@ -10976,6 +10978,88 @@ function LaneNodeInner(props) {
   );
 }
 var LaneNode = ReactExports.memo(LaneNodeInner);
+var FlowEditorContext = ReactExports.createContext(null);
+var FlowEditorProvider = FlowEditorContext.Provider;
+function useFlowEditor() {
+  const api = ReactExports.useContext(FlowEditorContext);
+  if (api === null) {
+    throw new Error("useFlowEditor() must be called inside <FlowEditor>.");
+  }
+  return api;
+}
+function useFlowEditorOptional() {
+  return ReactExports.useContext(FlowEditorContext);
+}
+var NOTE_COLORS = {
+  amber: { bg: "rgba(234, 179, 8, 0.14)", border: "rgba(234, 179, 8, 0.55)", title: "#a16207" },
+  sky: { bg: "rgba(14, 165, 233, 0.12)", border: "rgba(14, 165, 233, 0.5)", title: "#0369a1" },
+  violet: { bg: "rgba(139, 92, 246, 0.13)", border: "rgba(139, 92, 246, 0.5)", title: "#6d28d9" },
+  emerald: { bg: "rgba(16, 185, 129, 0.13)", border: "rgba(16, 185, 129, 0.5)", title: "#047857" },
+  rose: { bg: "rgba(244, 63, 94, 0.12)", border: "rgba(244, 63, 94, 0.5)", title: "#be123c" },
+  slate: { bg: "rgba(100, 116, 139, 0.12)", border: "rgba(100, 116, 139, 0.5)", title: "#475569" }
+};
+function coerceColor(v2) {
+  return typeof v2 === "string" && v2 in NOTE_COLORS ? v2 : "amber";
+}
+function NoteNodeInner(props) {
+  const data = props.data;
+  const config = data.config ?? {};
+  const api = useFlowEditorOptional();
+  const hasConfigText = typeof config.text === "string" && config.text.length > 0;
+  const text = hasConfigText ? String(config.text) : typeof data.body === "string" ? data.body : typeof data.text === "string" ? data.text : "";
+  const title = typeof config.title === "string" && config.title || (!hasConfigText && typeof data.body === "string" && typeof data.label === "string" ? data.label : "");
+  const skin = NOTE_COLORS[coerceColor(config.color)];
+  const [editing, setEditing] = ReactExports.useState(false);
+  const [draft, setDraft] = ReactExports.useState(text);
+  const areaRef = ReactExports.useRef(null);
+  ReactExports.useEffect(() => {
+    if (editing && areaRef.current) {
+      const el = areaRef.current;
+      el.focus();
+      el.setSelectionRange(el.value.length, el.value.length);
+    }
+  }, [editing]);
+  const commit = () => {
+    setEditing(false);
+    if (!api || draft === text) return;
+    const current = api.nodes.find((n) => n.id === props.id);
+    if (!current) return;
+    api.updateNode({
+      ...current,
+      data: { ...current.data, config: { ...config, text: draft } }
+    });
+  };
+  return /* @__PURE__ */ jsxRuntime.jsxs(
+    "div",
+    {
+      className: ["ff-note", props.selected ? "ff-note--selected" : ""].filter(Boolean).join(" "),
+      style: { background: skin.bg, borderColor: skin.border },
+      onDoubleClick: api ? () => {
+        setDraft(text);
+        setEditing(true);
+      } : void 0,
+      children: [
+        /* @__PURE__ */ jsxRuntime.jsx(NodeResizer, { isVisible: props.selected ?? false, color: skin.border, minWidth: 140, minHeight: 80 }),
+        title && /* @__PURE__ */ jsxRuntime.jsx("div", { className: "ff-note__title", style: { color: skin.title }, children: title }),
+        editing ? /* @__PURE__ */ jsxRuntime.jsx(
+          "textarea",
+          {
+            ref: areaRef,
+            className: "ff-note__input nodrag nowheel",
+            value: draft,
+            onChange: (e) => setDraft(e.target.value),
+            onBlur: commit,
+            onKeyDown: (e) => {
+              if (e.key === "Escape") setEditing(false);
+              if (e.key === "Enter" && (e.metaKey || e.ctrlKey)) commit();
+            }
+          }
+        ) : /* @__PURE__ */ jsxRuntime.jsx("div", { className: "ff-note__body", children: text || /* @__PURE__ */ jsxRuntime.jsx("span", { className: "ff-note__placeholder", children: api ? "Double-click to write a note\u2026" : "Note" }) })
+      ]
+    }
+  );
+}
+var NoteNode = ReactExports.memo(NoteNodeInner);
 
 // src/registry/capabilities.ts
 var llmClient = null;
@@ -11091,12 +11175,14 @@ async function runFlow(graph, executors, onEvent = () => {
         }
       }
       const visualKind = getNodeKind(node.type ?? "");
-      if (node.type === "note" || visualKind?.category === "layout") {
+      const isLayout = visualKind?.category === "layout";
+      const isAnnotation = node.type === "note" || visualKind?.category === "annotation";
+      if (isLayout || isAnnotation) {
         onEvent({
           type: "node-status",
           nodeId: node.id,
           status: "idle",
-          text: visualKind?.category === "layout" ? "lane" : "annotation"
+          text: isLayout ? "lane" : "annotation"
         });
         continue;
       }
@@ -12053,6 +12139,35 @@ var KINDS = [
     defaultConfig: { title: "Lane", orientation: "horizontal" },
     resizable: { minWidth: 160, minHeight: 72 },
     component: LaneNode
+  },
+  {
+    // Note — a sticky-note annotation. Portless + visual-only: the runtime skips
+    // the `annotation` category, so a note's text NEVER reaches a runner — it
+    // rides in the document purely for people, editors, and MCP tools. Uses its
+    // own renderer (NoteNode); double-click on the canvas to edit in place.
+    name: "@particle-academy/note",
+    aliases: ["note", "@fancy/note"],
+    category: "annotation",
+    label: "Note",
+    description: "A sticky note that documents the canvas. Never runs \u2014 editor + agent only.",
+    icon: "\u{1F5D2}",
+    inputs: [],
+    outputs: [],
+    configSchema: [
+      { type: "text", key: "title", label: "Title", placeholder: "Optional heading" },
+      { type: "textarea", key: "text", label: "Note", rows: 5, placeholder: "What does this part of the flow do?" },
+      { type: "select", key: "color", label: "Color", default: "amber", options: [
+        { value: "amber", label: "Amber" },
+        { value: "sky", label: "Sky" },
+        { value: "violet", label: "Violet" },
+        { value: "emerald", label: "Emerald" },
+        { value: "rose", label: "Rose" },
+        { value: "slate", label: "Slate" }
+      ] }
+    ],
+    defaultConfig: { text: "", color: "amber" },
+    resizable: { minWidth: 140, minHeight: 80 },
+    component: NoteNode
   }
 ];
 function registerBuiltinKinds() {
@@ -12151,14 +12266,6 @@ function OutputNodeInner(props) {
   return /* @__PURE__ */ jsxRuntime.jsx(NodeShell, { node: props, accent: "#a855f7", tag: "OUTPUT", icon: "\u25CF", showOutputs: false });
 }
 var OutputNode2 = ReactExports.memo(OutputNodeInner);
-function NoteNodeInner({ data, selected: selected2 }) {
-  const noteData = data;
-  return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: `ff-note ${selected2 ? "ff-note--selected" : ""}`, children: [
-    noteData.label && /* @__PURE__ */ jsxRuntime.jsx("div", { className: "ff-note__title", children: noteData.label }),
-    noteData.body && /* @__PURE__ */ jsxRuntime.jsx("p", { className: "ff-note__body", children: noteData.body })
-  ] });
-}
-var NoteNode = ReactExports.memo(NoteNodeInner);
 function SubgraphNodeInner(props) {
   const data = props.data;
   const childCount = data.childIds?.length ?? 0;
@@ -12545,7 +12652,7 @@ function FlowCanvas({
     }
   );
 }
-var CATEGORY_ORDER = ["trigger", "logic", "data", "ai", "io", "human", "output", "layout", "custom"];
+var CATEGORY_ORDER = ["trigger", "logic", "data", "ai", "io", "human", "output", "layout", "annotation", "custom"];
 var CATEGORY_LABELS = {
   trigger: "Triggers",
   logic: "Logic",
@@ -12555,6 +12662,7 @@ var CATEGORY_LABELS = {
   human: "Human",
   output: "Output",
   layout: "Layout",
+  annotation: "Notes",
   custom: "Custom"
 };
 function NodePalette({ categories, onPick, className, style: style2 }) {
@@ -13638,6 +13746,7 @@ function portStyle2(i, total) {
 }
 function DefaultBody({ config, kind }) {
   const fields = kind ?? [];
+  if (fields.length === 0) return null;
   const visible = fields.map((f) => ({ field: f, value: config[f.key] })).filter(({ value }) => value !== void 0 && value !== "" && value !== null);
   if (visible.length === 0) {
     return /* @__PURE__ */ jsxRuntime.jsx("div", { className: "ff-node__body-empty", children: "\u2014 configure in the panel" });
@@ -13694,17 +13803,132 @@ function buildNodeTypes() {
   }
   return map;
 }
-var FlowEditorContext = ReactExports.createContext(null);
-var FlowEditorProvider = FlowEditorContext.Provider;
-function useFlowEditor() {
-  const api = ReactExports.useContext(FlowEditorContext);
-  if (api === null) {
-    throw new Error("useFlowEditor() must be called inside <FlowEditor>.");
-  }
-  return api;
+function humanInputFields(config) {
+  const raw = Array.isArray(config?.fields) ? config.fields : [];
+  const fields = raw.filter((f) => f && typeof f === "object" && typeof f.key === "string" && f.key).map((f) => ({
+    key: f.key,
+    label: typeof f.label === "string" && f.label ? f.label : f.key,
+    type: ["text", "textarea", "number", "select", "switch"].includes(f.type) ? f.type : "text",
+    required: !!f.required,
+    placeholder: typeof f.placeholder === "string" ? f.placeholder : void 0,
+    options: Array.isArray(f.options) ? f.options : void 0,
+    default: f.default
+  }));
+  if (fields.length) return fields;
+  const title = typeof config?.title === "string" && config.title ? config.title : "Your answer";
+  return [{ key: "value", label: title, type: "textarea", required: true }];
 }
-function useFlowEditorOptional() {
-  return ReactExports.useContext(FlowEditorContext);
+function initialValues(fields) {
+  const v2 = {};
+  for (const f of fields) v2[f.key] = f.type === "switch" ? !!f.default : f.default ?? "";
+  return v2;
+}
+function HumanPrompt({ request, onCancel }) {
+  const firstRef = ReactExports.useRef(null);
+  ReactExports.useEffect(() => {
+    firstRef.current?.focus();
+    const onKey = (e) => {
+      if (e.key === "Escape") onCancel();
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [onCancel]);
+  return /* @__PURE__ */ jsxRuntime.jsx("div", { className: "ff-prompt-overlay", role: "dialog", "aria-modal": "true", "aria-label": request.title, children: /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "ff-prompt", onClick: (e) => e.stopPropagation(), children: [
+    /* @__PURE__ */ jsxRuntime.jsx("div", { className: "ff-prompt__title", children: request.title }),
+    request.kind === "approval" ? /* @__PURE__ */ jsxRuntime.jsx(ApprovalBody, { request, onCancel }) : /* @__PURE__ */ jsxRuntime.jsx(InputBody, { request, onCancel, firstRef })
+  ] }) });
+}
+function ApprovalBody({ request, onCancel }) {
+  return /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+    request.description && /* @__PURE__ */ jsxRuntime.jsx("p", { className: "ff-prompt__desc", children: request.description }),
+    /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "ff-prompt__actions", children: [
+      /* @__PURE__ */ jsxRuntime.jsx("button", { type: "button", className: "ff-prompt__btn ff-prompt__btn--ghost", onClick: onCancel, children: "Cancel" }),
+      /* @__PURE__ */ jsxRuntime.jsx("button", { type: "button", className: "ff-prompt__btn ff-prompt__btn--danger", onClick: () => request.resolve(false), children: "Deny" }),
+      /* @__PURE__ */ jsxRuntime.jsx("button", { type: "button", className: "ff-prompt__btn ff-prompt__btn--primary", onClick: () => request.resolve(true), children: "Approve" })
+    ] })
+  ] });
+}
+function InputBody({
+  request,
+  onCancel,
+  firstRef
+}) {
+  const [values, setValues] = ReactExports.useState(() => initialValues(request.fields));
+  const set3 = (k2, v2) => setValues((prev) => ({ ...prev, [k2]: v2 }));
+  const missing = request.fields.filter((f) => f.required && (values[f.key] === void 0 || values[f.key] === ""));
+  const submit = () => {
+    if (missing.length === 0) request.resolve(values);
+  };
+  return /* @__PURE__ */ jsxRuntime.jsxs(
+    "form",
+    {
+      onSubmit: (e) => {
+        e.preventDefault();
+        submit();
+      },
+      onKeyDown: (e) => {
+        if (e.key === "Enter" && (e.metaKey || e.ctrlKey)) {
+          e.preventDefault();
+          submit();
+        }
+      },
+      children: [
+        /* @__PURE__ */ jsxRuntime.jsx("div", { className: "ff-prompt__fields", children: request.fields.map((f, i) => /* @__PURE__ */ jsxRuntime.jsxs("label", { className: "ff-prompt__field", children: [
+          /* @__PURE__ */ jsxRuntime.jsxs("span", { className: "ff-prompt__label", children: [
+            f.label ?? f.key,
+            f.required && /* @__PURE__ */ jsxRuntime.jsx("span", { className: "ff-prompt__req", children: " *" })
+          ] }),
+          renderControl(f, values[f.key], (v2) => set3(f.key, v2), i === 0 ? firstRef : void 0)
+        ] }, f.key)) }),
+        /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "ff-prompt__actions", children: [
+          /* @__PURE__ */ jsxRuntime.jsx("button", { type: "button", className: "ff-prompt__btn ff-prompt__btn--ghost", onClick: onCancel, children: "Cancel" }),
+          /* @__PURE__ */ jsxRuntime.jsx("button", { type: "submit", className: "ff-prompt__btn ff-prompt__btn--primary", disabled: missing.length > 0, children: request.submitLabel || "Continue" })
+        ] })
+      ]
+    }
+  );
+}
+function renderControl(f, value, onChange, ref) {
+  const common = { className: "ff-prompt__input", placeholder: f.placeholder };
+  if (f.type === "textarea") {
+    return /* @__PURE__ */ jsxRuntime.jsx(
+      "textarea",
+      {
+        ...common,
+        ref,
+        rows: 3,
+        value: String(value ?? ""),
+        onChange: (e) => onChange(e.target.value)
+      }
+    );
+  }
+  if (f.type === "switch") {
+    return /* @__PURE__ */ jsxRuntime.jsx(
+      "input",
+      {
+        type: "checkbox",
+        className: "ff-prompt__switch",
+        checked: !!value,
+        onChange: (e) => onChange(e.target.checked)
+      }
+    );
+  }
+  if (f.type === "select" && f.options && f.options.length) {
+    return /* @__PURE__ */ jsxRuntime.jsxs("select", { className: "ff-prompt__input", value: String(value ?? ""), onChange: (e) => onChange(e.target.value), children: [
+      /* @__PURE__ */ jsxRuntime.jsx("option", { value: "", disabled: true, children: "Choose\u2026" }),
+      f.options.map((o) => /* @__PURE__ */ jsxRuntime.jsx("option", { value: o.value, children: o.label }, o.value))
+    ] });
+  }
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    "input",
+    {
+      ...common,
+      ref,
+      type: f.type === "number" ? "number" : "text",
+      value: String(value ?? ""),
+      onChange: (e) => onChange(f.type === "number" ? e.target.value === "" ? "" : Number(e.target.value) : e.target.value)
+    }
+  );
 }
 var FlowEditor = ReactExports.forwardRef(function FlowEditor2(props, ref) {
   return /* @__PURE__ */ jsxRuntime.jsx(ReactFlowProvider, { children: /* @__PURE__ */ jsxRuntime.jsx(
@@ -13739,6 +13963,41 @@ function FlowEditorInner({
   const internal = useFlowState(initial);
   const runner = useFlowRun();
   const rf = useReactFlow();
+  const [prompt, setPrompt] = ReactExports.useState(null);
+  const humanExecutors = ReactExports.useMemo(
+    () => ({
+      user_input: ({ node }) => new Promise((resolve) => {
+        const cfg = node.data?.config ?? {};
+        setPrompt({
+          kind: "input",
+          title: typeof cfg.title === "string" && cfg.title || "Your input",
+          submitLabel: typeof cfg.submitLabel === "string" ? cfg.submitLabel : void 0,
+          fields: humanInputFields(cfg),
+          resolve: (values) => {
+            setPrompt(null);
+            resolve(values);
+          }
+        });
+      }),
+      human_approval: ({ node }) => new Promise((resolve) => {
+        const cfg = node.data?.config ?? {};
+        setPrompt({
+          kind: "approval",
+          title: typeof cfg.title === "string" && cfg.title || "Approve action",
+          description: typeof cfg.description === "string" ? cfg.description : void 0,
+          resolve: (approved) => {
+            setPrompt(null);
+            resolve({ branch: approved ? "approved" : "denied" });
+          }
+        });
+      })
+    }),
+    []
+  );
+  const runExecutors = ReactExports.useMemo(() => ({ ...humanExecutors, ...executors }), [humanExecutors, executors]);
+  ReactExports.useEffect(() => {
+    if (!runner.running) setPrompt(null);
+  }, [runner.running]);
   const controlled = value !== void 0;
   const baseFlow = controlled ? makeControlledFlowAdapter(value, onChange) : internal;
   const hist = useFlowHistory(baseFlow);
@@ -14048,7 +14307,7 @@ function FlowEditorInner({
           ({ autoLayout: autoLayout2 }) => flow.setGraph({ nodes: autoLayout2({ nodes: flow.nodes, edges: flow.edges }, { scope: laneId }), edges: flow.edges })
         );
       },
-      run: () => runner.run({ nodes: flow.nodes, edges: flow.edges }, executors),
+      run: () => runner.run({ nodes: flow.nodes, edges: flow.edges }, runExecutors),
       cancel: runner.cancel,
       reset: runner.reset,
       toWorkflow,
@@ -14060,7 +14319,7 @@ function FlowEditorInner({
       canUndo: hist.canUndo,
       canRedo: hist.canRedo
     };
-  }, [flow, selectedId, selected2, selectedEdgeId, selectedEdge, selectedIds, selectedNodes, runner, executors, metadata, addNode, deleteNodes, deleteEdges, duplicateSelected, alignSelected, distributeSelected, copySelection, pasteClipboard, addLane, hist, rf]);
+  }, [flow, selectedId, selected2, selectedEdgeId, selectedEdge, selectedIds, selectedNodes, runner, runExecutors, metadata, addNode, deleteNodes, deleteEdges, duplicateSelected, alignSelected, distributeSelected, copySelection, pasteClipboard, addLane, hist, rf]);
   ReactExports.useImperativeHandle(apiRef, () => api, [api]);
   const dropHandlers = paletteDropHandlers((kindName, evt) => {
     const point = rf.screenToFlowPosition({ x: evt.clientX, y: evt.clientY });
@@ -14234,7 +14493,11 @@ function FlowEditorInner({
           onCancel: () => setLabelEdit(null)
         }
       ),
-      showFeed && (slots.feed ? slots.feed(api) : /* @__PURE__ */ jsxRuntime.jsx(FlowRunFeed, { entries: runner.feed, className: "ff-editor__feed" }))
+      showFeed && (slots.feed ? slots.feed(api) : /* @__PURE__ */ jsxRuntime.jsx(FlowRunFeed, { entries: runner.feed, className: "ff-editor__feed" })),
+      prompt && /* @__PURE__ */ jsxRuntime.jsx(HumanPrompt, { request: prompt, onCancel: () => {
+        setPrompt(null);
+        runner.cancel();
+      } })
     ] }),
     showPanel && (slots.panel ? slots.panel(api) : /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "ff-editor__panel-wrap", children: [
       /* @__PURE__ */ jsxRuntime.jsx(