@mauroandre/velojs 0.0.51 → 0.0.53

package/README.md

@@ -1320,7 +1320,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 +1332,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 +1359,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 +1370,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-boot-state/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: velojs-boot-state
+description: "Load localStorage/cookies BEFORE the first paint with `<Boot>` in client-root and read them with `useBoot()` — flicker-free themes, sidebars, and layout preferences. Use when UI state from the browser flashes on reload or when persisting layout preferences."
+---
+
+# Boot state (pre-paint loading)
+
+State stored in the browser (theme, collapsed sidebar, panel sizes) causes a flash on reload: the SSR HTML paints with defaults, then client JS corrects it — one visible frame of the wrong layout. The only code that runs between the `<head>` being parsed and the `<body>` being painted is a **synchronous inline script in the head**. `<Boot>` generates that script for you.
+
+## Declaring what to load
+
+In `client-root.tsx`, declare each storage separately with the exact key names your app uses:
+
+```tsx
+import { Boot, Scripts } from "@mauroandre/velojs";
+
+export const Component = ({ children }) => (
+    <html>
+        <head>
+            <Boot localStorage={["theme", "sidebarHidden"]} />
+            <Boot cookies={["org"]} />
+        </head>
+        <body>
+            {children}
+            <Scripts />
+        </body>
+    </html>
+);
+```
+
+The generated script runs before the first paint and does two things:
+
+1. Populates `window.__VELO_BOOT__ = { theme: "dark", sidebarHidden: "true" }` — only keys that exist; absent keys stay out.
+2. Mirrors each found key as a sanitized `data-*` attribute on `<html>`: `data-theme="dark"`, `data-sidebar-hidden`... Key sanitization: anything outside `[a-zA-Z0-9-]` becomes `-` — `"bc:terminal-colapsado"` → `data-bc-terminal-colapsado`.
+
+## Reading
+
+```tsx
+import { useBoot } from "@mauroandre/velojs/hooks";
+
+const { theme, sidebarHidden } = useBoot();
+```
+
+Values are **raw strings**, immutable by definition — the boot happened once. Seed your own signal with them for reactivity (`signal(boot.sidebarHidden === "true")`); parse numbers/JSON yourself.
+
+On the server `useBoot()` returns `{}` — SSR always renders defaults, never touches `window`.
+
+## The anti-flicker contract (the part that matters)
+
+**Visual state must be CSS reacting to the mirrored data-attribute — never conditional JSX.**
+
+```css
+html[data-theme="dark"] { --color-surface: #11151f; }
+html[data-sidebar-hidden="true"] .sidebar { display: none; }
+```
+
+- ✅ Always render the sidebar in the vdom; hide it with CSS on the attribute. The attribute is correct **before the first paint** → single correct paint, no flash, no hydration mismatch.
+- ❌ `{!sidebarHidden && <Sidebar />}` — the client's first render diverges from the SSR DOM (hydration mismatch) and only corrects **after** paint: the flash is back.
+
+A CSS `transition` on the mirrored property does not fire on load (the attribute is set before the first style computation) — transitions only run on interactive toggles, which is what you want.
+
+## Writing is the app's business
+
+`<Boot>` only loads. Persisting on change is a signal + storage write in your gestures:
+
+```tsx
+const sidebarHidden = signal(/* seeded from useBoot */);
+useEffect(() => {
+    document.documentElement.dataset.sidebarHidden = String(sidebarHidden.value);
+    localStorage.setItem("sidebarHidden", String(sidebarHidden.value));
+}, [sidebarHidden.value]);
+```
+
+## Reference
+
+| Piece | Behavior |
+|-------|----------|
+| `<Boot localStorage={[...]} />` | Inline pre-paint script; one `<Boot>` per storage |
+| `<Boot cookies={[...]} />` | Same, from `document.cookie` |
+| `useBoot()` | `Record<string, string>` — `{}` on the server, boot values on the client |
+| Key `a:b` in storage | Attribute `data-a-b`; object key stays `"a:b"` |
+| Storage throws (private mode) | Script is a no-op — app renders defaults |

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/components.d.ts

