@mauroandre/velojs 0.0.54 → 0.0.56

package/README.md

@@ -159,6 +159,8 @@ export const Component = () => {
 npm run dev     # http://localhost:3000
 ```
 
+To expose the dev server beyond loopback — a VPS behind a reverse proxy, an app reached by hostname — set `HOST=0.0.0.0`, in the shell or in the project's `.env`; no `--host` flag by hand. The security trade-off: a broad bind in dev (`0.0.0.0`, `::`, or `--host` with no value) turns Vite's Host check off, so a request whose `Host` header carries that domain is served instead of 403'd — the DNS-rebinding protection you get on loopback is consciously given up. Stay on localhost unless you are behind a proxy; a `server.allowedHosts` declared in `vite.config.ts` still pins the allowed list.
+
 ### Configuration
 
 ```typescript
@@ -167,6 +169,7 @@ veloPlugin({
     routesFile: "routes.tsx",   // default
     serverInit: "server.tsx",   // default
     clientInit: "client.tsx",   // default
+    hostname: "127.0.0.1",      // bind interface, dev and production (the HOST env wins)
 });
 ```
 
@@ -458,6 +461,317 @@ SPA navigation:
 
 ---
 
+## Live Loader
+
+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`.
+
+```tsx
+// app/expenses/Expenses.tsx
+export const loader = async ({ c }: LoaderArgs) => {
+    const user = c.get("user");
+    return {
+        teamTotal: await expensesService.teamTotal(user.teamId),
+        expenses: await expensesService.byTeam(user.teamId),
+    };
+};
+export const channels = ["teamExpenses"];
+
+export const Component = () => {
+    const { data, freshness } = useLoader();
+    return <h2 class={freshness.value}>Team: ${data.value?.teamTotal}</h2>;
+};
+```
+
+```ts
+// app/channels.ts — the app's channel map: name → partition resolver
+export const channels = {
+    teamExpenses: {
+        // ctx: on subscribe, the principal materialized in c.get("user");
+        // on emit, the object the emitter passed. Returns the partition key.
+        scope: (ctx) => `team:${ctx.teamId}`,
+    },
+};
+```
+
+```ts
+// anywhere server-side: an action, server.tsx, a scheduler, a webhook
+import { emit } from "@mauroandre/velojs/server";
+
+await emit("teamExpenses", { teamId: 7 });
+```
+
+### What happens
+
+- The framework derives one internal SSE route per declared channel —
+  `GET /_channel/{moduleId}/{channel}`, the same family as `/_action` and
+  `/_event` — inheriting the `middlewares` of the module's route node.
+- After hydration the client opens one connection per (module, channel) of the
+  rendered hierarchy (layout and page alike) and closes it on unmount. A
+  channel declared by both a layout and a page produces one connection per
+  module, each feeding its own module's data; a single `emit` reaches both.
+- Every new connection immediately receives the **current state**, computed by
+  re-executing the loader with that connection's own principal — so the pane
+  never shows the SSR value while the server has already moved on.
+- `emit(channel, ctx)` resolves the partition with the same `scope`, finds the
+  connections in that partition and pushes a fresh snapshot to each one — its
+  loader re-executed with its own principal. Connections of other partitions
+  receive nothing.
+- The snapshot **replaces** the module's loader data; the component re-renders
+  by itself. `useLoader()` and `Loader()` also expose `freshness` — `"live"`,
+  `"stale"` (connection closed/reconnecting/silent), `"error"` (the last
+  re-execution failed) — aggregated per page, plus `freshnessByChannel`, the
+  same states keyed by each of the module's channel names. They are data for
+  CSS to react to.
+
+### Two ways to emit
+
+**Invalidation** — `emit(channel, ctx)` says *this partition changed*, without
+knowing the shape of the data: the runtime re-executes the loader per connection
+and pushes the snapshot. Use it when only the server knows the new value (a
+background job, another request).
+
+**Slice** — `emit(module, channel, ctx, slice)` says *here is the new value*: the
+producer already holds it, so it travels as-is to the connections of that
+(module, channel) pair in the partition, and **no loader runs**. The slice is
+typed as a `Partial` of what that module's loader returns, so `tsc` rejects an
+unknown key or a wrong value type.
+
+```ts
+import { emit } from "@mauroandre/velojs/server";
+import * as Expenses from "../app/expenses/Expenses.js";
+
+// invalidation: the runtime re-executes Expenses.loader per connection
+await emit("teamExpenses", { teamId: 7 });
+
+// slice: the value is already in hand — delivered as-is, no re-execution
+await emit(Expenses, "teamExpenses", { teamId: 7 }, { teamTotal: 880 });
+```
+
+Why the module, and not just the channel name? Because the same channel can be
+declared by a layout **and** by a page, each with its own loader and its own
+`Data` — a slice is the shape of exactly one of them, and it reaches only that
+module's connections. `emit(channel, ctx)` keeps reaching every module of the
+channel.
+
+### The merge contract
+
+- **Snapshot replaces; slice merges.** A snapshot (connect or invalidation) is
+the whole value of the module's data; a slice applies a **shallow** merge by
+key on top of the current value.
+- The key sent is replaced by the **whole value** sent — lists travel whole
+  inside their key; there is no list diff. Keys not sent stay intact.
+- **Removal is explicit**: removing an item is re-sending the key with the new
+  whole list (without the item). An absent key never means "remove".
+- The merge happens **on arrival**, never at render: slices that land in the
+  same frame are applied together before the next render — none is lost — and
+  for the same key the last one in arrival order wins. A malformed payload keeps
+  the previous value.
+- The runtime merges blindly (it is JavaScript); shape safety comes from the
+  emit typing. A key that does not exist in the loader's `Data` only gets in
+  through a cast, and that is a usage error.
+
+### Bursts, log and revalidation
+
+- **Coalescing.** Invalidation emits are folded per (channel, partition): the
+  first opens a window, the emits inside it join, and closing the window fires
+  **one** re-execution round per connection — no invalidation is lost. The
+  default window is `50ms`; `registerChannels(map, { coalesceMs: 0 })` turns it
+  off (immediate), and a slice never waits for it (a slice is pushed directly).
+
+  The window decides what `await emit(…)` waits for: with it off (`0`, and the
+  test toolkit's default) the await resolves after the round was delivered;
+  with it open it resolves as soon as the gesture is registered — the log line
+  is out, the delivery comes later. Never assert a screen update right after
+  `await emit(…)` under the default window: await the arrival (`next()` /
+  `nextEvent()`) or wait for the effect.
+- **Emit log.** Every `emit`, in either mode, writes one `console.log` line at
+  the moment of the gesture:
+
+  ```
+  [velojs] emit kind=invalidate channel="teamExpenses" partition="team:7" connections=2 at=2026-09-30T12:00:00.000Z
+  ```
+
+  `connections` is the size of the group at that instant — before coalescing and
+  before revalidation — and the consolidated delivery writes no second line. An
+  emit whose `scope` resolves to nothing logs `partition=null connections=0`:
+  reaching nobody is exactly what the log is for.
+  `registerChannels(map, { logEmits: false })` silences it. In tests,
+  `createTestApp` registers with the window off and takes the same options in
+  `channelOptions`.
+- **Partition revalidation.** Before delivering anything, the runtime re-derives
+  each connection's partition by running the `scope` again with the principal
+  captured at subscribe. A connection whose partition moved — or whose scope now
+  returns `null` — is removed from the group and closed: the client sees the
+  connection closed (`freshness` goes `"stale"`) and receives none of that
+  emit's data. A `scope` that **throws** on re-derivation is treated the same
+  way — fail-closed, with the failure logged naming the channel — so a scope
+  that does I/O must handle its own failures. Only the partition is revalidated;
+  session expiry stays with the normal request pipeline.
+
+### Transport: heartbeat, idle timeout and the proxy
+
+An SSE connection crosses infrastructure that was not built for it — proxies,
+load balancers, browsers with sleeping tabs. The channel answer is built for
+that traffic, and its transport has exactly two clocks:
+
+- **Heartbeat** — an SSE comment (`: ping`) written through the write chain
+every `heartbeatMs`. It keeps proxies and browsers from buffering or closing an
+idle stream, and it is pure transport: it generates no event in the client and
+does not count as a delivery — it touches neither freshness nor idle. The
+default is `20000` (20s), the same `DEFAULT_HEARTBEAT_MS` the `stream_*` SSE
+surface uses — one transport ruler in the house. `0` disables it.
+- **Idle timeout** — a connection with **no deliveries** (snapshot or slice) for
+`idleMs` is closed by the server. The heartbeat does not reset it: idle is
+about data, heartbeat is transport. A live but quiet page cycles by design —
+close, `EventSource` reconnects by itself, snapshot on connect repairs the
+state — and an abandoned page's resources are freed for good. The default is
+`300000` (5 min) in any registration without options; `0` disables it.
+
+```ts
+// app/channels.ts registration with explicit windows
+registerChannels(channels, { idleMs: 60000, heartbeatMs: 15000 });
+```
+
+The answer also carries `Cache-Control: no-store`: a proxy or the browser must
+never serve a cached channel snapshot — a stale snapshot is exactly the illusion
+the live loader exists to kill.
+
+**Behind a reverse proxy (the house recipe, Caddy).** SSE needs the proxy to
+flush immediately and never buffer the response, or the page goes silent even
+with everything alive. In the Caddyfile, the reverse_proxy for the app needs
+`flush_interval -1` (flush as soon as data arrives — a negative value means
+"immediately", which is what SSE requires; a positive interval would batch
+chunks and delay every snapshot). Caddy passes the request through with
+streaming by default and closes dead upstreams on its own probes — the
+heartbeat then does its part at 20s, and the idle timeout closes what nobody is
+reading anymore. If you put another proxy in front (nginx, a cloud LB), the
+same two rules apply: no response buffering, and `X-Accel-Buffering: no` for
+nginx or the equivalent for the LB.
+
+### Inspecting the live channels
+
+When the incident happens, the server answers "what is alive?":
+
+```ts
+// anywhere server-side (an action, a guarded endpoint of your own)
+import { inspectChannels } from "@mauroandre/velojs/server";
+
+const report = inspectChannels();
+// {
+//   channels: [{
+//     channel: "teamExpenses",
+//     groups: [
+//       { moduleId: "expenses/Layout", partition: "team:7",
+//         connections: 1, lastDeliveryAt: "2026-09-30T12:00:00.000Z" },
+//       { moduleId: "expenses/Expenses", partition: "team:7",
+//         connections: 1, lastDeliveryAt: "2026-09-30T12:00:01.104Z" },
+//     ],
+//     connections: 2,
+//   }],
+//   openCoalesceWindows: [],
+//   totalConnections: 2,
+// }
+```
+
+Per channel, the groups are identified by the pair (moduleId, partition key) —
+in the incident you know which page/module holds every connection — each with
+its connection count and the timestamp of the last delivery; the coalescing
+windows still open; the grand totals. `inspectChannels()` is always available:
+the app decides how (and with what guard) to expose it.
+
+In development there is a ready-made lens: `GET /_channel-inspect` answers the
+same JSON in the browser. It exists **only in dev** — the map of channels and
+partitions is internal information, and it never ships in a production build.
+
+### The partition contract
+
+On subscribe the `scope` receives `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"` too). Without an authenticated
+principal it receives `undefined`: a public channel ignores it (`() => "all"`),
+an authenticated one returns `null`, which denies the subscription with 403.
+The partition **never** derives from the query string or from any client input.
+
+### State or flow?
+
+Two questions decide, every time:
+
+| Question | Answer | Tool |
+|---|---|---|
+| Is this a **value** or a **sequence**? | value — "what is it now?", replacement | `loader` + `channels` |
+| | sequence — "what happened?", accumulation (chat, log, progress) | `stream_*` / `socket_*` |
+| Does the change come from **someone else** or from **me**? | someone else / a background job | `loader` + `channels` |
+| | me, through my own action | `refetch()` after the action |
+
+### Guards
+
+- `channels` in a module **without** a `loader`: explicit error in the dev
+  server and in the build ("nothing to synchronize").
+- A channel **without an entry** in `app/channels.ts`: explicit error in the dev
+  server and in the build, naming the channel.
+- `emit()` on a channel with no entry in the map: throws immediately, naming
+  the channel. `emit()` on a valid channel with no subscribers is a no-op.
+- `emit(module, channel, …)` on a module that does not declare that channel, or
+  that has no `loader`: throws immediately, naming both. A slice that is not an
+  object throws too.
+- `velojs build --static` with a module declaring `channels`: the channels are
+  **inert** (no server for SSE) — the client opens no connection, `freshness`
+  stays `"live"` and the build warns, naming the module.
+- A module outside the conventions (`.jsx`/`.js`, or outside `app/`) is the one
+  genuinely silent line: no transform, so the channel is simply inert.
+
+### Testing a live loader
+
+```ts
+import { createTestApp } from "@mauroandre/velojs/testing";
+import { emit } from "@mauroandre/velojs/server";
+import { channels } from "../app/channels.js";
+import * as Expenses from "../app/expenses/Expenses.js";
+
+const app = await createTestApp({
+    routes,
+    channels,
+    getSessionCookie: async ({ user }) => ({ session: await sign(user) }),
+});
+
+const sub = await app.as({ user: { teamId: 7 } }).channel(Expenses, "teamExpenses");
+await sub.next({ timeoutMs: 1000 });     // snapshot on connect
+await emit("teamExpenses", { teamId: 7 });
+const snapshot = await sub.next({ timeoutMs: 1000 });
+await emit(Expenses, "teamExpenses", { teamId: 7 }, { teamTotal: 880 });
+const slice = await sub.next({ timeoutMs: 1000 });
+```
+
+`next()` returns the payload exactly as it travelled (a whole snapshot or a raw
+slice); `nextEvent()` returns the same arrivals discriminated —
+`{ type: "snapshot" | "slice", data }`. The toolkit registers the channels with
+the coalescing window off, so `await emit(…)` is the delivery; a test that
+exercises the window passes it in `channelOptions` — a sibling of `channels`,
+which stays the map — and drives it with fake timers:
+
+```ts
+const app = await createTestApp({
+    routes,
+    channels,                                    // the map
+    channelOptions: { coalesceMs: 20 },          // the registration options
+    getSessionCookie,
+});
+```
+
+The same `channelOptions` accepts `idleMs` and `heartbeatMs` — both default to
+`0` in the toolkit (deterministic: no connection dies, no comment is written
+unless the test asks for it and advances fake timers through the window it
+meant). `inspectChannels()` is process-wide and sees the test app's real
+channels: subscribe, emit, inspect, close, inspect again — all without network.
+A test that exercises the idle timeout or the heartbeat arms the window
+explicitly and drives it with fake timers; never assert freshness (in either
+surface) without advancing the fake timers through the window.
+
+---
+
 ## Actions
 
 Server-side functions callable from the client via RPC.
@@ -1272,6 +1586,7 @@ Callbacks queue until the server starts. If called after startup, executes immed
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `PORT` | `3000` | Server port. Overrides the `port` set in `defineConfig` |
+| `HOST` | — | Bind interface, in dev and production. Overrides `defineConfig`'s `hostname`; in dev an explicit `--host`/`server.host` still wins |
 | `NODE_ENV` | — | Set automatically by `velojs start`. Enables static file serving |
 | `STATIC_BASE_URL` | `""` | CDN/bucket prefix for static assets |
 
@@ -1371,6 +1686,12 @@ const event = await sub.next({ timeoutMs: 2000 });
 const asAlice = app.as({ user: alice });
 await asAlice.subscribe(stream_progress, { channel: appId });
 
+// Live loader — open a channel with a principal, emit, await the next snapshot
+const live = await app.as({ user: { teamId: 7 } }).channel(Expenses, "teamExpenses");
+await live.next({ timeoutMs: 1000 });            // snapshot on connect
+await emit("teamExpenses", { teamId: 7 });
+const snapshot = await live.next({ timeoutMs: 1000 });
+
 await app.close();
 ```
 
@@ -1384,6 +1705,7 @@ await app.close();
 | `app.action(fn, opts)` | Invoke `action_*` by function reference |
 | `app.loader(fn, opts)` | Invoke `loader` and unwrap response data |
 | `app.subscribe(stream, opts)` | Subscribe to a stream; returns `TestSubscription` with `next/nextN/snapshot/close/closed` |
+| `app.channel(module, name, opts)` | Open a live-loader channel connection; snapshots and slices arrive through `next()` (raw) or `nextEvent()` (`{ type, data }`) |
 | `app.as({ user })` | Sub-client with cookies bound to a user |
 | `app.sessionCookies({ user })` | Build cookies via `getSessionCookie` |
 | `app.mockContext(opts)` | Escape hatch — partial Hono Context for direct invocation |
@@ -1419,11 +1741,11 @@ See [Testing docs](https://github.com/mauro-andre/velojs/blob/dev/site/docs/17-t
 | Import | Contents |
 |--------|----------|
 | `@mauroandre/velojs` | Types (`AppRoutes`, `ActionArgs`, `LoaderArgs`, `Metadata`, `EventStream`, `EventStreamConfig`, `EmitFn`, `EmitOptions`, `SourceFn`, `PerChannelSourceFn`, `ChannelResolver`), `Scripts`, `Link`, `createEventStream`, `poll`, `defineConfig` |
-| `@mauroandre/velojs/server` | `startServer`, `createApp`, `addRoutes`, `onServer`, `serverDataStorage` |
+| `@mauroandre/velojs/server` | `startServer`, `createApp`, `addRoutes`, `onServer`, `serverDataStorage`, `emit`, `registerChannels`, `ChannelDefinition`, `ChannelMap`, `ChannelRegistryOptions` |
 | `@mauroandre/velojs/client` | `startClient` |
-| `@mauroandre/velojs/hooks` | `Loader`, `useLoader`, `useEventStream`, `useParams`, `useQuery`, `useNavigate`, `usePathname`, `touch` |
+| `@mauroandre/velojs/hooks` | `Loader`, `useLoader`, `useEventStream`, `useParams`, `useQuery`, `useNavigate`, `usePathname`, `touch`, `Freshness` |
 | `@mauroandre/velojs/events` | `createEventStream`, `poll`, `EventStream`, `EventStreamConfig`, `EmitFn`, `EmitOptions`, `SourceFn`, `PerChannelSourceFn`, `ChannelResolver` (also re-exported from root) |
-| `@mauroandre/velojs/testing` | `createTestApp`, `TestApp`, `TestResponse`, `TestSubscription`, `CreateTestAppOptions`, `MockContextOptions` |
+| `@mauroandre/velojs/testing` | `createTestApp`, `TestApp`, `TestResponse`, `TestSubscription`, `TestChannelSubscription`, `ChannelEvent`, `CreateTestAppOptions`, `MockContextOptions` |
 | `@mauroandre/velojs/cookie` | `getCookie`, `setCookie`, `deleteCookie`, `getSignedCookie`, `setSignedCookie` |
 | `@mauroandre/velojs/factory` | `createMiddleware`, `createFactory` |
 | `@mauroandre/velojs/vite` | `veloPlugin` |
@@ -1456,6 +1778,7 @@ interface Metadata {
 interface RouteModule {
     Component: ComponentType<any>;
     loader?: (args: LoaderArgs) => Promise<any>;
+    channels?: readonly string[];   // live loader: channel names kept fresh
     metadata?: Metadata;
     [key: `action_${string}`]: (args: ActionArgs) => Promise<any>;
 }
@@ -1475,6 +1798,8 @@ interface VeloConfig {
     routesFile?: string;     // default: "routes.tsx"
     serverInit?: string;     // default: "server.tsx"
     clientInit?: string;     // default: "client.tsx"
+    port?: number;           // default: 3000; the PORT env wins
+    hostname?: string;       // bind interface, dev and production; the HOST env wins
 }
 ```
 
@@ -1529,6 +1854,10 @@ export const staticPaths = async () => {
 
 Routes without `staticPaths` are skipped with a warning.
 
+### Live loader in a static build
+
+A module that declares `channels` keeps rendering, but its channels are **inert** there: there is no server to speak SSE, so the client opens no connection, `freshness` stays `"live"` and the build warns, naming the module. Static output has no live data by construction.
+
 ### Deploying
 
 The `dist/` folder is self-contained. Deploy to any static hosting (Nginx, Cloudflare Pages, S3, etc.). No server required.

package/agent/AGENTS.md

@@ -34,6 +34,7 @@ hard constraints, not style.
 | `useParams()` / `useQuery()` / `usePathname()` inside a `loader` | the loader's own args: `async ({ params, query, c }) => {}` | the async context wraps only rendering; loaders run **before** it → returns `{}` / `"/"` |
 | `c.req.param(...)` or `params.x` inside `action_*`, `stream_*`, `socket_*` | actions: read it from `body`. streams/sockets: send `?channel=` from the client and read `query.channel` | these register at **static** paths (`/_action/{moduleId}/{name}`, `/_event/…`, `/_socket/…`) — the page's `:params` are not in scope → always `{}` / `undefined` |
 | a page in `.jsx` / `.js`, or any page outside `appDirectory` | `.tsx` inside `app/` | **zero transforms**: no metadata, no stubs, loader ships to the client |
+| `export const channels = [...]` in a `.jsx` / `.js` page, or any page outside `appDirectory` | `.tsx` inside `app/` | **zero transforms**: the channel guards never run, so the channel is inert — no route, no connection, no error |
 | a root layout that doesn't render a literal `<head>` | `isRoot` component renders `<html><head>…</head><body>{children}</body></html>` | `__PAGE_DATA__` is injected by replacing `</head>` → **every loader hydrates `null`** and refetches |
 
 Never pass a module id to `useLoader()` / `Loader()` yourself — the plugin injects it.
@@ -63,6 +64,152 @@ An entry refreshes on navigation when the params **its own route declares** chan
 (`/x/:id`). A query string is not declared in `routes.tsx`, so nothing infers it — use
 `useLoader([query.tab])` when data depends on one.
 
+## Keeping a page value faithful: `loader` + `channels`
+
+The loader has two faces. The common one fetches once per request (SSR) and
+re-fetches on SPA navigation — that is all a page needs when its data changes
+because of the user themselves or not at all. When a value must **track server
+state over time** (a team's total updated by another person's request, a
+background scheduler mutating data), declare channels next to the loader:
+
+```tsx
+// app/expenses/Expenses.tsx
+export const loader = async ({ c }: LoaderArgs) => {
+    const user = c.get("user");
+    return { teamTotal: await expensesService.teamTotal(user.teamId) };
+};
+export const channels = ["teamExpenses"];
+
+export const Component = () => {
+    const { data, freshness } = useLoader();
+    return <h2 class={freshness.value}>Team: ${data.value?.teamTotal}</h2>;
+};
+```
+
+And declare the partition of each channel once, in `app/channels.ts`:
+
+```ts
+// app/channels.ts — the app's channel map: name → partition resolver
+export const channels = {
+    teamExpenses: {
+        // ctx: on subscribe, the principal materialized in c.get("user");
+        // on emit, the object the emitter passed. Returns the partition key.
+        scope: (ctx) => `team:${ctx.teamId}`,
+    },
+};
+```
+
+Any server-side code signals that the partition changed:
+
+```ts
+import { emit } from "@mauroandre/velojs/server";
+await emit("teamExpenses", { teamId: 7 });
+```
+
+Or, when the producer already holds the new value, it pushes it as a typed slice:
+
+```ts
+import * as Expenses from "../app/expenses/Expenses.js";
+await emit(Expenses, "teamExpenses", { teamId: 7 }, { teamTotal: 880 });
+```
+
+The framework derives `GET /_channel/{moduleId}/{channel}` (same family as
+`/_action` and `/_event`), inheriting the route node's `middlewares`; after
+hydration the client opens one connection per (module, channel) of the rendered
+hierarchy and closes it on unmount. Every new connection receives the **current
+state** (the loader re-executed with that connection's own principal), and every
+`emit` re-executes the loader per connection in the emitting partition, pushing
+a snapshot that replaces the module's data. The component re-renders on its own —
+the page has no code for any of it.
+
+### Two ways to emit — invalidation or the value itself
+
+| Mode | Call | What the runtime does |
+|---|---|---|
+| Invalidation | `emit(channel, ctx)` | Re-executes the loader **per connection** of the partition and pushes a snapshot. The producer does not know the shape of the data |
+| Slice | `emit(module, channel, ctx, slice)` | Pushes the payload as-is to the connections of that (module, channel) pair in the partition — **no loader runs** |
+
+Use invalidation when only the server knows the new value (a background job, a
+request from another user). Use the slice when the producer already has it — a
+webhook that arrived with the payload, a job that just computed the total.
+
+The slice is typed `Partial<Awaited<ReturnType<typeof Module.loader>>>`: an
+unknown key or a wrong value type is a `tsc` error, never `any`. The module is
+part of the address because one channel can be declared by modules with
+different `Data` (a layout and a page): a slice is the shape of exactly **one**
+of them, and it reaches only that module's connections. The invalidation mode by
+name keeps reaching every module of the channel.
+
+### The merge contract — snapshot replaces, slice merges
+
+- A snapshot (connect or invalidation) is the whole value: it **replaces** the module's data, gone keys included.
+- A slice applies a **shallow** merge by key: the key sent is replaced by the **whole** value sent (a list travels whole inside its key); keys not sent stay intact.
+- **Removal is explicit**: removing an item is re-sending the key with the new whole list (without the item). An absent key never means "remove".
+- The merge happens **on arrival**, never at render: slices that land in the same frame are applied together before the next render — none is lost — and for the same key the last one in arrival order wins. A malformed payload keeps the previous value.
+- No deep patch and no list diff: the semantics stop at one level, by design. The runtime merges blindly (it is JavaScript) — shape safety comes from the emit typing. A key that does not exist in the `Data` only gets in through a cast: a usage error, documented, not a silent failure.
+
+### Bursts, log and revalidation
+
+- **Coalescing.** Invalidation emits fold per (channel, partition): the first opens a window, the emits inside it join it (the deadline does not move), and closing the window fires **one** re-execution round per connection — no invalidation is lost. Default `50ms` in any registration without options; `registerChannels(map, { coalesceMs: 0 })` disables it (immediate). A slice never waits for a window: it is pushed directly.
+  **The window changes what `await emit(…)` means.** With the window off (`0`, and the test toolkit's default) the await resolves after the round was delivered; with a window open it resolves as soon as the gesture is registered — the log line is already out, the delivery comes later. Never assert a screen update right after `await emit(…)` under the default window: assert the arrival (`next()`/`nextEvent()`) or wait for the effect.
+- **Emit log.** Every `emit`, in either mode, writes one `console.log` line at the moment of the gesture: `channel`, `partition`, `kind` (`invalidate`/`slice`), `connections` (the size of the group at that instant — before coalescing and before revalidation) and a timestamp. The consolidated delivery writes no second line; an emit whose `scope` resolves to nothing logs `partition=null connections=0`. `registerChannels(map, { logEmits: false })` silences it; `createTestApp` registers with window `0` and takes the same options in `channelOptions` — the map itself stays in `channels`, the options are a sibling key.
+- **Partition revalidation.** Before delivering anything, the runtime re-derives each connection's partition by running the `scope` again with the principal captured at subscribe. A connection whose partition moved — or whose scope now returns `null` — is removed from the group and closed: the client sees the connection closed (`freshness` goes `"stale"`) and receives none of that emit's data. A `scope` that **throws** on re-derivation is treated the same way (fail-closed: a resolver that failed cannot vouch for the partition) and the failure is logged naming the channel — a scope that does I/O must handle its own failures. Only the partition is revalidated; session/cookie expiry stays with the normal request pipeline.
+- **Heartbeat and idle timeout — the transport clocks.** Every channel answer carries `Cache-Control: no-store` (a proxy or the browser must never serve a cached snapshot) and a heartbeat: an SSE comment (`: ping`) written through the write chain every `heartbeatMs` — default `20000`, the same ruler the `stream_*` SSE surface uses; `0` disables it. A comment generates no client event and does not count as a delivery. A connection with **no deliveries** (snapshot or slice) for `idleMs` — default `300000` (5 min); `0` disables — is closed by the server, and the heartbeat does **not** reset the idle clock: idle is about data, heartbeat is transport.
+  **Practical consequences.** A live but quiet page cycles by design: the server closes it, the `EventSource` reconnects by itself and the snapshot on connect repairs the state — do not build anything against that cycle, and do not interpret a periodic reconnect of a quiet page as a bug. In tests, `createTestApp` defaults both clocks to `0` (deterministic); a test exercising them passes `idleMs`/`heartbeatMs` in `channelOptions` and drives them with fake timers — **never assert freshness without advancing the fake timers through the window**.
+- **Behind a reverse proxy (the house recipe, Caddy).** SSE needs the proxy to flush immediately and never buffer the response, or the page goes silent with everything alive. In the Caddyfile: `flush_interval -1` on the app's `reverse_proxy` (negative value = flush as data arrives; a positive interval would batch chunks and delay every snapshot). For nginx in front: `X-Accel-Buffering: no`. The heartbeat keeps the proxy from killing the idle stream; the idle timeout closes what nobody reads anymore.
+- **Inspector — asking the server what is alive.** `inspectChannels()` (from `@mauroandre/velojs/server`) returns the live state: per channel, the groups identified by the pair (moduleId, partition key) — which page holds every connection — each with its connection count and the timestamp of its last delivery; the coalescing windows still open; the grand totals. Always available; expose it with whatever guard the app judges. In development only, `GET /_channel-inspect` answers the same JSON in the browser — it never ships in a production build (the map of channels and partitions is internal information); a production app that wants something similar exposes `inspectChannels()` itself.
+
+**The partition contract is fixed.** On subscribe the scope receives
+`c.get("user")` — the house key, the same one used by stream/socket resolvers. If
+your middlewares materialize the principal under another key, set it in `"user"`
+too. With no authenticated principal the scope receives `undefined`: a public
+channel ignores it (`() => "all"`), an authenticated one returns `null`, which
+denies the subscription with 403. The partition **never** comes from the query
+string or from any client input.
+
+Same channel declared by a layout and by a page → one connection per module,
+each feeding its own module's data; a single `emit` by channel name reaches both.
+
+`useLoader()` and `Loader()` also expose `freshness` — a signal with `"live"`,
+`"stale"` (connection closed, reconnecting **or silent**) and `"error"` (the
+last re-execution failed), aggregated per page — and `freshnessByChannel`, the
+same states keyed by the channel names the module declares: a page with two
+channels, one fallen and one following, shows both states at once. They are
+data for CSS to react to; the framework renders no JSX for them. Without
+`channels`, the record is empty and `freshness` stays `"live"`.
+
+The **silence detector** is the client half of the idle timeout: a connection
+open but without deliveries for `CHANNEL_SILENCE_MS` (60s, a runtime constant,
+not a configuration) is marked `"stale"` even with `EventSource` in `OPEN` —
+the tab in the background, the sleeping notebook, the proxy that stopped
+flushing without closing. Any delivery (or a reconnect's snapshot) brings the
+channel back to `"live"`; the heartbeat comment cannot mask the silence because
+it generates no client event. The aggregate folds it by the same rule: a
+silenced channel counts as not-open.
+
+Guards are explicit, never silent: `channels` in a module without a `loader`
+("nothing to synchronize") and a channel with no entry in `app/channels.ts` both
+fail the dev server and the build; `emit()` on an unknown channel throws
+immediately naming it (`emit` on a valid channel with no subscribers is a no-op);
+and `emit(module, channel, …)` on a module that does not declare that channel, or
+that has no `loader`, throws immediately naming both (a slice that is not an
+object throws too).
+In `velojs build --static` the channels are **inert** — no server, so the client
+opens no connection and freshness stays `"live"` — and the build warns, naming
+the module.
+
+### State or flow? Two questions, always the same two
+
+| Question | Answer | Tool |
+|---|---|---|
+| Is this a **value** or a **sequence**? | value — "what is it now?", replacement | `loader` + `channels` (live loader) |
+| | sequence — "what happened?", accumulation (chat, log, metric series, progress) | `stream_*` / `socket_*` |
+| Does the change come from **someone else** or from **me**? | from someone else / from a background job | `loader` + `channels` |
+| | from me (my own action) | `refetch()` after the action — no channel |
+
+Do not turn on a channel where a post-action `refetch()` suffices, and do not
+use `stream_*` for a value that is simply replaced.
+
 ## A stream/socket `channel` is untrusted client input
 
 `useEventStream(s, { channel })` and `useSocket(s, { channel })` put the channel on the
@@ -99,6 +246,7 @@ cannot influence it.
 | File | Role |
 |---|---|
 | `app/routes.tsx` | The route tree. `export default [...] satisfies AppRoutes`, `import * as` for every page/layout |
+| `app/channels.ts` | The live-loader channel map: channel name → partition resolver (`scope`). Convention file, imported by the framework |
 | `app/<domain>/Page.tsx` | One module per route: `Component`, plus optional `loader`, `action_*`, `stream_*`, `socket_*`, `metadata`. Group by domain (`app/auth/`, `app/admin/`), not in a flat `pages/` folder |
 | `app/layouts/*.tsx` | Shared layouts. Long-lived `stream_*` declarations usually live on the layout that spans their pages |
 | `app/modules/<domain>/` | Server-side logic imported by pages: `*.service.ts`, `*.middleware.ts`, `*.stream.ts`. Not routed |
@@ -134,6 +282,7 @@ API from this file — it is deliberately incomplete.
 | Navigation, `<Link>` | `link-component` |
 | `<Scripts />`, assets, favicon | `scripts-component` |
 | SSE, live/progress/streaming data | `event-streams` |
+| A page value that must track server state (`loader` + `channels`) | `live-loader` |
 | WebSockets, bidirectional realtime | `sockets` |
 | `addRoutes`, `onServer`, ports, server lifecycle | `server-api` |
 | The build, transforms, `veloPlugin` options | `vite-plugin` |

package/agent/skills/velojs-getting-started/SKILL.md

@@ -175,6 +175,8 @@ npm run dev
 
 Open `http://localhost:3000` in your browser. Changes to your code will hot-reload instantly.
 
+The dev server binds loopback by default. To expose it beyond that — a VPS behind a reverse proxy, an app reached by a real hostname — set `HOST=0.0.0.0`, in the shell or in the project's `.env`; no `--host` flag by hand. A broad bind in dev (`0.0.0.0`, `::`, or `--host` with no value) also turns Vite's Host check off, so a request whose `Host` header carries that domain is served instead of 403'd — the DNS-rebinding protection you get on loopback is consciously traded away. A `server.allowedHosts` declared in `vite.config.ts` still pins the allowed list.
+
 ## Configuration
 
 The `veloPlugin()` accepts optional configuration: