@open-mercato/core 0.7.1-develop.7193.1.910a5b0a1e → 0.7.1-develop.7194.1.ab4fc81f82

package/src/modules/workflows/lib/node-nudge.ts

@@ -0,0 +1,63 @@
+/**
+ * Arrow-key positioning for selected cards (spec section 4.6: "arrows nudge").
+ *
+ * Nudging is the keyboard's answer to dragging, so it obeys the same rule the
+ * drag path does (#4248): many keystrokes are ONE arrangement. The page captures
+ * the document before the first nudge of a burst and commits a single undo entry
+ * plus a single autosave once the burst settles.
+ *
+ * PURE: nodes in, nodes out.
+ */
+
+import type { Node } from '@xyflow/react'
+
+/** One press moves a card a hair; Shift moves it a visible step. */
+export const NUDGE_STEP = 1
+export const NUDGE_STEP_COARSE = 10
+
+/** Milliseconds of no arrow key before a nudge burst counts as finished. */
+export const NUDGE_COMMIT_DELAY_MS = 400
+
+export type NudgeDirection = 'up' | 'down' | 'left' | 'right'
+
+const NUDGE_KEYS: Record<string, NudgeDirection> = {
+  ArrowUp: 'up',
+  ArrowDown: 'down',
+  ArrowLeft: 'left',
+  ArrowRight: 'right',
+}
+
+export function resolveNudgeDirection(key: string): NudgeDirection | null {
+  return NUDGE_KEYS[key] ?? null
+}
+
+export function nudgeOffset(direction: NudgeDirection, coarse: boolean): { x: number; y: number } {
+  const distance = coarse ? NUDGE_STEP_COARSE : NUDGE_STEP
+  switch (direction) {
+    case 'up':
+      return { x: 0, y: -distance }
+    case 'down':
+      return { x: 0, y: distance }
+    case 'left':
+      return { x: -distance, y: 0 }
+    default:
+      return { x: distance, y: 0 }
+  }
+}
+
+/**
+ * Move every selected node by the offset. Returns the SAME array when nothing is
+ * selected so the caller can skip the commit and the autosave entirely.
+ */
+export function nudgeSelectedNodes(nodes: Node[], offset: { x: number; y: number }): Node[] {
+  if (!nodes.some((node) => node.selected)) return nodes
+  return nodes.map((node) =>
+    node.selected
+      ? { ...node, position: { x: node.position.x + offset.x, y: node.position.y + offset.y } }
+      : node,
+  )
+}
+
+export function selectedNodeIds(nodes: Node[]): string[] {
+  return nodes.filter((node) => node.selected).map((node) => node.id)
+}

package/src/modules/workflows/lib/node-outcome-rows.ts

