@stigmer/react 1.0.3 → 2.0.0

package/workflow/picker/compatibility.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compatibility.js","sourceRoot":"","sources":["../../../src/workflow/picker/compatibility.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AActD,sEAAsE;AACtE,MAAM,mBAAmB,GAAwB,IAAI,GAAG,CAAC;IACvD,WAAW;IACX,SAAS;CACV,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO,mBAAmB,CAAC;AAC7B,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAyB,EACzB,KAAyB;IAEzB,MAAM,QAAQ,GAAwB,EAAE,CAAC;IAEzC,4EAA4E;IAC5E,+DAA+D;IAC/D,IAAI,OAAO,CAAC,IAAI,KAAK,aAAa,IAAI,OAAO,CAAC,YAAY,KAAK,WAAW,EAAE,CAAC;QAC3E,uEAAuE;QACvE,8DAA8D;QAC9D,uDAAuD;IACzD,CAAC;IAED,+CAA+C;IAC/C,IAAI,OAAO,CAAC,mBAAmB,KAAK,UAAU,EAAE,CAAC;QAC/C,QAAQ,CAAC,IAAI,CAAC;YACZ,IAAI,EAAE,UAAU;YAChB,MAAM,EAAE,0DAA0D;SACnE,CAAC,CAAC;IACL,CAAC;IAED,8DAA8D;IAC9D,yEAAyE;IACzE,IAAI,uBAAuB,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC;QAC5C,QAAQ,CAAC,IAAI,CAAC;YACZ,IAAI,EAAE,MAAM;YACZ,MAAM,EAAE,qEAAqE;SAC9E,CAAC,CAAC;IACL,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;GAGG;AACH,SAAS,uBAAuB,CAC9B,OAAyB,EACzB,KAAyB;IAEzB,IAAI,OAAO,CAAC,IAAI,KAAK,aAAa,IAAI,OAAO,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;QACtE,OAAO,KAAK,CAAC;IACf,CAAC;IAED,mEAAmE;IACnE,6DAA6D;IAC7D,6BAA6B;IAC7B,MAAM,QAAQ,GAAG,OAAO,CAAC,YAAY,CAAC;IACtC,IAAI,CAAC,QAAQ;QAAE,OAAO,KAAK,CAAC;IAE5B,MAAM,UAAU,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,CACnC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,KAAK,WAAW,CACzD,CAAC;IACF,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAE1C,wEAAwE;IACxE,MAAM,gBAAgB,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC;IAC1E,OAAO,gBAAgB,CAAC,IAAI,CAC1B,CAAC,CAAC,EAAE,EAAE,CACJ,OAAO,CAAC,CAAC,YAAY,KAAK,QAAQ;QAClC,CAAC,CAAC,CAAC,YAAY,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,YAAY,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CAChF,CAAC;AACJ,CAAC"}

package/workflow/picker/index.d.ts

@@ -0,0 +1,11 @@
+export type { InsertionMode, InsertionContext } from "./insertion-context";
+export { buildInsertionHeader } from "./insertion-context";
+export type { TaskKindSuggestion } from "./suggestions";
+export { getSuggestedKinds } from "./suggestions";
+export type { DisabledKindEntry } from "./compatibility";
+export { getHiddenKinds, getDisabledKinds } from "./compatibility";
+export type { RecentKindEntry } from "./recents";
+export { getRecentKinds, recordRecentKind, clearRecentKinds } from "./recents";
+export type { PickerItem, PickerSection, PickerData } from "./usePickerData";
+export { usePickerData } from "./usePickerData";
+//# sourceMappingURL=index.d.ts.map

package/workflow/picker/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/workflow/picker/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC3E,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAE3D,YAAY,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAElD,YAAY,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEnE,YAAY,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE/E,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7E,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC"}

package/workflow/picker/index.js

@@ -0,0 +1,6 @@
+export { buildInsertionHeader } from "./insertion-context";
+export { getSuggestedKinds } from "./suggestions";
+export { getHiddenKinds, getDisabledKinds } from "./compatibility";
+export { getRecentKinds, recordRecentKind, clearRecentKinds } from "./recents";
+export { usePickerData } from "./usePickerData";
+//# sourceMappingURL=index.js.map

