@mauroandre/velojs 0.0.59 → 0.0.61

package/README.md

@@ -170,6 +170,7 @@ veloPlugin({
     serverInit: "server.tsx",   // default
     clientInit: "client.tsx",   // default
     hostname: "127.0.0.1",      // bind interface, dev and production (the HOST env wins)
+    serverOnly: ["server/**"],  // declares server-only modules to the leak diagnostic
 });
 ```
 
@@ -872,6 +873,134 @@ surface) without advancing the fake timers through the window.
 
 ---
 
+## Live actions
+
+The live loader keeps a **page** value faithful to server state. The newer
+apps are tab UIs (the VSCode shape): the page is the hull and every content
+opens in a tab — client state, not a route — loaded at open time by an action
+with its own arguments. When that content is a value that must **track server
+state over time** (an expense sheet that grows line by line, a card whose
+phase changes on its own), the action declares interest in living: the
+tab-facing twin of the live loader, addressed by the call's own args — the
+same `channels` map, the same `emit()`, zero polling.
+
+```tsx
+// app/expenses/Expenses.tsx — the page module (the tab hull)
+export const action_abrirExpense = async ({ body }: ActionArgs<{ id: number }>) => {
+    const { expenseSheet } = await import("./expenses.service.js");
+    return expenseSheet(body.id);          // a parameterized read
+};
+
+// The opt-in: key = action name without `action_`, value = channel names.
+export const liveActions = { abrirExpense: ["expenseSheet"] };
+```
+
+```tsx
+// the tab component — one per open tab
+import { useLiveAction } from "@mauroandre/velojs/hooks";
+import { action_abrirExpense } from "../expenses/Expenses.js";
+
+function ExpenseTab({ id }: { id: number }) {
+    const { data, loading, freshness } = useLiveAction(action_abrirExpense, { id });
+    return <article class={freshness.value}>{data.value?.total}</article>;
+}
+```
+
+```ts
+// the same emit() — no second mechanism was born
+import { emit } from "@mauroandre/velojs/server";
+
+await emit("expenseSheet", { args: { id: 7 } });
+```
+
+### What happens
+
+- The framework derives `GET /_live/{moduleId}/{actionName}` (the same family
+  as `/_action` and `/_channel`), inheriting the route node's `middlewares` —
+  the subscription is guarded exactly like the action call and the page are.
+- `useLiveAction(action, args)` opens one SSE connection per subscription with
+  the args in `?_args=`. The **connect snapshot is the loading gesture**: the
+  action executed once with the declared args — there is no initial POST, and
+  the tab never shows a value the server does not stand behind.
+- Every `emit()` in any declared channel re-executes the action with the
+  subscription's own args and pushes the fresh value, which **replaces**
+  `data` whole (no merge). An action that throws marks `freshness` `"error"`
+  and keeps the last valid value — a failure never blanks the tab.
+- The subscription's life is the mount: the tab unmounts and the connection
+  closes (nothing arrives afterwards; being the last of the group,
+  `onGroupClose` disarms the source). It remounts and is born again with a
+  snapshot of the current state — reopening is indistinguishable from never
+  having closed. Changing the args reconnects: they are the identity.
+- `freshness` is the subscription's own `"live"` / `"stale"` / `"error"`
+  signal (the same 60s silence detector as the live loader's) and never
+  touches the page aggregate — a stale tab does not stale the page, and the
+  other way around. On SSR the hook does not connect (`data` null,
+  `loading` true); in a static build the load really failed: no connection,
+  `data` undefined, `freshness` `"error"`.
+
+### The contract and the partition
+
+A live action is, by contract, a **parameterized read** — the server
+re-executes it at every signal, so a mutation with a side effect in a live
+action is a usage error (the re-execution would repeat the effect). The
+mutation the user makes inside the tab keeps being a common one-shot action;
+the tab updates through the channel. The re-execution receives the same
+`ActionArgs` of the common call, with `body` carrying the declared args.
+
+The scope ctx gains `args`, additively: a subscription resolves its partition
+with `{ user, args }`, a loader connection with `{ user, params }` as before.
+A channel declared by both ends has one scope and one partition — the
+canonical form (carved so no reader invents their own):
+
+```ts
+// app/channels.ts — one emit("expenseSheet", { args: { id: 7 } }) updates
+// the page (/expenses/:id, partitioned by params) and the tab (by args)
+export const channels = {
+    expenseSheet: {
+        scope: ({ params, args }) => "expense:" + (args?.id ?? params?.id),
+    },
+};
+```
+
+`null`, `undefined` or a `throw` from the scope denies the subscription with
+403, loudly; `onGroupOpen`/`onGroupClose` receive the args of the connection
+that opened the group; and the transport rules are the live loader's,
+inherited (heartbeat comment, idle timeout, coalescing, partition
+revalidation, `no-store`) — no periodic request exists anywhere.
+
+### Guards
+
+- `liveActions` naming an action the module does not export, or a channel with
+  no entry in `app/channels.ts`: error in the dev server and in the build,
+  naming module, action and channel.
+- Serialized args above **4096 bytes**: rejected with **400**, naming the
+  action and the limit — the args are the tab's address, not a payload.
+- `velojs build --static` with a module declaring `liveActions`: the build
+  warns naming module and action.
+
+### Testing a live action
+
+```ts
+const sub = await app
+    .as({ id: 1, teamId: 7 })
+    .liveAction(Expenses, "abrirExpense", { args: { id: 7 } });
+expect(await sub.next({ timeoutMs: 1000 })).toEqual({ total: 880 });   // connect
+
+await emit("expenseSheet", { args: { id: 7 } });
+expect(await sub.next({ timeoutMs: 1000 })).toEqual({ total: 940 });
+
+await sub.close();   // the tab closed: the group empties, onGroupClose fires
+```
+
+`next()` delivers the payloads in arrival order (the connect snapshot first);
+`nextEvent()` discriminates `{ type: "snapshot" | "error", data }`; `status`
+reads the guards (403 denied, 400 oversized args). The subscription and every
+delivery are traced as their own telemetry boundary (`live-action-connect`,
+ranked by `velojs telemetry` in `By live action`), and `inspectChannels()`
+lists the live subscriptions next to the loader groups.
+
+---
+
 ## Telemetry
 
 The framework records its own bottlenecks — pages, `?_data=1` refetches,
@@ -1780,13 +1909,15 @@ Callbacks queue until the server starts. If called after startup, executes immed
 
 ## Vite Plugin Architecture
 
-`veloPlugin()` returns 6 plugins:
+`veloPlugin()` returns 8 plugins:
 
 | Plugin | Purpose |
 |--------|---------|
 | `velo:config` | Build config (client/server modes, aliases, defines) |
 | `velo:transform` | AST transforms (metadata injection, action stubs, loader removal) |
 | `velo:static-url` | Rewrites CSS `url(/path)` to `url(STATIC_BASE_URL/path)` at build time |
+| `velo:graph` | Generates `.velojs/graph.json` (route tree + dependency graph) on build and dev |
+| `velo:leak-diagnostic` | Prints the server→client leak report on build and dev (read-only) |
 | `@preact/preset-vite` | Preact JSX support |
 | `@hono/vite-dev-server` | Dev server with SSR |
 | `velo:ws-bridge` | Exposes Vite's HTTP server for WebSocket handlers in dev mode |
@@ -1829,6 +1960,55 @@ velojs build
 
 When `routes.tsx` changes, the plugin rebuilds the fullPath map and triggers a full page reload (not partial HMR).
 
+### Server→Client Leak Diagnostic
+
+What ships to the browser is checked on every `velojs build` (including `build --static`) and `velojs dev`: the terminal prints a report of every server module the client entry can reach — a leak of the server→client boundary.
+
+A **server module** is a module that touches a Node builtin in its own code — static import, re-export or `await import()`, by any import path — or that matches a `serverOnly` pattern declared in the plugin config.
+A **leak** is a server module reachable from what the browser loads, following static and dynamic imports.
+The analysis reads the code *after* the client transforms — the same ones the build applies (loaders, actions, streams, sockets, middlewares and endpoints stripped, orphaned imports pruned) — so the normal VeloJS shape (a `loader` importing server code) is silent by construction: what the framework removes never travels.
+
+Each leak in the report brings:
+
+- the leaked module and what qualifies it as server (the Node builtin touched, or the `serverOnly` pattern matched);
+- the full import chain from the client entry to it — file and line at every link;
+- the **entry point** — the import where the chain pulls the first server module, marked `entry point (cut here)`: exactly where the cut happens.
+
+```text
+[velojs] server->client leak analysis: 1 leak(s) in what ships to the client.
+
+1) app/server-side.ts
+   server because: imports Node builtin "node:fs"
+   import chain from the client entry:
+     virtual:velo/client-entry (generated) -> app/routes.tsx
+     app/routes.tsx:3 -> app/pages/Home.tsx
+     app/pages/Home.tsx:6 -> app/server-side.ts  <- entry point (cut here)
+
+The report is read-only: nothing is blocked or rewritten; the cut is yours.
+```
+
+Two chains to the same module are two items — every cut point shows up — and the list is stable between runs.
+When there is nothing to report, one line says so (`0 leaks — what ships to the client is clean.`), so silence is distinguishable from the analysis not running.
+In dev the report appears when the server comes up (no navigation needed) and is re-emitted whenever a file change shifts what travels to the client — an import added stitches a new path into the next report, an import removed takes the leak out of it.
+
+The report is the light, never the hand: nothing is blocked, rewritten, stubbed or moved, `await import()` included; the build finishes with success, the dev keeps serving, and the decision to cut any edge is entirely yours.
+
+#### Declaring server-only code: `serverOnly`
+
+A module that touches no Node builtin is invisible to the analysis — the framework does not guess your app's domain.
+Declare it:
+
+```typescript
+veloPlugin({
+    serverOnly: ["src/fsm/**", "server/**"],
+});
+```
+
+Patterns are globs (`*`, `**`, `?`) matched against the module's file path relative to the project root, always with `/` as separator.
+The declaration feeds the diagnostic only — nothing is blocked or altered because of it.
+
+**Limitation (craved):** server code that touches no Node builtin and matches no `serverOnly` pattern generates no item; that is what the declaration is for.
+
 ---
 
 ## Request Isolation
@@ -1986,6 +2166,7 @@ interface VeloConfig {
     clientInit?: string;     // default: "client.tsx"
     port?: number;           // default: 3000; the PORT env wins
     hostname?: string;       // bind interface, dev and production; the HOST env wins
+    serverOnly?: string[];   // glob patterns declaring server-only modules to the leak diagnostic
 }
 ```
 

