@memberjunction/ng-task-graph-editor 6.1.0-edge.1 → 6.1.0-edge.3

package/dist/lib/task-graph-canvas-adapter.d.ts

@@ -16,13 +16,79 @@
  * @module @memberjunction/ng-task-graph-editor
  */
 import { type TaskGraphSpec, type TaskGraphSpecNode, type TaskGraphDependency } from '@memberjunction/ai-core-plus';
-import type { FlowConnection, FlowNode, FlowNodeStatus, FlowNodeTypeConfig } from '@memberjunction/ng-flow-editor';
-/** Node types the palette offers. Two, because a task is either an agent's or a person's. */
-export declare const TASK_GRAPH_NODE_TYPES: FlowNodeTypeConfig[];
+import type { FlowConnection, FlowNode, FlowNodeStatus, FlowNodeTypeConfig, FlowPosition } from '@memberjunction/ng-flow-editor';
+/**
+ * The shapes this canvas can DRAW.
+ *
+ * Three of the spec's seven `kind`s, and the choice is the canvas's: these are the shapes a person
+ * authors. `Prompt`, `ForEach`, `While` and `External` are expressible in the spec but have no
+ * authoring affordance here — a palette entry that cannot be configured would be worse than none.
+ *
+ * **Drawing and RENDERING are different questions**, which this type used to conflate. A run's
+ * graph is displayed on the same canvas, and it contains kinds nobody can draw — so mapping them
+ * all to `AgentTask` made a fully-configured ForEach render as "AGENT STEP · No agent chosen yet",
+ * which is not merely imprecise: it says the step is broken. See {@link TaskGraphRenderType}.
+ */
+export type TaskGraphNodeType = 'AgentTask' | 'ActionTask' | 'HumanTask';
+/**
+ * The shapes this canvas can SHOW — a superset of what it can draw.
+ *
+ * Display-only kinds exist because a task graph is rendered in two places: the editor, where a
+ * person builds one, and a run view, where one that already ran is shown. The second must be able
+ * to depict every kind the dispatcher can execute, whether or not the palette offers it.
+ */
+export type TaskGraphRenderType = TaskGraphNodeType | 'PromptTask' | 'ForEachTask' | 'WhileTask' | 'ExternalTask';
+/** A palette entry, pinned to one of the three authorable shapes. */
+export type TaskGraphNodeTypeConfig = FlowNodeTypeConfig & {
+    Type: TaskGraphNodeType;
+};
+/**
+ * Whether a shape is one a person can actually author here.
+ *
+ * The authoring paths — the palette, `NewTaskFromNodeType`, the properties panel — only handle the
+ * three drawable shapes. Rendering handles more. This is the seam between the two, stated as a type
+ * guard so the compiler enforces it rather than a cast pretending the distinction does not exist.
+ */
+export declare function IsAuthorableNodeType(type: TaskGraphRenderType): type is TaskGraphNodeType;
+/** A rendering entry — every shape the canvas can depict, authorable or not. */
+export type TaskGraphRenderTypeConfig = FlowNodeTypeConfig & {
+    Type: TaskGraphRenderType;
+};
+/**
+ * Port ids are scoped to their NODE, and must be.
+ *
+ * The canvas resolves a connection by looking its `fOutputId` / `fInputId` up among all registered
+ * ports — a flat, graph-wide namespace. Giving every node ports literally called `in` and `out` made
+ * every node's ports collide with every other node's, so a connection could not name which node's
+ * port it meant. The result was a workflow that drew its boxes correctly and **no edges at all**:
+ * nothing errored, because an unresolvable port is simply a connection with nowhere to attach.
+ *
+ * The Flow Agent editor — the other consumer of this canvas, whose edges have always drawn — scopes
+ * its ports the same way (`${stepId}-input` / `${stepId}-output`). This is that convention, named,
+ * so a future producer cannot reintroduce the collision by writing the obvious literal.
+ */
+export declare function InputPortID(tempId: string): string;
+export declare function OutputPortID(tempId: string): string;
+/** What the palette offers — one entry per assignment shape the spec supports. */
+export declare const TASK_GRAPH_NODE_TYPES: readonly TaskGraphNodeTypeConfig[];
+/**
+ * Everything the canvas can DEPICT: the palette, plus the kinds that only ever arrive from a run.
+ *
+ * Deliberately a superset rather than an extension of the palette — adding these to
+ * `TASK_GRAPH_NODE_TYPES` would put un-configurable entries in the authoring toolbox.
+ */
+export declare const TASK_GRAPH_RENDER_TYPES: readonly TaskGraphRenderTypeConfig[];
+/**
+ * The config for a node type, or null when the type is not one of ours.
+ *
+ * Searches the RENDER set, so a run's ForEach resolves to its own icon and label instead of
+ * silently falling back to the agent shape.
+ */
+export declare function GetNodeTypeConfig(type: string): TaskGraphRenderTypeConfig | null;
 /** Live per-task state for the runtime overlay, keyed by `tempId`. */
 export type TaskGraphRuntimeStatus = Record<string, TaskGraphRuntimeState>;
 /** What a task is doing right now, in the durable engine's own vocabulary. */