package/workflow/picker/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/workflow/picker/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAG3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAGlD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAGnE,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAG/E,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC"}

package/workflow/picker/insertion-context.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Describes the semantic context of a task insertion operation.
+ *
+ * Every `+` interaction on the canvas produces an `InsertionContext` that
+ * tells the picker what kind of insertion is intended, what the surrounding
+ * graph topology looks like, and which node triggered it. The picker uses
+ * this to generate contextual suggestions, filter incompatible kinds, and
+ * render an appropriate header.
+ */
+/** The semantic meaning of the `+` that was clicked. */
+export type InsertionMode = "edge-splice" | "append-after" | "add-at-position" | "add-switch-case" | "add-fork-branch" | "add-catch-handler";
+/**
+ * Full context for a task insertion operation.
+ *
+ * Produced by the canvas interaction layer and consumed by the picker
+ * intelligence (suggestions, compatibility, header text).
+ */
+export interface InsertionContext {
+    /** Which insertion mode the user triggered. */
+    readonly mode: InsertionMode;
+    /** The node upstream of the insertion point (source of the edge, or the node with `+`). */
+    readonly sourceNodeId?: string;
+    /** The task kind of the source node (for suggestion lookup). */
+    readonly sourceKind?: string;
+    /** The display name of the source node (for contextual header). */
+    readonly sourceDisplayName?: string;
+    /** The node downstream of the insertion point (target of the edge being spliced). */
+    readonly targetNodeId?: string;
+    /** The display name of the target node (for contextual header). */
+    readonly targetDisplayName?: string;
+    /** The edge being spliced (for edge-splice mode). */
+    readonly edgeId?: string;
+    /** If inserting inside a container (for_each, try_catch), the container's kind. */
+    readonly parentContainerKind?: string;
+}
+/**
+ * Builds a human-readable header string describing the insertion action.
+ *
+ * Examples:
+ * - "Insert between classify_ticket and route_by_severity"
+ * - "Add after run_analyst"
+ * - "Add case to classify_user"
+ * - "Add parallel branch"
+ */
+export declare function buildInsertionHeader(context: InsertionContext): string;
+//# sourceMappingURL=insertion-context.d.ts.map

package/workflow/picker/insertion-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"insertion-context.d.ts","sourceRoot":"","sources":["../../../src/workflow/picker/insertion-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,wDAAwD;AACxD,MAAM,MAAM,aAAa,GACrB,aAAa,GACb,cAAc,GACd,iBAAiB,GACjB,iBAAiB,GACjB,iBAAiB,GACjB,mBAAmB,CAAC;AAExB;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,2FAA2F;IAC3F,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,gEAAgE;IAChE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,mEAAmE;IACnE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,qFAAqF;IACrF,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,mEAAmE;IACnE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,qDAAqD;IACrD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,mFAAmF;IACnF,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,CA0BtE"}

package/workflow/picker/insertion-context.js

@@ -0,0 +1,46 @@
+/**
+ * Describes the semantic context of a task insertion operation.
+ *
+ * Every `+` interaction on the canvas produces an `InsertionContext` that
+ * tells the picker what kind of insertion is intended, what the surrounding
+ * graph topology looks like, and which node triggered it. The picker uses
+ * this to generate contextual suggestions, filter incompatible kinds, and
+ * render an appropriate header.
+ */
+/**
+ * Builds a human-readable header string describing the insertion action.
+ *
+ * Examples:
+ * - "Insert between classify_ticket and route_by_severity"
+ * - "Add after run_analyst"
+ * - "Add case to classify_user"
+ * - "Add parallel branch"
+ */
+export function buildInsertionHeader(context) {
+    switch (context.mode) {
+        case "edge-splice": {
+            const src = context.sourceDisplayName ?? context.sourceNodeId ?? "…";
+            const tgt = context.targetDisplayName ?? context.targetNodeId ?? "…";
+            return `Insert between ${src} and ${tgt}`;
+        }
+        case "append-after": {
+            const src = context.sourceDisplayName ?? context.sourceNodeId ?? "…";
+            return `Add after ${src}`;
+        }
+        case "add-at-position":
+            return "Add task";
+        case "add-switch-case": {
+            const src = context.sourceDisplayName ?? context.sourceNodeId ?? "switch";
+            return `Add case to ${src}`;
+        }
+        case "add-fork-branch": {
+            const src = context.sourceDisplayName ?? context.sourceNodeId ?? "fork";
+            return `Add branch to ${src}`;
+        }
+        case "add-catch-handler": {
+            const src = context.sourceDisplayName ?? context.sourceNodeId ?? "try/catch";
+            return `Add catch handler to ${src}`;
+        }
+    }
+}
+//# sourceMappingURL=insertion-context.js.map

