@mauroandre/velojs 0.0.57 → 0.0.58

package/README.md

@@ -467,6 +467,7 @@ A page value that must **track server state over time** — a total another
 person's request changes, data a background scheduler mutates — declares the
 channels that keep it fresh. No extra component, no manual subscription: the
 module exports `channels` next to its `loader`.
+The one-sentence model: the live loader keeps a page's state replica faithful to the server — the first payload arrives through the usual path (SSR, `__PAGE_DATA__`, the `?_data=1` refetch), and from then on every change is **addressed**, by the app's own rules, to the group of clients it concerns, **by duty or by interest**, each one receiving the state computed for its own scope.
 
 ```tsx
 // app/expenses/Expenses.tsx
@@ -768,6 +769,8 @@ partitions is internal information, and it never ships in a production build.
 
 ### The partition contract
 
+**Addressed, not broadcast.** A partition is not a filter applied after a broadcast. The `emit` is addressed: the runtime resolves the partition key and writes only to the connections of that group — a client outside the group never hears about the change, not even a byte. Two reasons make a partition matter, and they compose: **by duty** (authorization — the data belongs to that team, that family, that project; others must not see it) and **by interest** (relevance — the tab watching project 9 has nothing to wake up for when project 7 changes). The same `scope` serves both; the app decides which, or both at once.
+
 On subscribe the `scope` receives `{ user, params }`. `user` is `c.get("user")`
 — the house key, the same one the stream/socket channel resolvers use (a
 middleware that materializes the principal elsewhere should set it in `"user"`
@@ -2025,7 +2028,7 @@ velojs build
 
 Asset filenames include content hashes for long-term browser caching. The server build reads the Vite manifest to inject the correct filenames into `<Scripts>`.
 
-In production, `velojs start` sets `NODE_ENV=production` automatically and serves static files from `dist/client/`. HTML responses are served with `Cache-Control: no-cache` so browsers always fetch the latest HTML (which references the current hashed assets).
+In production, `velojs start` sets `NODE_ENV=production` automatically and serves static files from `dist/client/`. Assets carry content hashes and are **public by design**, so the server answers an existing file **before the app's route table** — a page route, an action endpoint or a route middleware (an auth guard redirecting to `/login`, for instance) never sees an asset path. Only the framework's own infra middlewares (trailing-slash normalization, the logger) run ahead of the asset lookup. Paths that are not files fall through to the app routes as usual (SSR pages, actions, streams, sockets, endpoints, the catch-all 404). HTML responses are served with `Cache-Control: no-cache` so browsers always fetch the latest HTML (which references the current hashed assets).
 
 ### Static assets on CDN
 
@@ -2035,7 +2038,7 @@ Set `STATIC_BASE_URL` to serve static assets from a CDN or S3 bucket:
 STATIC_BASE_URL=https://cdn.example.com/assets node dist/server.js
 ```
 
-The `<Scripts />` component and CSS `url()` references will use this prefix automatically.
+The `<Scripts />` component and CSS `url()` references will use this prefix automatically. When `STATIC_BASE_URL` starts with `http`, the server mounts no local static at all — every path is an app path, and the assets' public-by-design semantics come from the bucket/CDN.
 
 ---
 

package/agent/AGENTS.md

@@ -108,6 +108,8 @@ import { emit } from "@mauroandre/velojs/server";
 await emit("teamExpenses", { user: { teamId: 7 } });
 ```
 
+An `emit` is addressed to the partition's group — clients outside the group never hear about it (not a broadcast the client filters); partitions exist by duty (authorization) or by interest (relevance).
+
 Or, when the producer already holds the new value, it pushes it as a typed slice:
 
 ```ts

package/agent/skills/velojs-live-loader/SKILL.md

@@ -5,7 +5,7 @@ description: "Keep a loader value faithful to server state in real time: declare
 
 # Live loader
 
-A `loader` fetches a page's data once per request and re-fetches it on SPA navigation. That is everything a page needs when its data changes because of the user themselves — or not at all. A **value that must track server state over time** (a team total another person's request changes, data a background scheduler mutates) needs the loader to stay faithful. That is the live loader: the same `loader`, the same `useLoader()` read, plus a sibling `channels` export.
+A `loader` fetches a page's data once per request and re-fetches it on SPA navigation. That is everything a page needs when its data changes because of the user themselves — or not at all. A **value that must track server state over time** (a team total another person's request changes, data a background scheduler mutates) needs the loader to stay faithful. That is the live loader: the same `loader`, the same `useLoader()` read, plus a sibling `channels` export. The one-sentence model: the live loader keeps a page's state replica faithful to the server — the first payload arrives through the usual path (SSR, `__PAGE_DATA__`, the `?_data=1` refetch), and from then on every change is **addressed**, by the app's own rules, to the group of clients it concerns, **by duty or by interest**, each one receiving the state computed for its own scope.
 
 ## The three declarations
 
