@mauroandre/velojs 0.0.25 → 0.0.27

package/README.md

@@ -534,6 +534,47 @@ The client-side transform rewrites the import to fetch `/_action/admin/Layout/lo
 
 ---
 
+## Endpoints
+
+Declarative HTTP endpoints for anything that isn't a page — webhooks, email-verification redirects, OAuth callbacks, health checks.
+
+Declare them directly in `routes.tsx`:
+
+```tsx
+import type { AppRoutes, EndpointHandler } from "@mauroandre/velojs";
+import * as Home from "./pages/Home.js";
+import { githubWebhook } from "./webhooks/github.handler.js";
+
+export default [
+    { path: "/", module: Home },
+    { path: "/api/github/webhook", method: "POST", handler: githubWebhook },
+] satisfies AppRoutes;
+```
+
+The handler gets `{ c, params, query }` and must return a `Response`:
+
+```ts
+import type { EndpointHandler } from "@mauroandre/velojs";
+
+export const githubWebhook: EndpointHandler = async ({ c }) => {
+    const body = await c.req.json();
+    // ...verify signature, process event...
+    return c.json({ ok: true });
+};
+```
+
+Endpoints inherit parent `middlewares` and can be nested inside grouping nodes. The Vite plugin strips endpoint objects (and their handler imports) from the client bundle, so server-only code never ships to the browser.
+
+Because endpoints live in `routes.tsx`, the testing toolkit sees them automatically:
+
+```ts
+const res = await app.post("/api/github/webhook", { body: {...}, headers: {...} });
+```
+
+Full documentation: [site/docs/06-endpoints.md](./site/docs/06-endpoints.md).
+
+---
+
 ## Event Streams
 
 Push real-time updates from server to client via Server-Sent Events (SSE). Live progress, notifications, metrics, log streaming, AI tokens — anything server → client.
@@ -749,6 +790,85 @@ Only affects emits with `{ snapshot: true }`.
 
 ---
 
+## Sockets
+
+Declarative WebSocket handlers, co-located with the page that needs bidirectional communication. Use for interactive terminals, collaborative editing, live cursors — anything where the client also sends messages.
+
+Export `socket_<name>` from a page or layout, and VeloJS registers a WebSocket route at `/_socket/{moduleId}/{name}` with middleware inheritance.
+
+### Shortest example
+
+```tsx
+// app/workers/WorkerTerminal.tsx
+import type { SocketHandler } from "@mauroandre/velojs";
+import { parseJson } from "@mauroandre/velojs/sockets";
+import { useSocket } from "@mauroandre/velojs/hooks";
+
+export const socket_terminal: SocketHandler = async ({
+    incoming, send, keepOpen, abortSignal, c, params,
+}) => {
+    const session = await createTerminal(params.workerId);
+    session.on("data", (chunk) => send({ type: "data", data: chunk }));
+    abortSignal.addEventListener("abort", () => session.destroy());
+    keepOpen();
+
+    for await (const msg of parseJson<{ type: string; data?: string; cols?: number; rows?: number }>(incoming)) {
+        if (msg.type === "data" && msg.data) session.write(msg.data);
+        if (msg.type === "resize") session.resize(msg.cols!, msg.rows!);
+    }
+};
+
+export const Component = () => {
+    const { send, status } = useSocket(socket_terminal, { channel: workerId });
+    // ...
+};
+```
+
+### Handler args
+
+| Arg | Description |
+|---|---|
+| `incoming` | `AsyncIterable<string \| Uint8Array>` — raw frames. Wrap with `parseJson<T>()` for JSON auto-parse. |
+| `send(msg)` | Send a frame. `string` / `Uint8Array` pass through; `object` → `JSON.stringify`. |
+| `close(code?, reason?)` | Server-initiated close. |
+| `keepOpen()` | Required for long-lived handlers. If you return without it, the socket closes. `for await (const m of incoming)` implicitly holds the handler. |
+| `abortSignal` | Fires on disconnect / `app.close()`. Register all cleanup here. |
+| `c`, `params`, `query` | Hono context, URL params, query. Auth via `c.get("user")` from middleware. |
+
+### Middleware inheritance
+
+Middleware runs **before** the WebSocket upgrade — an `authMiddleware` that rejects returns an HTTP error and the client never sees an open socket. Same `middlewares` array on parent route nodes as pages/actions/streams.
+
+### Client hook
+
+```ts
+const { send, status, lastMessage, close } = useSocket(socket_terminal, {
+    channel: workerId,
+    onMessage: (msg) => { /* ... */ },
+});
+```
+
+- `status: Signal<"connecting" | "open" | "closed">` — reactive.
+- **No auto-reconnect** — sockets are usually stateful (pty sessions, collaborative state); blind reconnect loses state silently. Re-mount or toggle `enabled` to reconnect.
+
+### Testing
+
+```ts
+const ws = await app.socket(socket_terminal, {
+    user: { id: "alice" },
+    params: { workerId: "w42" },
+});
+ws.send({ type: "data", data: "ls\n" });
+const reply = await ws.next({ timeoutMs: 500 });
+await ws.close();
+```
+
+`app.socket()` invokes the handler in-memory and aborts on `app.close()`. **Middleware does NOT run** — pass `user` via options to shortcut `c.get("user")`; test middleware via regular endpoint tests that use the same middleware.
+
+Full reference: [site/docs/12-sockets.md](./site/docs/12-sockets.md).
+
+---
+
 ## Hooks
 
 All hooks work in both SSR and client (via AsyncLocalStorage on server, wouter/DOM on client).
@@ -1238,7 +1358,7 @@ await app.close();
 | `app.reset()` | Clear stream buffers/listeners between tests |
 | `app.close()` | Tear down everything (zero open handles guaranteed) |
 
-See [Testing docs](https://github.com/mauro-andre/velojs/blob/dev/site/docs/16-testing.md) for the full guide with patterns, isolation, and FAQ.
+See [Testing docs](https://github.com/mauro-andre/velojs/blob/dev/site/docs/17-testing.md) for the full guide with patterns, isolation, and FAQ.
 
 ---
 

package/dist/client.js

@@ -1,19 +1,46 @@
-import { jsx as r } from "preact/jsx-runtime";
-import { hydrate as l } from "preact";
-import { Router as p, Route as s, Switch as h } from "wouter-preact";
-const u = (e, o = !1) => e.map((t, n) => {
-  const c = t.module.Component;
-  if (!t.children)
-    return /* @__PURE__ */ r(s, { path: t.path || "", children: /* @__PURE__ */ r(c, {}) }, n);
-  const i = u(t.children, !!t.path);
-  return t.isRoot ? /* @__PURE__ */ r(h, { children: i }, n) : t.path ? /* @__PURE__ */ r(s, { path: t.path, nest: !0, children: /* @__PURE__ */ r(c, { children: /* @__PURE__ */ r(h, { children: i }) }) }, n) : /* @__PURE__ */ r(c, { children: /* @__PURE__ */ r(h, { children: i }) }, n);
-}), m = ({ routes: e }) => {
-  const o = u(e);
-  return /* @__PURE__ */ r(p, { children: o });
-}, R = (e) => {
-  const { routes: o } = e, t = document.querySelector("body");
-  t && l(/* @__PURE__ */ r(m, { routes: o }), t);
+import { jsx as e } from "preact/jsx-runtime";
+import { hydrate as p } from "preact";
+import { Router as f, Route as l, Switch as s } from "wouter-preact";
+const u = (r, i = !1) => {
+  const o = [];
+  for (let n = 0; n < r.length; n++) {
+    const t = r[n];
+    if (!t.module) {
+      if (t.children)
+        for (const d of u(t.children, i))
+          o.push(d);
+      continue;
+    }
+    const c = t.module.Component;
+    if (!t.children) {
+      o.push(
+        /* @__PURE__ */ e(l, { path: t.path || "", children: /* @__PURE__ */ e(c, {}) }, n)
+      );
+      continue;
+    }
+    const h = u(t.children, !!t.path);
+    if (t.isRoot) {
+      o.push(/* @__PURE__ */ e(s, { children: h }, n));
+      continue;
+    }
+    if (!t.path) {
+      o.push(
+        /* @__PURE__ */ e(c, { children: /* @__PURE__ */ e(s, { children: h }) }, n)
+      );
+      continue;
+    }
+    o.push(
+      /* @__PURE__ */ e(l, { path: t.path, nest: !0, children: /* @__PURE__ */ e(c, { children: /* @__PURE__ */ e(s, { children: h }) }) }, n)
+    );
+  }
+  return o;
+}, m = ({ routes: r }) => {
+  const i = u(r);
+  return /* @__PURE__ */ e(f, { children: i });
+}, C = (r) => {
+  const { routes: i } = r, o = document.querySelector("body");
+  o && p(/* @__PURE__ */ e(m, { routes: i }), o);
 };
 export {
-  R as startClient
+  C as startClient
 };

package/dist/events.d.ts

@@ -89,6 +89,45 @@ export type SourceFn<TEvent> = (emit: EmitFn<TEvent>, ctx: {
 export type PerChannelSourceFn<TEvent> = (channelKey: string, emit: (event: TEvent, options?: EmitOptions) => void, ctx: {
     abortSignal: AbortSignal;
 }) => void | Promise<void>;
+/**
+ * Arguments passed to a stream `pipe` handler.
+ *
+ * A `pipe` is a **per-channel producer** (same scoping as `perChannelSource`)
+ * with the unified vocabulary used across `stream_*` and `socket_*`:
+ * `send / keepOpen / close / abortSignal`. Prefer `pipe` for new code.
+ *
+ * `c`, `params`, `query` are captured from the **first** subscriber whose
+ * connect spawned the pipe on this channel. Subsequent subscribers share the
+ * same pipe instance.
+ */
+export interface StreamPipeArgs<TEvent> {
+    /** Emit an event to all current subscribers of this channel. */
+    send: (event: TEvent, options?: EmitOptions) => void;
+    /**
+     * Mark the pipe as long-running. If `pipe` returns **without** calling
+     * `keepOpen()`, the framework closes this channel (cleanup + notify subs).
+     * If `keepOpen()` is called, the pipe stays alive until the abort signal
+     * fires (last subscriber disconnected, or external `stream.close`).
+     */
+    keepOpen: () => void;
+    /** Close this channel imperatively (fires notify + schedules cleanup). */
+    close: () => void;
+    /** Fires when the last subscriber of this channel disconnects. */
+    abortSignal: AbortSignal;
+    /** Hono Context from the first subscriber's request. */
+    c: Context;
+    /** URL params from the first subscriber's request. */
+    params: Record<string, string>;
+    /** Query params from the first subscriber's request. */
+    query: Record<string, string>;
+    /** The channel key this pipe is running for. Empty string for broadcast streams. */
+    channel: string;
+}
+/**
+ * A `pipe` handler — per-channel producer with unified vocabulary.
+ * Mutually exclusive with `source` and `perChannelSource`.
+ */
+export type StreamPipeFn<TEvent> = (args: StreamPipeArgs<TEvent>) => void | Promise<void>;
 /**
  * Async-capable channel resolver. Returns a channel ID, or `null`/`undefined`
  * to reject the connection (framework responds 403).
@@ -172,9 +211,21 @@ export interface EventStreamConfig<TEvent, TSnapshot = TEvent> {
      * external pub/sub subscriptions). The `emit` provided is bound to the current
      * channel — call it with just the value.
      *
-     * Mutually exclusive with `source`.
+     * Mutually exclusive with `source` and `pipe`.
      */
     perChannelSource?: PerChannelSourceFn<TEvent>;
+    /**
+     * Per-channel producer with the unified `send / keepOpen / abortSignal`
+     * vocabulary shared with `socket_*`. Invoked when the first subscriber of a
+     * channel connects. Aborted when the last subscriber of that channel
+     * disconnects.
+     *
+     * Prefer `pipe` for new code. `source` and `perChannelSource` remain for
+     * backwards compatibility.
+     *
+     * Mutually exclusive with `source` and `perChannelSource`.
+     */
+    pipe?: StreamPipeFn<TEvent>;
     /**
      * Time (ms) the per-channel snapshot buffer is retained after `close()`.
      * Reconnecting clients within this window still see the final state.
@@ -217,8 +268,12 @@ export interface EventStream<TEvent, TSnapshot = TEvent> {
     readonly __buffers: Map<string, TEvent[]>;
     /** Internal: assigned URL path (set by standalone or by stream_* discovery) */
     __path: string | undefined;
-    /** Internal: source lifecycle hook */
-    __onConnect(channelKey: string, listener: StreamListener<TEvent>): void;
+    /** Internal: source lifecycle hook. `ctx` is used to seed `pipe` when it spawns. */
+    __onConnect(channelKey: string, listener: StreamListener<TEvent>, ctx?: {
+        c: Context;
+        params: Record<string, string>;
+        query: Record<string, string>;
+    }): void;
     /** Internal: source lifecycle hook */
     __onDisconnect(channelKey: string, listener: StreamListener<TEvent>): void;
     /** @internal Test-only: reset all transient state (buffers, listeners, controllers, timers). */