package/workflow/picker/insertion-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"insertion-context.js","sourceRoot":"","sources":["../../../src/workflow/picker/insertion-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAoCH;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAyB;IAC5D,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACrB,KAAK,aAAa,CAAC,CAAC,CAAC;YACnB,MAAM,GAAG,GAAG,OAAO,CAAC,iBAAiB,IAAI,OAAO,CAAC,YAAY,IAAI,GAAG,CAAC;YACrE,MAAM,GAAG,GAAG,OAAO,CAAC,iBAAiB,IAAI,OAAO,CAAC,YAAY,IAAI,GAAG,CAAC;YACrE,OAAO,kBAAkB,GAAG,QAAQ,GAAG,EAAE,CAAC;QAC5C,CAAC;QACD,KAAK,cAAc,CAAC,CAAC,CAAC;YACpB,MAAM,GAAG,GAAG,OAAO,CAAC,iBAAiB,IAAI,OAAO,CAAC,YAAY,IAAI,GAAG,CAAC;YACrE,OAAO,aAAa,GAAG,EAAE,CAAC;QAC5B,CAAC;QACD,KAAK,iBAAiB;YACpB,OAAO,UAAU,CAAC;QACpB,KAAK,iBAAiB,CAAC,CAAC,CAAC;YACvB,MAAM,GAAG,GAAG,OAAO,CAAC,iBAAiB,IAAI,OAAO,CAAC,YAAY,IAAI,QAAQ,CAAC;YAC1E,OAAO,eAAe,GAAG,EAAE,CAAC;QAC9B,CAAC;QACD,KAAK,iBAAiB,CAAC,CAAC,CAAC;YACvB,MAAM,GAAG,GAAG,OAAO,CAAC,iBAAiB,IAAI,OAAO,CAAC,YAAY,IAAI,MAAM,CAAC;YACxE,OAAO,iBAAiB,GAAG,EAAE,CAAC;QAChC,CAAC;QACD,KAAK,mBAAmB,CAAC,CAAC,CAAC;YACzB,MAAM,GAAG,GAAG,OAAO,CAAC,iBAAiB,IAAI,OAAO,CAAC,YAAY,IAAI,WAAW,CAAC;YAC7E,OAAO,wBAAwB,GAAG,EAAE,CAAC;QACvC,CAAC;IACH,CAAC;AACH,CAAC"}

package/workflow/picker/recents.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Manages a per-user list of recently used task kinds.
+ *
+ * Persisted to localStorage so recents survive page reloads and
+ * sessions. Scoped by a storage key prefix to allow per-workflow
+ * or per-project isolation if needed in the future.
+ *
+ * The store is intentionally simple and synchronous — localStorage
+ * access is fast enough for the 5-item list we maintain.
+ */
+/**
+ * A single recently-used task kind entry with a usage timestamp.
+ */
+export interface RecentKindEntry {
+    readonly kind: string;
+    readonly timestamp: number;
+}
+/**
+ * Retrieves the list of recently used task kinds, ordered by most recent first.
+ *
+ * Returns an empty array if localStorage is unavailable or contains
+ * invalid data.
+ */
+export declare function getRecentKinds(storageKey?: string): readonly RecentKindEntry[];
+/**
+ * Records a task kind as recently used.
+ *
+ * If the kind already exists in the list, it is moved to the front
+ * (most recent). The list is capped at {@link MAX_RECENTS} entries.
+ */
+export declare function recordRecentKind(kind: string, storageKey?: string): void;
+/**
+ * Clears all recent kind entries. Useful for testing or user preference reset.
+ */
+export declare function clearRecentKinds(storageKey?: string): void;
+//# sourceMappingURL=recents.d.ts.map