package/agent/AGENTS.md

@@ -35,10 +35,33 @@ hard constraints, not style.
 | `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 live action with a side effect (an action listed in `liveActions` that mutates anything) | a **parameterized read** in `liveActions`; the tab's mutations stay one-shot actions | the server re-executes a live action at every `emit` of its channels — **the side effect repeats** (duplicate rows, duplicate emails, double writes) |
+| `export const liveActions = {...}` in a `.jsx` / `.js` page, or any page outside `appDirectory` | `.tsx` inside `app/` | **zero transforms**: the live-action guards never run, so the declaration is inert — no `/_live` 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.
 
+## The server→client leak report
+
+`velojs build` (and `build --static`, `velojs dev`) prints a report of every **server module** the browser can reach — a module that touches a Node builtin in its own code (static import, re-export or `await import()`), or that matches a `serverOnly` pattern.
+The analysis reads the code **after** the client transforms (the table above describes what those remove), so a `loader`/`action_*`/`stream_*`/`socket_*`/`middlewares` importing server code where the framework strips it is silent by construction.
+
+What the warning means: the module named in the item reaches what ships to the browser; the chain lists every import from the client entry to it (file and line per link); `entry point (cut here)` marks the import where the chain pulls the first server module — that is where the cut happens.
+The report never blocks, rewrites, stubs or moves anything: the build finishes with success, the dev keeps serving, and cutting any edge is always your call.
+Two chains to the same module are two items — every cut point shows up.
+
+Code that touches **no** Node builtin is invisible to the analysis — the framework does not guess your app's domain. Declare it:
+
+```typescript
+veloPlugin({
+    serverOnly: ["src/fsm/**", "server/**"],
+});
+```
+
+Patterns are globs (`*`, `**`, `?`) matched against the module's file path relative to the project root, always with `/` as separator.
+The declaration feeds the diagnostic only — nothing is blocked or altered because of it.
+A server module with no builtin and no declaration generates no item: that limitation is craved, and the declaration is how you lift it.
+
 ## Sharing a layout's data with its children
 
 `Loader()` is the importable handle for a module's loader data; `useLoader()` is the
@@ -279,6 +302,66 @@ the module.
 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 tab value that must follow the server: `liveActions` + `useLiveAction`
+
+A tab is not a route: it is client state (persisted, restored on refresh) whose
+content loads at open time from an action with its own args. When that content
+is a value that must track server state over time, the action declares
+interest in living — the tab-facing twin of the live loader, same channels,
+same `emit()`, addressed by the call's own args:
+
+```tsx
+// app/expenses/Expenses.tsx
+export const action_abrirExpense = async ({ body }: ActionArgs<{ id: number }>) => {
+    const { expenseSheet } = await import("./expenses.service.js");
+    return expenseSheet(body.id);            // a parameterized read — ONLY
+};
+export const liveActions = { abrirExpense: ["expenseSheet"] };
+```
+
+```tsx
+// the tab component — one per open tab
+import { useLiveAction } from "@mauroandre/velojs/hooks";
+import { action_abrirExpense } from "../expenses/Expenses.js";
+
+const { data, loading, freshness } = useLiveAction(action_abrirExpense, { id });
+```
+
+```ts
+// the same emit() — the producer addresses the partition by args
+await emit("expenseSheet", { args: { id: 7 } });
+```
+
+The contract, in short:
+
+- A live action is a **parameterized read**. The server re-executes it with the
+  subscription's own args at every `emit()` of its declared channels — a
+  mutation there repeats its effect on every signal. The tab's mutations stay
+  one-shot actions; the tab updates through the channel.
+- The connect snapshot **is** the loading gesture: the action runs once on
+  subscribe, there is no initial POST. The re-execution receives the same
+  `ActionArgs`, with `body` carrying the declared args.
+- The scope ctx gains `args` (additively): a subscription resolves its
+  partition with `{ user, args }`; a loader connection keeps `{ user, params }`.
+  A channel declared by both ends has one scope and one partition — the
+  canonical form: `scope: ({ params, args }) => "expense:" + (args?.id ?? params?.id)`
+  — and one `emit` by name updates the page and the tab, each with its own data.
+- The subscription's life is the mount (unmount closes, remount reborn with
+  the current state), the args are the identity (a change reconnects), and
+  `freshness` (`"live"`/`"stale"`/`"error"`, same 60s silence detector) belongs
+  to the subscription — it never touches the page's aggregate.
+- Serialized args above **4096 bytes** reject the subscription with 400 — the
+  args are an address (an id), not a payload. `liveActions` naming an action
+  the module does not export, or a channel missing from `app/channels.ts`,
+  fails dev and build naming module, action and channel.
+- In `velojs build --static` there is no server to run the action: the build
+  warns naming module and action, and the hook returns `data` undefined with
+  `freshness` `"error"` — the load really failed (a channel, in contrast,
+  stays `"live"`: deliberate).
+- Test it with `app.liveAction(Module, "abrirExpense", { args: { id: 7 } })` —
+  `next()` (the connect snapshot first), `nextEvent()` (`snapshot`/`error`),
+  `close()`, `status` (403/400 guards), all deterministic like `app.channel`.
+
 ## A stream/socket `channel` is untrusted client input
 
 `useEventStream(s, { channel })` and `useSocket(s, { channel })` put the channel on the
@@ -352,6 +435,7 @@ API from this file — it is deliberately incomplete.
 | `<Scripts />`, assets, favicon | `scripts-component` |
 | SSE, live/progress/streaming data | `event-streams` |
 | A page value that must track server state (`loader` + `channels`) | `live-loader` |
+| A tab value that must track server state (`liveActions` + `useLiveAction`) | `live-actions` |
 | WebSockets, bidirectional realtime | `sockets` |
 | `addRoutes`, `onServer`, ports, server lifecycle | `server-api` |
 | The build, transforms, `veloPlugin` options | `vite-plugin` |

package/agent/skills/velojs-actions/SKILL.md

@@ -190,3 +190,35 @@ Both imports compile to the **same URL**: `POST /_action/admin/Layout/logout`. M
 ### Why this works
 
 The Vite plugin replaces the action body with a `fetch()` call to its registered URL **during compile time**, using the `moduleId` of the file where the export lives. Imports in other files just reuse that compiled stub — they never change the URL.
+
+## The action that lives — when the portrait ages
+
+An action is, by default, a one-shot gesture: the client calls, the server
+executes, the value returns. When the content it carries is a **value that
+tracks server state over time** — the tab of an expense sheet that grows line
+by line, the card whose phase changes on its own — the portrait ages minutes
+after opening. The way out is declaring interest in living ([live
+actions](/docs/23-live-actions), the tab-facing twin of the action):
+
+```tsx
+// app/expenses/Expenses.tsx
+export const action_abrirExpense = async ({ body }: ActionArgs<{ id: number }>) => {
+    const { expenseSheet } = await import("./expenses.service.js");
+    return expenseSheet(body.id);          // a parameterized read — ONLY
+};
+export const liveActions = { abrirExpense: ["expenseSheet"] };
+```
+
+```tsx
+import { useLiveAction } from "@mauroandre/velojs/hooks";
+
+const { data, loading, freshness } = useLiveAction(action_abrirExpense, { id });
+```
+
+The lifecycle changes hands: what loads the tab is no longer the POST call but
+the **subscription** (`GET /_live/{moduleId}/{actionName}?_args=`) — the
+connect snapshot is the action executed once, and every `emit()` of its
+declared channels re-executes it with the same args. The contract is rigid: a
+live action is a **parameterized read** — a side effect in it is a usage error
+(the re-execution would repeat the effect); the mutation the user makes inside
+the tab keeps being a common action, and the tab updates through the channel.

package/agent/skills/velojs-hooks/SKILL.md

@@ -14,6 +14,7 @@ VeloJS provides a set of hooks that work identically on both server (SSR) and cl
 | `useLoader<T>(deps?)` | `{ data, loading, refetch }` | Page data with SSR + SPA support |
 | `Loader<T>()` | `{ data, loading }` | Module-level SSR-only data |
 | `useEventStream<T, S>(stream, opts?)` | `{ data, snapshot, closed, error }` | Real-time SSE stream subscription |
+| `useLiveAction<T>(action, args)` | `{ data, loading, freshness }` | A live action's value, tracking server state (a tab) |
 | `useParams<T>()` | `T` | URL parameters (`:id`, etc) |
 | `useQuery<T>()` | `T` | Query string parameters |
 | `useNavigate()` | `navigate(path)` | Programmatic navigation |
@@ -83,6 +84,31 @@ const { data, snapshot, closed, error } = useEventStream(stream, {
 
 The hook handles `EventSource` lifecycle automatically: opens on mount, closes on unmount, re-opens when `channel` changes. See [Event Streams](/docs/event-streams) for the full guide.
 
+## useLiveAction
+
+Subscribes to a **live action** — the tab-facing twin of the live loader. The
+hook receives the action itself (its client stub carries the subscription
+address) and the args; the connect snapshot is the whole loading gesture, and
+every `emit()` of the action's declared channels re-executes it server-side
+and replaces `data` whole:
+
+```tsx
+import { useLiveAction } from "@mauroandre/velojs/hooks";
+import { action_abrirExpense } from "../expenses/Expenses.js";
+
+function ExpenseTab({ id }: { id: number }) {
+    const { data, loading, freshness } = useLiveAction(action_abrirExpense, { id });
+    if (loading.value) return <div class="tab-loading" />;
+    return <article class={freshness.value}>Total: {data.value?.total}</article>;
+}
+```
+
+The life is the mount (unmount closes the subscription, remount reopens it
+with the current state) and the args are the identity (a change reconnects).
+`freshness` is the subscription's own `"live"` / `"stale"` / `"error"` signal —
+never the page's aggregate. On SSR the hook does not connect (`data` null,
+`loading` true). See [Live actions](/docs/live-actions) for the full contract.
+
 ## touch
 
 Preact signals are great for reactivity, but they have a limitation: mutating a nested property (like changing `items[0].checked`) doesn't trigger a signal update. The `touch` function forces the signal to notify its subscribers after a mutation:

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

@@ -0,0 +1,211 @@
+---
+name: velojs-live-actions
+description: "Live actions: the tab-facing twin of the live loader. Declare `liveActions = { abrirFicha: [\"fichaProjeto\"] }` next to the action and subscribe with `useLiveAction(action, args)` — the connect snapshot is the loading gesture and every `emit()` of the declared channels re-executes the action with the subscription's own args, replacing the value whole. A live action is a parameterized read (no side effects); the partition derives from `args` in `app/channels.ts`. Use when a tab's content must track server state over time instead of being fetched once at open."
+---
+
+# Live actions
+
+The newer apps built on VeloJS are tab UIs (the VSCode shape): the page is the hull — sidebar, tab bar — and every content opens in a tab. A tab is **not a route**: it is client state, persisted in `localStorage` and restored on refresh, and its content loads at open time from an action with its own arguments (the resource id, the file path). The page's loader does not know the tabs — it loads only what belongs to the page itself.
+
+When a tab's content is a **value that tracks server state over time** — the expense sheet that grows line by line, the project card whose phase changes without anyone clicking — the one-shot action delivers a portrait that ages minutes after opening, and whoever reads it cannot know they are looking at the past. That is what a live action is for: the action declares interest in **living**, and the tab's value follows the server, addressed by the call's own arguments — one signaling mechanism (`emit()`), zero polling.
+
+It is the tab-facing twin of the live loader: the same channels, the same `emit()`, the same partition policy in `app/channels.ts` — addressed to an **action call with args** instead of a **route with params**.
+
+## The three declarations
+
+```tsx
+// app/expenses/Expenses.tsx — the page module (the tab hull)
+import type { ActionArgs } from "@mauroandre/velojs";
+
+// A live action is a parameterized read: it returns the tab's content for the
+// args it receives. Mutations inside the tab stay common one-shot actions.
+export const action_abrirExpense = async ({ body }: ActionArgs<{ id: number }>) => {
+    const { expenseSheet } = await import("./expenses.service.js");
+    return expenseSheet(body.id);   // { total: 880, linhas: [...] }
+};
+
+// The opt-in: the key is the action name WITHOUT the `action_` prefix, the
+// value is the list of channels — an emit in any one delivers.
+export const liveActions = { abrirExpense: ["expenseSheet"] };
+
+export const Component = () => <ExpensesShell />;   // sidebar + tab bar
+```
+
+```tsx
+// the tab component — one per open tab
+import { useLiveAction } from "@mauroandre/velojs/hooks";
+import { action_abrirExpense } from "../expenses/Expenses.js";
+
+function ExpenseTab({ id }: { id: number }) {
+    const { data, loading, freshness } = useLiveAction(action_abrirExpense, { id });
+    if (loading.value) return <div class="tab-loading" />;
+    return (
+        <article class={`tab ${freshness.value}`}>
+            <h3>{data.value?.total}</h3>
+            <ul>{data.value?.linhas.map((linha) => <li>{linha}</li>)}</ul>
+        </article>
+    );
+}
+```
+
+```ts
+// app/channels.ts — the same map the live loader uses
+export const channels = {
+    expenseSheet: {
+        scope: ({ user, args }) => {
+            if (args?.id == null) return null;
+            if (user && !podeVerTime(user, args.id)) return null;   // 403
+            return `expense:${args.id}`;
+        },
+    },
+};
+```
+
+```ts
+// anywhere server-side: the same emit() — no second mechanism was born
+import { emit } from "@mauroandre/velojs/server";
+
+await emit("expenseSheet", { args: { id: 7 } });
+```
+
+`export const liveActions = { ... }` is the whole opt-in. A module without it behaves exactly as before — no route, no connection, no cost. A module may declare `loader` + `channels` (the live page) **and** `liveActions` (the live tabs): the two surfaces coexist without interference.
+
+## What happens
+
+- The framework derives one internal SSE route per declared action — `GET /_live/{moduleId}/{actionName}`, the same family as `/_action`, `/_event` and `/_channel` — inheriting the `middlewares` of the module's route node: the subscription is guarded exactly like the action call and the page are.
+- `useLiveAction(action, args)` opens **one connection per subscription** with the args serialized in `?_args=`. The connect snapshot — the action executed once with the declared args — **is the loading gesture**: there is no initial POST, the tab never shows a value the server does not stand behind.
+- Every `emit()` in any of the action's declared channels re-executes the action **with the subscription's own args** and pushes the fresh value, which **replaces** `data` whole — the updated payload has the same shape as the original answer, no merge on the client.
+- The subscription's life is the mount: the tab component unmounts (tab closed, page left) and the connection closes — nothing arrives afterwards, and the server holds nothing for whoever left (being the last of the group, `onGroupClose` disarms the source). It remounts (tab reopened, refresh restored the tabs) and the subscription is born again with a snapshot of the current state: reopening is indistinguishable from never having closed.
+- The args are the identity: changing them reconnects — a new subscription with a new snapshot, the twin of the loader connection keyed by its route params.
+
+## The contract of a live action
+
+A live action is, by contract, a **parameterized read**. The server re-executes it with the subscription's args at every signal of its channels, and the result replaces the previous value whole — a mutation with a side effect in a live action is a **usage error**: the re-execution would repeat the effect (one more row, one more email). The row is explicit in the agent rules' silent-failure table.
+
+The mutation the user makes inside the tab keeps being a **common one-shot action**; the tab updates through the channel. The re-execution receives the same `ActionArgs` as the common call — `body` carries the args declared in the subscription, `c` is the connection's context (the same ruler as the loader re-executed by a channel connection).
+
+## The partition: `args` in the scope
+
+The ctx of a channel's `scope` gains `args` — additively. On a live action subscription the scope receives `{ user, args }`; on a loader connection it receives `{ user, params }` as before. On `emit` the producer builds the same shape of always: `emit("expenseSheet", { args: { id: 7 } })` — the public gesture is the existing `emit()`, nothing new.
+
+A channel declared by **both** ends has one scope that consumes what each end declares and resolves **one partition**. The canonical form is carved here so no reader invents their own — a channel `expenseSheet` declared by the `loader` of the page `/expenses/:id` and by the tab action `abrirExpense`:
+
+```ts
+// app/channels.ts
+export const channels = {
+    expenseSheet: {
+        scope: ({ params, args }) => "expense:" + (args?.id ?? params?.id),
+    },
+};
+```
+
+The loader connection (partitioned by the route it is seeing) and the tab subscription (partitioned by its own args) fall in the same partition `expense:{id}` — and **one** `emit("expenseSheet", { args: { id: 7 } })` re-executes the loader on the page and the action on the tab, each with its own data.
+
+The rest of the partition contract is the live loader's, unchanged: `null`, `undefined` or a `throw` from the scope denies the subscription with 403, loudly; the partition **never** derives from anything the client did not declare. `onGroupOpen`/`onGroupClose` receive the args of the connection that opened the group (`{ partition, params, args }`) — with the same arbitrariness caveat the live loader makes for `params` when the partition does not derive from them.
+
+## `useLiveAction(action, args)`
+
+The hook (exported from `@mauroandre/velojs/hooks`, the house of hooks) receives **the action itself** — its client stub, which the Vite plugin marks with the subscription address (`__path`, the socket-stub ruler) — and the args. The types are preserved from the action's own signature: args and return check in the app's typecheck at the same level as the common call.
+
+| Field | Behavior |
+|---|---|
+| `data` | Signal with the action's return, replaced whole by every snapshot |
+| `loading` | True until the first snapshot or error of the current subscription |
+| `freshness` | The subscription's own `"live"` / `"stale"` / `"error"` signal |
+
+`freshness` carries the same three states and the same silence detector as the live loader's: a connection open with no deliveries for 60s (`CHANNEL_SILENCE_MS`, a runtime constant) is `"stale"` even though `EventSource` still reads `OPEN`; any delivery brings it back. It is **per subscription** and never touches the page aggregate: a stale tab does not stale the page (`useLoader().freshness`), and the other way around.
+
+On the server (SSR) the hook does not connect — the tab is client state the server does not know — and returns `data` null with `loading` true. In a static build the load really failed (there is no server to run the action): no connection is opened and the handle is `data` undefined with `freshness` `"error"` — the deliberate contrast with a channel, which stays `"live"` in static because there is nothing to synchronize.
+
+An error — the action throwing on the snapshot or on a re-execution — arrives as the error event of the connection: `freshness` goes `"error"`, `loading` ends, and the **last valid value stays** (a failure never blanks the tab). A malformed payload keeps the previous value — the house ruler.
+
+## Transport — the channel ruler, inherited
+
+The live connection enters the same groups by (channel, partition) as the loader connections, with every transport rule of the live loader: the heartbeat is an SSE comment (no client event, no delivery), the idle timeout closes a subscription with no deliveries, invalidations coalesce per (channel, partition), the partition is revalidated before every delivery (the scope re-derived with the ctx captured at subscribe — a partition that moves or denies closes the subscription), and the answer carries `Cache-Control: no-store`. **No periodic request exists anywhere**: the update is born of `emit()`, never of a clock.
+
+One detail belongs to this surface: the subscription of an action that declares **two** channels enters the groups of both (one SSE stream, N group entries) — an emit in either one delivers, and any cause of death (idle, revalidation in any channel) ends the whole subscription: a tab cannot be half alive. In the inspector it counts once.
+
+## Guards
+
+The failures that would otherwise be silent are explicit:
+
+- `liveActions` naming an action the module does **not** export: error in the dev server and in the build, naming module and action — never an inert route.
+- A channel with no entry in `app/channels.ts`: error in the dev server and in the build, naming module, action and channel.
+- Serialized args above **4096 bytes**: the subscription is rejected with **400**, naming the action and the limit — the args are the tab's address (an id), not a payload; a bigger read wants a common action call.
+- A malformed `?_args=` payload: rejected with **400**, legibly.
+- A `scope` that returns nothing (or throws): the subscription is denied with **403**, loudly — and the route node's `middlewares` run for real, so a guard middleware denies an unauthenticated subscription exactly as it denies the page.
+- `velojs build --static` with a module declaring `liveActions`: the build warns naming module and action — in static the client opens no `/_live` connection and the hook reports the real failure.
+- A module outside the conventions (`.jsx`/`.js`, or outside `app/`) is the one genuinely silent line: no transform, so the declaration is simply inert (the row exists in the agent rules' table).
+
+## Telemetry and inspection
+
+The subscription and every delivery are traced as a boundary of their own — `live-action-connect`, carrying `module` and `name` (never a channel) — with one delivery line per snapshot and a closing line with the total: distinguishable from a loader's `channel-connect` in the JSONL and in `velojs telemetry`, which ranks the live actions (times, bytes, deliveries) in their own `By live action` section. The emit log stays one line per gesture, as always.
+
+`inspectChannels()` (and the dev-only `GET /_channel-inspect`) lists the live subscriptions next to the loader groups — each with module, action, declared args and the (channel, partition) groups it holds — and the grand total counts each subscription once.
+
+```ts
+import { inspectChannels } from "@mauroandre/velojs/server";
+
+inspectChannels().liveActions;
+// [{
+//   moduleId: "expenses/Expenses",
+//   action: "abrirExpense",
+//   channels: [{ channel: "expenseSheet", partition: "expense:7" }],
+//   args: { id: 7 },
+//   lastDeliveryAt: "2026-10-12T12:00:01.104Z",
+// }]
+```
+
+## Testing
+
+`app.liveAction(Module, "name", { args })` opens a real subscription — the family of `app.channel(...)`: the middlewares of the route node run for real, cookies come from the options or from `app.as(user)`, and the size guard and the scope run for real too. The toolkit registers the channels with the transport clocks at `0` (deterministic), so `await emit(…)` is the delivery — no sleep, no retry.
+
+```ts
+const app = await createTestApp({
+    routes,
+    channels,                                    // the map (app/channels.ts)
+    getSessionCookie,
+});
+
+const sub = await app
+    .as({ id: 1, teamId: 7 })
+    .liveAction(Expenses, "abrirExpense", { args: { id: 7 } });
+expect(await sub.next({ timeoutMs: 1000 })).toEqual({ total: 880, linhas: ["mercado"] });  // connect
+
+await emit("expenseSheet", { args: { id: 7 } });
+expect(await sub.next({ timeoutMs: 1000 })).toEqual({ total: 940, linhas: ["mercado", "luz"] });
+
+await sub.close();   // the tab closed: the group empties, onGroupClose fires
+```
+
+`next()` delivers the payloads in arrival order (the connect snapshot first); `nextEvent()` discriminates the arrival — `{ type: "snapshot" | "error", data }` (an error is an arrival for `nextEvent()`, never a payload for `next()`); `close()` ends the subscription, and `status` reads the guards (403 denied, 400 oversized args). The group hooks are observable at the subscription's entrances and exits, and the denial of the scope and the args limit are observable as status.
+
+## State or flow — the same two questions
+
+| Question | Answer | Tool |
+|---|---|---|
+| Is this a **value** or a **sequence**? | value — "what is it now?", replacement | `liveActions` + `useLiveAction` (a tab), `loader` + `channels` (the page) |
+| | sequence — "what happened?", accumulation (chat, log, progress) | `stream_*` / `socket_*` |
+| Is the address a **route** or a **call with args**? | the route the user is seeing | `loader` + `channels` |
+| | the tab's own arguments (client state) | `liveActions` + `useLiveAction` |
+
+Do not turn on a live action where the value is fetched once and never moves, and do not use it for flow — tokens being born in a chat keep being `stream_*`; a terminal keeps being `socket_*`.
+
+## Reference
+
+| Piece | Behavior |
+|---|---|
+| `export const liveActions = { abrir: ["canal"] }` | Module opt-in: key = action name without `action_`, value = channel names (an emit in any one delivers) |
+| `GET /_live/{moduleId}/{actionName}?_args=` | The subscription route — inherits the route node's `middlewares` |
+| `useLiveAction(action, args)` | `{ data, loading, freshness }`; the life is the mount, the args are the identity (a change reconnects) |
+| The connect snapshot | The action executed once with the declared args — the whole loading gesture |
+| The re-execution | `emit()` in a declared channel re-runs the action with the subscription's own args; the value replaces whole |
+| `scope({ user, args })` | The live half of the partition ctx; `null`/`undefined`/throw denies with 403 |
+| Shared channel | `scope: ({ params, args }) => "expense:" + (args?.id ?? params?.id)` — the canonical form for a channel declared by a loader and a live action |
+| `onGroupOpen`/`onGroupClose` | Receive `{ partition, params, args }` — the address of the connection that opened the group |
+| Args limit | Serialized args above 4096 bytes reject the subscription with 400, naming the action |
+| `freshness` | `"live"` / `"stale"` (closed, reconnecting or silent past 60s) / `"error"`, per subscription — never the page aggregate |
+| Static build | No connection; `data` undefined with `freshness` `"error"` — the load really failed (the channel stays `"live"` — deliberate contrast) |
+| Telemetry | `live-action-connect` + one `delivery` line per snapshot + the closing line; `velojs telemetry` ranks them in `By live action` |
+| `inspectChannels().liveActions` | The live subscriptions: module, action, args, groups, last delivery |
+| `app.liveAction(Module, "name", { args })` | Test subscription — `next()`, `nextEvent()`, `close()`, `status` |