@mauroandre/velojs 0.0.51 → 0.0.52

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/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
 };

package/package.json

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