@mauroandre/velojs 0.0.56 → 0.0.57

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

@@ -1,6 +1,6 @@
 ---
 name: velojs-live-loader
-description: "Keep a loader value faithful to server state in real time: declare `channels` next to the loader, map each channel to a partition resolver in `app/channels.ts`, and signal changes server-side with `emit()` — by name (the runtime re-executes the loader) or with a typed `Partial` slice when the producer already holds the value. Use when a page value must track server state over time instead of being fetched once."
+description: "Keep a loader value faithful to server state in real time: declare `channels` next to the loader, map each channel to a partition resolver in `app/channels.ts`, and signal changes server-side with `emit()` — by name (the runtime re-executes the loader) or with a typed `Partial` slice when the producer already holds the value. Covers routes with `:params` (the client declares the address it is seeing, the server validates it) and the group lifecycle (`onGroupOpen`/`onGroupClose`) for sources with a cost of life. Use when a page value must track server state over time instead of being fetched once."
 ---
 
 # Live loader
@@ -30,9 +30,11 @@ export const Component = () => {
 // 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}`,
+        // On subscribe the ctx is { user, params }: the principal materialized
+        // in c.get("user") and the route params the connection declared.
+        // On emit it is the object the producer built, with the fields this
+        // scope consumes. Returns the partition key.
+        scope: ({ user }) => `team:${user.teamId}`,
     },
 };
 ```
@@ -41,7 +43,7 @@ export const channels = {
 // anywhere server-side: an action, server.tsx, a scheduler, a webhook
 import { emit } from "@mauroandre/velojs/server";
 
-await emit("teamExpenses", { teamId: 7 });
+await emit("teamExpenses", { user: { teamId: 7 } });
 ```
 
 `export const channels = [...]` is the whole opt-in. A module without it behaves exactly as before — no connection, no cost.
