@mauroandre/velojs 0.0.59 → 0.0.61

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

@@ -5,7 +5,7 @@ description: "Native telemetry: the framework records its own boundaries — the
 
 # Telemetry
 
-The framework knows its own bottlenecks — they are finite: a page SSR (with the loaders of the hierarchy), a `?_data=1` refetch, an action, a declarative endpoint, a stream connect, a socket setup, a channel connect. It also knows the part that runs **outside any request**: when `emit()` invalidates a channel, the loader re-executes on an already-open connection, with no new request involved. Native telemetry turns each of those executions into one JSON line — duration, status, response bytes, child spans — and each long connection into one light line per delivery plus a final line when it closes.
+The framework knows its own bottlenecks — they are finite: a page SSR (with the loaders of the hierarchy), a `?_data=1` refetch, an action, a declarative endpoint, a stream connect, a socket setup, a channel connect, a live action connect. It also knows the part that runs **outside any request**: when `emit()` invalidates a channel, the loader (or the live action) re-executes on an already-open connection, with no new request involved. Native telemetry turns each of those executions into one JSON line — duration, status, response bytes, child spans — and each long connection into one light line per delivery plus a final line when it closes.
 
 What this buys you: **which route is slow, how big its response is, and why**. A page trace names every loader that ran and how long each took; an emit trace names the channel, the partition and how many connections re-executed. The file is plain JSONL in an operator-chosen path — no dev overlay, no dashboard inside the app, nothing to attack in production.
 
@@ -44,6 +44,7 @@ Each execution in one of the framework's bottlenecks produces a trace (type →
 | `stream-connect` | A `stream_*` / standalone SSE connect | `route`, `module`, `name`, `channel`, duration, status |
 | `socket-connect` | A `socket_*` upgrade | `route`, `module`, `name`, duration, status |
 | `channel-connect` | A live-loader channel connect | `route`, `module`, `channel`, duration, status, the `snapshot` span of the connect snapshot |
+| `live-action-connect` | A live action subscription (`useLiveAction`) | `route`, `module`, `name` (never a `channel`), duration, status, the `snapshot` span of the connect snapshot — plus its `delivery`/`close` lines, told from a loader's by the `name` they carry |
 | `emit` | Every `emit()` gesture | `channel`, `partition`, `mode` (`invalidate` / `slice`), `connections` reached, duration; in the invalidation mode, one child span per loader re-execution per connection |
 | `delivery` | Every frame a long connection delivers | `channel`/`route`/`module`, the cumulative ordinal (`deliveries`), `bytes` of the frame |
 | `close` | The end of a long connection | `channel`/`route`/`module`, the total of `deliveries`, the connection's lifetime as `duration` |
@@ -175,6 +176,10 @@ By action
 By channel
   key                      count  errors     p50      p95     bytes
   teamExpenses                52       0   12.7ms   20.1ms    1.3KB
+
+By live action
+  key                      count  errors     p50      p95     bytes
+  expenses/abrirExpense      18       0    8.9ms   14.0ms    2.4KB
 ```
 
 ## What is not here yet

package/agent/skills/velojs-type-reference/SKILL.md

@@ -139,5 +139,6 @@ interface VeloConfig {
     clientInit?: string;     // default: "client.tsx"
     port?: number;           // default: 3000 (the PORT env always 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/skills/velojs-vite-plugin/SKILL.md

@@ -5,9 +5,9 @@ description: "The `veloPlugin` build pipeline: the 9 AST transforms that inject
 
 # Vite Plugin
 
-The `veloPlugin()` is the core of VeloJS. It's a single function that returns 6 Vite plugins working together to handle routing, SSR, code transforms, and more.
+The `veloPlugin()` is the core of VeloJS. It's a single function that returns 8 Vite plugins working together to handle routing, SSR, code transforms, and more.
 
-## The 7 plugins
+## The 8 plugins
 
 | Plugin | What it does |
 |--------|-------------|
@@ -15,6 +15,7 @@ The `veloPlugin()` is the core of VeloJS. It's a single function that returns 6
 | `velo:transform` | Performs AST transforms on your code (the most important plugin) |
 | `velo:static-url` | Rewrites CSS `url(/path)` to use `STATIC_BASE_URL` in production builds |
 | `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` | Adds Preact JSX support |
 | `@hono/vite-dev-server` | Runs the SSR dev server |
 | `velo:ws-bridge` | Exposes Vite's HTTP server for WebSocket handlers during development |
@@ -79,6 +80,54 @@ VeloJS uses Vite virtual modules to generate the server and client entry points
 
 You never import these directly — they're generated by the plugin.
 
+## The 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 above — loaders, actions, streams, sockets, middlewares and endpoints stripped, orphaned imports pruned — never the raw source, so a `loader` importing server code is silent by construction.
+
+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 nothing leaks, 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.
+
+### 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.
+The diagnostic is the light, never the hand: nothing is blocked, rewritten, stubbed or moved, `await import()` included; the build finishes with success and the dev keeps serving.
+
 ## Hot reload
 
 When you edit `routes.tsx`, the plugin detects the change, rebuilds the path map, and triggers a full page reload. Other file changes use Vite's standard HMR (hot module replacement).

package/dist/channels.d.ts

@@ -7,6 +7,14 @@
  * family as `/_action` and `/_event` — which inherits the middlewares of the
  * module's route node and serves the module's loader as a stream of snapshots.
  *
+ * The tab-facing twin is the live action: a module declares
+ * `liveActions = { actionName: [channel, …] }` and the framework derives
+ * `GET /_live/{moduleId}/{actionName}` — a subscription whose args travel in
+ * `?_args=` and whose source is the action itself (a parameterized read,
+ * re-executed with those args). The subscription enters the SAME groups by
+ * (channel, partition): one `emit` by name wakes the loader connections and
+ * the live subscriptions of the partition, each re-executing its own source.
+ *
  * The app owns the partition policy in `app/channels.ts`, a name → resolver map:
  *
  * ```ts