@@ -0,0 +1,195 @@
+/**
+ * Workflows Module - Node outcome rows (pure)
+ *
+ * The data behind the node footer of the canvas redesign (fidelity gap #4): the
+ * labelled rows hanging off an agent or user-task card, each ending in a dot
+ * that IS its connection handle.
+ *
+ * Two producers, one row shape:
+ *
+ *  - an INVOKE_AGENT node renders spec §7.2's disposition outcomes, with the
+ *    progressive-disclosure rule applied — only WIRED outcomes plus `approved`,
+ *    which §7.2 renders unconditionally because it is the node's ordinary
+ *    output. Five agent nodes in a 60-node flow have to stay readable;
+ *  - a USER_TASK node renders its authored decisions, which need no engine work
+ *    at all: `taskDecisionSchema` already binds each decision to a durable
+ *    `transitionId`, so the row's handle is the only missing piece.
+ *
+ * PURE: no React, no `@xyflow/react`, no ORM. The component consumes rows; this
+ * decides what they are, which is what makes the rule testable without a canvas.
+ */
+
+import {
+  AGENT_OUTCOME_KINDS,
+  isAgentOutcomeKind,
+  outcomeSourceHandleId,
+  type AgentOutcomeKind,
+} from './outcome-routing'
+import { DEFAULT_SOURCE_HANDLE_ID } from './route-kinds'
+
+/**
+ * How a row reads at a glance. Paired with the row's LABEL, never standing in
+ * for it: at canvas zoom a 10px dot cannot carry meaning on its own, and two
+ * red dots are indistinguishable to a red-blind reader. The tone picks the DS
+ * status token; the glyph gives each row a second, non-colour discriminator.
+ */
+export type NodeOutcomeRowTone = 'success' | 'warning' | 'error' | 'info' | 'neutral'
+export type NodeOutcomeRowGlyph = 'check' | 'info' | 'slash' | 'shield' | 'alert' | 'dot' | 'corner'
+
+export interface NodeOutcomeRow {
+  /** Stable key AND the React Flow source handle id the dot binds to. */
+  handleId: string
+  /** i18n key for the row label. */
+  labelKey: string
+  /** English fallback, so an untranslated locale still names the row. */
+  labelFallback: string
+  tone: NodeOutcomeRowTone
+  glyph: NodeOutcomeRowGlyph
+}
+
+const OUTCOME_ROW_PRESENTATION: Record<
+  AgentOutcomeKind,
+  { tone: NodeOutcomeRowTone; glyph: NodeOutcomeRowGlyph; labelFallback: string }
+> = {
+  approved: { tone: 'success', glyph: 'check', labelFallback: 'approved' },
+  researcher: { tone: 'info', glyph: 'info', labelFallback: 'researcher' },
+  rejected: { tone: 'error', glyph: 'slash', labelFallback: 'rejected' },
+  guardrailBlocked: { tone: 'error', glyph: 'shield', labelFallback: 'guardrail blocked' },
+  error: { tone: 'warning', glyph: 'alert', labelFallback: 'error' },
+}
+
+export interface OutcomeRowTransitionLike {
+  fromStepId?: string
+  kind?: string
+  outcomeKind?: string
+}
+
+/**
+ * Which outcomes an agent node shows: every wired one, plus `approved`, in the
+ * platform's fixed order. Nothing else — an unwired outcome is reachable
+ * through the node's error directive, which the footer states rather than
+ * drawing a handle nobody connected.
+ */
+export function buildAgentOutcomeRows(
+  transitions: OutcomeRowTransitionLike[] | null | undefined,
+  stepId: string,
+): NodeOutcomeRow[] {
+  const shown = new Set<AgentOutcomeKind>(['approved'])
+  for (const transition of transitions ?? []) {
+    if (transition.fromStepId !== stepId) continue
+    if (transition.kind !== 'outcome') continue
+    if (isAgentOutcomeKind(transition.outcomeKind)) shown.add(transition.outcomeKind)
+  }
+
+  return AGENT_OUTCOME_KINDS.filter((outcome) => shown.has(outcome)).map((outcome) => ({
+    handleId: outcomeSourceHandleId(outcome),
+    labelKey: `workflows.outcomes.${outcome}`,
+    ...OUTCOME_ROW_PRESENTATION[outcome],
+  }))
+}
+
+export function buildAllAgentOutcomeRows(): NodeOutcomeRow[] {
+  return AGENT_OUTCOME_KINDS.map((outcome) => ({
+    handleId: outcomeSourceHandleId(outcome),
+    labelKey: `workflows.outcomes.${outcome}`,
+    ...OUTCOME_ROW_PRESENTATION[outcome],
+  }))
+}
+
+/**
+ * The step's ORDINARY output, as the footer's last row.
+ *
+ * It used to render as a lone handle floating at the card's right edge, roughly
+ * level with the first outcome row it then collided with. It is not decorative
+ * and deleting it would be a regression: `resolveAgentOutcomeHandling` returns
+ * `{ kind: 'default' }` — "route exactly as this instance always would have" —
+ * for a step that wired NO outcome at all (so this handle carries every
+ * disposition, which is how every definition written before §7.2 still runs)
+ * and for `approved` whenever `approved` is not separately wired.
+ *
+ * It is NOT a catch-all, which is why it is named `default` rather than
+ * `otherwise`: an unwired `rejected` / `researcher` / `guardrailBlocked` /
+ * `error` inherits the step's error directive instead, exactly as the footer's
+ * inheritance note states. A row promising "everything else comes here" would
+ * be the one label on this card an author could act on and be wrong.
+ *
+ * The handle id is unchanged (`source`), so a stored transition that resolves
+ * to it keeps resolving to it — this is presentation, not routing.
+ */
+export function buildDefaultRouteRow(): NodeOutcomeRow {
+  return {
+    handleId: DEFAULT_SOURCE_HANDLE_ID,
+    labelKey: 'workflows.outcomes.default',
+    labelFallback: 'default',
+    tone: 'neutral',
+    glyph: 'corner',
+  }
+}
+
+export interface DecisionRowLike {
+  id?: string
+  label?: unknown
+  transitionId?: string
+  style?: string
+}
+
+const DECISION_STYLE_PRESENTATION: Record<
+  string,
+  { tone: NodeOutcomeRowTone; glyph: NodeOutcomeRowGlyph }
+> = {
+  primary: { tone: 'success', glyph: 'check' },
+  secondary: { tone: 'neutral', glyph: 'dot' },
+  destructive: { tone: 'error', glyph: 'slash' },
+}
+
+/**
+ * A decision's authored label may be a plain string or a locale map
+ * (`taskLocalizedStringSchema`). The canvas shows the author's own words, so
+ * this reads the requested locale, then English, then the first entry — never
+ * an object rendered as `[object Object]`.
+ */
+export function readDecisionLabel(label: unknown, locale = 'en'): string {
+  if (typeof label === 'string') return label
+  if (!label || typeof label !== 'object') return ''
+  const map = label as Record<string, unknown>
+  for (const key of [locale, 'en']) {
+    if (typeof map[key] === 'string') return map[key] as string
+  }
+  const first = Object.values(map).find((value) => typeof value === 'string')
+  return typeof first === 'string' ? first : ''
+}
+
+/**
+ * A user task's decision buttons as footer rows. The handle id is the decision's
+ * DURABLE transition id, which is exactly what the engine already resolves the
+ * button to — so the canvas and the run agree by construction.
+ */
+export function buildDecisionOutcomeRows(
+  decisions: DecisionRowLike[] | null | undefined,
+  locale = 'en',
+): NodeOutcomeRow[] {
+  const rows: NodeOutcomeRow[] = []
+  for (const decision of decisions ?? []) {
+    if (!decision?.transitionId) continue
+    const label = readDecisionLabel(decision.label, locale) || decision.id || decision.transitionId
+    const presentation = DECISION_STYLE_PRESENTATION[decision.style ?? ''] ?? {
+      tone: 'neutral' as const,
+      glyph: 'dot' as const,
+    }
+    rows.push({
+      handleId: decision.transitionId,
+      labelKey: '',
+      labelFallback: label,
+      ...presentation,
+    })
+  }
+  return rows
+}
+
+export function isDecisionSourceHandle(
+  decisions: DecisionRowLike[] | null | undefined,
+  sourceHandle: unknown,
+): sourceHandle is string {
+  if (typeof sourceHandle !== 'string' || sourceHandle.length === 0) return false
+  return (decisions ?? []).some((decision) => decision.transitionId === sourceHandle)
+}