@@ -50,10 +52,69 @@ await emit("teamExpenses", { teamId: 7 });
 
 - 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, so `requireAuth`/`requireMaster` guard the subscription exactly as they guard the page.
 - After hydration the client opens one connection per (module, channel) of the rendered hierarchy — layouts and pages alike — and closes it on unmount (SPA navigation, page close). 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` by channel name reaches both.
-- Every new connection immediately receives the **current state**, computed by re-executing the loader with that connection's own principal. The pane never shows the SSR value while the server has already moved on, and a reconnect is a new connection with a new snapshot — no extra refetch.
-- `emit(channel, ctx)` resolves the partition with the same `scope`, finds the connections of that partition and pushes a fresh snapshot to each — the loader re-executed with each connection's own principal. Connections of other partitions receive nothing. A channel with no subscribers is a no-op; a channel with no entry in `app/channels.ts` throws immediately, naming it.
+- Every new connection immediately receives the **current state**, computed by re-executing the loader with that connection's own principal and route params. The pane never shows the SSR value while the server has already moved on, and a reconnect is a new connection with a new snapshot — no extra refetch.
+- `emit(channel, ctx)` resolves the partition with the same `scope` — the producer builds the same `{ user, params }` shape with the fields its scope consumes — finds the connections of that partition and pushes a fresh snapshot to each, the loader re-executed with each connection's own principal and route params. Connections of other partitions receive nothing. A channel with no subscribers is a no-op; a channel with no entry in `app/channels.ts` throws immediately, naming it.
 - The snapshot **replaces** the module's loader data, so the component reading `data.value` re-renders on its own. No subscription code, no merge, no manual refresh.
 
+## Routes with `:params`
+
+A channel declared in a module whose route declares `:params` — a page `/projeto/:id`, a layout — partitions per **resource**. The address travels with the connection, but it is not the client choosing its scope: the client **declares** the route it is already seeing (the same information `?_data=1` sends on every SPA navigation), and the server **decides** — validates the shape against the module's path and the policy in the `scope`.
+
+```tsx
+// app/projeto/Projeto.tsx — the route /projeto/:id
+export const loader = async ({ params }: LoaderArgs) => ({
+    arquivos: await projetoService.arquivos(params.id),   // params.id arrives, always
+});
+export const channels = ["projetoArquivos"];
+```
+
+```ts
+// app/channels.ts
+export const channels = {
+    projetoArquivos: {
+        // On subscribe the scope receives { user, params }: the resource is
+        // validated against the principal (ownership) and the key derived
+        // from it.
+        scope: ({ user, params }) => {
+            if (!params?.id) return null;
+            if (user && !podeVer(user, params.id)) return null;   // 403
+            return `projeto:${params.id}`;
+        },
+        // The emit side is trusted server code: it builds the same shape with
+        // the fields the scope consumes — for a resource channel, the params
+        // are the whole address (see `emit("projetoArquivos", { params: … })`
+        // in the group lifecycle example below).
+    },
+};
+```
+
+- **Extraction (client).** The connection of a module extracts the params its route declares, matching the module's `fullPath` as a **prefix** of the pathname: a layout declared at `/projeto/:id` covers `/projeto/7/sala` and extracts `id=7` — the child's suffix takes no part. A path with a catch-all (`/docs/*`) declares no `:` key: the connection travels by principal only. The params go serialized in one query param, `?_route=<json>`.
+- **Validation (server).** The runtime checks the received keys against the `:params` of the module's declared path. A key the path does not declare rejects the subscription with **400**, naming what is wrong — a declaration is not free input. Values are always URL strings.
+- **Policy (scope).** The partition resolves with the validated params: it is the **relevance** of the group (only the connections of that resource wake up on an emit) with the **authorization** validated on entry and re-derived on every emit, now with the connection's stored params.
+- **The loader re-executes** with `{ params, query, c }` of the connection — `params.id` filled exactly as on the rendered page. The internal `_route` key is transport, never data: the query the loader sees excludes it.
+- **The connection is keyed by the extracted params**, not by the pathname. `/projeto/7` → `/projeto/9` closes the old connection and opens a new one (with a snapshot on connect); `/projeto/7` → `/projeto/7/sala` does **not** reconnect — the child's suffix is not part of the connection's identity.
+
+## Group lifecycle: `onGroupOpen` / `onGroupClose`
+
+A source with a **cost of life** — a filesystem watcher, a process, a subscription to an external service — must not run forever for an empty group. The channel definition declares when it should live:
+
+```ts
+export const channels = {
+    projetoArquivos: {
+        scope: ({ params }) => (params?.id ? `projeto:${params.id}` : null),
+        onGroupOpen: ({ params }) =>
+            watchers.armar(params.id, () => emit("projetoArquivos", { params: { id: params.id } })),
+        onGroupClose: ({ partition }) => watchers.desarmar(),
+    },
+};
+```
+
+- The **first** connection of a group (channel + partition) fires `onGroupOpen({ partition, params })` and the **last** one fires `onGroupClose({ partition })` — by any cause: disconnect, idle timeout, partition revalidation. A second connection of the same group fires nothing; one that arrives while the close hook is still running joins the surviving group without opening it — the runtime re-arms the group when the disarm finishes, so a live group is never left without its source.
+- Both hooks may be async and are **awaited**: on open, before the connect snapshot (the source is armed before the first data arrives); on close, before the group is discarded (the watcher is disarmed before the group stops existing).
+- A hook that throws (or rejects) is logged loudly, naming channel and partition, and the group continues: the connect snapshot still delivers data from the cold source, the live data simply does not arrive until it is fixed — and the log is what says so.
+- The `params` of `onGroupOpen` are the declared params of the connection that opened the group. They are identical across the group only when the partition derives from them (a watcher per resource). A channel partitioned by **principal**, declared in a module with `:params`, mixes resources in the same group: the hook's params are the first connection's and are arbitrary for the rest — such a channel must not consume them.
+- The hook is infrastructure, not policy: it does not receive `user`.
+
 ## Two ways to emit
 
 The emit has two modes, and the difference is *who knows the new value*.
@@ -66,10 +127,10 @@ The emit has two modes, and the difference is *who knows the new value*.
 import * as Expenses from "../app/expenses/Expenses.js";
 
 // Invalidation: Expenses.loader runs once per connection of the partition.
-await emit("teamExpenses", { teamId: 7 });
+await emit("teamExpenses", { user: { teamId: 7 } });
 
 // Slice: nothing runs; the connections merge this payload into their data.
-await emit(Expenses, "teamExpenses", { teamId: 7 }, { teamTotal: 880 });
+await emit(Expenses, "teamExpenses", { user: { teamId: 7 } }, { teamTotal: 880 });
 ```
 
 The slice is typed as `Partial` of what the module's loader returns:
@@ -84,11 +145,11 @@ export const loader = async ({ c }: LoaderArgs) => {
 };
 
 // OK — known key, right type
-await emit(Expenses, "teamExpenses", { teamId: 7 }, { teamTotal: 880 });
+await emit(Expenses, "teamExpenses", { user: { teamId: 7 } }, { teamTotal: 880 });
 // tsc error — the key does not exist in the loader's return
-await emit(Expenses, "teamExpenses", { teamId: 7 }, { total: 880 });
+await emit(Expenses, "teamExpenses", { user: { teamId: 7 } }, { total: 880 });
 // tsc error — wrong value type
-await emit(Expenses, "teamExpenses", { teamId: 7 }, { teamTotal: "880" });
+await emit(Expenses, "teamExpenses", { user: { teamId: 7 } }, { teamTotal: "880" });
 ```
 
 Why does the module take part in the address? Because the same channel can be declared by a layout **and** by a page, and each has its own loader and its own data shape — a slice is the shape of one of them. The runtime delivers the slice only to the connections of the pair `(module, channel)`; `emit(channel, ctx)` by name keeps reaching every module that declares the channel.
@@ -108,12 +169,12 @@ The client merges every slice into the module's current value, with rules short
 
 ```ts
 // Current data: { teamTotal: 4, expenses: ["mercado", "luz"] }
-await emit("teamExpenses", { teamId: 7 });                          // whole value
-await emit(Expenses, "teamExpenses", { teamId: 7 }, { teamTotal: 9 });
+await emit("teamExpenses", { user: { teamId: 7 } });               // whole value
+await emit(Expenses, "teamExpenses", { user: { teamId: 7 } }, { teamTotal: 9 });
 // → { teamTotal: 9, expenses: ["mercado", "luz"] }
 
 // Removing "luz" is re-sending the whole list without it
-await emit(Expenses, "teamExpenses", { teamId: 7 }, { expenses: ["mercado"] });
+await emit(Expenses, "teamExpenses", { user: { teamId: 7 } }, { expenses: ["mercado"] });
 // → { teamTotal: 9, expenses: ["mercado"] }
 ```
 
@@ -144,7 +205,7 @@ The window also decides what `await emit(…)` waits for. With the window off (`
 
 `connections` is the size of the group **at the instant of the gesture** — 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. The log is off with `registerChannels(channels, { logEmits: false })`.
 
-**Partition revalidation.** Before delivering anything (a re-executed snapshot or a slice), 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 and `freshness` goes `"stale"`, no data of a group it left. 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 talks to an external service must handle its own failures. Only the partition is revalidated; an expired session is covered by the normal request pipeline on the next access.
+**Partition revalidation.** Before delivering anything (a re-executed snapshot or a slice), the runtime re-derives each connection's partition by running the `scope` again with the ctx captured at subscribe — the principal and the validated route params of that connection. A connection whose partition moved — or whose scope now returns `null` — is removed from the group and closed: the client sees the connection closed and `freshness` goes `"stale"`, no data of a group it left. 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 talks to an external service must handle its own failures. Only the partition is revalidated; an expired session is covered by the normal request pipeline on the next access.
 
 ## Transport: heartbeat, idle timeout and the proxy
 
@@ -223,7 +284,7 @@ On a page with no `channels` the fields exist, the record is empty and the aggre
 
 ## 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 somewhere else should set it in `"user"` too:
+On subscribe the `scope` receives `{ user, params }`. `user` is whatever a middleware materialized under the house key `"user"` — the same key the stream/socket channel resolvers use; a middleware that materializes the principal somewhere else should set it in `"user"` too:
 
 ```ts
 const auth = async (c, next) => {
@@ -234,8 +295,11 @@ const auth = async (c, next) => {
 };
 ```
 
-- 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** derives from the query string or from any client input. A client cannot choose which subject's data it receives.
+`params` are the route params the connection declared, already validated against the module's path. On emit the same scope receives the object the producer built, with the fields it consumes (`{ params: { id: 7 } }` for a resource channel, `{ user: … }` for a principal one).
+
+- No authenticated principal → `user` is `undefined`. A public channel ignores it (`() => "all"`); an authenticated one returns `null`, which denies the subscription with **403**. An app that does not materialize a principal at all (the border is a network guard, e.g. loopback) writes `({ params }) => …`.
+- **Declare, not choose.** `params` are not an authorization input: they are the address the client is already seeing, validated by shape on the server and by policy in the `scope`. The partition **never** derives from the query string or from any other client input.
+- A scope that **throws** on subscribe denies with **403** and logs loudly, naming the channel — fail-closed, never silent. A scope that resolves to `null` denies the same way.
 - No scope at all → the channel is public (`() => "all"`).
 
 ## State or flow?
@@ -257,6 +321,8 @@ The failures that would otherwise be silent are explicit:
 
 - `channels` in a module **without** a `loader`: error in the dev server and in the build — there is nothing to synchronize.
 - A channel **without an entry** in `app/channels.ts`: error in the dev server and in the build, naming the channel.
+- Route params with a key the module's path does **not** declare: the subscription is rejected with **400**, naming the key — the client may only declare what the route declares.
+- A `scope` that **throws** on subscribe: denied with **403** and logged loudly, naming the channel.
 - `emit()` on a channel with no entry in the map: throws immediately, naming it (a typo or a rename would otherwise be a no-op). `emit()` on a valid channel with no subscribers is a no-op, no error.
 - `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, so the client opens no connection, `freshness` stays `"live"` and the build warns, naming the module.
@@ -281,10 +347,10 @@ const app = await createTestApp({
 const sub = await app.as({ user: { teamId: 7 } }).channel(Expenses, "teamExpenses");
 expect(await sub.next({ timeoutMs: 1000 })).toEqual({ teamTotal: 4 });  // connect
 
-await emit("teamExpenses", { teamId: 7 });
+await emit("teamExpenses", { user: { teamId: 7 } });
 expect(await sub.next({ timeoutMs: 1000 })).toEqual({ teamTotal: 9 });  // emit
 
-await emit(Expenses, "teamExpenses", { teamId: 7 }, { teamTotal: 880 });
+await emit(Expenses, "teamExpenses", { user: { teamId: 7 } }, { teamTotal: 880 });
 expect(await sub.next({ timeoutMs: 1000 })).toEqual({ teamTotal: 880 }); // raw slice
 
 expect(await sub.nextEvent({ timeoutMs: 1000 })).toEqual({              // discriminated
@@ -298,6 +364,18 @@ await app.close();
 
 The connection only exists after the connect snapshot, so awaiting the first `next()` before emitting is what makes the test deterministic. `next()` returns the payload exactly as it travelled on the wire (a whole snapshot or a raw slice) — the same contract as the first slice; `nextEvent()` returns the same arrivals discriminated as `{ type: "snapshot" | "slice", data }`, for the tests that care which mode delivered the update. Use one or the other: each walks its own cursor over the arrivals.
 
+A route with `:params` declares them in the connection options; the server-side validation runs for real, so a key the module's path does not declare rejects the subscription at `status === 400`:
+
+```ts
+const project = await app.channel(Project, "projetoArquivos", { params: { id: "7" } });
+expect(await project.next({ timeoutMs: 1000 })).toEqual({ id: "7", files: ["a.txt"] });
+
+const forged = await app.channel(Project, "projetoArquivos", { params: { id: "7", outro: "9" } });
+expect(forged.status).toBe(400);
+```
+
+The group hooks are testable the same way: `onGroupOpen`/`onGroupClose` fire as connections enter and leave the group (first/last), including the exits by idle and by revalidation.
+
 The toolkit registers the channels with the coalescing window off (`coalesceMs: 0`), so `await emit(…)` is the delivery. The same determinism holds for the transport clocks: `idleMs` and `heartbeatMs` default to `0` in the toolkit — no connection dies and no comment is written unless the test asks for it. A test that exercises any of the three passes it explicitly and drives it with fake timers. Note where the options go: `channels` is the map, and the registration options are a **sibling** key, `channelOptions`:
 
 ```ts
@@ -315,8 +393,11 @@ await vi.advanceTimersByTimeAsync(20);   // the window closes: one round
 | Piece | Behavior |
 |---|---|
 | `export const channels = ["name"]` | Module opt-in: one internal route and one client connection per name |
-| `app/channels.ts` | Channel name → `{ scope }`; imported by the framework |
-| `scope(ctx)` | Returns the partition key; `null` denies with 403; omitted → `"all"`. Re-derived on every emit with the principal captured at subscribe |
+| `app/channels.ts` | Channel name → `{ scope, onGroupOpen, onGroupClose }`; imported by the framework |
+| `scope(ctx)` | `{ user, params }` on subscribe, the producer's object on emit; returns the partition key; `null` denies with 403; omitted → `"all"`. Re-derived on every emit with the ctx captured at subscribe |
+| Route params | The client extracts the params the module's path declares (prefix match of `fullPath`) and sends them in `?_route=`; the server validates the keys (400 on an undeclared one) and the connection is keyed by them — moving to another resource reconnects |
+| `onGroupOpen({ partition, params })` | Fires on the first connection of a (channel, partition) group; awaited before the connect snapshot; a throw is logged and the group continues |
+| `onGroupClose({ partition })` | Fires on the last connection out of the group, by any cause (disconnect, idle, revalidation); awaited before the group is discarded |
 | `emit(channel, ctx)` | Invalidation: re-executes the loader per connection of the partition and pushes snapshots |
 | `emit(module, channel, ctx, slice)` | Slice: pushes the typed `Partial` to the connections of that (module, channel) pair — no re-execution |
 | Merge | Shallow by key, on arrival; key sent replaced whole, absent key never removes, whole lists |
@@ -326,4 +407,4 @@ await vi.advanceTimersByTimeAsync(20);   // the window closes: one round
 | `CHANNEL_SILENCE_MS` | 60000 — client-side silence window; an open connection without deliveries past it is `"stale"` |
 | `inspectChannels()` | Server-side live report: groups per (moduleId, partition) with connections and last delivery, open coalesce windows, totals |
 | `GET /_channel-inspect` | Dev-only endpoint answering `inspectChannels()` as JSON; absent in production builds |
-| `app.channel(module, name)` | Test subscription; `next()` (raw data) and `nextEvent()` (`{ type, data }`) |
+| `app.channel(module, name, opts)` | Test subscription; `opts.params` declares the route params (validated for real); `next()` (raw data) and `nextEvent()` (`{ type, data }`) |

package/dist/channels.d.ts

@@ -11,21 +11,27 @@
  *
  * ```ts
  * export const channels = {
- *     teamExpenses: { scope: (ctx) => `team:${ctx.teamId}` },
+ *     teamExpenses: { scope: ({ user }) => `team:${user?.teamId}` },
  * };
  * ```
  *
- * On subscribe the resolver receives the materialized principal (`c.get("user")`,
- * the house key); without an authenticated principal it receives `undefined`, so
- * a public channel ignores it (`() => "all"`) and an authenticated one returns
- * `null` (which denies the subscription with 403). The partition NEVER derives
- * from the query string or from any client input.
+ * On subscribe the resolver receives `{ user, params }`: `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
+ * `params` are the route params the client declared and the runtime validated
+ * against the module's path (empty for a route without `:params`). The
+ * partition NEVER derives from the query string or from any other client input;
+ * `params` are not input — they are the address the client is already seeing,
+ * validated by shape and then by the scope (ownership/permission).
  *
- * `emit(channel, ctx)` resolves the same partition key on the producer side,
- * finds the group of connections in that partition and re-executes the loader
- * for each connection — with that connection's own principal — pushing a fresh
- * snapshot down the wire. Emitting to a channel with no subscribers is a no-op;
- * emitting to a channel with no entry in the app map throws immediately.
+ * `emit(channel, ctx)` resolves the same partition key on the producer side —
+ * the producer builds the same `{ user, params }` shape with the fields its
+ * scope consumes — finds the group of connections in that partition and
+ * re-executes the loader for each connection, with that connection's own
+ * principal and route params, pushing a fresh snapshot down the wire. Emitting
+ * to a channel with no subscribers is a no-op; emitting to a channel with no
+ * entry in the app map throws immediately.
  *
  * `emit(module, channel, ctx, slice)` is the second mode, addressed to the
  * (module, channel) pair: the producer already holds the value, so it travels
@@ -35,27 +41,76 @@
  * one channel can be declared by modules with different `Data` (a layout and a
  * page), and a slice is the shape of exactly one of them.
  *
+ * A channel's group (channel + partition) has a lifecycle: the first connection
+ * arms it (`onGroupOpen({ partition, params })`) and the last one disarms it
+ * (`onGroupClose({ partition })`), both awaited — that is where a watcher with a
+ * cost of life is armed and disarmed, instead of running forever for an empty
+ * group.
+ *
  * Every emit logs one line (channel, partition, kind, connections at the
  * moment of the gesture, timestamp) unless `logEmits: false` is registered,
  * and invalidations are folded by a coalescing window per (channel, partition)
  * (`coalesceMs`, default 50, `0` disables). Before delivering anything the
- * runtime re-derives each connection's partition with the principal captured
- * on subscribe: a connection that moved (or whose scope now returns null) is
+ * runtime re-derives each connection's partition with the ctx captured on
+ * subscribe: a connection that moved (or whose scope now returns null) is
  * 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";
 /** Result of a partition resolver. `null`/`undefined` denies the subscription. */
 export type ChannelScopeResult = string | null | undefined;