@@ -15,7 +23,8 @@
  * };
  * ```
  *
- * On subscribe the resolver receives `{ user, params }`: `user` is the
+ * On subscribe the resolver receives `{ user, params }` (a loader connection)
+ * or `{ user, args }` (a live action subscription): `user` is the
  * materialized principal (`c.get("user")`, the house key — `undefined` when the
  * app does not materialize one, so a public channel ignores it and an
  * authenticated one returns `null`, which denies the subscription with 403) and
@@ -56,7 +65,7 @@
  * dropped and closed instead of receiving data of a group it left.
  */
 import type { Context, Hono, MiddlewareHandler } from "hono";
-import type { LoaderArgs, RouteModule } from "./types.js";
+import type { ActionArgs, LoaderArgs, RouteModule } from "./types.js";
 import { type TelemetryStatus, type TelemetryTrace } from "./telemetry.js";
 /** Result of a partition resolver. `null`/`undefined` denies the subscription. */
 export type ChannelScopeResult = string | null | undefined;
@@ -76,6 +85,12 @@ export type ChannelScopeResult = string | null | undefined;
 export interface ChannelScopeContext {
     user?: any;
     params?: Record<string, any>;
+    /**
+     * The declared arguments of a **live action** subscription (`kind: "live"`).
+     * The tab-facing twin of `params`: the address the subscription itself
+     * declared, not something the route declares.
+     */
+    args?: Record<string, any> | undefined;
 }
 /**
  * What `onGroupOpen` receives: the partition key of the group that just got its
@@ -86,14 +101,27 @@ export interface ChannelScopeContext {
  * partitioned by principal, declared in a module with `:params`, mixes
  * resources in the same group and the hook's params are the first connection's
  * — arbitrary for the rest; such a channel must not consume them here.
+ *
+ * `args` is the live-action half of the same address: when the connection that
+ * opened the group is a live action subscription, they are the args that
+ * subscription declared (with the same arbitrariness caveat when the partition
+ * does not derive from them).
  */
 export interface ChannelGroupOpenContext {
     partition: string;
     params: Record<string, string>;
+    /** The declared args of the connection that opened the group (live actions). */
+    args?: Record<string, unknown> | undefined;
 }
-/** What `onGroupClose` receives: the partition key of the group being torn down. */
+/**
+ * What `onGroupClose` receives: the partition key of the group being torn
+ * down and, when the group was opened by a live action subscription, the args
+ * of that connection — the same fields `onGroupOpen` saw.
+ */
 export interface ChannelGroupCloseContext {
     partition: string;
+    /** The declared args of the connection that opened the group (live actions). */
+    args?: Record<string, unknown> | undefined;
 }
 /**
  * One entry of the app's channel map (`app/channels.ts`).
@@ -206,13 +234,31 @@ export interface ChannelConnection {
     /** Partition key resolved at subscribe time — never from client input. */
     partition: string;
     moduleId: string;
+    /**
+     * Which surface the connection feeds: `"loader"` (the page's live-loader
+     * connection — the default) or `"live"` (a live action subscription, the
+     * tab-facing twin).
+     */
+    kind?: "loader" | "live";
     /**
      * The principal materialized at subscribe (`c.get("user")`), captured for
      * the partition revalidation of every emit — the scope re-runs against it.
      */
     principal: unknown;
-    loader: (args: LoaderArgs) => Promise<unknown>;
-    /** The subscribing request's context — the loader re-runs against it. */
+    /** The module's loader — the data source of a `"loader"` connection. */
+    loader?: (args: LoaderArgs) => Promise<unknown>;
+    /** The live action — the data source of a `"live"` connection. */
+    action?: (args: ActionArgs<any>) => Promise<unknown>;
+    /** The action name without the `action_` prefix (`"live"` connections). */
+    actionName?: string | undefined;
+    /** The subscription's declared args (`"live"` connections) — the tab's address. */
+    args?: Record<string, unknown> | undefined;
+    /**
+     * Identifies one live action subscription across the N group entries it
+     * holds (one per declared channel) — the inspector's key.
+     */
+    liveId?: string | undefined;
+    /** The subscribing request's context — the loader/action re-runs against it. */
     c: Context;
     params: Record<string, string>;
     query: Record<string, string>;
@@ -260,25 +306,47 @@ export interface ChannelInspectWindow {
     channel: string;
     partition: string;
 }
+/** One live action subscription, as the inspector reports it. */
+export interface ChannelInspectLiveAction {
+    /** The route module holding the action (`metadata.moduleId`). */
+    moduleId: string;
+    /** The action name, without the `action_` prefix. */
+    action: string;
+    /** Every (channel, partition) group the subscription entered. */
+    channels: {
+        channel: string;
+        partition: string;
+    }[];
+    /** The args the subscription declared — its address. */
+    args: Record<string, unknown> | null;
+    /** ISO timestamp of the subscription's last delivery; `null` when none yet. */
+    lastDeliveryAt: string | null;
+}
 /** The full live state of the channel registry, as `inspectChannels()` sees it. */
 export interface ChannelInspectReport {
     channels: ChannelInspectChannel[];
     /** Open coalescing windows, per (channel, partition). */
     openCoalesceWindows: ChannelInspectWindow[];
+    /** The live action subscriptions, per (moduleId, action, args). */
+    liveActions: ChannelInspectLiveAction[];
     totalConnections: number;
 }
 /**
  * Server-side snapshot of the live channels: per channel, the groups
  * identified by (moduleId, partition key), each with its connection count and
- * the timestamp of its last delivery; the coalescing windows still open; and
- * the grand totals. Always available — the app decides how (and with what
- * guard) to expose it; the dev server exposes it as `GET /_channel-inspect`.
+ * the timestamp of its last delivery; the coalescing windows still open; the
+ * live action subscriptions (module, action, args and the groups they hold);
+ * and the grand totals — where each live subscription counts once, however
+ * many channel groups it entered. Always available — the app decides how (and
+ * with what guard) to expose it; the dev server exposes it as
+ * `GET /_channel-inspect`.
  */
 export declare function inspectChannels(): ChannelInspectReport;
 /** Test-only. Drops every live connection, group and open window. */
 export declare function __resetChannels(): void;
 /**
- * Executes the connection's loader with the connection's own principal and
+ * Executes the connection's data source (the loader of a page connection, the
+ * action of a live subscription) with the connection's own principal and
  * pushes the result as a snapshot. Per-connection execution (rather than one
  * execution per partition) is deliberate: every subscriber always receives the
  * snapshot computed with its own scope, which makes the homogeneous-partition
@@ -286,8 +354,8 @@ export declare function __resetChannels(): void;
  * amortizes is the number of *rounds*, not the executions inside one — a single
  * computation serving the whole partition is a later slice.
  *
- * A loader that throws reports the failure on the connection (`error` event)
- * instead of dying silently; a loader that returns a `Response` (a redirect
+ * A source that throws reports the failure on the connection (`error` event)
+ * instead of dying silently; a source that returns a `Response` (a redirect
  * short-circuit) has no state to send.
  */
 export declare function pushSnapshot(conn: ChannelConnection): Promise<TelemetryStatus>;
@@ -375,3 +443,41 @@ export declare function parseRouteParamsQuery(raw: string | undefined | null, de
  * whose partition no longer holds.
  */
 export declare function registerChannelRoute(app: Hono, path: string, channel: string, module: RouteModule, moduleId: string, middlewares: MiddlewareHandler[]): void;
+/** Query key carrying the subscription's declared args. */
+export declare const LIVE_ARGS_QUERY = "_args";
+/**
+ * The serialized-args ceiling of a live action subscription, in bytes. Args
+ * travel on the URL — the ceiling keeps the address an address, not a payload;
+ * a bigger read wants an action call plus channels on the page.
+ */
+export declare const LIVE_ARGS_MAX_BYTES = 4096;
+/**
+ * Parses and validates the `?_args=` payload of a live action subscription.
+ *
+ * The client declares the args of the tab it opened; they are the subscription's
+ * identity (a change reconnects) and the `body` of every re-execution. An
+ * absent payload is the empty object — a live action may take no arguments.
+ */
+export declare function parseLiveArgsQuery(raw: string | undefined | null): {
+    args: Record<string, unknown>;
+    error: string | null;
+};
+/**
+ * Registers the internal SSE route of one declared live action:
+ * `GET /_live/{moduleId}/{actionName}`, inheriting the route node's
+ * middlewares — the subscription is guarded exactly like the action call and
+ * the page are.
+ *
+ * The action runs once on subscribe (the snapshot of connection is the whole
+ * loading gesture — no initial POST exists) and once per emit in any of the
+ * declared channels, always with the args declared in the subscription as
+ * `body`. The subscription enters the groups of every declared channel: an
+ * emit in any one delivers.
+ *
+ * Guards are loud: an action that does not exist in the module, or a channel
+ * with no entry in `app/channels.ts`, is an explicit error — never a silent
+ * inert route. Args above `LIVE_ARGS_MAX_BYTES` reject the subscription with
+ * 400, naming the action and the limit; a scope that resolves to nothing (or
+ * throws) denies it with 403.
+ */
+export declare function registerLiveActionRoute(app: Hono, path: string, actionName: string, channels: readonly string[], module: RouteModule, moduleId: string, middlewares: MiddlewareHandler[]): void;