@yiyi_zhang/reactflow-ui 1.3.0 → 1.3.1

package/dist/utils/executionAnalyzer.d.ts

@@ -12,7 +12,10 @@ export interface StepInfo {
     startTime?: number;
     endTime?: number;
     durationMs?: number;
+    /** Retries only (R5): loop iterations are not retries. */
     retryCount: number;
+    /** Loop iterations the step ran (0 outside loops). */
+    iterationCount: number;
     reasonForIncompletion?: string;
     diagnostics: DiagnosticResult[];
 }
@@ -28,5 +31,7 @@ export interface ExecutionSummary {
 export declare function diagnoseTask(taskRef: string, executionData: Record<string, TaskExecutionData>): DiagnosticResult[];
 export declare function analyzeExecution(executionData: Record<string, TaskExecutionData>, workflowInstance: WorkflowInstance | null): ExecutionSummary;
 export declare function formatDuration(ms?: number): string;
+/** Icon name from the CMASTER icon registry (render with <CmIcon name=…>). */
 export declare function getCategoryIcon(category: DiagnosticResult['category']): string;
+/** Every diagnostic is a problem, so the colour is a status colour; the icon and label tell the categories apart. */
 export declare function getCategoryColor(category: DiagnosticResult['category']): string;

package/dist/utils/executionImport.d.ts

@@ -0,0 +1,52 @@
+import type { TaskExecutionData } from '../types/workflow';
+import type { TaskInstance } from '../types/conductor';
+/**
+ * Pure helpers behind `importExecutionJSON` and the run view (R3, R5, R9).
+ *
+ * Conductor names tasks inside a DO_WHILE `<ref>__<iteration>` and gives each retry a new task with a higher
+ * `retryCount`. Iterations and retries are different things: an iteration is a new pass through the loop, a retry is
+ * another attempt at the same pass.
+ */
+type DefTask = {
+    type?: string;
+    taskReferenceName?: string;
+    decisionCases?: Record<string, DefTask[]>;
+    defaultCase?: DefTask[];
+    forkTasks?: DefTask[][];
+    loopOver?: DefTask[];
+};
+/** Split `step__3` into `{ baseRef: 'step', iteration: 3 }` when `step` is a task of the definition. */
+export declare function splitIterationRef(ref: string, knownRefs: Record<string, unknown>): {
+    baseRef: string;
+    iteration?: number;
+};
+/** Number of retries across all attempts: per iteration, the highest retryCount (or extra attempts when absent). */
+export declare function countRetries(attempts: TaskInstance[] | undefined): number;
+/** Number of distinct loop iterations in the attempts (0 when the task is not in a loop). */
+export declare function countIterations(attempts: TaskInstance[] | undefined): number;
+/** The last attempt (highest retry) of the given iteration, or undefined. */
+export declare function pickAttemptForIteration(attempts: TaskInstance[], iteration: number): TaskInstance | undefined;
+/**
+ * Innermost DO_WHILE that contains `ref` (at any depth inside its loopOver, including branches), or null.
+ */
+export declare function findEnclosingLoopRef(tasks: DefTask[] | undefined, ref: string): string | null;
+/**
+ * Execution view of one node with the loop iteration chosen for ITS enclosing loop only (R3).
+ * Other loops' choices do not affect it; within the iteration the last attempt (latest retry) wins.
+ */
+export declare function selectExecutionForIteration(execution: TaskExecutionData, loopRef: string | null, activeLoopIterations: Record<string, number>): TaskExecutionData;
+/**
+ * Runtime children of each dynamic fork (R9). Inside a loop the fork and join run as `fork__N` / `join__N`; each fork
+ * occurrence is paired with the join of the same suffix. The base fork key holds the latest iteration's children;
+ * `fork__N` keys hold each iteration's children.
+ */
+export declare function collectDynamicForkChildren(tasks: TaskInstance[], pairs: Array<{
+    forkRef: string;
+    joinRef: string;
+}>, knownRefs: Record<string, unknown>): Record<string, TaskInstance[]>;
+/**
+ * Group runtime tasks by definition ref (R5): a `ref__N` record is registered once, under its base ref, as the
+ * attempt for iteration N. Attempts are ordered by iteration, then retry; the node's status is its last attempt.
+ */
+export declare function buildExecutionData(tasks: TaskInstance[], knownRefs: Record<string, unknown>): Record<string, TaskExecutionData>;
+export {};

package/dist/utils/executionPoller.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Cancellable execution polling with back-off and a failure cap (R2).
+ *
+ * - `cancel()` (or aborting `signal`) stops the loop: no further timers and no more `onInstance` calls, even if a
+ *   request is in flight when it is cancelled.
+ * - Thrown errors and `null` results count as failures; after `maxFailures` consecutive failures the loop stops and
+ *   calls `onGiveUp` with a message that says what happened and how to fix it.
+ * - `shouldContinue()` is checked before every request and before delivering a result (e.g. "the user is still in run
+ *   mode"); when it returns false the loop stops quietly.
+ */
+export interface PollableInstance {
+    status: string;
+}
+export interface ExecutionPollerOptions<T extends PollableInstance> {
+    workflowId: string;
+    poll: (workflowId: string, signal: AbortSignal) => Promise<T | null>;
+    onInstance: (instance: T) => void;
+    onDone?: (instance: T) => void;
+    onGiveUp?: (message: string) => void;
+    shouldContinue?: () => boolean;
+    /** First delay in ms (default 3000). */
+    interval?: number;
+    /** Longest delay in ms (default 15000). */
+    maxInterval?: number;
+    /** Consecutive failures before giving up (default 5). */
+    maxFailures?: number;
+    signal?: AbortSignal;
+    /** Injectable timer for tests. */
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+}
+export declare const TERMINAL_WORKFLOW_STATUSES: Set<string>;
+export interface ExecutionPoller {
+    cancel: () => void;
+    readonly cancelled: boolean;
+}
+export declare function startExecutionPolling<T extends PollableInstance>(opts: ExecutionPollerOptions<T>): ExecutionPoller;

package/dist/utils/localSandboxEngine.d.ts

@@ -1,4 +1,18 @@
 import type { WorkflowDef, TaskDef as WorkflowTask, WorkflowInstance, TaskInstance as TaskExecution } from '../types/conductor';
+import { type ScriptEvaluator } from './sandbox/scriptRunner';
+/**
+ * In-browser sandbox for Conductor workflows.
+ *
+ * Tasks that need no outside system run for real with Conductor semantics: INLINE / LAMBDA (JavaScript), JSON_JQ_TRANSFORM
+ * (jq subset), SWITCH / DECISION (value-param and javascript), DO_WHILE (loop condition evaluated after each iteration),
+ * FORK_JOIN, FORK_JOIN_DYNAMIC, JOIN, SET_VARIABLE, TERMINATE, WAIT. Tasks that call outside systems (HTTP, SIMPLE, HUMAN,
+ * EVENT, KAFKA_PUBLISH, SUB_WORKFLOW, START_WORKFLOW, DYNAMIC …) return mock data, which the user can override per task.
+ * Every task execution says which one happened in `sandboxExecution`.
+ *
+ * Scripts run in an isolated Web Worker, so script evaluation is asynchronous: use `executeLocalSandboxDryRunAsync`.
+ * The synchronous `executeLocalSandboxDryRun` is kept for existing hosts; it does not run scripts and marks the affected
+ * tasks as not executed instead of inventing a result.
+ */
 export interface TaskMockOverride {
     __isMockOverride?: boolean;
     /** Override execution status (e.g. simulate FAILED or TIMED_OUT) */
@@ -17,33 +31,56 @@ export interface SandboxDryRunOptions {
     workflowInput?: Record<string, any>;
     /** Custom task output or behavior overrides keyed by taskReferenceName */
     taskMocks?: Record<string, Record<string, any> | TaskMockOverride>;
-    /** Max iterations per DO_WHILE loop in dry-run (default: 2) */
+    /**
+     * Safety limit for DO_WHILE iterations. The loop condition decides when a loop ends; when it is still true at this
+     * limit the loop stops and is marked COMPLETED_WITH_ERRORS. Default 20 (async API). The synchronous API cannot evaluate
+     * loop conditions, so there it is the number of iterations run (default 2, as before).
+     */
     maxLoopIterations?: number;
 }
+export interface SandboxAsyncOptions extends SandboxDryRunOptions {
+    /** Time budget per script in ms (default 2000). A script that runs longer is stopped and its task fails. */
+    scriptTimeoutMs?: number;
+    /** Custom script evaluator (tests, or hosts with their own isolation). Defaults to an isolated Web Worker. */
+    scriptEvaluator?: ScriptEvaluator;
+}
 interface SandboxRuntimeContext {
     workflowInput: Record<string, any>;
     variables: Record<string, any>;
     taskOutputs: Record<string, Record<string, any>>;
+    taskInputs: Record<string, Record<string, any>>;
     taskMocks: Record<string, Record<string, any> | TaskMockOverride>;
     tasks: TaskExecution[];
     currentTimeMs: number;
     maxLoopIterations: number;
+    /** false in the synchronous API: loop conditions are not evaluated there */
+    canRunScripts: boolean;
     seqCounter: number;
+    /** refs spawned by the most recent FORK_JOIN_DYNAMIC, consumed by its JOIN */
+    lastDynamicSpawn: string[] | null;
 }
 /**
- * Resolve Conductor `${...}` expressions against current sandbox context
+ * Resolve Conductor `${...}` expressions against current sandbox context.
+ * References that cannot be resolved stay as written and are added to `misses` when given.
  */
-export declare function resolveExpressionValue(val: any, ctx: SandboxRuntimeContext): any;
+export declare function resolveExpressionValue(val: any, ctx: SandboxRuntimeContext, misses?: string[]): any;
 /**
- * Generate default synthetic output for a given task (used both at runtime and as UI template preview)
+ * Default output shown for a task as a starting point for a custom mock (also what mocked tasks return).
  */
 export declare function generateDefaultTaskOutputPreview(task: WorkflowTask, resolvedInput?: Record<string, any>, iteration?: number): Record<string, any>;
 /**
- * Build default mock input from workflowDef.inputParameters and auto-discovered ${workflow.input.*} references
+ * Build mock workflow input: declared input parameters plus every `${workflow.input.<field>}` the tasks reference.
  */
 export declare function buildDefaultWorkflowMockInput(workflowDef: WorkflowDef): Record<string, any>;
 /**
- * Execute an entire WorkflowDef in-browser deterministically and return a complete WorkflowInstance
+ * Run a WorkflowDef in the browser and return a complete WorkflowInstance.
+ * Scripts (INLINE, javascript SWITCH / DECISION, DO_WHILE conditions) run in an isolated Web Worker.
+ */
+export declare function executeLocalSandboxDryRunAsync(workflowDef: WorkflowDef, options?: SandboxAsyncOptions): Promise<WorkflowInstance>;
+/**
+ * Synchronous variant kept for existing hosts. It does not run scripts: INLINE tasks are SKIPPED with
+ * `sandboxExecution: 'not_executed'`, javascript conditions take the default branch with a warning, and DO_WHILE runs
+ * `maxLoopIterations` iterations (default 2). Prefer `executeLocalSandboxDryRunAsync`.
  */
 export declare function executeLocalSandboxDryRun(workflowDef: WorkflowDef, options?: SandboxDryRunOptions): WorkflowInstance;
 export {};

package/dist/utils/runStory.d.ts

@@ -0,0 +1,20 @@
+import type { TaskInstance, WorkflowInstance } from '../types/conductor';
+import { type StatusTone } from './statusMeta';
+/**
+ * One sentence describing what a step did in this run.
+ * @param actionName display name of the step's action (falls back to task names)
+ * @param allTasks all tasks of the run (used for JOIN summaries)
+ */
+export declare function generateStorySentence(task: TaskInstance, options?: {
+    actionId?: string;
+    actionName?: string;
+    allTasks?: TaskInstance[];
+}): string;
+export interface RunHeadline {
+    title: string;
+    tone: StatusTone;
+    /** Duration in seconds when the run has both start and end, else undefined. */
+    durationSec?: string;
+}
+/** Banner title for the whole run (B11): one wording per workflow status, never "all done" for a running run. */
+export declare function runHeadline(instance: Pick<WorkflowInstance, 'status' | 'startTime' | 'endTime'>): RunHeadline;

package/dist/utils/sandbox/jq.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A small jq interpreter for the in-browser sandbox (JSON_JQ_TRANSFORM).
+ *
+ * It covers the jq that workflow authors actually write: paths, iteration, pipes, comma, object / array construction,
+ * arithmetic and comparison, `and/or/not`, `//`, `if-then-elif-else-end`, `as $x`, `reduce`, string interpolation, optional
+ * `?`, and the common builtins (see BUILTINS). Anything outside that raises a JqError that says which syntax is not
+ * supported, so the sandbox reports a failure instead of inventing a result.
+ */
+export declare class JqError extends Error {
+    constructor(message: string);
+}
+/** Run a jq program against one input. Returns all outputs; throws JqError on syntax / runtime errors. */
+export declare function runJq(query: string, input: unknown): unknown[];

package/dist/utils/sandbox/scriptRunner.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Runs Conductor JavaScript expressions (INLINE, SWITCH / DECISION javascript evaluators, DO_WHILE loop conditions)
+ * for the in-browser sandbox.
+ *
+ * The expression is workflow content, possibly written by someone else, so it never runs on the page itself: it runs in a
+ * dedicated Web Worker with network, storage and messaging APIs removed, and the worker is terminated when a script
+ * exceeds its time budget (an infinite loop cannot freeze the IDE).
+ */
+export type ScriptResult = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    error: string;
+    notExecuted?: boolean;
+};
+/** Evaluate `expression` with `$` bound to `input`; the value of the last expression statement is the result. */
+export type ScriptEvaluator = (expression: string, input: Record<string, unknown>) => Promise<ScriptResult>;
+export interface WorkerScriptEvaluator {
+    evaluate: ScriptEvaluator;
+    /** Stop the worker. Further calls start a new one. */
+    dispose: () => void;
+}
+export declare const DEFAULT_SCRIPT_TIMEOUT_MS = 2000;
+/**
+ * Create an evaluator backed by an isolated Web Worker.
+ * Returns an evaluator that reports `notExecuted` when the page cannot create workers (no Worker API, or a CSP that
+ * forbids blob: workers), so the sandbox can say why a script did not run instead of guessing a result.
+ */
+export declare function createWorkerScriptEvaluator(options?: {
+    timeoutMs?: number;
+}): WorkerScriptEvaluator;
+/** Evaluator used by the synchronous API: never runs scripts, says so. */
+export declare const notExecutedEvaluator: (expression: string) => ScriptResult;

package/dist/utils/statusMeta.d.ts

@@ -0,0 +1,35 @@
+import { type LucideIcon } from 'lucide-react';
+/**
+ * One source for "status → colour + icon + Chinese word" (CMASTER rule 5: never colour alone).
+ * Covers every Conductor task status and workflow status. Use it in badges, bars, timelines and summaries
+ * instead of a local map.
+ */
+export type StatusTone = 'pending' | 'running' | 'success' | 'warning' | 'failed' | 'skipped' | 'muted';
+export interface StatusMeta {
+    /** Raw Conductor status (upper case). */
+    status: string;
+    /** Chinese word shown to the user. */
+    label: string;
+    /** Lucide icon component (render with strokeWidth 1.75). */
+    icon: LucideIcon;
+    /** Stable icon key, useful for tests and CSS hooks. */
+    iconName: string;
+    /** Colour token (CSS custom property reference). */
+    color: string;
+    /** Semantic group. */
+    tone: StatusTone;
+    /** CSS class suffix, kebab-case of the status (e.g. `completed-with-errors`). */
+    className: string;
+    /** The run / task reached a final state. */
+    terminal: boolean;
+    /** Final state that counts as a failure (failed, timed out, terminated…). */
+    isFailure: boolean;
+    /** Still running or waiting to run. */
+    isActive: boolean;
+}
+/** Every status the helper knows, in a sensible display order. */
+export declare const KNOWN_STATUSES: string[];
+/** Look up a status. Unknown or empty values get a neutral "未知" entry (never throws). */
+export declare function getStatusMeta(status: string | null | undefined): StatusMeta;
+/** Chinese word for a status, e.g. `COMPLETED` → `成功`. */
+export declare function statusLabel(status: string | null | undefined): string;

package/dist/utils/taskEditing.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 专业模式编辑器的纯函数助手：新建任务默认值、引用名 / 分支名校验、删除影响说明、粘贴改名。
+ * 只依赖定义数据，不依赖 React / store，方便单测（v1.3.1 E1–E4、E7、E13–E15、E19、E20）。
+ */
+import type { TaskDef, WorkflowDef } from '../types/conductor';
+/** Conductor 引用名允许的字符 */
+export declare const TASK_REF_PATTERN: RegExp;
+/**
+ * 按任务类型生成 Conductor 能直接接受的新任务（字段位置以 Conductor OSS WorkflowTask / 各 TaskMapper 为准）。
+ * FORK_JOIN / FORK_JOIN_DYNAMIC 的配对 JOIN 用 {@link createJoinTaskFor} 生成。
+ */
+export declare function createDefaultTask(type: string, name: string, taskReferenceName: string): TaskDef;
+/** 为 FORK_JOIN / FORK_JOIN_DYNAMIC 生成紧随其后的 JOIN；引用名与 `takenRefs` 不冲突 */
+export declare function createJoinTaskFor(fork: TaskDef, takenRefs?: Set<string>): TaskDef;
+/**
+ * 校验引用名改名（E7）。返回 null 表示可以提交，否则返回给用户看的中文原因（说明发生了什么、怎么改）。
+ */
+export declare function validateTaskRefName(def: Pick<WorkflowDef, 'tasks'> | null | undefined, newRef: string, currentRef: string): string | null;
+/**
+ * 校验 SWITCH / DECISION 的分支名（E14）。`oldName` 为空表示新增分支。
+ */
+export declare function validateBranchName(task: TaskDef | null | undefined, newName: string, oldName?: string): string | null;
+/**
+ * 删除任务前的影响说明（E13）：FORK 与 JOIN 成对删除，容器任务连带删除内部任务，确认文案要讲清楚。
+ */
+export declare function describeTaskRemoval(def: Pick<WorkflowDef, 'tasks'> | null | undefined, taskRef: string): {
+    message: string;
+    removedRefs: string[];
+};
+/**
+ * 准备粘贴的任务副本（E15）：子树内所有引用名加后缀并保证全局唯一，
+ * 子树内部的引用（`${ref.output.x}`、loopCondition 里的 `$.ref`、joinOn 等）同步改名；
+ * 指向子树外部任务的引用保持不变。FORK_JOIN / FORK_JOIN_DYNAMIC 同时返回配对 JOIN。
+ */
+export declare function prepareTaskForPaste(task: TaskDef, existingRefs: Set<string>, suffix: string): {
+    task: TaskDef;
+    join: TaskDef | null;
+};
+export declare const TASK_DEFINITION_FIELDS: readonly ["timeoutSeconds", "retryLogic", "retryDelaySeconds", "timeoutPolicy"];
+export type TaskDefinitionField = typeof TASK_DEFINITION_FIELDS[number];
+/** 读取执行控制字段：优先 taskDefinition，回退到旧版写在顶层的值 */
+export declare function readTaskDefinitionField(task: TaskDef, field: TaskDefinitionField): any;
+/**
+ * 写入执行控制字段，返回要交给 updateTask 的补丁：
+ * 写到 `taskDefinition`，并删除旧版的顶层同名字段；保证 Conductor TaskDef 校验要求的 name 与
+ * responseTimeoutSeconds ≤ timeoutSeconds。
+ */
+export declare function patchTaskDefinitionField(task: TaskDef, field: TaskDefinitionField, value: any, ownerEmail?: string): Record<string, any>;
+/** 把 JSON 文本解析为对象；失败时返回给用户看的原因 */
+export declare function parseJsonDraft(text: string, opts?: {
+    allowEmpty?: boolean;
+    requireObject?: boolean;
+}): {
+    ok: true;
+    value: any;
+} | {
+    ok: false;
+    error: string;
+};

package/dist/utils/taskTypeMeta.d.ts

@@ -7,6 +7,7 @@
  */
 export interface TaskTypeMeta {
     label: string;
+    /** CMASTER icon name (see components/icons/iconRegistry.ts), rendered with <CmIcon>. */
     icon: string;
     who: string;
     color: string;

package/dist/utils/validationRules.d.ts

@@ -36,12 +36,19 @@ export declare const TASK_RULES: {
             level: string;
             message: string;
         })[];
-        INLINE: {
+        INLINE: ({
             field: string;
             type: string;
             validate: (_val: any, task: any) => boolean;
             message: string;
-        }[];
+            level?: undefined;
+        } | {
+            field: string;
+            type: string;
+            level: string;
+            message: string;
+            validate?: undefined;
+        })[];
         LAMBDA: {
             field: string;
             type: string;
@@ -93,12 +100,19 @@ export declare const TASK_RULES: {
             validate: (val: any) => boolean;
             message: string;
         }[];
-        SWITCH: {
+        SWITCH: ({
             field: string;
             type: string;
-            validate: (val: any) => boolean;
+            validate: (val: any, task: any) => boolean;
             message: string;
-        }[];
+            level?: undefined;
+        } | {
+            field: string;
+            type: string;
+            level: string;
+            validate: (val: any, task: any) => boolean;
+            message: string;
+        })[];
         FORK_JOIN_DYNAMIC: {
             field: string;
             type: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yiyi_zhang/reactflow-ui",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Conductor Workflow IDE — Next-Gen AI-Native visual workflow designer with W-LSP data lineage, deterministic in-browser sandbox dry-run, time-travel waterfall debugger, and live split-view sync built with React 19, ReactFlow and Zustand.",
   "keywords": [
     "conductor",
@@ -49,7 +49,11 @@
     "preview": "vite preview",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage"
+    "test:coverage": "vitest run --coverage",
+    "tokens:build": "node scripts/tokens/build.mjs",
+    "tokens:check": "node scripts/tokens/build.mjs --check",
+    "test:visual": "playwright test",
+    "test:visual:update": "playwright test --update-snapshots"
   },
   "dependencies": {
     "dagre": "^0.8.5",