+/**
+ * The ctx of a partition resolver — the same shape on both sides.
+ *
+ * On **subscribe** the runtime builds it: `user` is the materialized principal
+ * (`c.get("user")`, the house key — `undefined` when the app does not
+ * materialize one) and `params` are the route params the client declared and
+ * the runtime validated against the module's path (URL strings; empty for a
+ * route without `:params`).
+ *
+ * On **emit** the producer builds the same object with the fields its scope
+ * consumes — `{ params: { id: 7 } }` for a resource channel, `{ user: … }`
+ * for a principal one — and the same `scope` runs against it.
+ */
+export interface ChannelScopeContext {
+    user?: any;
+    params?: Record<string, any>;
+}
+/**
+ * What `onGroupOpen` receives: the partition key of the group that just got its
+ * first connection, and the validated route params of **that** connection.
+ *
+ * The params are identical across the group only when the partition derives
+ * from them (a watcher per resource — the case the hook exists for). A channel
+ * 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.
+ */
+export interface ChannelGroupOpenContext {
+    partition: string;
+    params: Record<string, string>;
+}
+/** What `onGroupClose` receives: the partition key of the group being torn down. */
+export interface ChannelGroupCloseContext {
+    partition: string;
+}
 /**
  * One entry of the app's channel map (`app/channels.ts`).
  *
- * `scope` receives the materialized principal on subscribe (`c.get("user")`)
- * and the emitter's object on emit. Returning `null` denies with 403.
- * Omitted → the channel is public (`() => "all"`).
+ * `scope` receives `{ user, params }` on subscribe and the emitter's object on
+ * emit; returning `null` denies with 403. Omitted → the channel is public
+ * (`() => "all"`).
+ *
+ * `onGroupOpen`/`onGroupClose` are the group lifecycle — armed by the first
+ * connection of a (channel, partition) group, disarmed by the last one — and
+ * may be async: the runtime awaits them (the group is only marked open after
+ * `onGroupOpen` resolves; only discarded after `onGroupClose` resolves). A hook
+ * that throws or rejects is logged loudly and the group continues.
  */
 export interface ChannelDefinition {
-    scope?: (ctx: any) => ChannelScopeResult | Promise<ChannelScopeResult>;
+    scope?: (ctx: ChannelScopeContext) => ChannelScopeResult | Promise<ChannelScopeResult>;
+    onGroupOpen?: (ctx: ChannelGroupOpenContext) => void | Promise<void>;
+    onGroupClose?: (ctx: ChannelGroupCloseContext) => void | Promise<void>;
 }
 /** The `app/channels.ts` map: channel name → partition resolver. */
 export type ChannelMap = Record<string, ChannelDefinition>;