@@ -29,6 +29,45 @@ interface ScriptsProps {
  * ```
  */
 export declare function Scripts({ basePath, favicon }?: ScriptsProps): import("preact").JSX.Element;
+interface BootProps {
+    /**
+     * localStorage keys to load before the first paint. The value of each
+     * key found is exposed on `window.__VELO_BOOT__` and mirrored as a
+     * sanitized `data-*` attribute on `<html>` — CSS reacting to the
+     * attribute is what makes the first paint flicker-free.
+     */
+    localStorage?: string[];
+    /**
+     * Cookie names to load before the first paint (same exposure/mirroring
+     * as localStorage keys). Declare storages separately: one Boot per
+     * storage keeps each script minimal.
+     */
+    cookies?: string[];
+}
+/**
+ * Generates the pre-paint boot script. Pure and isomorphic — Boot must
+ * render the SAME string on server and client so hydration matches.
+ * Exported for tests.
+ */
+export declare function bootScript({ localStorage: lsKeys, cookies: ckKeys }?: BootProps): string;
+/**
+ * Declares client state to load BEFORE the first paint. Place it in the
+ * `<head>` of client-root — a synchronous inline script is the only code
+ * that runs between the head being parsed and the body being painted, so
+ * values it mirrors as data-attributes produce a single, correct paint.
+ *
+ * Reading: `useBoot()` destructures by the declared names.
+ * Writing/persisting stays with the app (signals + storage in its gestures).
+ *
+ * @example
+ * ```tsx
+ * <head>
+ *     <Boot localStorage={["theme", "sidebarHidden"]} />
+ *     <Boot cookies={["org"]} />
+ * </head>
+ * ```
+ */
+export declare function Boot(props: BootProps): import("preact").JSX.Element | null;
 import type { ComponentProps } from "preact";
 import type { RouteModule } from "./types.js";
 type WouterLinkProps = ComponentProps<typeof WouterLink>;

package/dist/components.js

@@ -1,58 +1,69 @@
-import { jsx as o, jsxs as d, Fragment as m } from "preact/jsx-runtime";
-import { useRouter as v, Link as L } from "wouter-preact";
+import { jsx as r, jsxs as p, Fragment as g } from "preact/jsx-runtime";
+import { useRouter as L, Link as $ } from "wouter-preact";
 import "@preact/signals";
 import "preact/hooks";
 import { __veloUpdatePending as C } from "./loader-store.js";
-function j({ basePath: e, favicon: t = "/favicon.ico" } = {}) {
+function w({ basePath: t, favicon: e = "/favicon.ico" } = {}) {
   const n = process.env.NODE_ENV !== "production";
-  e = e || process.env.STATIC_BASE_URL || (process.env.VELO_STATIC ? "/client" : "");
-  const r = t === !1 ? void 0 : t.endsWith(".svg") ? "image/svg+xml" : t.endsWith(".png") ? "image/png" : "image/x-icon", i = t !== !1 && /* @__PURE__ */ o("link", { rel: "icon", href: `${e}${t}`, type: r });
+  t = t || process.env.STATIC_BASE_URL || (process.env.VELO_STATIC ? "/client" : "");
+  const s = e === !1 ? void 0 : e.endsWith(".svg") ? "image/svg+xml" : e.endsWith(".png") ? "image/png" : "image/x-icon", i = e !== !1 && /* @__PURE__ */ r("link", { rel: "icon", href: `${t}${e}`, type: s });
   if (n)
-    return /* @__PURE__ */ d(m, { children: [
+    return /* @__PURE__ */ p(g, { children: [
       i,
-      /* @__PURE__ */ o("script", { type: "module", src: "/@vite/client" }),
-      /* @__PURE__ */ o("script", { type: "module", src: "/__velo_client.js" })
+      /* @__PURE__ */ r("script", { type: "module", src: "/@vite/client" }),
+      /* @__PURE__ */ r("script", { type: "module", src: "/__velo_client.js" })
     ] });
-  const l = globalThis.__veloClientJs || (typeof __VELO_CLIENT_JS__ < "u" ? __VELO_CLIENT_JS__ : "client.js"), c = globalThis.__veloClientCss || (typeof __VELO_CLIENT_CSS__ < "u" ? __VELO_CLIENT_CSS__ : "client.css");
-  return /* @__PURE__ */ d(m, { children: [
+  const c = globalThis.__veloClientJs || (typeof __VELO_CLIENT_JS__ < "u" ? __VELO_CLIENT_JS__ : "client.js"), l = globalThis.__veloClientCss || (typeof __VELO_CLIENT_CSS__ < "u" ? __VELO_CLIENT_CSS__ : "client.css");
+  return /* @__PURE__ */ p(g, { children: [
     i,
-    /* @__PURE__ */ o("link", { rel: "stylesheet", href: `${e}/${c}` }),
-    /* @__PURE__ */ o("script", { type: "module", src: `${e}/${l}` })
+    /* @__PURE__ */ r("link", { rel: "stylesheet", href: `${t}/${l}` }),
+    /* @__PURE__ */ r("script", { type: "module", src: `${t}/${c}` })
   ] });
 }
-function h(e, t) {
-  let n = e;
-  for (const [r, i] of Object.entries(t))
-    n = n.replace(`:${r}`, i);
+function S({ localStorage: t, cookies: e } = {}) {
+  if ((!t || t.length === 0) && (!e || e.length === 0)) return "";
+  const n = (c) => JSON.stringify(c).replace(/</g, "\\u003c"), s = t && t.length > 0 ? `var L=${n(t)};for(var i=0;i<L.length;i++){var v=localStorage.getItem(L[i]);if(v!==null)b[L[i]]=v;}` : "", i = e && e.length > 0 ? `var C=${n(e)};var s=document.cookie?document.cookie.split("; "):[];var m={};for(var j=0;j<s.length;j++){var p=s[j].indexOf("=");if(p>0){m[s[j].slice(0,p)]=decodeURIComponent(s[j].slice(p+1));}}for(var k=0;k<C.length;k++){if(C[k]in m)b[C[k]]=m[C[k]];}` : "";
+  return `(function(){var b={};try{${s}}catch(e){}try{${i}}catch(e){}if(Object.keys(b).length){window.__VELO_BOOT__=Object.assign(window.__VELO_BOOT__||{},b);var d=document.documentElement;for(var q in b){d.setAttribute("data-"+String(q).replace(/[^a-zA-Z0-9-]/g,"-"),b[q]);}}})();`;
+}
+function y(t) {
+  const e = S(t);
+  return e ? /* @__PURE__ */ r("script", { dangerouslySetInnerHTML: { __html: e } }) : null;
+}
+function m(t, e) {
+  let n = t;
+  for (const [s, i] of Object.entries(e))
+    n = n.replace(`:${s}`, i);
   return n;
 }
-function I({ to: e, params: t, search: n, absolute: r, ...i }) {
-  const l = typeof e != "string", c = v(), f = l ? e.metadata?.fullPath ?? "/" : e, u = t ? h(f, t) : f, a = n ? `?${new URLSearchParams(n).toString()}` : "", $ = `${u}${a}`;
+function I({ to: t, params: e, search: n, absolute: s, ...i }) {
+  const c = typeof t != "string", l = L(), _ = c ? t.metadata?.fullPath ?? "/" : t, f = e ? m(_, e) : _, u = n ? `?${new URLSearchParams(n).toString()}` : "", v = `${f}${u}`;
   if (typeof window < "u" && C.value) {
-    let _;
-    if (l) {
-      const s = e.metadata?.fullPath ?? f;
-      _ = `${t ? h(s, t) : s}${a}`;
+    let a;
+    if (c) {
+      const o = t.metadata?.fullPath ?? _;
+      a = `${e ? m(o, e) : o}${u}`;
     } else {
-      const s = u.replace(/^~/, "");
-      _ = `${!u.startsWith("~") && c.base ? c.base : ""}${s}${a}`;
+      const o = f.replace(/^~/, "");
+      a = `${!f.startsWith("~") && l.base ? l.base : ""}${o}${u}`;
     }
-    const { onClick: p, ...g } = i;
-    return /* @__PURE__ */ o(
+    const { onClick: d, ...h } = i;
+    return /* @__PURE__ */ r(
       "a",
       {
-        href: _,
-        onClick: (s) => {
-          p && p(s), s.defaultPrevented || (s.preventDefault(), window.location.href = _);
+        href: a,
+        onClick: (o) => {
+          d && d(o), o.defaultPrevented || (o.preventDefault(), window.location.href = a);
         },
-        ...g
+        ...h
       }
     );
   }
-  return /* @__PURE__ */ o(L, { to: $, ...i });
+  return /* @__PURE__ */ r($, { to: v, ...i });
 }
 export {
+  y as Boot,
   I as Link,
-  j as Scripts,
-  h as substituteParams
+  w as Scripts,
+  S as bootScript,
+  m as substituteParams
 };

package/dist/hooks.d.ts

@@ -3,6 +3,30 @@ import type { EventStream } from "./events.js";
 import type { SocketHandler, SocketStub } from "./sockets.js";
 import { __veloUpdatePending } from "./loader-store.js";
 export { __veloUpdatePending };
+declare global {
+    interface Window {
+        /** Populated by <Boot>'s pre-paint script — see components.tsx. */
+        __VELO_BOOT__?: Record<string, string>;
+    }
+}
+/**
+ * Reads the boot state loaded before the first paint by `<Boot>`.
+ *
+ * Values are raw strings, immutable by definition (the boot happened once —
+ * state evolves through the app's own signals, seeded with these values).
+ * On the server it returns an empty object: there is no window to read.
+ *
+ * The anti-flicker contract: visual state derived from these values must be
+ * CSS reacting to the mirrored data-attributes on `<html>`, not conditional
+ * JSX — the attribute is correct before the first paint, a conditional
+ * render only corrects after hydration.
+ *
+ * @example
+ * ```tsx
+ * const { theme, sidebarHidden } = useBoot();
+ * ```
+ */
+export declare function useBoot(): Record<string, string>;
 /**
  * Força o signal a notificar mudanças após mutação de propriedades aninhadas
  *

package/dist/hooks.js

@@ -1,30 +1,33 @@
-import { signal as S, useSignal as c } from "@preact/signals";
-import { useEffect as E, useRef as w } from "preact/hooks";
-import { useLocation as D, useParams as $, useSearch as C } from "wouter-preact";
-import { refetchModule as L, loaderLoading as m, loaderEntry as N } from "./loader-store.js";
+import { signal as w, useSignal as u } from "@preact/signals";
+import { useEffect as E, useRef as S } from "preact/hooks";
+import { useLocation as b, useParams as O, useSearch as $ } from "wouter-preact";
+import { refetchModule as D, loaderLoading as m, loaderEntry as N } from "./loader-store.js";
 import { __veloUpdatePending as z } from "./loader-store.js";
-function U(e) {
+function U() {
+  return typeof window > "u" ? {} : window.__VELO_BOOT__ ?? {};
+}
+function W(e) {
   const n = e.value;
   n === null || typeof n != "object" || (e.value = Array.isArray(n) ? [...n] : { ...n });
 }
-function W(e) {
+function j(e) {
   return typeof window > "u" ? {
     data: {
       get value() {
         return e ? globalThis.__veloServerData?.getStore?.()?.[e] ?? null : null;
       }
     },
-    loading: S(!1),
+    loading: w(!1),
     refetch: () => {
     }
   } : e ? {
     data: N(e),
     loading: m(e),
-    refetch: () => L(e)
-  } : { data: S(null), loading: S(!1), refetch: () => {
+    refetch: () => D(e)
+  } : { data: w(null), loading: w(!1), refetch: () => {
   } };
 }
-function j(e, n) {
+function B(e, n) {
   let t, r;
   if (Array.isArray(e) ? r = e : (t = e, r = n), typeof window > "u") {
     let g = null;
@@ -33,40 +36,40 @@ function j(e, n) {
       h?.[t] && (g = h[t]);
     }
     return {
-      data: c(g),
-      loading: c(!1),
+      data: u(g),
+      loading: u(!1),
       refetch: () => {
       }
     };
   }
   if (!t)
-    return { data: c(null), loading: c(!1), refetch: () => {
+    return { data: u(null), loading: u(!1), refetch: () => {
     } };
-  const o = N(t), a = m(t), u = () => L(t), d = w(!0);
+  const o = N(t), a = m(t), c = () => D(t), d = S(!0);
   return E(() => {
-    d.current && (d.current = !1, o.value !== null) || u();
-  }, r ?? []), { data: o, loading: a, refetch: u };
+    d.current && (d.current = !1, o.value !== null) || c();
+  }, r ?? []), { data: o, loading: a, refetch: c };
 }
 function J() {
-  const [, e] = D();
+  const [, e] = b();
   return e;
 }
 function M() {
-  return typeof window > "u" ? globalThis.__veloServerData?.getStore?.()?.__params ?? {} : $();
+  return typeof window > "u" ? globalThis.__veloServerData?.getStore?.()?.__params ?? {} : O();
 }
 function q() {
   if (typeof window > "u")
     return globalThis.__veloServerData?.getStore?.()?.__query ?? {};
-  const e = C(), n = {};
+  const e = $(), n = {};
   return new URLSearchParams(e).forEach((t, r) => {
     n[r] = t;
   }), n;
 }
 function x() {
-  return typeof window > "u" ? globalThis.__veloServerData?.getStore?.()?.__pathname ?? "/" : (D(), window.location.pathname);
+  return typeof window > "u" ? globalThis.__veloServerData?.getStore?.()?.__pathname ?? "/" : (b(), window.location.pathname);
 }
 function G(e, n = {}) {
-  const t = c(null), r = c(null), o = c(!1), a = c(null), { channel: u, enabled: d = !0 } = n;
+  const t = u(null), r = u(null), o = u(!1), a = u(null), { channel: c, enabled: d = !0 } = n;
   return E(() => {
     if (typeof window > "u" || !d) return;
     if (!e.__path) {
@@ -74,18 +77,18 @@ function G(e, n = {}) {
       return;
     }
     t.value = null, r.value = null, o.value = !1, a.value = null;
-    const g = u ? `${e.__path}?channel=${encodeURIComponent(u)}` : e.__path, s = new EventSource(g);
+    const g = c ? `${e.__path}?channel=${encodeURIComponent(c)}` : e.__path, s = new EventSource(g);
     return s.addEventListener("snapshot", (h) => {
       try {
         r.value = JSON.parse(h.data);
-      } catch (_) {
-        a.value = _;
+      } catch (y) {
+        a.value = y;
       }
     }), s.addEventListener("message", (h) => {
       try {
         t.value = JSON.parse(h.data);
-      } catch (_) {
-        a.value = _;
+      } catch (y) {
+        a.value = y;
       }
     }), s.addEventListener("heartbeat", () => {
     }), s.addEventListener("close", () => {
@@ -95,12 +98,12 @@ function G(e, n = {}) {
     }), () => {
       s.close();
     };
-  }, [e, u, d]), { data: t, snapshot: r, closed: o, error: a };
+  }, [e, c, d]), { data: t, snapshot: r, closed: o, error: a };
 }
-function B(e, n = {}) {
-  const t = c("connecting"), r = c(null), o = c(null), a = w(null), u = w([]), { channel: d, onMessage: g, onOpen: s, onClose: h, onError: _, enabled: b = !0 } = n;
+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;
   return E(() => {
-    if (typeof window > "u" || !b) return;
+    if (typeof window > "u" || !L) return;
     if (!e.__path) {
       console.warn("[velojs] useSocket: stub has no __path");
       return;
@@ -109,27 +112,27 @@ function B(e, n = {}) {
     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 = u.current;
-      u.current = [];
-      for (const y of l)
+      const l = c.current;
+      c.current = [];
+      for (const _ of l)
         try {
-          f.send(y);
+          f.send(_);
         } catch {
         }
       s?.();
     }), f.addEventListener("message", (l) => {
-      let y;
+      let _;
       if (typeof l.data == "string")
-        y = l.data;
+        _ = l.data;
       else if (l.data instanceof ArrayBuffer)
-        y = new Uint8Array(l.data);
+        _ = new Uint8Array(l.data);
       else
         return;
-      r.value = y, g?.(y);
+      r.value = _, g?.(_);
     }), f.addEventListener("close", (l) => {
       t.value = "closed", a.current = null, h?.(l);
     }), f.addEventListener("error", (l) => {
-      o.value = l, _?.(l);
+      o.value = l, y?.(l);
     }), () => {
       a.current = null;
       try {
@@ -137,7 +140,7 @@ function B(e, n = {}) {
       } catch {
       }
     };
-  }, [e.__path, d, b]), { send: (p) => {
+  }, [e.__path, d, L]), { send: (p) => {
     let v;
     typeof p == "string" || p instanceof Uint8Array ? v = p : v = JSON.stringify(p);
     const i = a.current;
@@ -146,7 +149,7 @@ function B(e, n = {}) {
         i.send(v);
       } catch {
       }
-    else i && i.readyState === WebSocket.CONNECTING && u.current.push(v);
+    else i && i.readyState === WebSocket.CONNECTING && c.current.push(v);
   }, close: (p, v) => {
     const i = a.current;
     if (i)
@@ -157,14 +160,15 @@ function B(e, n = {}) {
   }, status: t, lastMessage: r, error: o };
 }
 export {
-  W as Loader,
+  j as Loader,
   z as __veloUpdatePending,
-  U as touch,
+  W as touch,
+  U as useBoot,
   G as useEventStream,
-  j as useLoader,
+  B as useLoader,
   J as useNavigate,
   M as useParams,
   x as usePathname,
   q as useQuery,
-  B as useSocket
+  F as useSocket
 };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export type { AppRoutes, RouteNode, RouteModule, LoaderArgs, ActionArgs, Metadata, HTTPMethod, EndpointHandler, EndpointHandlerArgs, } from "./types.js";
 export type { VeloConfig } from "./config.js";
 export { defineConfig } from "./config.js";
-export { Scripts, Link } from "./components.js";
+export { Scripts, Link, Boot } from "./components.js";
 export { createEventStream, poll } from "./events.js";
 export type { EventStream, EventStreamConfig, EmitFn, EmitOptions, SourceFn, PerChannelSourceFn, StreamPipeFn, StreamPipeArgs, ChannelResolver, } from "./events.js";
 export type { SocketHandler, SocketHandlerArgs, SocketStub, } from "./sockets.js";

package/dist/index.js

@@ -1,10 +1,11 @@
-import { defineConfig as o } from "./config.js";
-import { Link as f, Scripts as p } from "./components.js";
-import { createEventStream as m, poll as n } from "./events.js";
+import { defineConfig as r } from "./config.js";
+import { Boot as f, Link as p, Scripts as i } from "./components.js";
+import { createEventStream as n, poll as x } from "./events.js";
 export {
-  f as Link,
-  p as Scripts,
-  m as createEventStream,
-  o as defineConfig,
-  n as poll
+  f as Boot,
+  p as Link,
+  i as Scripts,
+  n as createEventStream,
+  r as defineConfig,
+  x as poll
 };