-export type TaskGraphRuntimeState = 'Pending' | 'In Progress' | 'Complete' | 'Failed' | 'Blocked' | 'Cancelled' | 'Deferred';
+export type TaskGraphRuntimeState = 'Pending' | 'In Progress' | 'Complete' | 'Failed' | 'Blocked' | 'Cancelled' | 'Deferred' | 'Skipped';
 /**
  * Maps a durable task state onto the canvas's visual vocabulary.
  *
@@ -32,8 +98,38 @@ export type TaskGraphRuntimeState = 'Pending' | 'In Progress' | 'Complete' | 'Fa
  * on a schedule and waiting on a prerequisite look and mean the same thing.
  */
 export declare function RuntimeStateToNodeStatus(state: TaskGraphRuntimeState | undefined): FlowNodeStatus;
-/** True when the node is a person's step rather than an agent's. */
+/**
+ * True when the node is a person's step.
+ *
+ * One field decides it now: spec v2 gives every node exactly one `kind`, so "is this a person's
+ * step" stopped being an inference over three optional flags and became a comparison.
+ */
 export declare function IsHumanTask(node: TaskGraphSpecNode): boolean;
+/**
+ * Which of the three shapes a node is, for rendering.
+ *
+ * An unassigned node (just added, nothing picked yet) reads as an agent step: it is the commonest
+ * intent, and the validator is already telling the author, in words, that it needs an assignee.
+ * Guessing "person" instead — which is what the old `!agentName` rule did — put a step in the
+ * graph that claimed to be waiting on someone when nobody had said so.
+ */
+export declare function GetTaskNodeType(node: TaskGraphSpecNode): TaskGraphRenderType;
+/**
+ * Builds the task a palette entry stands for.
+ *
+ * Pure, and here rather than in the component, because "what does clicking *Person Step* actually
+ * put in the graph" is a fact about the spec — testable without a TestBed, and the one place the
+ * assignment xor is honoured on creation.
+ *
+ * `defaultAgentName` / `defaultActionName` are what the host has to offer. When it has nothing, the
+ * step is created unassigned on purpose: inventing an agent name that may not exist would produce a
+ * graph that passes the canvas and fails at submission, whereas an unassigned step is reported
+ * immediately by the same validator the engine runs.
+ */
+export declare function NewTaskFromNodeType(spec: TaskGraphSpec, type: TaskGraphNodeType, defaults?: {
+    agentName?: string;
+    actionName?: string;
+}): TaskGraphSpecNode;
 /** Entry points: nodes nothing else has to finish first. Same rule the traversal engine uses. */
 export declare function GetEntryTempIds(spec: TaskGraphSpec): string[];
 /** Every dependency of a node, in normalized object form. */
@@ -47,7 +143,44 @@ export declare function GetDependents(spec: TaskGraphSpec, tempId: string): stri
  * geometry precisely because a task graph is a *logical* structure. An agent that emitted one never
  * had an opinion about where the boxes go.
  */