package/workflow/picker/recents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recents.d.ts","sourceRoot":"","sources":["../../../src/workflow/picker/recents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,UAAU,SAAsB,GAAG,SAAS,eAAe,EAAE,CAe3F;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,UAAU,SAAsB,GAC/B,IAAI,CAYN;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,SAAsB,GAAG,IAAI,CAMvE"}

package/workflow/picker/recents.js

@@ -0,0 +1,74 @@
+/**
+ * Manages a per-user list of recently used task kinds.
+ *
+ * Persisted to localStorage so recents survive page reloads and
+ * sessions. Scoped by a storage key prefix to allow per-workflow
+ * or per-project isolation if needed in the future.
+ *
+ * The store is intentionally simple and synchronous — localStorage
+ * access is fast enough for the 5-item list we maintain.
+ */
+const DEFAULT_STORAGE_KEY = "stigmer:picker:recent-kinds";
+const MAX_RECENTS = 5;
+/**
+ * Retrieves the list of recently used task kinds, ordered by most recent first.
+ *
+ * Returns an empty array if localStorage is unavailable or contains
+ * invalid data.
+ */
+export function getRecentKinds(storageKey = DEFAULT_STORAGE_KEY) {
+    try {
+        const raw = globalThis.localStorage?.getItem(storageKey);
+        if (!raw)
+            return [];
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed
+            .filter(isValidEntry)
+            .sort((a, b) => b.timestamp - a.timestamp)
+            .slice(0, MAX_RECENTS);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Records a task kind as recently used.
+ *
+ * If the kind already exists in the list, it is moved to the front
+ * (most recent). The list is capped at {@link MAX_RECENTS} entries.
+ */
+export function recordRecentKind(kind, storageKey = DEFAULT_STORAGE_KEY) {
+    try {
+        const existing = getRecentKinds(storageKey).filter((e) => e.kind !== kind);
+        const updated = [
+            { kind, timestamp: Date.now() },
+            ...existing,
+        ].slice(0, MAX_RECENTS);
+        globalThis.localStorage?.setItem(storageKey, JSON.stringify(updated));
+    }
+    catch {
+        // localStorage unavailable (SSR, private browsing quota exceeded)
+    }
+}
+/**
+ * Clears all recent kind entries. Useful for testing or user preference reset.
+ */
+export function clearRecentKinds(storageKey = DEFAULT_STORAGE_KEY) {
+    try {
+        globalThis.localStorage?.removeItem(storageKey);
+    }
+    catch {
+        // Silently ignore storage errors
+    }
+}
+function isValidEntry(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "kind" in value &&
+        "timestamp" in value &&
+        typeof value.kind === "string" &&
+        typeof value.timestamp === "number");
+}
+//# sourceMappingURL=recents.js.map

package/workflow/picker/recents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recents.js","sourceRoot":"","sources":["../../../src/workflow/picker/recents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,mBAAmB,GAAG,6BAA6B,CAAC;AAC1D,MAAM,WAAW,GAAG,CAAC,CAAC;AAUtB;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,UAAU,GAAG,mBAAmB;IAC7D,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,UAAU,CAAC,YAAY,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;QACzD,IAAI,CAAC,GAAG;YAAE,OAAO,EAAE,CAAC;QAEpB,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACxC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;YAAE,OAAO,EAAE,CAAC;QAEtC,OAAO,MAAM;aACV,MAAM,CAAC,YAAY,CAAC;aACpB,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC;aACzC,KAAK,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAY,EACZ,UAAU,GAAG,mBAAmB;IAEhC,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;QAC3E,MAAM,OAAO,GAAsB;YACjC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE;YAC/B,GAAG,QAAQ;SACZ,CAAC,KAAK,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC;QAExB,UAAU,CAAC,YAAY,EAAE,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;IACxE,CAAC;IAAC,MAAM,CAAC;QACP,kEAAkE;IACpE,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,UAAU,GAAG,mBAAmB;IAC/D,IAAI,CAAC;QACH,UAAU,CAAC,YAAY,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,iCAAiC;IACnC,CAAC;AACH,CAAC;AAED,SAAS,YAAY,CAAC,KAAc;IAClC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,MAAM,IAAI,KAAK;QACf,WAAW,IAAI,KAAK;QACpB,OAAQ,KAAyB,CAAC,IAAI,KAAK,QAAQ;QACnD,OAAQ,KAAyB,CAAC,SAAS,KAAK,QAAQ,CACzD,CAAC;AACJ,CAAC"}

package/workflow/picker/suggestions.d.ts

@@ -0,0 +1,21 @@
+import type { InsertionContext } from "./insertion-context";
+/**
+ * A suggested task kind with a human-readable reason.
+ *
+ * Rendered in the "Suggested" section of the picker, above Recent and
+ * All Categories. Suggestions are derived from static domain knowledge
+ * about common workflow patterns.
+ */
+export interface TaskKindSuggestion {
+    readonly kind: string;
+    readonly reason: string;
+}
+/**
+ * Returns suggested task kinds for the given insertion context.
+ *
+ * The suggestions are based on a static compatibility map that encodes
+ * common workflow authoring patterns. Results are ordered by relevance
+ * (most common pairing first) and capped at `maxResults`.
+ */
+export declare function getSuggestedKinds(context: InsertionContext, maxResults?: number): readonly TaskKindSuggestion[];
+//# sourceMappingURL=suggestions.d.ts.map

package/workflow/picker/suggestions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggestions.d.ts","sourceRoot":"","sources":["../../../src/workflow/picker/suggestions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAkLD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,gBAAgB,EACzB,UAAU,SAAI,GACb,SAAS,kBAAkB,EAAE,CAgB/B"}

package/workflow/picker/suggestions.js

@@ -0,0 +1,196 @@
+/**
+ * Static compatibility map: source task kind -> suggested next kinds.
+ *
+ * Derived from the research report (Section 4.2) and common workflow
+ * authoring patterns observed across n8n, Retool, and Step Functions.
+ *
+ * The map encodes domain knowledge: "after an HTTP call, users commonly
+ * validate the response, transform the data, or branch on status."
+ */
+const SUGGESTIONS_AFTER_KIND = new Map([
+    [
+        "http_call",
+        [
+            { kind: "validate", reason: "Validate HTTP response" },
+            { kind: "transform", reason: "Transform response data" },
+            { kind: "switch_case", reason: "Branch on status/content" },
+        ],
+    ],
+    [
+        "grpc_call",
+        [
+            { kind: "validate", reason: "Validate gRPC response" },
+            { kind: "transform", reason: "Transform response data" },
+            { kind: "switch_case", reason: "Branch on result" },
+        ],
+    ],
+    [
+        "llm_call",
+        [
+            { kind: "eval", reason: "Evaluate LLM output quality" },
+            { kind: "switch_case", reason: "Branch on structured output" },
+            { kind: "set_vars", reason: "Store output in variables" },
+            { kind: "transform", reason: "Extract from response" },
+        ],
+    ],
+    [
+        "agent_call",
+        [
+            { kind: "switch_case", reason: "Branch on agent result" },
+            { kind: "human_input", reason: "Review agent output" },
+            { kind: "transform", reason: "Extract structured data" },
+            { kind: "eval", reason: "Evaluate agent quality" },
+        ],
+    ],
+    [
+        "transform",
+        [
+            { kind: "switch_case", reason: "Branch on transformed value" },
+            { kind: "http_call", reason: "Send transformed data" },
+            { kind: "agent_call", reason: "Process with agent" },
+            { kind: "validate", reason: "Validate transformation" },
+        ],
+    ],
+    [
+        "set_vars",
+        [
+            { kind: "switch_case", reason: "Branch on variable value" },
+            { kind: "http_call", reason: "Use variables in request" },
+            { kind: "agent_call", reason: "Pass variables to agent" },
+        ],
+    ],
+    [
+        "validate",
+        [
+            { kind: "switch_case", reason: "Branch on validation result" },
+            { kind: "transform", reason: "Fix validation issues" },
+            { kind: "raise_error", reason: "Fail on invalid data" },
+        ],
+    ],
+    [
+        "human_input",
+        [
+            { kind: "switch_case", reason: "Branch on approval decision" },
+            { kind: "agent_call", reason: "Continue with agent" },
+            { kind: "http_call", reason: "Proceed with API call" },
+            { kind: "notification", reason: "Notify about decision" },
+        ],
+    ],
+    [
+        "eval",
+        [
+            { kind: "switch_case", reason: "Branch on evaluation score" },
+            { kind: "human_input", reason: "Review if score is low" },
+            { kind: "notification", reason: "Alert on quality issue" },
+        ],
+    ],
+    [
+        "switch_case",
+        [
+            { kind: "agent_call", reason: "Process in branch" },
+            { kind: "http_call", reason: "Call API in branch" },
+            { kind: "llm_call", reason: "Generate in branch" },
+        ],
+    ],
+    [
+        "fork",
+        [
+            { kind: "transform", reason: "Merge parallel results" },
+            { kind: "switch_case", reason: "Branch on merged result" },
+            { kind: "agent_call", reason: "Process merged output" },
+        ],
+    ],
+    [
+        "for_each",
+        [
+            { kind: "transform", reason: "Aggregate iteration results" },
+            { kind: "switch_case", reason: "Branch on aggregated result" },
+        ],
+    ],
+    [
+        "listen",
+        [
+            { kind: "switch_case", reason: "Branch on event type" },
+            { kind: "agent_call", reason: "Process received event" },
+            { kind: "transform", reason: "Extract event data" },
+        ],
+    ],
+    [
+        "wait",
+        [
+            { kind: "http_call", reason: "Poll after delay" },
+            { kind: "agent_call", reason: "Resume processing" },
+            { kind: "notification", reason: "Notify after wait" },
+        ],
+    ],
+    [
+        "notification",
+        [
+            { kind: "wait", reason: "Wait for response" },
+            { kind: "listen", reason: "Wait for event" },
+            { kind: "human_input", reason: "Await acknowledgment" },
+        ],
+    ],
+]);
+/**
+ * Context-specific suggestions for branch addition modes.
+ */
+const SUGGESTIONS_FOR_BRANCH = new Map([
+    [
+        "add-switch-case",
+        [
+            { kind: "agent_call", reason: "Process this case with agent" },
+            { kind: "http_call", reason: "Call API for this case" },
+            { kind: "human_input", reason: "Require approval for this case" },
+            { kind: "llm_call", reason: "Generate for this case" },
+        ],
+    ],
+    [
+        "add-fork-branch",
+        [
+            { kind: "agent_call", reason: "Run agent in parallel" },
+            { kind: "http_call", reason: "Call API in parallel" },
+            { kind: "llm_call", reason: "Generate in parallel" },
+            { kind: "transform", reason: "Transform in parallel" },
+        ],
+    ],
+    [
+        "add-catch-handler",
+        [
+            { kind: "notification", reason: "Notify on error" },
+            { kind: "agent_call", reason: "Attempt recovery with agent" },
+            { kind: "raise_error", reason: "Re-raise with context" },
+            { kind: "http_call", reason: "Report error to service" },
+        ],
+    ],
+]);
+/** Default suggestions when no specific context is available. */
+const DEFAULT_SUGGESTIONS = [
+    { kind: "agent_call", reason: "Most common task type" },
+    { kind: "llm_call", reason: "Direct LLM invocation" },
+    { kind: "http_call", reason: "External API call" },
+    { kind: "switch_case", reason: "Conditional branching" },
+];
+/**
+ * Returns suggested task kinds for the given insertion context.
+ *
+ * The suggestions are based on a static compatibility map that encodes
+ * common workflow authoring patterns. Results are ordered by relevance
+ * (most common pairing first) and capped at `maxResults`.
+ */
+export function getSuggestedKinds(context, maxResults = 5) {
+    // Branch-specific modes have their own suggestion sets
+    const branchSuggestions = SUGGESTIONS_FOR_BRANCH.get(context.mode);
+    if (branchSuggestions) {
+        return branchSuggestions.slice(0, maxResults);
+    }
+    // For edge-splice and append-after, look up by source kind
+    if (context.sourceKind) {
+        const kindSuggestions = SUGGESTIONS_AFTER_KIND.get(context.sourceKind);
+        if (kindSuggestions && kindSuggestions.length > 0) {
+            return kindSuggestions.slice(0, maxResults);
+        }
+    }
+    return DEFAULT_SUGGESTIONS.slice(0, maxResults);
+}
+//# sourceMappingURL=suggestions.js.map

package/workflow/picker/suggestions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggestions.js","sourceRoot":"","sources":["../../../src/workflow/picker/suggestions.ts"],"names":[],"mappings":"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"}

package/workflow/picker/usePickerData.d.ts

@@ -0,0 +1,50 @@
+import type { TaskKindDescriptor, TaskKindCategory } from "../types";
+import type { WorkflowGraphModel } from "../workflow-graph-model";
+import type { InsertionContext } from "./insertion-context";
+/**
+ * A picker item enriched with context-awareness metadata.
+ */
+export interface PickerItem {
+    readonly descriptor: TaskKindDescriptor;
+    readonly disabled: boolean;
+    readonly disabledReason?: string;
+}
+/**
+ * A named section in the picker (Suggested, Recent, or a category group).
+ */
+export interface PickerSection {
+    readonly id: string;
+    readonly label: string;
+    readonly items: readonly PickerItem[];
+    /** If true, this section is a special (Suggested/Recent) section, not a category. */
+    readonly isSpecial?: boolean;
+}
+/**
+ * The complete picker data model returned by {@link usePickerData}.
+ */
+export interface PickerData {
+    /** Contextual header text (e.g., "Insert between A and B"). */
+    readonly header: string;
+    /** Ordered sections to render in the picker. */
+    readonly sections: readonly PickerSection[];
+    /** Flat list of all selectable (non-disabled) items for keyboard navigation. */
+    readonly selectableItems: readonly PickerItem[];
+    /** Whether the registry is still loading. */
+    readonly isLoading: boolean;
+}
+/**
+ * Computes the full picker data model from insertion context, task registry,
+ * and graph model.
+ *
+ * This hook is the bridge between the pure intelligence layer (suggestions,
+ * compatibility, recents) and the picker UI component. It produces a stable,
+ * memoized data structure that drives rendering.
+ *
+ * @param context - The insertion context describing where and how the user is inserting.
+ * @param categories - Category-grouped task descriptors from `useTaskKindRegistry()`.
+ * @param graph - The current workflow graph model (for constraint evaluation).
+ * @param isLoading - Whether the task kind registry is still loading.
+ * @param searchQuery - Current search query for filtering.
+ */
+export declare function usePickerData(context: InsertionContext | null, categories: ReadonlyMap<TaskKindCategory, readonly TaskKindDescriptor[]>, graph: WorkflowGraphModel | null, isLoading: boolean, searchQuery: string): PickerData;
+//# sourceMappingURL=usePickerData.d.ts.map

package/workflow/picker/usePickerData.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePickerData.d.ts","sourceRoot":"","sources":["../../../src/workflow/picker/usePickerData.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACrE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAElE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAM5D;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;IACtC,qFAAqF;IACrF,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;IAC5C,gFAAgF;IAChF,QAAQ,CAAC,eAAe,EAAE,SAAS,UAAU,EAAE,CAAC;IAChD,6CAA6C;IAC7C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,gBAAgB,GAAG,IAAI,EAChC,UAAU,EAAE,WAAW,CAAC,gBAAgB,EAAE,SAAS,kBAAkB,EAAE,CAAC,EACxE,KAAK,EAAE,kBAAkB,GAAG,IAAI,EAChC,SAAS,EAAE,OAAO,EAClB,WAAW,EAAE,MAAM,GAClB,UAAU,CAwGZ"}