jev-devtools 0.5.2 → 0.5.3

package/README.md

@@ -1,10 +1,10 @@
 # Jev DevTools
 
-[![npm version 0.5.2](https://img.shields.io/badge/npm-v0.5.2-E551BA?labelColor=0D0A0F&logo=npm)](https://www.npmjs.com/package/jev-devtools/v/0.5.2)
+[![npm version 0.5.3](https://img.shields.io/badge/npm-v0.5.3-E551BA?labelColor=0D0A0F&logo=npm)](https://www.npmjs.com/package/jev-devtools/v/0.5.3)
 
 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.
 
-**Source version: 0.5.2 — pending publication.** npm currently provides 0.5.1. Check the [release history](https://github.com/diegoag64/jev-devtools/blob/main/CHANGELOG.md) for compatibility notes. To try this release candidate, install the local archive below. **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.
+**Package version: 0.5.3.** [See release notes for verified publication status.](https://github.com/diegoag64/jev-devtools/releases/tag/v0.5.3) Check the [release history](https://github.com/diegoag64/jev-devtools/blob/main/CHANGELOG.md) for compatibility notes. To try newer source changes, install the local archive below. **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.
 
 [Website](https://jevtools.dev/) · [Documentation](https://docs.jevtools.dev/) · [Quick start](https://docs.jevtools.dev/getting-started/) · [API reference](https://docs.jevtools.dev/api/reference/) · [Release history](https://docs.jevtools.dev/changelog/)
 
@@ -48,7 +48,7 @@ To try local changes before a future release:
 npm ci
 npm run pack:devtools
 # From the consuming app:
-npm install /absolute/path/to/jev-devtools-0.5.2.tgz
+npm install /absolute/path/to/jev-devtools-0.5.3.tgz
 ```
 
 Mount once. The drawer loads its own styles; no CSS import is needed:

package/lib/server/index.js

@@ -73,6 +73,60 @@ export function createJevDevtools(options) {
             scheduled = undefined;
         }
     }
+    const pendingFlows = new Set();
+    let scheduledFlows;
+    const encodeFlowUpdate = (session, cursor, knownDefinitions) => {
+        const update = flows.changes(session, cursor, knownDefinitions);
+        return {
+            bytes: encoder.encode(`event: flows\ndata: ${JSON.stringify(update.data)}\n\n`),
+            revision: update.revision,
+            retainedDefinitionIds: update.retainedDefinitionIds,
+        };
+    };
+    function scheduleFlow(flush) {
+        pendingFlows.add(flush);
+        if (scheduledFlows)
+            return;
+        scheduledFlows = setImmediate(() => {
+            scheduledFlows = undefined;
+            const batch = [...pendingFlows];
+            pendingFlows.clear();
+            // A lone reader has nothing to share; keep its direct encoding path and
+            // avoid allocating a cache or copying an otherwise unshared buffer.
+            if (batch.length === 1) {
+                batch[0](encodeFlowUpdate);
+                return;
+            }
+            // Scope sharing to this synchronous turn: no snapshots survive a later
+            // update/clear. Different cursors or definition knowledge need their own
+            // projection, even when the authorized session matches.
+            const encoded = new Map();
+            const updateFor = (session, cursor, knownDefinitions) => {
+                const key = JSON.stringify([
+                    session,
+                    cursor,
+                    [...knownDefinitions].sort(),
+                ]);
+                let update = encoded.get(key);
+                if (!update) {
+                    update = encodeFlowUpdate(session, cursor, knownDefinitions);
+                    encoded.set(key, update);
+                }
+                // Response consumers can mutate/transfer their chunk. Never expose the
+                // cached backing buffer to a reader.
+                return { ...update, bytes: update.bytes.slice() };
+            };
+            for (const deliver of batch)
+                deliver(updateFor);
+        });
+    }
+    function unscheduleFlow(flush) {
+        pendingFlows.delete(flush);
+        if (!pendingFlows.size && scheduledFlows) {
+            clearImmediate(scheduledFlows);
+            scheduledFlows = undefined;
+        }
+    }
     let disposed = false;
     const enabled = () => options.enabled === true && !disposed;
     const sessionFor = async (request) => {
@@ -112,15 +166,14 @@ export function createJevDevtools(options) {
             let stop = () => { };
             const body = new ReadableStream({
                 start(controller) {
-                    let closed = false, dirty = true, cursor, timer;
+                    let closed = false, dirty = true, cursor;
                     let knownDefinitions = new Set();
-                    const flush = () => {
-                        timer = undefined;
+                    const flush = (updateFor) => {
                         if (closed || !dirty || (controller.desiredSize ?? 0) <= 0)
                             return;
                         try {
-                            const update = flows.changes(session, cursor, knownDefinitions);
-                            controller.enqueue(encoder.encode(`event: flows\ndata: ${JSON.stringify(update.data)}\n\n`));
+                            const update = updateFor(session, cursor, knownDefinitions);
+                            controller.enqueue(update.bytes);
                             // Match the browser's pruning after this delivered order. A clear
                             // coalesced away under backpressure must not discard reader state.
                             knownDefinitions = update.retainedDefinitionIds;
@@ -134,8 +187,8 @@ export function createJevDevtools(options) {
                         }
                     };
                     const wake = () => {
-                        if (!closed && dirty && !timer)
-                            timer = setImmediate(flush);
+                        if (!closed && dirty && (controller.desiredSize ?? 0) > 0)
+                            scheduleFlow(flush);
                     };
                     const unsubscribe = flows.subscribe((sessions) => {
                         if (sessions.has(session)) {
@@ -151,9 +204,9 @@ export function createJevDevtools(options) {
                         if (closed)
                             return;
                         closed = true;
-                        knownDefinitions.clear();
+                        knownDefinitions = new Set();
                         unsubscribe();
-                        clearImmediate(timer);
+                        unscheduleFlow(flush);
                         clearInterval(heartbeat);
                         request.signal.removeEventListener("abort", stop);
                         streams.delete(stop);
@@ -168,7 +221,7 @@ export function createJevDevtools(options) {
                     if (request.signal.aborted)
                         stop();
                     else
-                        flush();
+                        flush(encodeFlowUpdate);
                 },
                 pull() {
                     flowPull();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jev-devtools",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "type": "module",
   "engines": {
     "node": ">=22.12"

package/skills/setup-jev-devtools/SKILL.md

@@ -19,7 +19,7 @@ Inspect the app's package manager/lockfile, React and Node versions, root compon
 
 Install `jev-devtools` using the app's existing package manager (npm: `npm install jev-devtools @typesafe-ai/sdk`; pnpm: `pnpm add jev-devtools @typesafe-ai/sdk`; Yarn: `yarn add jev-devtools @typesafe-ai/sdk`; Bun: `bun add jev-devtools @typesafe-ai/sdk`). `@typesafe-ai/sdk` is a peer dependency: keep the app's existing SDK version when it satisfies the peer range. Install in the workspace(s) that actually import it. It is a regular dependency when application modules import it, even though capture/display are development-only. Do not replace the app's framework or upgrade unrelated dependencies to force compatibility.
 
-### Consumer compatibility (0.5.2)
+### Consumer compatibility (0.5.3)
 
 | Requirement       | Contract                                                                                                                              |
 | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
@@ -35,7 +35,7 @@ Import application APIs from `jev-devtools` (React and browser-safe capture help
 
 ## Optional connected flow API
 
-When asked to build or inspect connected calls, read [references/flows.md](references/flows.md) after the framework recipe. For 0.5.2 it covers requests, server function tasks, runtime request factories, parallel checks, terminal branches, returning conditionals, bounded collections, stateful loops, captured-answer replay, and fixture comparison. It includes sample verification, scope/execution rules, and privacy limits. For an older installation, use its bundled recipe and declarations rather than assuming these operations exist. Preserve existing application policies; do not convert unrelated calls just to install the drawer. Flow execution is server-only and continues even with the inspector disabled.
+When asked to build or inspect connected calls, read [references/flows.md](references/flows.md) after the framework recipe. For 0.5.3 it covers requests, server function tasks, runtime request factories, parallel checks, terminal branches, returning conditionals, bounded collections, stateful loops, captured-answer replay, and fixture comparison. It includes sample verification, scope/execution rules, and privacy limits. For an older installation, use its bundled recipe and declarations rather than assuming these operations exist. Preserve existing application policies; do not convert unrelated calls just to install the drawer. Flow execution is server-only and continues even with the inspector disabled.
 
 ## Integration invariants
 

package/skills/setup-jev-devtools/references/flows.md

@@ -1,6 +1,6 @@
 # Build and inspect a Jev flow
 
-For `jev-devtools` **0.5.2**. Check the repository changelog for publication status when installing from source. Read the installed package version and `lib/flow/index.d.ts` first; online `main` may describe newer APIs. Use this recipe when the user asks to connect multiple Jev requests, inspect branches, run server function steps, or visualize parallel checks, collections, and loops. Adding the inspector alone does not require converting existing calls to flows.
+For `jev-devtools` **0.5.3**. Check the [release notes](https://github.com/diegoag64/jev-devtools/releases/tag/v0.5.3) for verified publication status when installing from source. Read the installed package version and `lib/flow/index.d.ts` first; online `main` may describe newer APIs. Use this recipe when the user asks to connect multiple Jev requests, inspect branches, run server function steps, or visualize parallel checks, collections, and loops. Adding the inspector alone does not require converting existing calls to flows.
 
 ## Plan the integration
 
@@ -9,7 +9,7 @@ For `jev-devtools` **0.5.2**. Check the repository changelog for publication sta
 3. Import `defineJevFlow` (and `all`, `any`, `not` when needed) from **server-only** `jev-devtools/flow`. Define the graph once at module scope and call `run()` from the existing Node handler/action. In Next.js, mark the module `server-only` and keep the executing route/segment on the Node runtime. No new client provider or root component is needed.
 4. A named output returns data and does not execute an action. Existing business actions can remain in the application after the returned outcome; use `task()` when the user wants application-owned server work included in the flow. Preserve authorization, idempotency, input validation, and error handling. Cancellation cannot undo side effects.
 
-If importing question helpers as below, install `@typesafe-ai/sdk` as a direct dependency in the server workspace using its package manager. Version 0.5.2 requires SDK `>=0.7.0 <0.8.0` and is verified with 0.7.0; preserve a compatible existing version rather than silently changing SDK semantics. The flow also accepts ordinary SDK question objects.
+If importing question helpers as below, install `@typesafe-ai/sdk` as a direct dependency in the server workspace using its package manager. Version 0.5.3 requires SDK `>=0.7.0 <0.8.0` and is verified with 0.7.0; preserve a compatible existing version rather than silently changing SDK semantics. The flow also accepts ordinary SDK question objects.
 
 ## Complete example: parallel checks, one decision, two outcomes