@@ -284,6 +284,8 @@ On a page with no `channels` the fields exist, the record is empty and the aggre
 
 ## The partition contract
 
+**Addressed, not broadcast.** A partition is not a filter applied after a broadcast. The `emit` is addressed: the runtime resolves the partition key and writes only to the connections of that group — a client outside the group never hears about the change, not even a byte. Two reasons make a partition matter, and they compose: **by duty** (authorization — the data belongs to that team, that family, that project; others must not see it) and **by interest** (relevance — the tab watching project 9 has nothing to wake up for when project 7 changes). The same `scope` serves both; the app decides which, or both at once.
+
 On subscribe the `scope` receives `{ user, params }`. `user` is whatever a middleware materialized under the house key `"user"` — the same key the stream/socket channel resolvers use; a middleware that materializes the principal somewhere else should set it in `"user"` too:
 
 ```ts

package/agent/skills/velojs-production-deploy/SKILL.md

@@ -25,6 +25,12 @@ npx velojs start
 
 This automatically sets `NODE_ENV=production` and starts the server. In production mode, VeloJS serves static files from `dist/client/` and handles SSR for all page routes.
 
+### Assets are served before the app routes
+
+`dist/client` assets are **public by design**: their names carry content hashes and their URLs are fetched by the browser with no session and no route logic attached. The server answers an existing file from `dist/client` **before the app's route table** — so a page route, an action endpoint or a route middleware (an auth guard redirecting to `/login`, for instance) never sees an asset path. Only the framework's own infra middlewares (trailing-slash normalization and the logger) run ahead of the asset lookup.
+
+Paths that are not files keep the normal flow: SSR pages, actions, streams, sockets, endpoints and the app's catch-all 404. A top-level dynamic route (`/:mes`) therefore means only app paths — `/client.<hash>.js` is served as a file, while `/2026-10` goes through the route's middlewares and loaders.
+
 ## Dockerfile
 
 Here's a production-ready Dockerfile with multi-stage build:
@@ -124,7 +130,7 @@ If you want to serve static assets (JS, CSS, images) from a CDN or S3 bucket ins
 STATIC_BASE_URL=https://cdn.example.com/assets npx velojs start
 ```
 
-The `<Scripts />` component and CSS `url()` references will automatically use this prefix. The server will skip serving static files when `STATIC_BASE_URL` points to an external URL.
+The `<Scripts />` component and CSS `url()` references will automatically use this prefix. When `STATIC_BASE_URL` starts with `http`, the server mounts no local static at all: every path is an app path, and the public-by-design semantics come from the bucket/CDN.
 
 ## Included dependencies
 

package/dist/server.js

@@ -1,38 +1,38 @@
 import { jsx as w } from "preact/jsx-runtime";
-import { Hono as C } from "hono";
-import { logger as E } from "hono/logger";
+import { Hono as j } from "hono";
+import { logger as q } from "hono/logger";
 import { trimTrailingSlash as T } from "hono/trailing-slash";
 import { render as A } from "preact-render-to-string";
 import { Router as $ } from "wouter-preact";
 import { AsyncLocalStorage as k } from "node:async_hooks";
 import { getAppContext as _ } from "./app-context.js";
-import { flushPendingStreamRoutes as D, registerStreamHandler as I } from "./events.js";
-import { registerSocketRoutes as N, injectWebSocketServer as S } from "./sockets.js";
-import { inspectChannels as O, registerChannelRoute as H } from "./channels.js";
-import { emit as le, registerChannels as de } from "./channels.js";
+import { flushPendingStreamRoutes as D, registerStreamHandler as N } from "./events.js";
+import { registerSocketRoutes as O, injectWebSocketServer as S } from "./sockets.js";
+import { inspectChannels as I, registerChannelRoute as H } from "./channels.js";
+import { emit as de, registerChannels as ue } from "./channels.js";
 const P = new k();
 globalThis.__veloServerData = P;
 let g = null;
