jev-devtools 0.3.0 → 0.4.1

package/README.md

@@ -1,10 +1,10 @@
 # Jev DevTools
 
-[![npm version 0.3.0](https://img.shields.io/badge/npm-v0.3.0-E551BA?labelColor=0D0A0F&logo=npm)](https://www.npmjs.com/package/jev-devtools/v/0.3.0)
+[![npm version 0.4.1](https://img.shields.io/badge/npm-v0.4.1-E551BA?labelColor=0D0A0F&logo=npm)](https://www.npmjs.com/package/jev-devtools/v/0.4.1)
 
 A React drawer and Node adapter for inspecting TypeSafe Jev requests with animated diagrams. Includes request history, context, questions, typed answers, transport attempts, and raw snapshots.
 
-**Experimental (pre-1.0).** React 18/19 and Node 22.12+ are supported. APIs may change before 1.0. Verification uses sample responses through the real TypeSafe SDK, not live inference.
+**Version 0.4.1 is prepared for release; publication is pending.** Check the release history for verified publication status. **Experimental (pre-1.0).** React 18/19 and Node 22.12+ are supported. APIs may change before 1.0. Verification uses sample responses through the real TypeSafe SDK, not live inference.
 
 [Changelog and release history](https://github.com/diegoag64/jev-devtools/blob/main/CHANGELOG.md) — published versions and unreleased work.
 
@@ -31,27 +31,26 @@ The [setup skill](https://github.com/diegoag64/jev-devtools/blob/main/packages/j
 
 ## Install
 
-Install from npm:
+The npm command installs the latest published release (0.4.0 at preparation time):
 
 ```sh
-npm install jev-devtools
+npm install jev-devtools @typesafe-ai/sdk
 ```
 
-To try unpublished local changes instead:
+To try local changes before a future release:
 
 ```sh
 # From the jev-devtools repository root:
 npm ci
 npm run pack:devtools
 # From the consuming app:
-npm install /absolute/path/to/jev-devtools-0.3.0.tgz
+npm install /absolute/path/to/jev-devtools-0.4.1.tgz
 ```
 
-Mount once:
+Mount once. The drawer loads its own styles; no CSS import is needed:
 
 ```tsx
 import { JevDevtools } from 'jev-devtools';
-import 'jev-devtools/styles.css';
 
 <JevDevtools enabled={import.meta.env.DEV} defaultOpen={false} />
 ```
@@ -73,7 +72,7 @@ app.use(inspector.middleware); // Mount at root, before fallback handlers.
 
 Only calls through that client are captured. The React component subscribes via same-origin SSE, receiving an initial snapshot followed by changed traces. Older client/server combinations remain compatible through full snapshots. Both sides default to disabled. API keys remain server-side. Browser code is SSR-safe. The drawer uses a Shadow DOM boundary and its own stylesheet so host page selectors cannot alter its internal layout. Existing stylesheet imports remain supported; no Tailwind or shadcn installation is required. Drag the Flow canvas to pan, scroll/pinch to zoom, or use Fit.
 
-History is bounded to 50 calls in memory by default. API routes and inspector endpoints must share an adapter instance; distributed processes and edge runtimes are not supported. Non-loopback use requires explicit authorization. Captures include bounded/redacted context and answers, not hidden model reasoning.
+History is bounded to 50 calls in memory by default. API routes and inspector endpoints must share an adapter instance; distributed processes and edge runtimes are not supported. Without `authorize`, the middleware accepts only loopback connections; Web Request handlers can't see the connection's address, so run those servers on `127.0.0.1`. Captures include bounded/redacted context and answers, not hidden model reasoning.
 
 For Next.js App Router, use `getJevDevtools(appKey, optionsFactory)` from `/server` to share an adapter across server reloads, expose `handleNodeRoute` through an optional catch-all Route Handler, and mount the root component in a client boundary. See the [Next.js guide](https://github.com/diegoag64/jev-devtools/blob/main/docs/nextjs.md) and runnable example. No Next dependency is required by this package.
 
@@ -81,9 +80,9 @@ For Next.js App Router, use `getJevDevtools(appKey, optionsFactory)` from `/serv
 
 MIT for project code. See bundled LICENSE and THIRD_PARTY_NOTICES.txt for original design attribution and TypeSafe branding.
 
-## Connected Jev flows
+## Connected Jev flows with `jev-devtools/flow`
 
-New in **0.3.0**: define calls, conditions, parallel checks, and named outcomes with `jev-devtools/flow`. The drawer connects each request's complete diagram on one canvas. Condition cards show the incoming value and its requirement; optional titles and descriptions explain each step. Existing single-request integrations need no changes.
+Define calls, conditions, parallel checks, and named outcomes with `jev-devtools/flow`. **0.4.0 adds** server function steps (`task`), runtime request factories, bounded collections (`map`), returning conditionals (`if`), stateful iteration (`loop`), and strict numeric `.gt()` comparisons. The drawer connects request diagrams, function results, selected paths, collection items, and loop iterations on one canvas. Existing single-request integrations remain supported.
 
 On the server, reuse the instrumented `jev` client and `inspector` from the setup above:
 
@@ -112,7 +111,7 @@ const result = await review.run({ message: 'Please review my ticket.' }, {
 // Handle result.outcome in your app. The flow does not execute business actions.
 ```
 
-Define once in a Node module and run per request. Use `flow.parallel` for concurrent named lanes; downstream calls wait for every lane to succeed. Branches are terminal in their block. Runs are in-process, with bounded inspector history, SDK retries, and cancellation support; they are not durable workflows.
+Define once in a Node module and run per request. Use `flow.parallel` for concurrent named lanes; downstream calls wait for every lane to succeed. `flow.branch` is terminal in its block; use `flow.if` when selected values feed shared downstream work. Tasks execute application code on Node with JSON-compatible inputs/results; maps and loops have explicit bounds. Runs have SDK retries and cooperative cancellation, with bounded in-memory inspector history. They do not provide durable or distributed execution. Keep the 0.4.0 server and drawer together to inspect its new step kinds.
 
 [Full flow guide](https://github.com/diegoag64/jev-devtools/blob/main/docs/flows.md) · [AI flow recipe](https://github.com/diegoag64/jev-devtools/blob/main/packages/jev-devtools/skills/setup-jev-devtools/references/flows.md)
 

package/lib/flow/index.d.ts

@@ -14,17 +14,19 @@ type Ast = {
     op: "literal";
     value: unknown;
 } | {
-    op: "eq" | "lt" | "gte" | "all" | "any" | "not";
+    op: "eq" | "lt" | "gt" | "gte" | "all" | "any" | "not";
     args: Ast[];
 };
+declare const valueTypeBrand: unique symbol;
 /** Inspectable expression, not an application callback. Use get() for input fields. */
 export declare class FlowExpression<T> {
     readonly ast: Ast;
-    private readonly valueType;
+    protected readonly [valueTypeBrand]: T;
     constructor(ast: Ast, owner?: object);
     get<K extends keyof T & (string | number)>(key: K): FlowExpression<T[K]>;
     eq(value: T | FlowExpression<T>): FlowExpression<boolean>;
     lt(this: FlowExpression<number>, value: number | FlowExpression<number>): FlowExpression<boolean>;
+    gt(this: FlowExpression<number>, value: number | FlowExpression<number>): FlowExpression<boolean>;
     gte(this: FlowExpression<number>, value: number | FlowExpression<number>): FlowExpression<boolean>;
 }
 export declare const all: (...conditions: FlowExpression<boolean>[]) => FlowExpression<boolean>;
@@ -35,6 +37,10 @@ export type FlowOutcome = {
     value?: unknown;
 };
 type AnswerRefs<Q extends Questions> = {
+    /** All answers, including question names created by a runtime request factory. */
+    readonly answers: FlowExpression<{
+        [K in keyof Q]: ResultFor<Q[K]>;
+    }>;
     answer<K extends keyof Q & string>(name: K): {
         [F in keyof ResultFor<Q[K]>]: FlowExpression<ResultFor<Q[K]>[F]>;
     };
@@ -42,6 +48,28 @@ type AnswerRefs<Q extends Questions> = {
 type Request<Q extends Questions> = Omit<SystemOneRequest<Q>, "state"> & {
     state: unknown;
 };
+/** Resolve nested references before invoking a server callback. */
+export type Resolved<T> = T extends FlowExpression<infer V> ? V : T extends readonly unknown[] ? {
+    [K in keyof T]: Resolved<T[K]>;
+} : T extends object ? {
+    [K in keyof T]: Resolved<T[K]>;
+} : T;
+export type TaskContext = {
+    signal: AbortSignal;
+    runId: string;
+    stepId: string;
+    executionId: string;
+};
+export type FlowTask<I, O> = {
+    input: I;
+    run: (input: Resolved<I>, context: TaskContext) => O | Promise<O>;
+    timeoutMs?: number;
+};
+export type FlowRequestFactory<I, Q extends Questions> = {
+    input: I;
+    /** Synchronous construction only; the runner executes the SDK request. */
+    request: (input: Resolved<I>) => SystemOneRequest<Q>;
+};
 /** Observer contract used by createJevDevtools; execution never depends on successful recording. */
 export type FlowObserver = {
     startFlow(definition: FlowDefinition, run: FlowRun): {
@@ -58,9 +86,43 @@ export type FlowRunOptions = {
     devtools?: FlowObserver;
     signal?: AbortSignal;
 };
+export declare class FlowLoopLimitError extends Error {
+    readonly name = "FlowLoopLimitError";
+    constructor();
+}
 export interface FlowBuilder<T> {
     readonly input: FlowExpression<T>;
     jev<const Q extends Questions>(id: string, request: Request<Q>, display?: FlowDisplay): AnswerRefs<Q>;
+    jev<I, const Q extends Questions>(id: string, request: FlowRequestFactory<I, Q>, display?: FlowDisplay): AnswerRefs<Q>;
+    task<I, O>(id: string, task: FlowTask<I, O>, display?: FlowDisplay): FlowExpression<Awaited<O>>;
+    /** Execute a reusable item program with bounded concurrency; return results in input order. */
+    map<I, C, O>(id: string, options: {
+        items: FlowExpression<readonly I[]> | readonly I[];
+        input: C;
+        concurrency?: number;
+        maxItems: number;
+    }, build: (item: FlowBuilder<{
+        item: I;
+        index: number;
+        context: Resolved<C>;
+    }>) => FlowExpression<O>, display?: FlowDisplay): FlowExpression<O[]>;
+    /** Pre-test loop with JSON state, explicit context and a required iteration limit. */
+    loop<S, C>(id: string, options: {
+        initial: S | FlowExpression<S>;
+        input: C;
+        while: (state: FlowExpression<NoInfer<S>>) => FlowExpression<boolean>;
+        maxIterations: number;
+    }, build: (iteration: FlowBuilder<{
+        state: S;
+        index: number;
+        context: Resolved<C>;
+    }>) => FlowExpression<NoInfer<S>>, display?: FlowDisplay): FlowExpression<S>;
+    /** Execute one value-returning path, then continue with its typed result. */
+    if<A, B>(id: string, paths: {
+        when: FlowExpression<boolean>;
+        then: (path: FlowBuilder<T>) => FlowExpression<A>;
+        else: (path: FlowBuilder<T>) => FlowExpression<B>;
+    }, display?: FlowDisplay): FlowExpression<A | B>;
     /** Terminal decision: each callback must return output() or another branch(). */
     branch(id: string, paths: {
         when: FlowExpression<boolean>;