@@ -213,7 +268,7 @@ export interface ChannelInspectReport {
  * guard) to expose it; the dev server exposes it as `GET /_channel-inspect`.
  */
 export declare function inspectChannels(): ChannelInspectReport;
-/** Test-only. Drops every live connection and closes every open window. */
+/** 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
@@ -232,16 +287,20 @@ export declare function pushSnapshot(conn: ChannelConnection): Promise<void>;
 /**
  * Signals that a channel's partition changed: every connection in that
  * partition receives a fresh snapshot (its loader re-executed with the
- * connection's own principal). Connections in other partitions receive
- * nothing; a channel with no subscribers is a no-op; a channel with no entry
- * in the app map throws immediately, naming the channel.
+ * connection's own principal and route params). Connections in other
+ * partitions receive nothing; a channel with no subscribers is a no-op; a
+ * channel with no entry in the app map throws immediately, naming the channel.
+ *
+ * The ctx is the object the same `scope` receives: the producer builds it with
+ * the fields its scope consumes (`{ params: { id: 7 } }` for a resource
+ * channel, `{ user: … }` for a principal one).
  *
  * ```ts
  * import { emit } from "@mauroandre/velojs/server";
- * await emit("teamExpenses", { teamId: 7 });
+ * await emit("teamExpenses", { user: { teamId: 7 } });
  * ```
  */
