@mauroandre/velojs 0.0.53 → 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

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/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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mauroandre/velojs",
-    "version": "0.0.53",
+    "version": "0.0.54",
     "type": "module",
     "description": "Fullstack web framework built on Hono + Preact with Vite-powered AST transforms",
     "keywords": [