@particle-academy/fancy-flow 0.24.0 → 0.25.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 }) {
@@ -13694,18 +13802,6 @@ 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 useFlowEditorOptional() {
-  return ReactExports.useContext(FlowEditorContext);
-}
 var FlowEditor = ReactExports.forwardRef(function FlowEditor2(props, ref) {
   return /* @__PURE__ */ jsxRuntime.jsx(ReactFlowProvider, { children: /* @__PURE__ */ jsxRuntime.jsx(
     "div",