package/src/modules/workflows/lib/node-placement.ts

@@ -0,0 +1,104 @@
+/**
+ * New-node placement (spec section 4.1/4.2, issue #4248).
+ *
+ * "Manual `_editorPosition` always wins until explicit Tidy" only holds if a
+ * newly added step lands somewhere deliberate: the cursor when it was dropped
+ * there, otherwise after the right-most step. Either way the placement is
+ * nudged until it stops overlapping an existing card, so appending never hides
+ * a node under another one and never drifts diagonally off-canvas.
+ *
+ * Pure: plain coordinates in, plain coordinates out. Shared by the palette's
+ * click-append path and (step 3.8) the drag-from-palette drop path, which
+ * supplies the flow-space cursor position.
+ */
+
+import { NODE_HEIGHT, NODE_MIN_WIDTH } from './node-geometry'
+
+export interface NodeFootprint {
+  position: { x: number; y: number }
+  measured?: { width?: number | null; height?: number | null } | null
+}
+
+export interface NodePlacementOptions {
+  /**
+   * Flow-space position the node was dropped at (card centre). Absent for the
+   * keyboard/click-append path, which places after the right-most node.
+   */
+  dropPosition?: { x: number; y: number } | null
+  width?: number
+  height?: number
+  gap?: number
+}
+
+const DEFAULT_GAP = 48
+
+function footprintOf(node: NodeFootprint, width: number, height: number) {
+  const nodeWidth = node.measured?.width ?? width
+  const nodeHeight = node.measured?.height ?? height
+  return {
+    left: node.position.x,
+    top: node.position.y,
+    right: node.position.x + nodeWidth,
+    bottom: node.position.y + nodeHeight,
+  }
+}
+
+function overlaps(
+  candidate: { x: number; y: number },
+  nodes: NodeFootprint[],
+  width: number,
+  height: number,
+  gap: number,
+): boolean {
+  const left = candidate.x - gap / 2
+  const top = candidate.y - gap / 2
+  const right = candidate.x + width + gap / 2
+  const bottom = candidate.y + height + gap / 2
+  return nodes.some((node) => {
+    const box = footprintOf(node, width, height)
+    return left < box.right && right > box.left && top < box.bottom && bottom > box.top
+  })
+}
+
+/**
+ * Resolve the position for a node about to be added to the graph.
+ *
+ * With a drop position the card is centred on the cursor; without one it is
+ * placed one gap to the right of the right-most card, vertically aligned with
+ * it. In both cases the result is pushed down in whole card heights until it no
+ * longer collides with an existing card.
+ */
+export function resolveNewNodePlacement(
+  nodes: NodeFootprint[],
+  options: NodePlacementOptions = {},
+): { x: number; y: number } {
+  const width = options.width ?? NODE_MIN_WIDTH
+  const height = options.height ?? NODE_HEIGHT
+  const gap = options.gap ?? DEFAULT_GAP
+
+  let candidate: { x: number; y: number }
+  if (options.dropPosition) {
+    candidate = {
+      x: Math.round(options.dropPosition.x - width / 2),
+      y: Math.round(options.dropPosition.y - height / 2),
+    }
+  } else if (nodes.length === 0) {
+    candidate = { x: 0, y: 0 }
+  } else {
+    const rightMost = nodes.reduce((furthest, node) => {
+      const edge = footprintOf(node, width, height).right
+      return edge > furthest.edge ? { edge, node } : furthest
+    }, { edge: Number.NEGATIVE_INFINITY, node: nodes[0] })
+    candidate = {
+      x: Math.round(rightMost.edge + gap),
+      y: Math.round(rightMost.node.position.y),
+    }
+  }
+
+  let attempts = 0
+  while (overlaps(candidate, nodes, width, height, gap) && attempts < nodes.length + 1) {
+    candidate = { x: candidate.x, y: candidate.y + height + gap }
+    attempts += 1
+  }
+  return candidate
+}

