jev-devtools 0.1.3 → 0.2.0

package/lib/src/inspector.css

@@ -1040,3 +1040,227 @@
   width: auto;
   max-width: none;
 }
+
+.jev-devtools .detail-body-questions {
+  display: flex;
+  flex-direction: column;
+  overflow: auto;
+}
+.jev-devtools .questions-list {
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  min-height: 180px;
+}
+.jev-devtools .questions-navigation {
+  display: flex;
+  align-items: end;
+  gap: 8px;
+  flex-wrap: wrap;
+  flex-shrink: 0;
+}
+.jev-devtools .questions-navigation label {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  white-space: nowrap;
+  flex: 1;
+  min-width: 240px;
+  max-width: 480px;
+  font-size: 11px;
+  color: #bc9db5;
+}
+.jev-devtools .questions-navigation select {
+  display: block;
+  min-width: 0;
+}
+.jev-devtools .questions-navigation > span {
+  align-self: center;
+  color: #a89bac;
+}
+.jev-devtools .questions-help {
+  margin: 8px 0;
+  flex-shrink: 0;
+}
+.jev-devtools .questions-viewport {
+  flex: 1;
+  min-height: 0;
+  overflow: auto;
+  overflow-anchor: none;
+  scrollbar-gutter: stable;
+  padding: 3px;
+}
+.jev-devtools .questions-spacer {
+  position: relative;
+  width: 100%;
+}
+.jev-devtools .questions-row {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  padding-bottom: 14px;
+}
+.jev-devtools .questions-row .standalone {
+  margin-bottom: 0;
+}
+.jev-devtools .questions-viewport:focus-visible,
+.jev-devtools .questions-row article:focus-visible {
+  outline: 2px solid #e551ba;
+  outline-offset: -2px;
+}
+
+/* Reserve measured card geometry while rapid scrolling uses a light preview. */
+.jev-devtools .questions-row[data-preview="true"] article {
+  height: 100%;
+}
+.jev-devtools .question-scroll-preview p {
+  margin-top: 16px;
+}
+
+/* The full distribution stays at reading size, outside the zoomable canvas. */
+.jev-devtools .lab-flow-viewport[hidden] {
+  display: none;
+}
+.jev-devtools .lab-choice-browser {
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  min-height: 0;
+  padding: 8px 16px;
+  gap: 10px;
+}
+.jev-devtools .lab-choice-controls {
+  display: flex;
+  gap: 12px;
+  align-items: end;
+  flex-wrap: wrap;
+  font-size: 12px;
+}
+.jev-devtools .lab-choice-controls label {
+  display: grid;
+  gap: 5px;
+}
+.jev-devtools .lab-choice-table-scroll {
+  overflow: auto;
+  min-height: 0;
+  flex: 1;
+}
+.jev-devtools .lab-choice-browser table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 13px;
+}
+.jev-devtools .lab-choice-browser caption {
+  text-align: left;
+  padding: 8px 0;
+  color: #aaa0af;
+}
+.jev-devtools .lab-choice-browser th,
+.jev-devtools .lab-choice-browser td {
+  padding: 9px 12px;
+  border-bottom: 1px solid #302634;
+  text-align: left;
+}
+.jev-devtools .lab-choice-browser th {
+  overflow-wrap: anywhere;
+  max-width: 320px;
+}
+.jev-devtools .lab-choice-browser td {
+  font-variant-numeric: tabular-nums;
+}
+.jev-devtools .lab-choice-browser code {
+  white-space: normal;
+  overflow-wrap: anywhere;
+}
+.jev-devtools .lab-choice-returned {
+  display: block;
+  font-size: 10px;
+  color: #e551ba;
+}
+.jev-devtools .lab-choice-pagination {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  justify-content: space-between;
+  font-size: 12px;
+}
+.jev-devtools .lab-choice-remainder button {
+  margin-top: 7px;
+}
+
+.jev-devtools .lab-flow-compact .lab-output {
+  padding: 12px;
+  height: 104px;
+}
+.jev-devtools .lab-flow-compact .lab-output .lab-eyebrow {
+  margin-bottom: 6px;
+}
+.jev-devtools .lab-flow-compact .lab-output h3 {
+  font-size: 16px;
+  margin-bottom: 8px;
+}
+.jev-devtools .lab-flow-compact .lab-output p {
+  font-size: 12px;
+  margin: 4px 0;
+}
+.jev-devtools .lab-flow-compact .lab-result {
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+  overflow-wrap: anywhere;
+}
+.jev-devtools .lab-choice-remainder {
+  padding: 12px;
+}
+.jev-devtools .lab-choice-remainder .lab-small {
+  margin: 8px 0 0;
+  font-size: 11px;
+}
+
+.jev-devtools .detail-body.detail-body-flow {
+  flex-direction: column;
+}
+.jev-devtools .detail-body-flow > .warning,
+.jev-devtools .detail-body-flow > .error-banner {
+  flex-shrink: 0;
+  margin: 6px 16px;
+}
+.jev-devtools .lab-choice-browser {
+  overflow: auto;
+}
+.jev-devtools .lab-choice-table-scroll {
+  flex: 1 0 110px;
+}
+
+/* Only freshly revealed branches enter; pan/zoom remains on the canvas. */
+.jev-devtools .lab-card-enter {
+  animation: jev-card-enter 280ms cubic-bezier(0.2, 0.8, 0.2, 1) backwards;
+}
+.jev-devtools .lab-branch-enter {
+  stroke-dasharray: 1;
+  animation: jev-branch-enter 280ms ease-out backwards;
+}
+@keyframes jev-card-enter {
+  from {
+    opacity: 0;
+    transform: translateX(-16px) scale(0.96);
+  }
+}
+@keyframes jev-branch-enter {
+  from {
+    opacity: 0;
+    stroke-dashoffset: 1;
+  }
+  to {
+    opacity: 1;
+    stroke-dashoffset: 0;
+  }
+}
+@media (prefers-reduced-motion: reduce) {
+  .jev-devtools .lab-card-enter,
+  .jev-devtools .lab-branch-enter {
+    animation: none;
+  }
+}

