@mauroandre/velojs 0.0.52 → 0.0.54

package/README.md

@@ -731,7 +731,24 @@ const { data, snapshot, closed, error } = useEventStream(stream, {
 | `closed` | `true` when server closed the stream |
 | `error` | Parse or connection error, if any |
 
-Lifecycle is automatic: opens on mount, closes on unmount, re-opens fresh when `channel` changes.
+Lifecycle is automatic: opens on mount, closes on unmount, re-opens when `channel` changes.
+
+**Reconnect is stale-while-revalidate.** When the connection re-opens — `channel`, `stream` or `enabled` changed — `data` and `snapshot` keep their previous values until the first event of the new connection overwrites them, the same choice the loader store makes (a refresh must not blank the screen). A channel switch therefore never paints an empty state; only `closed` and `error` reset, because a re-open is a fresh attempt. First mount still starts at `null` and fills in when the snapshot arrives. An app that wants to blank the view on a new channel can clear the signals itself when the channel changes.
+
+**Channel coming from loader data?** Pass `enabled` so the hook does not connect before the channel exists — the first render of a SPA navigation has `data = null`, and connecting with `channel: undefined` reaches the server without `?channel=`, which a resolver answers with `null` → 403 → a flash of `closed`:
+
+```tsx
+const { data } = useLoader<{ id: string }>();
+const channel = data.value?.id;
+
+// no connection until the loader resolves the channel
+const { snapshot, closed } = useEventStream(stream_logs, {
+    // spread only when it exists — `exactOptionalPropertyTypes` (the repo's own
+    // tsconfig) rejects an explicit `undefined` in an optional property
+    ...(channel != null && { channel }),
+    enabled: channel != null,
+});
+```
 
 ### `poll` helper
 
@@ -853,6 +870,9 @@ const { send, status, lastMessage, close } = useSocket(socket_terminal, {
 ```
 
 - `status: Signal<"connecting" | "open" | "closed">` — reactive.
+- `lastMessage: Signal<string | Uint8Array | null>` — last frame received.
+- **Reconnect preserves `lastMessage`** — changing `stub.__path`, `channel` or `enabled` opens a new socket, but the previous frame stays until the first frame of the new one arrives (stale-while-revalidate, same as `useEventStream`); `status` restarts at `"connecting"` and `error` resets. Swapping the stub object with the same `__path` does not reconnect. Clear `lastMessage` yourself in `onOpen` if a channel switch must blank the view.
+- **Channel coming from loader data?** Pass `enabled: channel != null` so the socket only opens once the channel resolves — same reason as `useEventStream`.
 - **No auto-reconnect** — sockets are usually stateful (pty sessions, collaborative state); blind reconnect loses state silently. Re-mount or toggle `enabled` to reconnect.
 
 ### Testing
@@ -1320,7 +1340,7 @@ Hooks (`useParams`, `useQuery`, `usePathname`, `Loader`, `useLoader`) access thi
 
 ## Testing
 
-VeloJS ships a backend testing toolkit at `@mauroandre/velojs/testing`. Spin up the app in memory, fire HTTP requests against the registered handlers, subscribe to event streams. No socket, no browser, no fragile mocks of framework internals.
+VeloJS ships a backend testing toolkit at `@mauroandre/velojs/testing`. Spin up the app in memory, fire HTTP requests against the registered handlers, subscribe to event streams. No browser, no fragile mocks of framework internals — and a real TCP port when an external actor has to reach the app.
 
 ```typescript
 import { createTestApp } from "@mauroandre/velojs/testing";
@@ -1332,6 +1352,7 @@ const app = await createTestApp({
     routes,
     bootstrap: async () => { await connect(process.env.MONGO_URI!); },
     getSessionCookie: async ({ user }) => ({ session: await sign(user) }),
+    // port: 0,   // optional — also serve this app over real TCP (see below)
 });
 
 // HTTP
@@ -1358,6 +1379,7 @@ await app.close();
 | API | Purpose |
 |-----|---------|
 | `createTestApp(options)` | Build isolated app with bootstrap + auth callback |
+| `app.port` / `app.url` | Real port and base URL of the TCP listener — `undefined` in the default in-memory mode |
 | `app.get/post/put/patch/delete` | HTTP requests (cookies, headers, query, JSON/FormData body) |
 | `app.action(fn, opts)` | Invoke `action_*` by function reference |
 | `app.loader(fn, opts)` | Invoke `loader` and unwrap response data |
@@ -1368,6 +1390,26 @@ await app.close();
 | `app.reset()` | Clear stream buffers/listeners between tests |
 | `app.close()` | Tear down everything (zero open handles guaranteed) |
 
+### External actors over TCP
+
+In-memory requests never leave the process, so an actor that does — a worker in another VM POSTing a notify callback — needs a real socket. Pass `port` and the **same app instance** is served over TCP as well:
+
+```typescript
+const app = await createTestApp({ routes, port: 0 });   // 0 → free port
+
+// Hand the URL to the external client (worker, container, another test process)
+await provisioning.startWorker({ notifyUrl: `${app.url}/_action/Jobs/notify` });
+
+// The worker POSTs over real HTTP; the in-memory subscription sees the event —
+// same app, same stream registry, no glue and no second instance
+const sub = await app.subscribe(stream_progress, { channel: jobId });
+const event = await sub.next({ timeoutMs: 5000 });
+
+await app.close();   // closes the listener, dropping in-flight SSE/WebSocket connections
+```
+
+Pages, endpoints, actions, `?_data=1` loaders, SSE and WebSocket all answer as in production; `app.close()` also terminates connections still open on the listener. `port` and `hostname` come from the options only — never from `process.env.PORT`/`HOST` (test determinism). Omitted `hostname` follows Node's default bind (all interfaces — the listener is reachable from the local network); `app.url` reports `http://localhost:<port>` unless an explicit hostname was given.
+
 See [Testing docs](https://github.com/mauro-andre/velojs/blob/dev/site/docs/17-testing.md) for the full guide with patterns, isolation, and FAQ.
 
 ---

package/agent/skills/velojs-event-streams/SKILL.md

@@ -389,6 +389,34 @@ useEventStream(stream, {
 
 The hook handles `EventSource` lifecycle automatically: opens on mount, closes on unmount, re-opens with a fresh connection when `channel` changes.
 
+### Reconnect keeps the last value (stale-while-revalidate)
+
+When the connection re-opens — `channel`, `stream` or `enabled` changed — `data` and `snapshot` keep their previous values until the first event of the new connection overwrites them. It is the same choice the loader store makes: a refresh must not blank the screen. Without it, a channel switch (navigating from `/deploys/1` to `/deploys/2` with the stream in a layout that survives the navigation) would paint an empty state for a full round-trip before the new snapshot arrives.
+
+`closed` and `error` do reset on a re-open: a reconnect is a fresh attempt, not a closed stream. First mount still starts at `null` and fills in when the snapshot arrives — seed it from loader data if that first frame matters to your UI.
+
+If a channel switch must blank the view, clear the signals yourself in an effect keyed on the channel.
+
+### Don't connect before the channel exists
+
+When `channel` derives from loader data, the first render of a SPA navigation has it `undefined` (the loader fetch is post-mount). The hook would then connect **without** `?channel=`, and a resolver that returns `null`/`undefined` for a missing channel answers **403** — the client sees `closed = true` and paints a broken state for the milliseconds until the loader resolves and the effect reconnects.
+
+Pass `enabled` to gate the connection on the channel:
+
+```tsx
+const { data } = useLoader<{ id: string }>();
+const channel = data.value?.id;
+
+const { snapshot, closed } = useEventStream(stream_logs, {
+    // spread only when it exists — `exactOptionalPropertyTypes` (the repo's own
+    // tsconfig) rejects an explicit `undefined` in an optional property
+    ...(channel != null && { channel }),
+    enabled: channel != null,   // no connection until the loader resolves the id
+});
+```
+
+That flash is a documentation-level concern, not a hook one: the hook cannot distinguish "channel still loading" from "stream has no channel". `enabled` is the switch that expresses the difference.
+
 ## Heartbeat
 
 VeloJS sends a `:heartbeat` SSE comment every 20 seconds by default. Without this, idle connections are closed by Cloudflare (~100s), Nginx (~60s), and AWS ALB (~60s) — and the client doesn't even notice.

package/agent/skills/velojs-sockets/SKILL.md

@@ -206,6 +206,22 @@ const { send, status, lastMessage, error, close } = useSocket(stub, {
 - `send(msg)` — queues messages sent while `connecting`; drops messages sent while `closed`.
 - `close(code?, reason?)` — client-initiated disconnect.
 
+**Reconnect keeps `lastMessage` (stale-while-revalidate).** Changing `stub.__path`, `channel` or `enabled` opens a fresh socket, but the previous frame stays in `lastMessage` until the first frame of the new socket arrives — switching from a worker terminal to another one does not paint a blank view for a round-trip. It is the same choice the loader store and `useEventStream` make. `status` restarts at `"connecting"` and `error` resets, because a reconnect is a fresh attempt; a new stub object with the same `__path` is not a reconnect at all. If a channel switch must blank the view, clear `lastMessage` in `onOpen`.
+
+**Channel coming from loader data?** The first render of a SPA navigation has no channel yet (the loader fetch is post-mount), and connecting then reaches the server without `?channel=` — for a guarded socket that is an error, not a connection. Pass `enabled: channel != null` to wait for the loader:
+
+```tsx
+const { data } = useLoader<{ workerId: string }>();
+const channel = data.value?.workerId;
+
+const { send, status, lastMessage } = useSocket(socket_terminal, {
+    // spread only when it exists — `exactOptionalPropertyTypes` (the repo's own
+    // tsconfig) rejects an explicit `undefined` in an optional property
+    ...(channel != null && { channel }),
+    enabled: channel != null,   // no socket until the loader resolves the id
+});
+```
+
 **No auto-reconnect.** If the server closes the socket (network drop, server restart), `status` goes to `"closed"` and stays there. The caller decides whether/when to reconnect — typically by toggling `enabled` or re-mounting the component. This is intentional: sockets are usually stateful (pty session, collaborative cursor) and a blind reconnect would silently lose state.
 
 ## Testing

package/agent/skills/velojs-testing/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: velojs-testing
-description: "Writing tests with `createTestApp` from `@mauroandre/velojs/testing`: HTTP requests, actions, loaders, auth, SSE subscriptions, sockets. Use when writing or fixing a test for a VeloJS app."
+description: "Writing tests with `createTestApp` from `@mauroandre/velojs/testing`: HTTP requests, actions, loaders, auth, SSE subscriptions, sockets, and serving the app on a real TCP port for external actors. Use when writing or fixing a test for a VeloJS app."
 ---
 
 # Testing
 
-VeloJS ships a backend testing toolkit at `@mauroandre/velojs/testing`. It spins up your app in memory, fires HTTP requests against the registered handlers, subscribes to event streams, and asserts on the result. No socket. No browser. No fragile mocks of the framework internals.
+VeloJS ships a backend testing toolkit at `@mauroandre/velojs/testing`. It spins up your app in memory, fires HTTP requests against the registered handlers, subscribes to event streams, and asserts on the result. No browser. No fragile mocks of the framework internals. And when an actor outside this process has to reach the app — a worker sending a notify callback — the same app instance is served over a real TCP port.
 
 You test the whole stack — middleware, auth, routing, conventions, serialization — through the API your real users hit.
 
@@ -77,6 +77,7 @@ const app = await createTestApp({
     routes,
     bootstrap?: async () => { ... },
     getSessionCookie?: async ({ user }) => ({ ... }),
+    port?: 0,
 });
 ```
 
@@ -85,10 +86,12 @@ const app = await createTestApp({
 | `routes` | Required. Your app's `routes` array — typically `import routes from "./app/routes.js"` (it is the **default** export of `routes.tsx`) |
 | `bootstrap` | Runs once before the app is created. Use for DB connections, index creation, anything `app/server.tsx` does at startup. `addRoutes()` and `onServer()` calls here are **scoped to this app only** |
 | `getSessionCookie` | Maps a user object to cookies the test client will attach. Required for `app.as(user)` and `app.sessionCookies(user)` |
+| `port` | Optional. Serves the same app over real TCP on this port (`0` → free port, see [External actors over TCP](#external-actors-over-tcp)) |
+| `hostname` | Interface to bind when `port` is set (e.g. `"127.0.0.1"`). Omitted → Node's default, all interfaces |
 
 ### app.close()
 
-Tears down everything: heartbeats, retention timers, listeners, callbacks. After `close()`, Vitest must report **zero open handles**. Always call it in `afterAll`.
+Tears down everything: heartbeats, retention timers, listeners, callbacks — and the TCP listener when `port` was passed, terminating the SSE/WebSocket connections still open on it. After `close()`, Vitest must report **zero open handles**. Always call it in `afterAll`.
 
 ### app.reset()
 
@@ -159,6 +162,34 @@ await app.get("/api/posts", { query: { tag: ["preact", "ssr"] } });
 // → /api/posts?tag=preact&tag=ssr
 ```
 
+## External actors over TCP
+
+The in-memory client never leaves the process. When the actor under test *does* — a worker in another VM POSTing a notify callback to the control-plane — pass `port` and the **same instance** is served over real TCP:
+
+```typescript
+const app = await createTestApp({ routes, port: 0 });   // 0 → free port
+
+// `app.url` / `app.port` are the real, usable address — hand it to the worker
+await provisioning.startWorker({ notifyUrl: `${app.url}/_action/Jobs/notify` });
+
+// The worker POSTs over real HTTP. It's the same instance behind app.get and
+// app.subscribe, so a stream watched in-memory sees the event — no glue and no
+// "test watches an empty stream because it hit another instance":
+const sub = await app.subscribe(stream_progress, { channel: jobId });
+const event = await sub.next({ timeoutMs: 5000 });
+
+await app.close();   // listener down; in-flight SSE/WS connections dropped
+```
+
+Everything answers as in production — pages, endpoints, `action_*`, `?_data=1` loaders, SSE (`stream_*`) and WebSocket (`socket_*`). `app.close()` refuses new connections and terminates the ones still open, so a suite that keeps the app alive across tests tears down promptly even with a worker mid-SSE.
+
+Two rules keep tests deterministic:
+
+- **Ports come from the options only.** `port` and `hostname` are never read from `process.env.PORT`/`HOST`.
+- **The bind follows the option.** An explicit `hostname` (e.g. `"127.0.0.1"`) keeps the listener loopback; omitted, Node's default applies — all interfaces, reachable from the local network. `app.url` reports `http://localhost:<port>` unless an explicit hostname was given.
+
+Without `port`, nothing changes: the app is purely in-memory, and `app.port`/`app.url` are `undefined`.
+
 ## Auth — getSessionCookie and .as
 
 Most authenticated tests look like:
@@ -293,7 +324,7 @@ it("perChannelSource aborts when the last subscriber leaves", async () => {
 
 ## Sockets — `.socket(handler)`
 
-`app.socket(handlerOrStubOrPath, opts)` opens an **in-memory** WebSocket session against a `socket_*` handler — no real TCP, no upgrade handshake. The handler runs directly with a mock Context.
+`app.socket(handlerOrStubOrPath, opts)` opens an **in-memory** WebSocket session against a `socket_*` handler — no real TCP, no upgrade handshake. The handler runs directly with a mock Context. (For a real handshake, create the app with `port` and connect a client to `ws://...` — see [External actors over TCP](#external-actors-over-tcp).)
 
 ```typescript
 import { socket_terminal } from "../app/workers/WorkerTerminal.js";

package/dist/hooks.d.ts

@@ -166,6 +166,13 @@ export declare function usePathname(): string;
  *
  * The connection closes automatically when the component unmounts or when
  * the channel changes (re-opens with new channel).
+ *
+ * Stale-while-revalidate: on a re-open (new `channel`/`stream`/`enabled`) the
+ * previous `data`/`snapshot` stay in place until the first event of the new
+ * connection overwrites them — the same choice the loader store makes. Only
+ * `closed`/`error` reset, because a re-open is a fresh attempt. To connect
+ * only once a channel derived from loader data has resolved, pass
+ * `enabled: channel != null`.
  */
 export declare function useEventStream<TEvent, TSnapshot = TEvent>(stream: EventStream<TEvent, TSnapshot>, options?: {
     channel?: string;
@@ -218,6 +225,11 @@ export interface UseSocketApi {
  * becomes `"closed"` and stays that way — user flow decides whether to
  * reconnect (typically by re-mounting or toggling `enabled`).
  *
+ * Stale-while-revalidate: on reconnect (new `stub.__path`/`channel`/`enabled`)
+ * `lastMessage` keeps its previous value until the first frame of the new
+ * socket arrives; `status`/`error` restart as a fresh attempt
+ * (`"connecting"` → `"open"`).
+ *
  * ```tsx
  * const { send, status, lastMessage } = useSocket(socket_terminal, {
  *     channel: workerId,

package/dist/hooks.js

@@ -45,10 +45,10 @@ function B(e, n) {
   if (!t)
     return { data: u(null), loading: u(!1), refetch: () => {
     } };
-  const o = N(t), a = m(t), c = () => D(t), d = S(!0);
+  const o = N(t), a = m(t), l = () => D(t), d = S(!0);
   return E(() => {
-    d.current && (d.current = !1, o.value !== null) || c();
-  }, r ?? []), { data: o, loading: a, refetch: c };
+    d.current && (d.current = !1, o.value !== null) || l();
+  }, r ?? []), { data: o, loading: a, refetch: l };
 }
 function J() {
   const [, e] = b();
@@ -69,15 +69,15 @@ function x() {
   return typeof window > "u" ? globalThis.__veloServerData?.getStore?.()?.__pathname ?? "/" : (b(), window.location.pathname);
 }
 function G(e, n = {}) {
-  const t = u(null), r = u(null), o = u(!1), a = u(null), { channel: c, enabled: d = !0 } = n;
+  const t = u(null), r = u(null), o = u(!1), a = u(null), { channel: l, enabled: d = !0 } = n;
   return E(() => {
     if (typeof window > "u" || !d) return;
     if (!e.__path) {
       console.warn("[velojs] useEventStream: stream has no __path");
       return;
     }
-    t.value = null, r.value = null, o.value = !1, a.value = null;
-    const g = c ? `${e.__path}?channel=${encodeURIComponent(c)}` : e.__path, s = new EventSource(g);
+    o.value = !1, a.value = null;
+    const g = l ? `${e.__path}?channel=${encodeURIComponent(l)}` : e.__path, s = new EventSource(g);
     return s.addEventListener("snapshot", (h) => {
       try {
         r.value = JSON.parse(h.data);
@@ -98,41 +98,41 @@ function G(e, n = {}) {
     }), () => {
       s.close();
     };
-  }, [e, c, d]), { data: t, snapshot: r, closed: o, error: a };
+  }, [e, l, d]), { data: t, snapshot: r, closed: o, error: a };
 }
 function F(e, n = {}) {
-  const t = u("connecting"), r = u(null), o = u(null), a = S(null), c = S([]), { channel: d, onMessage: g, onOpen: s, onClose: h, onError: y, enabled: L = !0 } = n;
+  const t = u("connecting"), r = u(null), o = u(null), a = S(null), l = S([]), { channel: d, onMessage: g, onOpen: s, onClose: h, onError: y, enabled: L = !0 } = n;
   return E(() => {
     if (typeof window > "u" || !L) return;
     if (!e.__path) {
       console.warn("[velojs] useSocket: stub has no __path");
       return;
     }
-    t.value = "connecting", r.value = null, o.value = null;
+    t.value = "connecting", o.value = null;
     const v = `${window.location.protocol === "https:" ? "wss:" : "ws:"}//${window.location.host}`, i = d ? `${v}${e.__path}?channel=${encodeURIComponent(d)}` : `${v}${e.__path}`, f = new WebSocket(i);
     return f.binaryType = "arraybuffer", a.current = f, f.addEventListener("open", () => {
       t.value = "open";
-      const l = c.current;
-      c.current = [];
-      for (const _ of l)
+      const c = l.current;
+      l.current = [];
+      for (const _ of c)
         try {
           f.send(_);
         } catch {
         }
       s?.();
-    }), f.addEventListener("message", (l) => {
+    }), f.addEventListener("message", (c) => {
       let _;
-      if (typeof l.data == "string")
-        _ = l.data;
-      else if (l.data instanceof ArrayBuffer)
-        _ = new Uint8Array(l.data);
+      if (typeof c.data == "string")
+        _ = c.data;
+      else if (c.data instanceof ArrayBuffer)
+        _ = new Uint8Array(c.data);
       else
         return;
       r.value = _, g?.(_);
-    }), f.addEventListener("close", (l) => {
-      t.value = "closed", a.current = null, h?.(l);
-    }), f.addEventListener("error", (l) => {
-      o.value = l, y?.(l);
+    }), f.addEventListener("close", (c) => {
+      t.value = "closed", a.current = null, h?.(c);
+    }), f.addEventListener("error", (c) => {
+      o.value = c, y?.(c);
     }), () => {
       a.current = null;
       try {
@@ -149,7 +149,7 @@ function F(e, n = {}) {
         i.send(v);
       } catch {
       }
-    else i && i.readyState === WebSocket.CONNECTING && c.current.push(v);
+    else i && i.readyState === WebSocket.CONNECTING && l.current.push(v);
   }, close: (p, v) => {
     const i = a.current;
     if (i)

package/dist/server.d.ts

@@ -4,6 +4,21 @@ import { AsyncLocalStorage } from "node:async_hooks";
 export declare const serverDataStorage: AsyncLocalStorage<Record<string, unknown>>;
 type ServerCallback = (server: import("http").Server) => void;
 export declare function onServer(fn: ServerCallback): void;
+/**
+ * Points the global `activeServer` at `server` and drains the callbacks
+ * registered in the current context. Exported for the testing toolkit, which
+ * serves a TestApp over TCP and must hand the real server to `onServer()`
+ * callbacks (same flush as `startServer`).
+ */
+export declare function flushServerCallbacks(server: import("http").Server): void;
+/**
+ * Drops the global `activeServer` when it still points at `server`. A closed
+ * server must stop answering `onServer()`: a late registrant would receive a
+ * dead instance (address() === null) instead of queueing for the next one.
+ * `startServer` does the same through `server.once("close", …)`; the testing
+ * toolkit has no such event to lean on because it closes the server itself.
+ */
+export declare function clearActiveServer(server: import("http").Server): void;
 export interface StartServerOptions {
     routes: AppRoutes;
     port?: number;

package/dist/server.js

@@ -1,17 +1,17 @@
-import { jsx as v } from "preact/jsx-runtime";
+import { jsx as w } from "preact/jsx-runtime";
 import { Hono as R } from "hono";
 import { logger as T } from "hono/logger";
 import { trimTrailingSlash as E } from "hono/trailing-slash";
 import { render as C } from "preact-render-to-string";
-import { Router as $ } from "wouter-preact";
-import { AsyncLocalStorage as k } from "node:async_hooks";
+import { Router as A } from "wouter-preact";
+import { AsyncLocalStorage as $ } from "node:async_hooks";
 import { getAppContext as _ } from "./app-context.js";
-import { flushPendingStreamRoutes as A, registerStreamHandler as D } from "./events.js";
+import { flushPendingStreamRoutes as k, registerStreamHandler as D } from "./events.js";
 import { registerSocketRoutes as O, injectWebSocketServer as S } from "./sockets.js";
-const P = new k();
+const P = new $();
 globalThis.__veloServerData = P;
 let g = null;
-function Z(e) {
+function ee(e) {
   if (g) {
     e(g);
     return;
@@ -24,23 +24,26 @@ function b(e) {
   for (const s of t.serverCallbacks) s(e);
   t.serverCallbacks.length = 0;
 }
-function ee(e) {
+function I(e) {
+  g === e && (g = null);
+}
+function te(e) {
   _().pendingRoutes.push(e);
 }
-const I = (e) => JSON.stringify(e).replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029"), N = (e, t, s, a) => {
+const N = (e) => JSON.stringify(e).replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029"), H = (e, t, s, a) => {
   if (a && a !== 200 && e.status(a), e.req.query("_data") === "1") {
     const c = globalThis.__veloBuildHash || void 0, r = s ? { ...s, __buildHash: c } : { __buildHash: c };
     return e.json(r);
   }
   const o = e.req.path, n = P.run(
     s ?? {},
-    () => C(/* @__PURE__ */ v($, { ssrPath: o, children: t }))
+    () => C(/* @__PURE__ */ w(A, { ssrPath: o, children: t }))
   );
   if (e.header("Cache-Control", "no-cache"), !s)
     return e.html(n);
-  const i = `<script>window.__PAGE_DATA__=${I(s)}<\/script>`;
+  const i = `<script>window.__PAGE_DATA__=${N(s)}<\/script>`;
   return e.html(n.replace("</head>", () => `${i}</head>`));
-}, H = async (e, t) => {
+}, G = async (e, t) => {
   const s = t.req.param(), a = t.req.query(), o = { params: s, query: a, c: t }, n = await Promise.all(
     e.map(async (r) => {
       if (!r.loader) return null;
@@ -66,16 +69,16 @@ const I = (e) => JSON.stringify(e).replace(/</g, "\\u003c").replace(/>/g, "\\u00
     data: c,
     shortCircuit: i
   };
-}, G = (e) => {
+}, x = (e) => {
   if (e.length === 0) return null;
   const t = e.filter(Boolean);
   if (t.length === 0) return null;
   if (t.length === 1) {
     const o = t[0];
-    return /* @__PURE__ */ v(o, {});
+    return /* @__PURE__ */ w(o, {});
   }
   const s = t[t.length - 1];
-  return t.slice(0, -1).reduceRight((o, n) => /* @__PURE__ */ v(n, { children: o }), /* @__PURE__ */ v(s, {}));
+  return t.slice(0, -1).reduceRight((o, n) => /* @__PURE__ */ w(n, { children: o }), /* @__PURE__ */ w(s, {}));
 }, y = (e, t, s = [], a = []) => {
   for (const o of t) {
     if (o.handler && !o.module) {
@@ -107,13 +110,13 @@ const I = (e) => JSON.stringify(e).replace(/</g, "\\u003c").replace(/>/g, "\\u00
         continue;
       }
       const l = async (d) => {
-        const { components: u, data: h, shortCircuit: m } = await H(n, d);
+        const { components: u, data: h, shortCircuit: m } = await G(n, d);
         if (m) {
-          const w = m.headers.get("Location");
-          return d.req.query("_data") === "1" && w && m.status >= 300 && m.status < 400 ? d.json({ __redirect: w }) : m;
+          const v = m.headers.get("Location");
+          return d.req.query("_data") === "1" && v && m.status >= 300 && m.status < 400 ? d.json({ __redirect: v }) : m;
         }
-        const p = G(u);
-        return N(d, p, h, r);
+        const p = x(u);
+        return H(d, p, h, r);
       };
       c ? e.notFound(l) : i.length > 0 ? e.on(["GET"], [f], ...i, l) : e.on(["GET"], [f], l);
     } else
@@ -148,8 +151,8 @@ const I = (e) => JSON.stringify(e).replace(/</g, "\\u003c").replace(/>/g, "\\u00
               const p = await f(m);
               return u.json(p ?? { ok: !0 });
             } catch (p) {
-              const w = p instanceof Error ? p.message : "Action failed";
-              return u.json({ error: w }, 500);
+              const v = p instanceof Error ? p.message : "Action failed";
+              return u.json({ error: v }, 500);
             }
           };
           n.length > 0 ? e.on(
@@ -163,7 +166,7 @@ const I = (e) => JSON.stringify(e).replace(/</g, "\\u003c").replace(/>/g, "\\u00
     }
     a.children && q(e, a.children, n);
   }
-}, x = async (e, t, s = []) => {
+}, V = async (e, t, s = []) => {
   const a = (o, n) => {
     for (const i of o) {
       const c = i.module?.metadata?.moduleId, r = [
@@ -191,7 +194,7 @@ const I = (e) => JSON.stringify(e).replace(/</g, "\\u003c").replace(/>/g, "\\u00
     }
   };
   a(t, s);
-}, V = (e, t) => t ? t.startsWith("/") ? e + t : e ? e + "/" + t : "/" + t : e || "", W = (e) => {
+}, W = (e, t) => t ? t.startsWith("/") ? e + t : e ? e + "/" + t : "/" + t : e || "", K = (e) => {
   const t = /* @__PURE__ */ new Set(), s = (a) => {
     for (const o of a) {
       if (o.module && !o.children) {
@@ -204,7 +207,7 @@ const I = (e) => JSON.stringify(e).replace(/</g, "\\u003c").replace(/>/g, "\\u00
   return s(e), t;
 }, j = (e, t, s, a = "", o = []) => {
   for (const n of t) {
-    const i = V(a, n.path), c = [
+    const i = W(a, n.path), c = [
       ...o,
       ...n.middlewares || []
     ], r = !!n.handler, f = !!n.method;
@@ -236,21 +239,21 @@ const I = (e) => JSON.stringify(e).replace(/</g, "\\u003c").replace(/>/g, "\\u00
       c
     );
   }
-}, K = async (e) => {
+}, L = async (e) => {
   const t = new R();
   t.use(E()), process.env.NODE_ENV !== "production" && t.use("*", T());
   const a = _().pendingRoutes.splice(0);
   for (const n of a)
     await n(t);
-  y(t, e), q(t, e), await x(t, e);
-  const o = W(e);
-  if (j(t, e, o), await O(t, e), A(t), process.env.NODE_ENV !== "production" && !g) {
+  y(t, e), q(t, e), await V(t, e);
+  const o = K(e);
+  if (j(t, e, o), await O(t, e), k(t), process.env.NODE_ENV !== "production" && !g) {
     const n = globalThis.__veloDevServer;
     n && (b(n), await S(t, n));
   }
   return t;
-}, te = async (e) => {
-  const { routes: t } = e, s = Number(process.env.PORT) || e.port || 3e3, a = process.env.HOST || e.hostname || void 0, o = await K(t);
+}, oe = async (e) => {
+  const { routes: t } = e, s = Number(process.env.PORT) || e.port || 3e3, a = process.env.HOST || e.hostname || void 0, o = await L(t);
   if (process.env.NODE_ENV === "production" && !process.env.VELO_STATIC) {
     const { serve: n } = await import("@hono/node-server"), { serveStatic: i } = await import("@hono/node-server/serve-static"), { join: c } = await import("node:path"), r = c(process.cwd(), "dist/client");
     (process.env.STATIC_BASE_URL || "").startsWith("http") || o.use("/*", i({ root: r }));
@@ -263,17 +266,19 @@ const I = (e) => JSON.stringify(e).replace(/</g, "\\u003c").replace(/>/g, "\\u00
     } else
       console.log(`Server running on port ${s}`);
     await S(o, l), b(l), l.once("close", () => {
-      g === l && (g = null);
+      I(l);
     });
   }
   return o;
 };
 export {
-  ee as addRoutes,
-  K as createApp,
-  K as default,
-  I as jsonForScript,
-  Z as onServer,
+  te as addRoutes,
+  I as clearActiveServer,
+  L as createApp,
+  L as default,
+  b as flushServerCallbacks,
+  N as jsonForScript,
+  ee as onServer,
   P as serverDataStorage,
-  te as startServer
+  oe as startServer
 };

package/dist/testing/createTestApp.d.ts

@@ -19,5 +19,13 @@ import type { TestApp, CreateTestAppOptions } from "./types.js";
  *     getSessionCookie: async ({ user }) => ({ session: await sign(user) }),
  * });
  * ```
+ *
+ * Pass `port` to also serve the same app over real TCP — for external actors
+ * (a worker in another process) that cannot call `hono.fetch` in-memory:
+ *
+ * ```typescript
+ * const app = await createTestApp({ routes, port: 0 });
+ * await handToWorker(`${app.url}/_action/Jobs/notify`);
+ * ```
  */
 export declare function createTestApp(opts: CreateTestAppOptions): Promise<TestApp>;