-export declare function SpecToNodes(spec: TaskGraphSpec, runtime?: TaskGraphRuntimeStatus): FlowNode[];
+/**
+ * Projects the spec onto canvas nodes.
+ *
+ * `positions` carries geometry the spec cannot hold. `TaskGraphSpec` is an execution contract with
+ * no layout field, so without a caller-held map every re-projection would return every node to the
+ * origin — which is what previously forced a full re-arrange (and a viewport re-zoom) after every
+ * single edit. Unknown ids fall back to the origin, which is also the correct starting state for a
+ * graph that has never been laid out.
+ */
+/**
+ * Debug overlay the run view hands the adapter. Paint only — the widget never calls an operation.
+ *
+ * Breakpoints and the paused-at step become badges. Overrides restyle connections (dotted, never
+ * dashed — dashed already means "this edge is conditional"). Held/forced edges stay visible even
+ * when a skip cascade would otherwise drop them, so the run history cannot lie about why a branch
+ * ran.
+ */
+export type TaskGraphDebugOverlay = {
+    breakpoints?: readonly string[];
+    pausedAtTaskID?: string | null;
+    /** Graph is claim-gated. With no paused-at step, the entry node is what is waiting. */
+    paused?: boolean;
+    edgeOverrides?: Readonly<Record<string, 'true' | 'false'>>;
+    /** Show the condition expression on the connection label, not just the word "if". */
+    showConditions?: boolean;
+    /** Edge IDs (or from→to) currently flowing — painted animated + brand. */
+    activeEdgeIDs?: readonly string[];
+};
+export declare function SpecToNodes(spec: TaskGraphSpec, runtime?: TaskGraphRuntimeStatus, positions?: ReadonlyMap<string, FlowPosition>, debug?: TaskGraphDebugOverlay): FlowNode[];
+/** Badge pills for an armed breakpoint and the step the graph actually stopped on. */
+export declare function NodeDebugBadges(taskID: string, breakpoints: ReadonlySet<string>, debug?: TaskGraphDebugOverlay, runtime?: TaskGraphRuntimeStatus, entryIds?: ReadonlySet<string>): FlowNode['Badges'];
+/**
+ * The one line under a node's name: who or what runs it.
+ *
+ * An unassigned step says so rather than showing nothing — a blank subtitle looks like a step that
+ * is fine, and this one is the reason the validation banner is complaining.
+ */
+export declare function TaskSubtitle(task: TaskGraphSpecNode, type?: TaskGraphRenderType): string;
 /**
  * Projects the spec's dependencies onto canvas connections, reversing their direction.
  *
@@ -59,7 +192,9 @@ export declare function SpecToNodes(spec: TaskGraphSpec, runtime?: TaskGraphRunt
  * validator reports them as `UnknownDependency`, and rendering a connection to nowhere would be a
  * second, worse way of saying the same thing.
  */
-export declare function SpecToConnections(spec: TaskGraphSpec): FlowConnection[];
+export declare function SpecToConnections(spec: TaskGraphSpec, runtime?: TaskGraphRuntimeStatus, debug?: TaskGraphDebugOverlay): FlowConnection[];
+/** One canvas connection, including the override styling that must never look like a real verdict. */
+export declare function ProjectConnection(dep: TaskGraphDependency, toTempId: string, override?: 'true' | 'false', showConditions?: boolean, flowing?: boolean, traveled?: boolean): FlowConnection;
 /**
  * Adds a dependency to the spec, returning a NEW spec.
  *

package/dist/lib/task-graph-canvas-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task-graph-canvas-adapter.d.ts","sourceRoot":"","sources":["../../src/lib/task-graph-canvas-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAEH,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EAC3B,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAEnH,6FAA6F;AAC7F,eAAO,MAAM,qBAAqB,EAAE,kBAAkB,EAuBrD,CAAC;AAEF,sEAAsE;AACtE,MAAM,MAAM,sBAAsB,GAAG,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;AAE3E,8EAA8E;AAC9E,MAAM,MAAM,qBAAqB,GAC3B,SAAS,GACT,aAAa,GACb,UAAU,GACV,QAAQ,GACR,SAAS,GACT,WAAW,GACX,UAAU,CAAC;AAEjB;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,qBAAqB,GAAG,SAAS,GAAG,cAAc,CAWjG;AAED,oEAAoE;AACpE,wBAAgB,WAAW,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAE5D;AAED,iGAAiG;AACjG,wBAAgB,eAAe,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,EAAE,CAE7D;AAED,6DAA6D;AAC7D,wBAAgB,eAAe,CAAC,IAAI,EAAE,iBAAiB,GAAG,mBAAmB,EAAE,CAE9E;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAI3E;AAOD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,sBAAsB,GAAG,QAAQ,EAAE,CAsB7F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,aAAa,GAAG,cAAc,EAAE,CA0BvE;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,aAAa,CAa1H;AAED,kDAAkD;AAClD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,aAAa,CASzG;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa,CAO7E;AAED,yCAAyC;AACzC,wBAAgB,OAAO,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,iBAAiB,GAAG,aAAa,CAEnF;AAED,kEAAkE;AAClE,wBAAgB,UAAU,CAAC,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,GAAG,aAAa,CAEtG;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAmBnG;AAED,qEAAqE;AACrE,wBAAgB,UAAU,CAAC,IAAI,EAAE,aAAa,EAAE,MAAM,SAAS,GAAG,MAAM,CAKvE"}
+{"version":3,"file":"task-graph-canvas-adapter.d.ts","sourceRoot":"","sources":["../../src/lib/task-graph-canvas-adapter.ts"],"names":[],"mappings":"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"}

package/dist/lib/task-graph-canvas-adapter.js

@@ -15,8 +15,46 @@
  *
  * @module @memberjunction/ng-task-graph-editor
  */