package/lib/src/protocol.d.ts

@@ -62,3 +62,16 @@ export type Snapshot = {
     version: 1;
     traces: Trace[];
 };
+export type StreamSnapshot = {
+    version: 2;
+    revision: number;
+    traces: Trace[];
+};
+export type TraceDelta = {
+    version: 2;
+    base: number;
+    revision: number;
+    upserts: Trace[];
+    /** Authoritative newest-first retained IDs. Omitted IDs are removed. */
+    order: string[];
+};

package/lib/src/trace-store.d.ts

@@ -0,0 +1,6 @@
+import type { Trace } from "./protocol.js";
+export declare class TraceStore {
+    private current;
+    private revision;
+    apply(event: "snapshot" | "delta", input: unknown): Trace[];
+}

package/lib/src/trace-store.js

@@ -0,0 +1,66 @@
+const revision = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+function traces(value) {
+    if (!Array.isArray(value) || value.length > 200)
+        throw new Error("Invalid traces");
+    const ids = new Set();
+    for (const trace of value) {
+        if (!trace ||
+            trace.version !== 1 ||
+            typeof trace.id !== "string" ||
+            !trace.id ||
+            ids.has(trace.id))
+            throw new Error("Invalid trace ID");
+        ids.add(trace.id);
+    }
+    return value;
+}
+// Owned by one EventSource connection. Unchanged trace objects keep their
+// identity; validate the complete update before replacing any current state.
+export class TraceStore {
+    current = [];
+    revision;
+    apply(event, input) {
+        if (!input || typeof input !== "object")
+            throw new Error("Invalid update");
+        const data = input;
+        if (event === "snapshot") {
+            if (data.version !== 1 && data.version !== 2)
+                throw new Error("Unsupported stream");
+            if (data.version === 2 && !revision(data.revision))
+                throw new Error("Invalid revision");
+            const next = traces(data.traces);
+            this.current = next;
+            this.revision =
+                data.version === 2 ? data.revision : undefined;
+            return next;
+        }
+        if (data.version !== 2 ||
+            this.revision === undefined ||
+            data.base !== this.revision ||
+            !revision(data.revision) ||
+            data.revision <= this.revision)
+            throw new Error("Inspector stream needs a fresh snapshot");
+        if (!Array.isArray(data.order) ||
+            data.order.length > 200 ||
+            data.order.some((id) => typeof id !== "string") ||
+            new Set(data.order).size !== data.order.length)
+            throw new Error("Invalid retained order");
+        const order = data.order;
+        const retained = new Set(order);
+        const upserts = traces(data.upserts);
+        if (upserts.some((t) => !retained.has(t.id)))
+            throw new Error("Unexpected upsert");
+        const byId = new Map(this.current.map((t) => [t.id, t]));
+        for (const trace of upserts)
+            byId.set(trace.id, trace);
+        const next = order.map((id) => {
+            const trace = byId.get(id);
+            if (!trace)
+                throw new Error("Missing retained trace");
+            return trace;
+        });
+        this.current = next;
+        this.revision = data.revision;
+        return next;
+    }
+}

package/lib/src/trace-stream.d.ts

@@ -0,0 +1,2 @@
+import type { Trace } from "./protocol.js";
+export declare function connectTraceStream(url: string, onTraces: (traces: Trace[]) => void, onConnection: (status: string) => void): () => void;

package/lib/src/trace-stream.js

