@particle-academy/fancy-flow 0.45.0 → 0.47.0

package/dist/index.cjs

@@ -1719,199 +1719,15 @@ var init_layout = __esm({
     init_dagre_esm();
   }
 });
-
-// src/registry/registry.ts
-var kinds = /* @__PURE__ */ new Map();
-var aliases = /* @__PURE__ */ new Map();
-var listeners = /* @__PURE__ */ new Set();
-var overrides = /* @__PURE__ */ new Map();
-function registerNodeKind(definition) {
-  kinds.set(definition.name, definition);
-  for (const alias of definition.aliases ?? []) aliases.set(alias, definition.name);
-  notify();
-  return () => {
-    if (kinds.get(definition.name) === definition) {
-      kinds.delete(definition.name);
-      for (const alias of definition.aliases ?? []) {
-        if (aliases.get(alias) === definition.name) aliases.delete(alias);
-      }
-      notify();
-    }
-  };
-}
-function resolveKindId(id2) {
-  if (kinds.has(id2)) return id2;
-  const canonical = aliases.get(id2);
-  return canonical && kinds.has(canonical) ? canonical : null;
-}
-function overrideNodeKind(name, patch) {
-  const canonical = resolveKindId(name) ?? name;
-  const previous = overrides.get(canonical);
-  overrides.set(canonical, { ...previous, ...patch });
-  notify();
-  return () => {
-    if (previous) {
-      overrides.set(canonical, previous);
-    } else {
-      overrides.delete(canonical);
-    }
-    notify();
-  };
-}
-function clearNodeKindOverrides() {
-  if (overrides.size === 0) return;
-  overrides.clear();
-  notify();
-}
-function withOverride(kind) {
-  if (!kind) return null;
-  const patch = overrides.get(kind.name);
-  return patch ? { ...kind, ...patch } : kind;
-}
-function getNodeKind(name) {
-  const canonical = resolveKindId(name);
-  return canonical ? withOverride(kinds.get(canonical)) : null;
-}
-function kindIds(kind) {
-  return [kind.name, ...kind.aliases ?? []];
-}
-function listNodeKinds(category) {
-  const all = Array.from(kinds.values()).map(
-    (k2) => withOverride(k2)
-  );
-  return category ? all.filter((k2) => k2.category === category) : all;
-}
-function onNodeKindsChanged(listener) {
-  listeners.add(listener);
-  return () => listeners.delete(listener);
-}
-function notify() {
-  for (const l of listeners) l();
-}
-function defaultConfigFor(kind) {
-  const fromKind = kind.defaultConfig ? { ...kind.defaultConfig } : {};
-  for (const field of kind.configSchema ?? []) {
-    if (fromKind[field.key] !== void 0) continue;
-    if ("default" in field && field.default !== void 0) {
-      fromKind[field.key] = field.default;
-    }
-  }
-  return fromKind;
-}
-function validateConfig(kind, config) {
-  const issues = [];
-  for (const field of kind.configSchema ?? []) {
-    const value = config[field.key];
-    if (field.required && (value === void 0 || value === null || value === "")) {
-      issues.push({ key: field.key, message: `${field.label} is required` });
-      continue;
-    }
-    if (value === void 0 || value === null) continue;
-    const issue = validateField(field, value);
-    if (issue) issues.push({ key: field.key, message: issue });
-  }
-  return issues;
-}
-function validateField(field, value) {
-  switch (field.type) {
-    case "text":
-    case "textarea":
-    case "expression":
-    case "credential":
-      return typeof value === "string" ? null : `${field.label} must be a string`;
-    case "number": {
-      if (typeof value !== "number" || !Number.isFinite(value)) return `${field.label} must be a number`;
-      if (field.min !== void 0 && value < field.min) return `${field.label} must be >= ${field.min}`;
-      if (field.max !== void 0 && value > field.max) return `${field.label} must be <= ${field.max}`;
-      return null;
-    }
-    case "switch":
-      return typeof value === "boolean" ? null : `${field.label} must be a boolean`;
-    case "select": {
-      const allowed = field.options.map((o) => o.value);
-      return allowed.includes(String(value)) ? null : `${field.label} must be one of ${allowed.join(", ")}`;
-    }
-    case "json":
-      return null;
-    // permissive — just JSON-shaped
-    case "repeater": {
-      if (!Array.isArray(value)) return `${field.label} must be a list`;
-      if (field.minItems !== void 0 && value.length < field.minItems) {
-        return `${field.label} needs at least ${field.minItems}`;
-      }
-      if (field.maxItems !== void 0 && value.length > field.maxItems) {
-        return `${field.label} allows at most ${field.maxItems}`;
-      }
-      for (let i = 0; i < value.length; i++) {
-        const row = value[i];
-        if (!row || typeof row !== "object" || Array.isArray(row)) {
-          return `${field.label} item ${i + 1} must be an object`;
-        }
-        for (const sub of field.fields) {
-          const cell = row[sub.key];
-          if (sub.required && (cell === void 0 || cell === null || cell === "")) {
-            return `${field.label} item ${i + 1}: ${sub.label} is required`;
-          }
-          if (cell === void 0 || cell === null) continue;
-          const issue = validateField(sub, cell);
-          if (issue) return `${field.label} item ${i + 1}: ${issue}`;
-        }
-      }
-      return null;
-    }
-    case "keyvalue": {
-      if (typeof value !== "object" || value === null || Array.isArray(value)) {
-        return `${field.label} must be a key/value map`;
-      }
-      const allowed = field.valueOptions?.map((o) => o.value);
-      for (const [k2, v2] of Object.entries(value)) {
-        if (typeof v2 !== "string") return `${field.label}: "${k2}" must be a string`;
-        if (allowed && !allowed.includes(v2)) {
-          return `${field.label}: "${k2}" must be one of ${allowed.join(", ")}`;
-        }
-      }
-      return null;
-    }
-    case "document":
-      return null;
-    // opaque to fancy-flow — the host's editor owns its shape
-    default:
-      return null;
-  }
-}
-function categoryAccent(category) {
-  switch (category) {
-    case "trigger":
-      return "#10b981";
-    case "logic":
-      return "#f59e0b";
-    case "data":
-      return "#0ea5e9";
-    case "ai":
-      return "#8b5cf6";
-    case "io":
-      return "#3b82f6";
-    case "human":
-      return "#ec4899";
-    case "output":
-      return "#a855f7";
-    case "layout":
-      return "#64748b";
-    case "annotation":
-      return "#eab308";
-    default:
-      return "#71717a";
-  }
-}
 var adapter = null;