-import { NormalizeDependency, } from '@memberjunction/ai-core-plus';
-/** Node types the palette offers. Two, because a task is either an agent's or a person's. */
+import { ConfigOf, NormalizeDependency, TaskNode, } from '@memberjunction/ai-core-plus';
+/**
+ * Whether a shape is one a person can actually author here.
+ *
+ * The authoring paths — the palette, `NewTaskFromNodeType`, the properties panel — only handle the
+ * three drawable shapes. Rendering handles more. This is the seam between the two, stated as a type
+ * guard so the compiler enforces it rather than a cast pretending the distinction does not exist.
+ */
+export function IsAuthorableNodeType(type) {
+    return type === 'AgentTask' || type === 'ActionTask' || type === 'HumanTask';
+}
+/**
+ * Port ids are scoped to their NODE, and must be.
+ *
+ * The canvas resolves a connection by looking its `fOutputId` / `fInputId` up among all registered
+ * ports — a flat, graph-wide namespace. Giving every node ports literally called `in` and `out` made
+ * every node's ports collide with every other node's, so a connection could not name which node's
+ * port it meant. The result was a workflow that drew its boxes correctly and **no edges at all**:
+ * nothing errored, because an unresolvable port is simply a connection with nowhere to attach.
+ *
+ * The Flow Agent editor — the other consumer of this canvas, whose edges have always drawn — scopes
+ * its ports the same way (`${stepId}-input` / `${stepId}-output`). This is that convention, named,
+ * so a future producer cannot reintroduce the collision by writing the obvious literal.
+ */
+export function InputPortID(tempId) {
+    return `${tempId}-in`;
+}
+export function OutputPortID(tempId) {
+    return `${tempId}-out`;
+}
+/**
+ * Palette defaults. These carry the bare names because a palette entry describes a node TYPE, not a
+ * placed node — there is no id to scope them to yet. {@link SpecToNodes} assigns the real, scoped
+ * ids when a node is actually placed on the canvas.
+ */
+const TASK_GRAPH_PORTS = [
+    { ID: 'in', Direction: 'input', Side: 'top', Multiple: true },
+    { ID: 'out', Direction: 'output', Side: 'bottom', Multiple: true },
+];
+/** What the palette offers — one entry per assignment shape the spec supports. */
 export const TASK_GRAPH_NODE_TYPES = [
     {
         Type: 'AgentTask',
@@ -24,10 +62,15 @@ export const TASK_GRAPH_NODE_TYPES = [
         Icon: 'fa-robot',
         Color: '#4A6FA5',
         Category: 'Steps',
-        DefaultPorts: [
-            { ID: 'in', Direction: 'input', Side: 'top', Multiple: true },
-            { ID: 'out', Direction: 'output', Side: 'bottom', Multiple: true },
-        ],
+        DefaultPorts: TASK_GRAPH_PORTS,
+    },
+    {
+        Type: 'ActionTask',
+        Label: 'Action Step',
+        Icon: 'fa-bolt',
+        Color: '#3B82F6',
+        Category: 'Steps',
+        DefaultPorts: TASK_GRAPH_PORTS,
     },
     {
         Type: 'HumanTask',
@@ -35,12 +78,31 @@ export const TASK_GRAPH_NODE_TYPES = [
         Icon: 'fa-user-check',
         Color: '#7B1FA2',
         Category: 'Steps',
-        DefaultPorts: [
-            { ID: 'in', Direction: 'input', Side: 'top', Multiple: true },
-            { ID: 'out', Direction: 'output', Side: 'bottom', Multiple: true },
-        ],
+        DefaultPorts: TASK_GRAPH_PORTS,
     },
 ];
+/**
+ * Everything the canvas can DEPICT: the palette, plus the kinds that only ever arrive from a run.
+ *
+ * Deliberately a superset rather than an extension of the palette — adding these to
+ * `TASK_GRAPH_NODE_TYPES` would put un-configurable entries in the authoring toolbox.
+ */
+export const TASK_GRAPH_RENDER_TYPES = [
+    ...TASK_GRAPH_NODE_TYPES,
+    { Type: 'PromptTask', Label: 'Prompt Step', Icon: 'fa-comment-dots', Color: '#8B5CF6', Category: 'Steps', DefaultPorts: TASK_GRAPH_PORTS },
+    { Type: 'ForEachTask', Label: 'For Each Step', Icon: 'fa-repeat', Color: '#D97706', Category: 'Steps', DefaultPorts: TASK_GRAPH_PORTS },
+    { Type: 'WhileTask', Label: 'While Step', Icon: 'fa-rotate', Color: '#D97706', Category: 'Steps', DefaultPorts: TASK_GRAPH_PORTS },
+    { Type: 'ExternalTask', Label: 'External Step', Icon: 'fa-arrow-up-right-from-square', Color: '#0891B2', Category: 'Steps', DefaultPorts: TASK_GRAPH_PORTS },
+];
+/**
+ * The config for a node type, or null when the type is not one of ours.
+ *
+ * Searches the RENDER set, so a run's ForEach resolves to its own icon and label instead of
+ * silently falling back to the agent shape.
+ */
+export function GetNodeTypeConfig(type) {
+    return TASK_GRAPH_RENDER_TYPES.find((c) => c.Type === type) ?? null;
+}
 /**
  * Maps a durable task state onto the canvas's visual vocabulary.
  *
@@ -56,15 +118,79 @@ export function RuntimeStateToNodeStatus(state) {
         case 'Failed': return 'error';
         case 'Blocked': return 'warning';
         case 'Cancelled': return 'disabled';
+        // Its own state, not a shade of disabled: a branch the workflow did not take is a normal
+        // outcome. Falling through to 'default' — which is what happened before — drew it as an
+        // ordinary node, so a conditional workflow looked like it had run every branch.
+        case 'Skipped': return 'skipped';
         case 'Deferred': return 'pending';
         case 'Pending': return 'pending';
         default: return 'default';
     }
 }
-/** True when the node is a person's step rather than an agent's. */
+/**
+ * True when the node is a person's step.
+ *
+ * One field decides it now: spec v2 gives every node exactly one `kind`, so "is this a person's
+ * step" stopped being an inference over three optional flags and became a comparison.
+ */
 export function IsHumanTask(node) {
-    return !node.agentName;
+    return node.kind === 'Human';
+}
+/**
+ * Which of the three shapes a node is, for rendering.
+ *
+ * An unassigned node (just added, nothing picked yet) reads as an agent step: it is the commonest
+ * intent, and the validator is already telling the author, in words, that it needs an assignee.
+ * Guessing "person" instead — which is what the old `!agentName` rule did — put a step in the
+ * graph that claimed to be waiting on someone when nobody had said so.
+ */
+export function GetTaskNodeType(node) {
+    switch (node.kind) {
+        case 'Human': return 'HumanTask';
+        case 'Action': return 'ActionTask';
+        case 'Prompt': return 'PromptTask';
+        case 'ForEach': return 'ForEachTask';
+        case 'While': return 'WhileTask';
+        case 'External': return 'ExternalTask';
+        // An unassigned node — just added, nothing picked — reads as an agent step: the commonest
+        // intent, and the validator is already saying in words that it needs an assignee.
+        default: return 'AgentTask';
+    }
+}
+/**
+ * Builds the task a palette entry stands for.
+ *
+ * Pure, and here rather than in the component, because "what does clicking *Person Step* actually
+ * put in the graph" is a fact about the spec — testable without a TestBed, and the one place the
+ * assignment xor is honoured on creation.
+ *
+ * `defaultAgentName` / `defaultActionName` are what the host has to offer. When it has nothing, the
+ * step is created unassigned on purpose: inventing an agent name that may not exist would produce a
+ * graph that passes the canvas and fails at submission, whereas an unassigned step is reported
+ * immediately by the same validator the engine runs.
+ */
+export function NewTaskFromNodeType(spec, type, defaults = {}) {
+    const base = {
+        tempId: NextTempId(spec),
+        name: NEW_TASK_NAMES[type],
+        description: '',
+        dependsOn: [],
+    };
+    switch (type) {
+        case 'HumanTask': return TaskNode.Human(base);
+        // A step created before the host has any names to offer is created with an empty one on
+        // purpose: the validator reports it immediately, whereas inventing a name would produce a
+        // graph that passes here and fails at submission.
+        case 'ActionTask': return TaskNode.Action(base, { actionName: defaults.actionName ?? '' });
+        default: return TaskNode.Agent(base, { agentName: defaults.agentName ?? '' });
+    }
 }
+/** Default step names, so a new box says what it is before the author renames it. */
+const NEW_TASK_NAMES = {
+    AgentTask: 'New agent step',
+    ActionTask: 'New action step',
+    HumanTask: 'New person step',
+};
 /** Entry points: nodes nothing else has to finish first. Same rule the traversal engine uses. */
 export function GetEntryTempIds(spec) {
     return (spec.tasks ?? []).filter((t) => (t.dependsOn ?? []).length === 0).map((t) => t.tempId);
@@ -83,35 +209,86 @@ export function GetDependents(spec, tempId) {
 function edgeId(fromTempId, toTempId) {
     return `${fromTempId}->${toTempId}`;
 }
-/**
- * Projects the spec onto canvas nodes.
- *
- * Positions are left at the origin: layout is the canvas's job (Dagre), and a spec carries no
- * geometry precisely because a task graph is a *logical* structure. An agent that emitted one never
- * had an opinion about where the boxes go.
- */
-export function SpecToNodes(spec, runtime) {
+export function SpecToNodes(spec, runtime, positions, debug) {
     const entryIds = new Set(GetEntryTempIds(spec));
+    const breakpoints = new Set(debug?.breakpoints ?? []);
     return (spec.tasks ?? []).map((task) => {
-        const human = IsHumanTask(task);
+        const type = GetTaskNodeType(task);
+        const known = positions?.get(task.tempId);
+        const awaiting = isAwaitingUser(task.tempId, entryIds, runtime, debug);
+        const nextToRun = isNextToRun(task, runtime, debug, entryIds);
+        const running = runtime?.[task.tempId] === 'In Progress';
         return {
             ID: task.tempId,
-            Type: human ? 'HumanTask' : 'AgentTask',
+            Type: type,
             Label: task.name,
-            Subtitle: human ? 'Waiting on a person' : task.agentName,
-            Icon: human ? 'fa-user-check' : 'fa-robot',
+            Subtitle: TaskSubtitle(task, type),
+            Icon: GetNodeTypeConfig(type)?.Icon ?? 'fa-circle-nodes',
+            IconColor: awaiting || nextToRun || running ? 'var(--mj-brand-primary)' : undefined,
+            // Keep the real runtime status. Mapping "paused here" to `running` drew a spinner
+            // on a step that is waiting for the operator — it read as "this is executing".
             Status: RuntimeStateToNodeStatus(runtime?.[task.tempId]),
             StatusMessage: task.description,
             IsStartNode: entryIds.has(task.tempId),
-            Position: { X: 0, Y: 0 },
+            Badges: NodeDebugBadges(task.tempId, breakpoints, debug, runtime, entryIds),
+            Position: known ? { ...known } : { X: 0, Y: 0 },
             Ports: [
-                { ID: 'in', Direction: 'input', Side: 'top', Multiple: true },
-                { ID: 'out', Direction: 'output', Side: 'bottom', Multiple: true },
+                { ID: InputPortID(task.tempId), Direction: 'input', Side: 'top', Multiple: true },
+                { ID: OutputPortID(task.tempId), Direction: 'output', Side: 'bottom', Multiple: true },
             ],
-            Data: { TempId: task.tempId },
+            Data: { TempId: task.tempId, AwaitingUser: awaiting, NextToRun: nextToRun },
         };
     });
 }
+/** Badge pills for an armed breakpoint and the step the graph actually stopped on. */
+export function NodeDebugBadges(taskID, breakpoints, debug, runtime, entryIds) {
+    const badges = [];
+    if (isAwaitingUser(taskID, entryIds ?? new Set(), runtime, debug)) {
+        badges.push({
+            Label: 'Waiting on you — Continue or Step to run this step',
+            Value: 'Waiting here',
+            Icon: 'fa-pause',
+            Color: 'var(--mj-brand-primary)',
+        });
+    }
+    if (breakpoints.has(taskID)) {
+        badges.push({
+            Label: 'Breakpoint',
+            Value: 'break',
+            Icon: 'fa-circle',
+            Color: 'var(--mj-status-error)',
+        });
+    }
+    return badges.length > 0 ? badges : undefined;
+}
+/**
+ * The one line under a node's name: who or what runs it.
+ *
+ * An unassigned step says so rather than showing nothing — a blank subtitle looks like a step that
+ * is fine, and this one is the reason the validation banner is complaining.
+ */
+export function TaskSubtitle(task, type = GetTaskNodeType(task)) {
+    switch (type) {
+        case 'HumanTask': return 'Waiting on a person';
+        case 'ActionTask': return ConfigOf(task, 'Action')?.actionName || 'No action chosen yet';
+        case 'PromptTask': return ConfigOf(task, 'Prompt')?.promptName || 'No prompt chosen yet';
+        // A loop's subtitle is what it REPEATS — the one fact that makes the node readable.
+        case 'ForEachTask': return LoopBodyLabel(ConfigOf(task, 'ForEach')) ?? 'Repeats for each item';
+        case 'WhileTask': return LoopBodyLabel(ConfigOf(task, 'While')) ?? 'Repeats until its condition is false';
+        case 'ExternalTask': return ConfigOf(task, 'External')?.domain || 'Completed by an outside system';
+        // Only a genuinely unassigned node reaches this now. It used to catch Prompt, ForEach,
+        // While and External too — so a fully-configured loop displayed "No agent chosen yet",
+        // which reads as a broken step rather than an unrecognised one.
+        default: return ConfigOf(task, 'Agent')?.agentName || 'No agent chosen yet';
+    }
+}
+/** What a loop repeats, when it says. */
+function LoopBodyLabel(op) {
+    if (!op)
+        return null;
+    const body = op.action?.name ?? op.subAgent?.name ?? op.prompt?.name;
+    return body ? `Repeats: ${body}` : null;
+}
 /**
  * Projects the spec's dependencies onto canvas connections, reversing their direction.
  *
@@ -123,32 +300,130 @@ export function SpecToNodes(spec, runtime) {
  * validator reports them as `UnknownDependency`, and rendering a connection to nowhere would be a
  * second, worse way of saying the same thing.
  */
-export function SpecToConnections(spec) {
+export function SpecToConnections(spec, runtime, debug) {
     const known = new Set((spec.tasks ?? []).map((t) => t.tempId));
+    const entryIds = new Set(GetEntryTempIds(spec));
     const connections = [];
     for (const task of spec.tasks ?? []) {
         for (const dep of GetDependencies(task)) {
             if (!known.has(dep.tempId))
                 continue;
-            const conditional = !!dep.condition?.trim();
-            connections.push({
-                ID: edgeId(dep.tempId, task.tempId),
-                // Reversed: dependsOn points back at the prerequisite, the drawn arrow points forward.
-                SourceNodeID: dep.tempId,
-                SourcePortID: 'out',
-                TargetNodeID: task.tempId,
-                TargetPortID: 'in',
-                Label: conditional ? 'if' : undefined,
-                LabelDetail: dep.condition ?? undefined,
-                LabelIcon: conditional ? 'fa-code-branch' : undefined,
-                Condition: dep.condition ?? undefined,
-                Style: conditional ? 'dashed' : 'solid',
-                Data: { FromTempId: dep.tempId, ToTempId: task.tempId },
-            });
+            const override = dep.id ? debug?.edgeOverrides?.[dep.id] : undefined;
+            const eitherSkipped = runtime
+                && (runtime[task.tempId] === 'Skipped' || runtime[dep.tempId] === 'Skipped');
+            // RUN MODE DRAWS ONLY THE PATH TAKEN — except an operator-forced edge, which must stay
+            // visible or the history lies about why a branch ran (or did not).
+            if (eitherSkipped && !override)
+                continue;
+            const destQueued = isNextToRun(task, runtime, debug, entryIds);
+            const flowing = destQueued || isFlowingEdge(dep.tempId, task.tempId, runtime, debug);
+            connections.push(ProjectConnection(dep, task.tempId, override, debug?.showConditions === true, flowing, !flowing && isTraveledEdge(dep.tempId, task.tempId, runtime)));
         }
     }
     return connections;
 }
+/** One canvas connection, including the override styling that must never look like a real verdict. */
+export function ProjectConnection(dep, toTempId, override, showConditions = false, flowing = false, traveled = false) {
+    const conditional = !!dep.condition?.trim();
+    const forced = override === 'true' || override === 'false';
+    const conditionLabel = dep.condition?.trim()
+        ? TruncateCondition(dep.condition.trim())
+        : undefined;
+    return {
+        ID: edgeId(dep.tempId, toTempId),
+        SourceNodeID: dep.tempId,
+        SourcePortID: OutputPortID(dep.tempId),
+        TargetNodeID: toTempId,
+        TargetPortID: InputPortID(toTempId),
+        Label: forced
+            ? (override === 'true' ? 'forced yes' : 'forced no')
+            : (conditional ? (showConditions && conditionLabel ? conditionLabel : 'if') : undefined),
+        LabelDetail: forced
+            ? `Operator set this path to ${override}${dep.condition ? ` — ${dep.condition}` : ''}`
+            : (dep.condition ?? undefined),
+        LabelIcon: forced ? 'fa-hand' : (conditional ? 'fa-code-branch' : undefined),
+        LabelIconColor: forced ? 'var(--mj-status-warning)' : undefined,
+        Condition: dep.condition ?? undefined,
+        // Dotted is the override. Dashed means "only sometimes" until the path is taken —
+        // after that the condition stays on the label, but the stroke is solid so a finished
+        // branch does not still look tentative.
+        Style: forced ? 'dotted' : (conditional && !traveled ? 'dashed' : 'solid'),
+        Color: flowing
+            ? 'var(--mj-brand-primary)'
+            : (forced ? 'var(--mj-status-warning)' : (traveled ? 'var(--mj-status-success)' : undefined)),
+        StrokeWidth: flowing ? 4.5 : (traveled || forced ? 3 : undefined),
+        Animated: flowing,
+        Data: { FromTempId: dep.tempId, ToTempId: toTempId, EdgeID: dep.id },
+    };
+}
+const TERMINAL_RUNTIME = new Set(['Complete', 'Failed', 'Cancelled', 'Skipped']);
+function isPausedHere(taskID, runtime, debug) {
+    if (debug?.pausedAtTaskID !== taskID)
+        return false;
+    const state = runtime?.[taskID];
+    return !state || !TERMINAL_RUNTIME.has(state);
+}
+/**
+ * The step the operator has to act on: the breakpoint we stopped at, or — at start-paused
+ * before any claim — the entry node.
+ */
+function isAwaitingUser(taskID, entryIds, runtime, debug) {
+    if (isPausedHere(taskID, runtime, debug))
+        return true;
+    if (!debug?.paused || debug.pausedAtTaskID)
+        return false;
+    if (!entryIds.has(taskID))
+        return false;
+    const state = runtime?.[taskID];
+    return !state || !TERMINAL_RUNTIME.has(state);
+}
+/**
+ * The next claimable step: prerequisites are done (or it is an entry) and the engine has not
+ * started it. Distinct from "waiting on you" — this one is waiting on the dispatcher.
+ */
+function isNextToRun(task, runtime, debug, entryIds) {
+    if (isAwaitingUser(task.tempId, entryIds ?? new Set(), runtime, debug))
+        return false;
+    const state = runtime?.[task.tempId];
+    if (state === 'In Progress' || (state && TERMINAL_RUNTIME.has(state)))
+        return false;
+    const incoming = GetDependencies(task);
+    if (incoming.length === 0)
+        return true;
+    const live = incoming.filter((d) => runtime?.[d.tempId] !== 'Skipped');
+    if (live.length === 0)
+        return false;
+    return live.every((d) => runtime?.[d.tempId] === 'Complete');
+}
+function isFlowingEdge(fromTempId, toTempId, runtime, debug) {
+    if (isPausedHere(toTempId, runtime, debug))
+        return true;
+    if (debug?.activeEdgeIDs?.includes(edgeId(fromTempId, toTempId)))
+        return true;
+    if (!runtime)
+        return false;
+    return runtime[fromTempId] === 'Complete' && runtime[toTempId] === 'In Progress';
+}
+const TAKEN_ORIGIN = new Set(['Complete', 'Failed', 'Cancelled']);
+const TAKEN_DEST = new Set(['In Progress', 'Complete', 'Failed', 'Cancelled']);
+/**
+ * Path already taken — origin finished AND dest has actually started. Pending dests are still
+ * candidates (a gate has not fired), so they stay dashed until one is claimed and the rest skip.
+ */
+function isTraveledEdge(fromTempId, toTempId, runtime) {
+    if (!runtime)
+        return false;
+    const fromState = runtime[fromTempId];
+    const toState = runtime[toTempId];
+    if (!fromState || !TAKEN_ORIGIN.has(fromState))
+        return false;
+    if (!toState || !TAKEN_DEST.has(toState))
+        return false;
+    return true;
+}
+function TruncateCondition(text, max = 28) {
+    return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
+}
 /**
  * Adds a dependency to the spec, returning a NEW spec.
  *