@@ -0,0 +1,65 @@
+import { TraceStore } from "./trace-store.js";
+export function connectTraceStream(url, onTraces, onConnection) {
+    let alive = true, events, retry, frame, fallback, pending;
+    const cancelPublish = () => {
+        if (frame !== undefined)
+            cancelAnimationFrame(frame);
+        clearTimeout(fallback);
+        frame = undefined;
+        fallback = undefined;
+        pending = undefined;
+    };
+    const publish = () => {
+        const next = pending;
+        cancelPublish();
+        if (alive && next)
+            onTraces(next);
+    };
+    const schedule = (next) => {
+        pending = next;
+        if (frame !== undefined)
+            return;
+        // Merge every protocol event, but render only the newest state per frame.
+        // Background tabs may suspend rAF; keep delivery bounded there as well.
+        frame = requestAnimationFrame(publish);
+        fallback = setTimeout(publish, 100);
+    };
+    const connect = () => {
+        if (!alive)
+            return;
+        // Native reconnects receive a full snapshot too. After an invalid delta,
+        // discard the cursor and reconnect rather than applying partial history.
+        const store = new TraceStore();
+        const source = new EventSource(url + "/events?protocol=2");
+        events = source;
+        const receive = (kind, event) => {
+            if (!alive || events !== source)
+                return;
+            try {
+                const next = store.apply(kind, JSON.parse(event.data));
+                schedule(next);
+                onConnection("connected");
+            }
+            catch {
+                cancelPublish();
+                source.close();
+                events = undefined;
+                onConnection("resynchronizing");
+                retry = setTimeout(connect, 1000);
+            }
+        };
+        source.addEventListener("snapshot", (event) => receive("snapshot", event));
+        source.addEventListener("delta", (event) => receive("delta", event));
+        source.onerror = () => {
+            if (alive && events === source)
+                onConnection("reconnecting");
+        };
+    };
+    connect();
+    return () => {
+        alive = false;
+        clearTimeout(retry);
+        cancelPublish();
+        events?.close();
+    };
+}

package/lib/src/useDiagramViewport.d.ts

@@ -6,4 +6,5 @@ export declare function useDiagramViewport(width: number, height: number, scene:
     zoom: number;
     zoomBy: (factor: number, point?: Point) => void;
     fit: () => void;
+    preserveCamera: () => void;
 };

package/lib/src/useDiagramViewport.js

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useLayoutEffect, useRef, useState, } from "react";
 import { fitCamera, zoomCamera, } from "./diagram-camera.js";
 /** Lab-style camera. Pointer frames update the transform without rerendering cards. */
 export function useDiagramViewport(width, height, scene) {
@@ -7,6 +7,10 @@ export function useDiagramViewport(width, height, scene) {
     const camera = useRef({ x: 0, y: 0, scale: 1 });
     const size = useRef({ width: 0, height: 0 });
     const fitted = useRef(true);
+    const bounds = useRef({ width, height });
+    useLayoutEffect(() => {
+        bounds.current = { width, height };
+    }, [width, height]);
     const frame = useRef(null);
     const [zoom, setZoom] = useState(100);
     const paint = useCallback(() => {
@@ -28,9 +32,16 @@ export function useDiagramViewport(width, height, scene) {
         fitted.current = true;
         if (size.current.width <= 0 || size.current.height <= 0)
             return;
-        camera.current = fitCamera(size.current, { width, height });
+        camera.current = fitCamera(size.current, bounds.current);
         paint();
-    }, [width, height, paint]);
+    }, [paint]);
+    const preserveCamera = useCallback(() => {
+        fitted.current = false;
+    }, []);
+    useEffect(() => {
+        if (fitted.current)
+            fit();
+    }, [width, height, fit]);
     const zoomBy = useCallback((factor, point) => {
         fitted.current = false;
         camera.current = zoomCamera(camera.current, factor, point ?? { x: size.current.width / 2, y: size.current.height / 2 });
@@ -168,5 +179,5 @@ export function useDiagramViewport(width, height, scene) {
             frame.current = null;
         };
     }, [fit, zoomBy, paint, scene]);
-    return { viewport, canvas, zoom, zoomBy, fit };
+    return { viewport, canvas, zoom, zoomBy, fit, preserveCamera };
 }

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "jev-devtools",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "type": "module",
   "engines": {
     "node": ">=22.12"
   },
   "dependencies": {
+    "@tanstack/react-virtual": "3.14.22",
     "@typesafe-ai/sdk": "0.7.0"
   },
   "description": "A React drawer and Node server adapter for inspecting TypeSafe Jev requests.",

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

@@ -79,3 +79,5 @@ Report HTTP/capture checks separately from visual browser checks, and sample ver
 | Production 404 | Expected when disabled; app inference remains independent. |
 
 Capture is bounded to 50 calls in memory by default. Built-in redaction has limits; arbitrary secrets in prose are not detected. Diagrams show captured inputs/outputs, not hidden model reasoning or application routing decisions.
+
+The current browser requests `/events?protocol=2`: the first event is a full version 2 `snapshot`, followed by `delta` events containing changed traces and the retained ID order. The unqualified `/events` check above intentionally remains compatible with legacy clients. Reconnecting always supplies a fresh snapshot.