-function re(e) {
+function se(e) {
   if (g) {
     e(g);
     return;
   }
   _().serverCallbacks.push(e);
 }
-function b(e) {
+function C(e) {
   g = e;
   const t = _();
   for (const a of t.serverCallbacks) a(e);
   t.serverCallbacks.length = 0;
 }
-function x(e) {
+function V(e) {
   g === e && (g = null);
 }
-function se(e) {
+function ae(e) {
   _().pendingRoutes.push(e);
 }
-const G = (e) => JSON.stringify(e).replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029"), V = (e, t, a, r) => {
+const x = (e) => JSON.stringify(e).replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029"), G = (e, t, a, r) => {
   if (r && r !== 200 && e.status(r), e.req.query("_data") === "1") {
     const c = globalThis.__veloBuildHash || void 0, i = a ? { ...a, __buildHash: c } : { __buildHash: c };
     return e.json(i);
@@ -43,14 +43,14 @@ const G = (e) => JSON.stringify(e).replace(/</g, "\\u003c").replace(/>/g, "\\u00
   );
   if (e.header("Cache-Control", "no-cache"), !a)
     return e.html(n);
-  const s = `<script>window.__PAGE_DATA__=${G(a)}<\/script>`;
+  const s = `<script>window.__PAGE_DATA__=${x(a)}<\/script>`;
   return e.html(n.replace("</head>", () => `${s}</head>`));
-}, M = async (e, t) => {
+}, L = async (e, t) => {
   const a = t.req.param(), r = t.req.query(), o = { params: a, query: r, c: t }, n = await Promise.all(
     e.map(async (i) => {
       if (!i.loader) return null;
-      const f = await i.loader(o), l = i.metadata?.moduleId;
-      return l ? { moduleId: l, loaderData: f } : null;
+      const l = await i.loader(o), d = i.metadata?.moduleId;
+      return d ? { moduleId: d, loaderData: l } : null;
     })
   );
   let s;
@@ -71,7 +71,7 @@ const G = (e) => JSON.stringify(e).replace(/</g, "\\u003c").replace(/>/g, "\\u00
     data: c,
     shortCircuit: s
   };
-}, W = (e) => {
+}, M = (e) => {
   if (e.length === 0) return null;
   const t = e.filter(Boolean);
   if (t.length === 0) return null;
@@ -104,27 +104,27 @@ const G = (e) => JSON.stringify(e).replace(/</g, "\\u003c").replace(/>/g, "\\u00
         s
       );
     else if (o.module) {
-      const c = o.path === "*", i = o.statusCode ?? (c ? 404 : void 0), f = o.module.metadata?.fullPath;
-      if (!f && !c) {
+      const c = o.path === "*", i = o.statusCode ?? (c ? 404 : void 0), l = o.module.metadata?.fullPath;
+      if (!l && !c) {
         console.warn(
           `Module ${o.module.metadata?.moduleId} has no fullPath`
         );
         continue;
       }
-      const l = async (d) => {
-        const { components: u, data: h, shortCircuit: m } = await M(n, d);
-        if (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 d = async (f) => {
+        const { components: u, data: m, shortCircuit: h } = await L(n, f);
+        if (h) {
+          const v = h.headers.get("Location");
+          return f.req.query("_data") === "1" && v && h.status >= 300 && h.status < 400 ? f.json({ __redirect: v }) : h;
         }
-        const p = W(u);
-        return V(d, p, h, i);
+        const p = M(u);
+        return G(f, p, m, i);
       };
-      c ? e.notFound(l) : s.length > 0 ? e.on(["GET"], [f], ...s, l) : e.on(["GET"], [f], l);
+      c ? e.notFound(d) : s.length > 0 ? e.on(["GET"], [l], ...s, d) : e.on(["GET"], [l], d);
     } else
       continue;
   }
-}, R = (e, t, a = []) => {
+}, E = (e, t, a = []) => {
   for (const r of t) {
     const o = r.module?.metadata?.moduleId, n = [
       ...a,
@@ -135,22 +135,22 @@ const G = (e) => JSON.stringify(e).replace(/</g, "\\u003c").replace(/>/g, "\\u00
         (c) => c.startsWith("action_")
       );
       for (const c of s) {
-        const i = c.replace("action_", ""), f = r.module[c];
-        if (typeof f == "function") {
-          const l = `/_action/${o}/${i}`, d = async (u) => {
-            let h = {};
+        const i = c.replace("action_", ""), l = r.module[c];
+        if (typeof l == "function") {
+          const d = `/_action/${o}/${i}`, f = async (u) => {
+            let m = {};
             try {
-              h = await u.req.json();
+              m = await u.req.json();
             } catch {
             }
-            const m = {
-              body: h,
+            const h = {
+              body: m,
               params: u.req.param(),
               query: u.req.query(),
               c: u
             };
             try {
-              const p = await f(m);
+              const p = await l(h);
               return u.json(p ?? { ok: !0 });
             } catch (p) {
               const v = p instanceof Error ? p.message : "Action failed";
@@ -159,16 +159,16 @@ const G = (e) => JSON.stringify(e).replace(/</g, "\\u003c").replace(/>/g, "\\u00
           };
           n.length > 0 ? e.on(
             ["POST"],
-            [l],
+            [d],
             ...n,
-            d
-          ) : e.on(["POST"], [l], d);
+            f
+          ) : e.on(["POST"], [d], f);
         }
       }
     }
-    r.children && R(e, r.children, n);
+    r.children && E(e, r.children, n);
   }
-}, K = async (e, t, a = []) => {
+}, W = async (e, t, a = []) => {
   const r = (o, n) => {
     for (const s of o) {
       const c = s.module?.metadata?.moduleId, i = [
@@ -176,16 +176,16 @@ const G = (e) => JSON.stringify(e).replace(/</g, "\\u003c").replace(/>/g, "\\u00
         ...s.middlewares || []
       ];
       if (s.module && c) {
-        const f = Object.keys(s.module).filter(
-          (l) => l.startsWith("stream_")
+        const l = Object.keys(s.module).filter(
+          (d) => d.startsWith("stream_")
         );
-        for (const l of f) {
-          const d = l.replace("stream_", ""), u = s.module[l];
+        for (const d of l) {
+          const f = d.replace("stream_", ""), u = s.module[d];
           if (u?.__isVeloEventStream) {
-            const h = `/_event/${c}/${d}`;
-            u.__path = h, I(
+            const m = `/_event/${c}/${f}`;
+            u.__path = m, N(
               e,
-              h,
+              m,
               u,
               i
             );
@@ -196,7 +196,7 @@ const G = (e) => JSON.stringify(e).replace(/</g, "\\u003c").replace(/>/g, "\\u00
     }
   };
   r(t, a);
-}, j = (e, t, a = []) => {
+}, b = (e, t, a = []) => {
   for (const r of t) {
     const o = r.module?.metadata?.moduleId, n = [
       ...a,
@@ -215,9 +215,9 @@ const G = (e) => JSON.stringify(e).replace(/</g, "\\u003c").replace(/>/g, "\\u00
             n
           );
     }
-    r.children && j(e, r.children, n);
+    r.children && b(e, r.children, n);
   }
-}, L = (e, t) => t ? t.startsWith("/") ? e + t : e ? e + "/" + t : "/" + t : e || "", B = (e) => {
+}, K = (e, t) => t ? t.startsWith("/") ? e + t : e ? e + "/" + t : "/" + t : e || "", B = (e) => {
   const t = /* @__PURE__ */ new Set(), a = (r) => {
     for (const o of r) {
       if (o.module && !o.children) {
@@ -228,33 +228,33 @@ const G = (e) => JSON.stringify(e).replace(/</g, "\\u003c").replace(/>/g, "\\u00
     }
   };
   return a(e), t;
-}, q = (e, t, a, r = "", o = []) => {
+}, R = (e, t, a, r = "", o = []) => {
   for (const n of t) {
-    const s = L(r, n.path), c = [
+    const s = K(r, n.path), c = [
       ...o,
       ...n.middlewares || []
-    ], i = !!n.handler, f = !!n.method;
-    if (i && !f ? console.warn(
+    ], i = !!n.handler, l = !!n.method;
+    if (i && !l ? console.warn(
       `[velojs] invalid route at "${s || "/"}" — "handler" set without "method"; endpoint skipped`
-    ) : f && !i ? console.warn(
+    ) : l && !i ? console.warn(
       `[velojs] invalid route at "${s || "/"}" — "method" set without "handler"; endpoint skipped`
     ) : i && n.module ? console.warn(
       `[velojs] ambiguous route at "${s || "/"}" — both "module" and "handler" set; endpoint ignored, page kept`
     ) : i && n.isRoot && console.warn(
       `[velojs] "isRoot" has no effect on endpoint at "${s || "/"}"; ignored`
-    ), i && f && !n.module) {
-      const d = n.method;
-      d === "GET" && a.has(s) && console.warn(
+    ), i && l && !n.module) {
+      const f = n.method;
+      f === "GET" && a.has(s) && console.warn(
         `[velojs] path "${s}" has both a page GET and an endpoint GET; the page wins and the endpoint is unreachable. Consider renaming one.`
       );
-      const u = n.handler, h = async (m) => await u({
-        c: m,
-        params: m.req.param(),
-        query: m.req.query()
+      const u = n.handler, m = async (h) => await u({
+        c: h,
+        params: h.req.param(),
+        query: h.req.query()
       });
-      c.length > 0 ? e.on([d], [s], ...c, h) : e.on([d], [s], h);
+      c.length > 0 ? e.on([f], [s], ...c, m) : e.on([f], [s], m);
     }
-    n.children && q(
+    n.children && R(
       e,
       n.children,
       a,
@@ -263,48 +263,50 @@ const G = (e) => JSON.stringify(e).replace(/</g, "\\u003c").replace(/>/g, "\\u00
     );
   }
 }, F = async (e) => {
-  const t = new C();
-  t.use(T()), process.env.NODE_ENV !== "production" && t.use("*", E());
+  if (process.env.NODE_ENV !== "production" || process.env.VELO_STATIC || (process.env.STATIC_BASE_URL || "").startsWith("http")) return;
+  const { serveStatic: a } = await import("@hono/node-server/serve-static"), { join: r } = await import("node:path");
+  e.use("/*", a({ root: r(process.cwd(), "dist/client") }));
+}, U = async (e) => {
+  const t = new j();
+  t.use(T()), process.env.NODE_ENV !== "production" && t.use("*", q()), await F(t);
   const r = _().pendingRoutes.splice(0);
   for (const n of r)
     await n(t);
-  y(t, e), R(t, e), await K(t, e), j(t, e), process.env.NODE_ENV !== "production" && t.get("/_channel-inspect", (n) => n.json(O()));
+  y(t, e), E(t, e), await W(t, e), b(t, e), process.env.NODE_ENV !== "production" && t.get("/_channel-inspect", (n) => n.json(I()));
   const o = B(e);
-  if (q(t, e, o), await N(t, e), D(t), process.env.NODE_ENV !== "production" && !g) {
+  if (R(t, e, o), await O(t, e), D(t), process.env.NODE_ENV !== "production" && !g) {
     const n = globalThis.__veloDevServer;
-    n && (b(n), await S(t, n));
+    n && (C(n), await S(t, n));
   }
   return t;
-}, ae = async (e) => {
-  const { routes: t } = e, a = Number(process.env.PORT) || e.port || 3e3, r = process.env.HOST || e.hostname || void 0, o = await F(t);
+}, ie = async (e) => {
+  const { routes: t } = e, a = Number(process.env.PORT) || e.port || 3e3, r = process.env.HOST || e.hostname || void 0, o = await U(t);
   if (process.env.NODE_ENV === "production" && !process.env.VELO_STATIC) {
-    const { serve: n } = await import("@hono/node-server"), { serveStatic: s } = await import("@hono/node-server/serve-static"), { join: c } = await import("node:path"), i = c(process.cwd(), "dist/client");
-    (process.env.STATIC_BASE_URL || "").startsWith("http") || o.use("/*", s({ root: i }));
-    const l = n({ fetch: o.fetch, port: a, ...r ? { hostname: r } : {} });
-    l.listening || await new Promise((u) => l.once("listening", u));
-    const d = l.address();
-    if (d && typeof d == "object") {
-      const h = d.address === "::" || d.address === "0.0.0.0" ? "0.0.0.0 (all interfaces)" : d.address;
-      console.log(`Server running on ${h}:${d.port}`);
+    const { serve: n } = await import("@hono/node-server"), s = n({ fetch: o.fetch, port: a, ...r ? { hostname: r } : {} });
+    s.listening || await new Promise((i) => s.once("listening", i));
+    const c = s.address();
+    if (c && typeof c == "object") {
+      const l = c.address === "::" || c.address === "0.0.0.0" ? "0.0.0.0 (all interfaces)" : c.address;
+      console.log(`Server running on ${l}:${c.port}`);
     } else
       console.log(`Server running on port ${a}`);
-    await S(o, l), b(l), l.once("close", () => {
-      x(l);
+    await S(o, s), C(s), s.once("close", () => {
+      V(s);
     });
   }
   return o;
 };
 export {
-  se as addRoutes,
-  x as clearActiveServer,
-  F as createApp,
-  F as default,
-  le as emit,
-  b as flushServerCallbacks,
-  O as inspectChannels,
-  G as jsonForScript,
-  re as onServer,
-  de as registerChannels,
+  ae as addRoutes,
+  V as clearActiveServer,
+  U as createApp,
+  U as default,
+  de as emit,
+  C as flushServerCallbacks,
+  I as inspectChannels,
+  x as jsonForScript,
+  se as onServer,
+  ue as registerChannels,
   P as serverDataStorage,
-  ae as startServer
+  ie as startServer
 };

package/package.json

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