-var listeners2 = /* @__PURE__ */ new Set();
+var listeners = /* @__PURE__ */ new Set();
 function registerRichInputAdapter(next) {
   adapter = next;
-  for (const l of listeners2) l();
+  for (const l of listeners) l();
   return () => {
     if (adapter === next) {
       adapter = null;
-      for (const l of listeners2) l();
+      for (const l of listeners) l();
     }
   };
 }
@@ -1922,8 +1738,8 @@ function isRichInputEnabled() {
   return adapter !== null && (adapter.renderDocument !== void 0 || adapter.renderEditor !== void 0);
 }
 function onRichInputAdapterChanged(fn2) {
-  listeners2.add(fn2);
-  return () => listeners2.delete(fn2);
+  listeners.add(fn2);
+  return () => listeners.delete(fn2);
 }
 function RichInputPreview({ config }) {
   const a = getRichInputAdapter();
@@ -11172,10 +10988,121 @@ function resolveNodePorts(node, kind) {
   };
 }
 
+// src/runtime/run-identity.ts
+function escapeSegment(value) {
+  return value.replace(/%/g, "%25").replace(/\//g, "%2F").replace(/#/g, "%23");
+}
+function renderSegment(value, occurrence) {
+  const escaped = escapeSegment(value);
+  return occurrence === void 0 || occurrence === null ? escaped : `${escaped}#${occurrence}`;
+}
+function instant(value) {
+  const ms = Date.parse(value);
+  if (Number.isNaN(ms)) {
+    throw new Error(
+      `RunIdentity: firstAttemptAt is not a parseable timestamp: ${JSON.stringify(value)}`
+    );
+  }
+  return ms;
+}
+var RunIdentity = class _RunIdentity {
+  constructor(runKey, path = [], attempt = 1, firstAttemptAt = (/* @__PURE__ */ new Date()).toISOString()) {
+    if (!runKey || runKey.trim() === "") {
+      throw new Error("RunIdentity: runKey must be a non-empty string.");
+    }
+    this.runKey = runKey;
+    this.path = Object.freeze([...path]);
+    this.attempt = Math.max(1, Math.trunc(attempt));
+    this.firstAttemptAt = firstAttemptAt;
+    Object.freeze(this);
+  }
+  /**
+   * The identity of one execution of one node — stable across retries of that
+   * execution, distinct from every other execution of the same node.
+   *
+   * Pass `occurrence` when an executor runs the same node more than once at the
+   * same level (a loop body, one item of a fan-out it drives itself).
+   */
+  stepKey(nodeId, occurrence) {
+    return `${this.runKey}:${[...this.path, renderSegment(nodeId, occurrence)].join("/")}`;
+  }
+  /**
+   * A child identity for work nested inside this step.
+   *
+   * `subflow` pushes the invoking node's id, so a node inside the child graph
+   * cannot collide with a same-named node in the parent. Attempt and
+   * `firstAttemptAt` are carried down unchanged: the nested work happens inside
+   * this step's attempt, and shares its clock.
+   */
+  descend(segment, occurrence) {
+    return new _RunIdentity(
+      this.runKey,
+      [...this.path, renderSegment(segment, occurrence)],
+      this.attempt,
+      this.firstAttemptAt
+    );
+  }
+  /** A copy on a different attempt, first-attempt clock preserved. */
+  withAttempt(attempt, firstAttemptAt) {
+    return new _RunIdentity(
+      this.runKey,
+      this.path,
+      attempt,
+      firstAttemptAt ?? this.firstAttemptAt
+    );
+  }
+  /**
+   * May this attempt reuse the step key and still be deduplicated?
+   *
+   * Providers forget idempotency keys — Stripe after 24 hours. Past that
+   * window, resending the key creates a second charge and sending a fresh one
+   * creates a second charge, so **the caller must refuse rather than pick
+   * between them**: a loud stuck run beats a silent double write.
+   *
+   * `true` on attempt 1 whatever the elapsed time — nothing was sent on an
+   * earlier attempt, so there is nothing for the provider to have forgotten.
+   * That is what lets a run park on a human gate for a week and then write.
+   *
+   * `windowSeconds: null` means the provider does not expire keys. `0` means
+   * it does not dedupe at all, so no retry may reuse a key — it is a real
+   * window, not an absent one, and the two must not be conflated: reading `0`
+   * as `null` turns "this provider does not dedupe" into "this provider
+   * dedupes forever", which is the more dangerous of the two by a distance.
+   */
+  isReplaySafe(windowSeconds, now2 = /* @__PURE__ */ new Date()) {
+    if (this.attempt <= 1) return true;
+    if (windowSeconds === null || windowSeconds === void 0) return true;
+    if (windowSeconds <= 0) return false;
+    const nowMs = typeof now2 === "string" ? instant(now2) : now2.getTime();
+    const elapsedSeconds = Math.max(0, (nowMs - instant(this.firstAttemptAt)) / 1e3);
+    return elapsedSeconds <= windowSeconds;
+  }
+  toJSON() {
+    return {
+      runKey: this.runKey,
+      path: [...this.path],
+      attempt: this.attempt,
+      firstAttemptAt: this.firstAttemptAt
+    };
+  }
+  /** Rebuild from a queue payload. */
+  static from(value) {
+    if (value instanceof _RunIdentity) return value;
+    if (typeof value === "string") return new _RunIdentity(value);
+    return new _RunIdentity(
+      value.runKey,
+      value.path ?? [],
+      value.attempt ?? 1,
+      value.firstAttemptAt ?? (/* @__PURE__ */ new Date()).toISOString()
+    );
+  }
+};
+
 // src/runtime/run-flow.ts
 async function runFlow(graph, executors, onEvent = () => {
 }, options = {}) {
-  const { signal, initialInputs = {}, timeoutMs, depth = 0 } = options;
+  const { signal, initialInputs = {}, timeoutMs, depth = 0, resumeOutputs = {} } = options;
+  const run = options.run === void 0 ? void 0 : RunIdentity.from(options.run);
   const outputs = {};
   const portValues = /* @__PURE__ */ new Map();
   const completed = /* @__PURE__ */ new Set();
@@ -11193,6 +11120,18 @@ async function runFlow(graph, executors, onEvent = () => {
     for (const node of order) {
       if (signal?.aborted) throw new Error("aborted");
       if (errors.length) break;
+      if (Object.prototype.hasOwnProperty.call(resumeOutputs, node.id)) {
+        const stored = resumeOutputs[node.id];
+        outputs[node.id] = stored;
+        const activated = activatedPorts(node, stored);
+        for (const portId of activated.ports) {
+          portValues.set(`${node.id}:${portId}`, activated.value);
+          onEvent({ type: "node-output", nodeId: node.id, portId, value: activated.value });
+        }
+        completed.add(node.id);
+        onEvent({ type: "node-status", nodeId: node.id, status: "done", text: "resumed" });
+        continue;
+      }
       const incoming = incomingByNode.get(node.id) ?? [];
       if (incoming.length > 0) {
         const anyActive = incoming.some((e) => portValues.has(`${e.source}:${e.sourceHandle ?? "out"}`));
@@ -11232,7 +11171,8 @@ async function runFlow(graph, executors, onEvent = () => {
               throw new Error(reason ?? "aborted");
             },
             emit: onEvent,
-            depth
+            depth,
+            run
           })
         );
         outputs[node.id] = result;
@@ -11385,7 +11325,13 @@ var subflowExecutor = async (ctx) => {
         // require no configuration at all.
         __parent: ctx.inputs
       },
-      depth: depth + 1
+      depth: depth + 1,
+      // Push THIS node onto the identity path, so a node inside the child graph
+      // cannot share an idempotency key with a same-named node in the parent —
+      // or with the same child graph invoked from a different parent node.
+      // Attempt and the first-attempt clock ride down unchanged: the child's
+      // work happens inside this node's attempt.
+      run: ctx.run?.descend(ctx.node.id)
     }
   );
   if (!result.ok) {
@@ -12241,6 +12187,199 @@ function registerBuiltinKinds() {
   for (const k2 of KINDS) registerNodeKind(k2);
 }
 var BUILTIN_KINDS = KINDS;
+
+// src/registry/registry.ts
+var kinds = /* @__PURE__ */ new Map();
+var aliases = /* @__PURE__ */ new Map();
+var listeners2 = /* @__PURE__ */ new Set();
+var overrides = /* @__PURE__ */ new Map();
+var builtinsEnsured = false;
+function ensureBuiltinKinds() {
+  if (builtinsEnsured) return;
+  builtinsEnsured = true;
+  registerBuiltinKinds();
+}
+function registerNodeKind(definition) {
+  ensureBuiltinKinds();
+  kinds.set(definition.name, definition);
+  for (const alias of definition.aliases ?? []) aliases.set(alias, definition.name);
+  notify();
+  return () => {
+    if (kinds.get(definition.name) === definition) {
+      kinds.delete(definition.name);
+      for (const alias of definition.aliases ?? []) {
+        if (aliases.get(alias) === definition.name) aliases.delete(alias);
+      }
+      notify();
+    }
+  };
+}
+function resolveKindId(id2) {
+  ensureBuiltinKinds();
+  if (kinds.has(id2)) return id2;
+  const canonical = aliases.get(id2);
+  return canonical && kinds.has(canonical) ? canonical : null;
+}
+function overrideNodeKind(name, patch) {
+  const canonical = resolveKindId(name) ?? name;
+  const previous = overrides.get(canonical);
+  overrides.set(canonical, { ...previous, ...patch });
+  notify();
+  return () => {
+    if (previous) {
+      overrides.set(canonical, previous);
+    } else {
+      overrides.delete(canonical);
+    }
+    notify();
+  };
+}
+function clearNodeKindOverrides() {
+  if (overrides.size === 0) return;
+  overrides.clear();
+  notify();
+}
+function withOverride(kind) {
+  if (!kind) return null;
+  const patch = overrides.get(kind.name);
+  return patch ? { ...kind, ...patch } : kind;
+}
+function getNodeKind(name) {
+  const canonical = resolveKindId(name);
+  return canonical ? withOverride(kinds.get(canonical)) : null;
+}
+function kindIds(kind) {
+  return [kind.name, ...kind.aliases ?? []];
+}
+function listNodeKinds(category) {
+  ensureBuiltinKinds();
+  const all = Array.from(kinds.values()).map(
+    (k2) => withOverride(k2)
+  );
+  return category ? all.filter((k2) => k2.category === category) : all;
+}
+function onNodeKindsChanged(listener) {
+  listeners2.add(listener);
+  return () => listeners2.delete(listener);
+}
+function notify() {
+  for (const l of listeners2) l();
+}
+function defaultConfigFor(kind) {
+  const fromKind = kind.defaultConfig ? { ...kind.defaultConfig } : {};
+  for (const field of kind.configSchema ?? []) {
+    if (fromKind[field.key] !== void 0) continue;
+    if ("default" in field && field.default !== void 0) {
+      fromKind[field.key] = field.default;
+    }
+  }
+  return fromKind;
+}
+function validateConfig(kind, config) {
+  const issues = [];
+  for (const field of kind.configSchema ?? []) {
+    const value = config[field.key];
+    if (field.required && (value === void 0 || value === null || value === "")) {
+      issues.push({ key: field.key, message: `${field.label} is required` });
+      continue;
+    }
+    if (value === void 0 || value === null) continue;
+    const issue = validateField(field, value);
+    if (issue) issues.push({ key: field.key, message: issue });
+  }
+  return issues;
+}
+function validateField(field, value) {
+  switch (field.type) {
+    case "text":
+    case "textarea":
+    case "expression":
+    case "credential":
+      return typeof value === "string" ? null : `${field.label} must be a string`;
+    case "number": {
+      if (typeof value !== "number" || !Number.isFinite(value)) return `${field.label} must be a number`;
+      if (field.min !== void 0 && value < field.min) return `${field.label} must be >= ${field.min}`;
+      if (field.max !== void 0 && value > field.max) return `${field.label} must be <= ${field.max}`;
+      return null;
+    }
+    case "switch":
+      return typeof value === "boolean" ? null : `${field.label} must be a boolean`;
+    case "select": {
+      const allowed = field.options.map((o) => o.value);
+      return allowed.includes(String(value)) ? null : `${field.label} must be one of ${allowed.join(", ")}`;
+    }
+    case "json":
+      return null;
+    // permissive — just JSON-shaped
+    case "repeater": {
+      if (!Array.isArray(value)) return `${field.label} must be a list`;
+      if (field.minItems !== void 0 && value.length < field.minItems) {
+        return `${field.label} needs at least ${field.minItems}`;
+      }
+      if (field.maxItems !== void 0 && value.length > field.maxItems) {
+        return `${field.label} allows at most ${field.maxItems}`;
+      }
+      for (let i = 0; i < value.length; i++) {
+        const row = value[i];
+        if (!row || typeof row !== "object" || Array.isArray(row)) {
+          return `${field.label} item ${i + 1} must be an object`;
+        }
+        for (const sub of field.fields) {
+          const cell = row[sub.key];
+          if (sub.required && (cell === void 0 || cell === null || cell === "")) {
+            return `${field.label} item ${i + 1}: ${sub.label} is required`;
+          }
+          if (cell === void 0 || cell === null) continue;
+          const issue = validateField(sub, cell);
+          if (issue) return `${field.label} item ${i + 1}: ${issue}`;
+        }
+      }
+      return null;
+    }
+    case "keyvalue": {
+      if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return `${field.label} must be a key/value map`;
+      }
+      const allowed = field.valueOptions?.map((o) => o.value);
+      for (const [k2, v2] of Object.entries(value)) {
+        if (typeof v2 !== "string") return `${field.label}: "${k2}" must be a string`;
+        if (allowed && !allowed.includes(v2)) {
+          return `${field.label}: "${k2}" must be one of ${allowed.join(", ")}`;
+        }
+      }
+      return null;
+    }
+    case "document":
+      return null;
+    // opaque to fancy-flow — the host's editor owns its shape
+    default:
+      return null;
+  }
+}
+function categoryAccent(category) {
+  switch (category) {
+    case "trigger":
+      return "#10b981";
+    case "logic":
+      return "#f59e0b";
+    case "data":
+      return "#0ea5e9";
+    case "ai":
+      return "#8b5cf6";
+    case "io":
+      return "#3b82f6";
+    case "human":
+      return "#ec4899";
+    case "output":
+      return "#a855f7";
+    case "layout":
+      return "#64748b";
+    case "annotation":
+      return "#eab308";
+    default:
+      return "#71717a";
+  }
+}
 function NodeShellInner({
   node,
   accent,
@@ -15086,7 +15225,9 @@ function FlowViewer({
       return {
         node,
         index: index2,
-        title: kind?.label ?? node.data?.label ?? node.data?.kind ?? node.id,
+        // The node's own label is the name the AUTHOR gave THIS node ("Summarize");
+        // the kind label is the generic type name ("LLM Call"). Specific wins.
+        title: node.data?.label ?? kind?.label ?? node.data?.kind ?? node.id,
         description: kind?.description ?? null,
         accent: kind?.accent ?? categoryAccent(kind?.category ?? "custom"),
         status: statuses?.[node.id] ?? null
@@ -15364,7 +15505,7 @@ function evaluateConfig(config, context) {
 }
 
 // src/index.ts
-registerBuiltinKinds();
+ensureBuiltinKinds();
 /*! Bundled license information:
 
 @dagrejs/dagre/dist/dagre.esm.js:
@@ -15416,6 +15557,7 @@ exports.defineNode = defineNode;
 exports.describeExpressionGrammar = describeExpressionGrammar;
 exports.distributeNodes = distributeNodes;
 exports.encodePause = encodePause;
+exports.ensureBuiltinKinds = ensureBuiltinKinds;
 exports.evaluateConfig = evaluateConfig;
 exports.evaluateExpression = evaluateExpression;
 exports.exportWorkflow = exportWorkflow;