package/src/modules/workflows/lib/node-type-icons.ts

@@ -1,6 +1,6 @@
-import { CircleDot, CircleStop, User, Zap, Workflow, Clock, Timer, Split, Merge, LucideIcon } from 'lucide-react'
+import { CircleDot, CircleStop, User, Zap, Workflow, Clock, Timer, Split, Merge, Bot, GitBranch, ListTree, Filter, LucideIcon } from 'lucide-react'
 
-export type NodeType = 'start' | 'end' | 'userTask' | 'automated' | 'subWorkflow' | 'waitForSignal' | 'waitForTimer' | 'parallelFork' | 'parallelJoin'
+export type NodeType = 'start' | 'end' | 'userTask' | 'automated' | 'subWorkflow' | 'waitForSignal' | 'waitForTimer' | 'waitForCondition' | 'parallelFork' | 'parallelJoin' | 'invokeAgent' | 'ifElse' | 'switch'
 
 export const NODE_TYPE_ICONS: Record<NodeType, LucideIcon> = {
   start: CircleDot,
@@ -10,21 +10,69 @@ export const NODE_TYPE_ICONS: Record<NodeType, LucideIcon> = {
   subWorkflow: Workflow,
   waitForSignal: Clock,
   waitForTimer: Timer,
+  waitForCondition: Filter,
   parallelFork: Split,
   parallelJoin: Merge,
+  invokeAgent: Bot,
+  ifElse: GitBranch,
+  switch: ListTree,
 }
 
+/**
+ * Node TYPE is categorical, node STATUS is semantic — two different channels
+ * that used to fight over the card's border. Type now comes from the `chart-*`
+ * palette, which the DS ships expressly for categorical encoding
+ * (`.ai/ds-rules.md` - Data Visualization), so the card's border and background
+ * are free to speak only for run status. This also retires the raw Tailwind
+ * shades (`text-blue-500`, `text-amber-500`, ...) that had no guaranteed
+ * dark-mode value.
+ */
 export const NODE_TYPE_COLORS: Record<NodeType, string> = {
-  start: 'text-emerald-500',
-  end: 'text-red-500',
-  userTask: 'text-blue-500',
-  automated: 'text-amber-500',
-  subWorkflow: 'text-purple-500',
-  waitForSignal: 'text-purple-500',
-  waitForTimer: 'text-cyan-500',
-  // New nodes use a semantic token (DS rule: no hardcoded color shades).
+  start: 'text-status-success-icon',
+  end: 'text-status-error-icon',
+  userTask: 'text-chart-amber',
+  automated: 'text-chart-blue',
+  subWorkflow: 'text-chart-violet',
+  waitForSignal: 'text-chart-teal',
+  waitForTimer: 'text-chart-teal',
+  // Predicate wait is a routing/guard construct, not a status indicator.
+  waitForCondition: 'text-primary',
   parallelFork: 'text-primary',
   parallelJoin: 'text-primary',
+  // AI / agent touchpoint — brand-violet is reserved for AI features (DS rule),
+  // so it stays on brand-violet rather than moving to chart-violet.
+  invokeAgent: 'text-brand-violet',
+  // Branching nodes share the parallel-split semantic token: they are routing
+  // constructs, not status indicators.
+  ifElse: 'text-primary',
+  switch: 'text-primary',
+}
+
+/**
+ * The 3px painted cap along the top of a node card. Because it is a
+ * `border-top` rather than a child element it sits inside the card's radius and
+ * reads as part of the object. Rendered with `border-t-4` — the DS scale's
+ * nearest step, one pixel heavier than the design mock and visually
+ * indistinguishable from it; `border-t-[3px]` would be an arbitrary value and
+ * is not DS-legal.
+ *
+ * Terminals carry no accent (the design draws them as pills, not capped
+ * cards), so they resolve to the same `--border` the rest of the card uses.
+ */
+export const NODE_TYPE_ACCENTS: Record<NodeType, string> = {
+  start: 'border-t-border',
+  end: 'border-t-border',
+  userTask: 'border-t-chart-amber',
+  automated: 'border-t-chart-blue',
+  subWorkflow: 'border-t-chart-violet',
+  waitForSignal: 'border-t-chart-teal',
+  waitForTimer: 'border-t-chart-teal',
+  waitForCondition: 'border-t-primary',
+  parallelFork: 'border-t-primary',
+  parallelJoin: 'border-t-primary',
+  invokeAgent: 'border-t-brand-violet',
+  ifElse: 'border-t-primary',
+  switch: 'border-t-primary',
 }
 
 export const NODE_TYPE_LABELS: Record<NodeType, { title: string; description: string }> = {
@@ -35,8 +83,12 @@ export const NODE_TYPE_LABELS: Record<NodeType, { title: string; description: st
   subWorkflow: { title: 'SUB-WORKFLOW', description: 'Invoke workflow' },
   waitForSignal: { title: 'WAIT FOR SIGNAL', description: 'Pause for external event' },
   waitForTimer: { title: 'WAIT FOR TIMER', description: 'Pause for a duration' },
+  waitForCondition: { title: 'WAIT FOR CONDITION', description: 'Pause until a condition holds' },
   parallelFork: { title: 'PARALLEL FORK', description: 'Split into parallel branches' },
   parallelJoin: { title: 'PARALLEL JOIN', description: 'Wait for all branches' },
+  invokeAgent: { title: 'INVOKE AGENT', description: 'Run an AI agent' },
+  ifElse: { title: 'IF / ELSE', description: 'Route on a condition' },
+  switch: { title: 'SWITCH', description: 'Route on one field value' },
 }
 
 const STEP_TYPE_TO_NODE_TYPE: Record<string, NodeType> = {
@@ -47,8 +99,17 @@ const STEP_TYPE_TO_NODE_TYPE: Record<string, NodeType> = {
   SUB_WORKFLOW: 'subWorkflow',
   WAIT_FOR_SIGNAL: 'waitForSignal',
   WAIT_FOR_TIMER: 'waitForTimer',
+  WAIT_FOR_CONDITION: 'waitForCondition',
   PARALLEL_FORK: 'parallelFork',
   PARALLEL_JOIN: 'parallelJoin',
+  // The Invoke-Agent node compiles to an AUTOMATED step carrying a single
+  // INVOKE_AGENT activity; the editor detects that activity to round-trip it
+  // back to this node type (see graph-utils mapStepToNodeType). This synthetic
+  // entry keeps the lookup table complete for any caller keying off the
+  // activity type directly.
+  INVOKE_AGENT: 'invokeAgent',
+  IF_ELSE: 'ifElse',
+  SWITCH: 'switch',
 }
 
 export function stepTypeToNodeType(stepType: string): NodeType {