-export declare function emit(channel: string, ctx?: unknown): Promise<void>;
+export declare function emit(channel: string, ctx?: ChannelScopeContext): Promise<void>;
 /**
  * Slice mode: pushes the value the producer already holds to the connections
  * of the (module, channel) pair in the emitting partition — **without**
@@ -250,10 +309,10 @@ export declare function emit(channel: string, ctx?: unknown): Promise<void>;
  *
  * ```ts
  * import * as Expenses from "../app/expenses/Expenses.js";
- * await emit(Expenses, "teamExpenses", { teamId: 7 }, { teamTotal: 880 });
+ * await emit(Expenses, "teamExpenses", { user: { teamId: 7 } }, { teamTotal: 880 });
  * ```
  */
-export declare function emit<M extends ChannelEmitModule>(module: M, channel: string, ctx: unknown, slice: ChannelSlice<M>): Promise<void>;
+export declare function emit<M extends ChannelEmitModule>(module: M, channel: string, ctx: ChannelScopeContext, slice: ChannelSlice<M>): Promise<void>;
 /**
  * Serializes the SSE writes of one connection and never lets a failed write
  * break the chain.
@@ -273,6 +332,27 @@ export type ChannelWritePayload = {
     event: string;
     data: string;
 } | string;
+/** Query key carrying the route params the connection declares. */
+export declare const ROUTE_PARAMS_QUERY = "_route";
+/**
+ * The `:param` names a route path declares, in declaration order. A path with
+ * a catch-all (`/docs/*`) declares none: the pattern has no key to extract, so
+ * the connection travels by principal only.
+ */
+export declare function declaredRouteParams(fullPath: string | null | undefined): string[];
+/**
+ * Parses and validates the `?_route=` payload of a channel connection against
+ * the names the module's route path declares.
+ *
+ * The client declares the params of the URL it is already seeing; it is not
+ * free input: a key the module's path does not declare rejects the
+ * subscription with an explicit error, and every value is a URL string. An
+ * absent payload is the empty object — a route without `:params` sends none.
+ */
+export declare function parseRouteParamsQuery(raw: string | undefined | null, declared: readonly string[]): {
+    params: Record<string, string>;
+    error: string | null;
+};
 /**
  * Registers the internal SSE route of one declared channel:
  * `GET /_channel/{moduleId}/{channel}`, inheriting the route node's
@@ -282,8 +362,9 @@ export type ChannelWritePayload = {
  * channel with no entry in `app/channels.ts`, is an explicit error — never a
  * silent inert route.
  *
- * The principal is captured on the connection for the partition revalidation
- * of every emit, and `terminate` lets an emit close a connection whose
- * partition no longer holds.
+ * The connection carries the client-declared route params (validated here
+ * against the module's path), the principal captured for the partition
+ * revalidation of every emit, and `terminate` lets an emit close a connection
+ * whose partition no longer holds.
  */
 export declare function registerChannelRoute(app: Hono, path: string, channel: string, module: RouteModule, moduleId: string, middlewares: MiddlewareHandler[]): void;