@mauroandre/velojs 0.0.26 → 0.0.27

package/README.md

@@ -571,7 +571,7 @@ Because endpoints live in `routes.tsx`, the testing toolkit sees them automatica
 const res = await app.post("/api/github/webhook", { body: {...}, headers: {...} });
 ```
 
-Full documentation: [site/docs/17-endpoints.md](./site/docs/17-endpoints.md).
+Full documentation: [site/docs/06-endpoints.md](./site/docs/06-endpoints.md).
 
 ---
 
@@ -790,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).
@@ -1279,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/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). */

package/dist/events.js

@@ -1,130 +1,165 @@
-import { getAppContext as A } from "./app-context.js";
-const M = 2e4, R = 300 * 1e3, m = "";
-function x(t) {
-  const n = A().pendingStreamRoutes.splice(0);
-  for (const l of n) l(t);
+import { getAppContext as R } from "./app-context.js";
+const D = 2e4, N = 300 * 1e3, M = "";
+function F(r) {
+  const o = R().pendingStreamRoutes.splice(0);
+  for (const a of o) a(r);
 }
-const I = /* @__PURE__ */ new Set();
-function y() {
-  return I;
+const q = /* @__PURE__ */ new Set();
+function O() {
+  return q;
 }
-function L(t = {}) {
-  if (t.broadcast && t.channel && console.warn(
+function x(r = {}) {
+  if (r.broadcast && r.channel && console.warn(
     "[velojs] createEventStream: `broadcast: true` ignores `channel`. Remove one of them — broadcast streams have no channels."
-  ), t.source && t.perChannelSource)
+  ), (r.source ? 1 : 0) + (r.perChannelSource ? 1 : 0) + (r.pipe ? 1 : 0) > 1)
     throw new Error(
-      "[velojs] createEventStream: `source` and `perChannelSource` are mutually exclusive. Use `source` for stream-wide producers or `perChannelSource` for per-channel resources, not both."
+      "[velojs] createEventStream: `source`, `perChannelSource`, and `pipe` are mutually exclusive — pick one. `source` is stream-wide, `perChannelSource` and `pipe` are per-channel (prefer `pipe` for new code)."
     );
-  const a = /* @__PURE__ */ new Map(), n = /* @__PURE__ */ new Map(), l = /* @__PURE__ */ new Set(), h = /* @__PURE__ */ new Map();
-  let c = null, w = 0;
-  const i = /* @__PURE__ */ new Map(), b = () => {
-    t.source && (c || (c = new AbortController(), Promise.resolve(
-      t.source(_, { abortSignal: c.signal })
+  const o = /* @__PURE__ */ new Map(), a = /* @__PURE__ */ new Map(), p = /* @__PURE__ */ new Set(), l = /* @__PURE__ */ new Map();
+  let f = null, i = 0;
+  const h = /* @__PURE__ */ new Map(), S = /* @__PURE__ */ new Map(), d = () => {
+    r.source && (f || (f = new AbortController(), Promise.resolve(
+      r.source(v, { abortSignal: f.signal })
     ).catch((e) => {
       console.error("[velojs] event stream source threw:", e);
     })));
-  }, g = () => {
-    w > 0 || c && (c.abort(), c = null);
-  }, d = (e) => {
-    if (!t.perChannelSource || i.has(e)) return;
-    const r = new AbortController();
-    i.set(e, r);
-    const o = (s, f) => {
-      p.emit(e, s, f);
+  }, m = () => {
+    i > 0 || f && (f.abort(), f = null);
+  }, C = (e) => {
+    if (!r.perChannelSource || h.has(e)) return;
+    const t = new AbortController();
+    h.set(e, t);
+    const s = (n, u) => {
+      c.emit(e, n, u);
     };
     Promise.resolve(
-      t.perChannelSource(e, o, { abortSignal: r.signal })
-    ).catch((s) => {
+      r.perChannelSource(e, s, { abortSignal: t.signal })
+    ).catch((n) => {
       console.error(
         `[velojs] perChannelSource threw for channel "${e}":`,
-        s
+        n
       );
     });
-  }, S = (e) => {
-    const r = i.get(e);
-    r && (r.abort(), i.delete(e));
+  }, P = (e) => {
+    const t = h.get(e);
+    t && (t.abort(), h.delete(e));
+  }, w = (e, t) => {
+    if (!r.pipe || S.has(e) || !t)
+      return;
+    const s = new AbortController();
+    S.set(e, s);
+    let n = !1;
+    const u = (g, _) => {
+      c.emit(e, g, _);
+    }, A = () => c.close(e), j = () => {
+      n = !0;
+    };
+    Promise.resolve(
+      r.pipe({
+        send: u,
+        keepOpen: j,
+        close: A,
+        abortSignal: s.signal,
+        c: t.c,
+        params: t.params,
+        query: t.query,
+        channel: e
+      })
+    ).then(() => {
+      s.signal.aborted || n || c.close(e);
+    }).catch((g) => {
+      console.error(
+        `[velojs] stream pipe threw for channel "${e}":`,
+        g
+      ), s.signal.aborted || c.close(e);
+    });
+  }, E = (e) => {
+    const t = S.get(e);
+    t && (t.abort(), S.delete(e));
   };
-  function _(e, r, o) {
-    let s, f, u;
-    if (!!t.broadcast ? (s = m, f = e, u = r) : (s = e, f = r, u = o), l.has(s)) {
+  function v(e, t, s) {
+    let n, u, A;
+    if (!!r.broadcast ? (n = M, u = e, A = t) : (n = e, u = t, A = s), p.has(n)) {
       console.warn(
-        `[velojs] emit() called on closed channel "${s}" — ignored. Reopen the channel by emitting to a fresh ID, or remove the close() call.`
+        `[velojs] emit() called on closed channel "${n}" — ignored. Reopen the channel by emitting to a fresh ID, or remove the close() call.`
       );
       return;
     }
-    if (u?.snapshot) {
-      const v = n.get(s) ?? [];
-      v.push(f);
-      const T = t.bufferSize ?? 1 / 0;
-      v.length > T && v.splice(0, v.length - T), n.set(s, v);
+    if (A?.snapshot) {
+      const _ = a.get(n) ?? [];
+      _.push(u);
+      const I = r.bufferSize ?? 1 / 0;
+      _.length > I && _.splice(0, _.length - I), a.set(n, _);
     }
-    const E = a.get(s);
-    if (E)
-      for (const v of E) v(f);
+    const g = o.get(n);
+    if (g)
+      for (const _ of g) _(u);
   }
-  function C(e = m) {
-    if (l.has(e)) return;
-    l.add(e);
-    const r = a.get(e);
-    if (r)
-      for (const f of r) f.close();
-    const o = t.retainMs ?? R, s = h.get(e);
-    s && clearTimeout(s), h.set(
+  function T(e = M) {
+    if (p.has(e)) return;
+    p.add(e);
+    const t = o.get(e);
+    if (t)
+      for (const u of t) u.close();
+    const s = r.retainMs ?? N, n = l.get(e);
+    n && clearTimeout(n), l.set(
       e,
       setTimeout(() => {
-        n.delete(e), h.delete(e), l.delete(e);
-      }, o)
+        a.delete(e), l.delete(e), p.delete(e);
+      }, s)
     );
   }
-  const p = {
-    emit: _,
-    close: C,
+  const c = {
+    emit: v,
+    close: T,
     __isVeloEventStream: !0,
-    __config: t,
-    __listeners: a,
-    __buffers: n,
-    __path: t.path,
-    __onConnect(e, r) {
-      let o = a.get(e);
-      const s = !o || o.size === 0;
-      o || (o = /* @__PURE__ */ new Set(), a.set(e, o)), o.add(r), w++, b(), s && d(e);
+    __config: r,
+    __listeners: o,
+    __buffers: a,
+    __path: r.path,
+    __onConnect(e, t, s) {
+      let n = o.get(e);
+      const u = !n || n.size === 0;
+      n || (n = /* @__PURE__ */ new Set(), o.set(e, n)), n.add(t), i++, d(), u && (C(e), w(e, s));
     },
-    __onDisconnect(e, r) {
-      const o = a.get(e);
-      o && (o.delete(r), o.size === 0 && (a.delete(e), S(e)), w--, g());
+    __onDisconnect(e, t) {
+      const s = o.get(e);
+      s && (s.delete(t), s.size === 0 && (o.delete(e), P(e), E(e)), i--, m());
     },
     __reset() {
-      for (const e of a.values())
-        for (const r of e)
+      for (const e of o.values())
+        for (const t of e)
           try {
-            r.close();
+            t.close();
           } catch {
           }
-      a.clear(), n.clear(), l.clear();
-      for (const e of h.values()) clearTimeout(e);
-      h.clear(), c && (c.abort(), c = null);
-      for (const e of i.values()) e.abort();
-      i.clear(), w = 0;
+      o.clear(), a.clear(), p.clear();
+      for (const e of l.values()) clearTimeout(e);
+      l.clear(), f && (f.abort(), f = null);
+      for (const e of h.values()) e.abort();
+      h.clear();
+      for (const e of S.values()) e.abort();
+      S.clear(), i = 0;
     }
   };
-  return t.path && A().pendingStreamRoutes.push((e) => {
-    P(e, t.path, p, t.middlewares ?? []);
-  }), I.add(p), p;
+  return r.path && R().pendingStreamRoutes.push((e) => {
+    k(e, r.path, c, r.middlewares ?? []);
+  }), q.add(c), c;
 }
-function B(t) {
-  return async (a, { abortSignal: n }) => {
-    for (; !n.aborted; ) {
+function z(r) {
+  return async (b, { abortSignal: o }) => {
+    for (; !o.aborted; ) {
       try {
-        await t.tick(a);
-      } catch (l) {
-        console.error("[velojs] poll tick threw:", l);
+        await r.tick(b);
+      } catch (a) {
+        console.error("[velojs] poll tick threw:", a);
       }
-      await new Promise((l) => {
-        const h = setTimeout(l, t.intervalMs);
-        n.addEventListener(
+      await new Promise((a) => {
+        const p = setTimeout(a, r.intervalMs);
+        o.addEventListener(
           "abort",
           () => {
-            clearTimeout(h), l();
+            clearTimeout(p), a();
           },
           { once: !0 }
         );
@@ -132,70 +167,74 @@ function B(t) {
     }
   };
 }
-function j(t) {
-  return t.req.query("channel") ?? m;
+function L(r) {
+  return r.req.query("channel") ?? M;
 }
-function P(t, a, n, l = []) {
-  const h = async (c) => {
-    const { streamSSE: w } = await import("hono/streaming");
+function k(r, b, o, a = []) {
+  const p = async (l) => {
+    const { streamSSE: f } = await import("hono/streaming");
     let i;
-    if (n.__config.broadcast)
-      i = m;
+    if (o.__config.broadcast)
+      i = M;
     else {
-      const d = n.__config.channel ?? j;
-      let S;
+      const d = o.__config.channel ?? L;
+      let m;
       try {
-        S = await d(c);
-      } catch (_) {
-        return console.error("[velojs] channel resolver threw:", _), c.json({ error: "internal" }, 500);
+        m = await d(l);
+      } catch (C) {
+        return console.error("[velojs] channel resolver threw:", C), l.json({ error: "internal" }, 500);
       }
-      if (S == null)
-        return c.json({ error: "forbidden" }, 403);
-      i = S;
+      if (m == null)
+        return l.json({ error: "forbidden" }, 403);
+      i = m;
     }
-    const b = n.__config.heartbeatMs, g = b === !1 ? 0 : b ?? M;
-    return w(c, async (d) => {
-      const S = n.__buffers.get(i);
-      if (S && S.length > 0 && await d.writeSSE({
+    const h = o.__config.heartbeatMs, S = h === !1 ? 0 : h ?? D;
+    return f(l, async (d) => {
+      const m = o.__buffers.get(i);
+      if (m && m.length > 0 && await d.writeSSE({
         event: "snapshot",
-        data: JSON.stringify(S)
-      }), n.__config.snapshot) {
-        const u = await n.__config.snapshot(
-          i === m ? void 0 : i
+        data: JSON.stringify(m)
+      }), o.__config.snapshot) {
+        const t = await o.__config.snapshot(
+          i === M ? void 0 : i
         );
-        u !== void 0 && await d.writeSSE({
+        t !== void 0 && await d.writeSSE({
           event: "snapshot",
-          data: JSON.stringify(u)
+          data: JSON.stringify(t)
         });
       }
-      let _;
-      const C = new Promise((u) => {
-        _ = u;
+      let C;
+      const P = new Promise((t) => {
+        C = t;
       });
-      let p = !1, e = null, r = Promise.resolve();
-      const o = (u) => (r = r.then(() => d.writeSSE(u)).catch(() => {
-      }), r), s = () => {
-        p || (p = !0, e && clearInterval(e), n.__onDisconnect(i, f), _());
-      }, f = ((u) => {
-        p || (o({ data: JSON.stringify(u) }), n.__config.closeOn?.(u) && r.then(() => {
-          d.close(), s();
+      let w = !1, E = null, v = Promise.resolve();
+      const T = (t) => (v = v.then(() => d.writeSSE(t)).catch(() => {
+      }), v), c = () => {
+        w || (w = !0, E && clearInterval(E), o.__onDisconnect(i, e), C());
+      }, e = ((t) => {
+        w || (T({ data: JSON.stringify(t) }), o.__config.closeOn?.(t) && v.then(() => {
+          d.close(), c();
         }));
       });
-      f.close = () => {
-        p || (o({ event: "close", data: "" }), r.then(() => {
-          d.close(), s();
+      e.close = () => {
+        w || (T({ event: "close", data: "" }), v.then(() => {
+          d.close(), c();
         }));
-      }, n.__onConnect(i, f), e = g > 0 ? setInterval(() => {
-        p || o({ event: "heartbeat", data: "" });
-      }, g) : null, d.onAbort(s), await C;
+      }, o.__onConnect(i, e, {
+        c: l,
+        params: l.req.param(),
+        query: l.req.query()
+      }), E = S > 0 ? setInterval(() => {
+        w || T({ event: "heartbeat", data: "" });
+      }, S) : null, d.onAbort(c), await P;
     });
   };
-  l.length > 0 ? t.on(["GET"], [a], ...l, h) : t.on(["GET"], [a], h);
+  a.length > 0 ? r.on(["GET"], [b], ...a, p) : r.on(["GET"], [b], p);
 }
 export {
-  L as createEventStream,
-  x as flushPendingStreamRoutes,
-  y as getRegisteredStreams,
-  B as poll,
-  P as registerStreamHandler
+  x as createEventStream,
+  F as flushPendingStreamRoutes,
+  O as getRegisteredStreams,
+  z as poll,
+  k as registerStreamHandler
 };

package/dist/hooks.d.ts

@@ -1,5 +1,6 @@
 import { type Signal } from "@preact/signals";
 import type { EventStream } from "./events.js";
+import type { SocketStub } from "./sockets.js";
 export declare const __veloUpdatePending: Signal<boolean>;
 /**
  * Força o signal a notificar mudanças após mutação de propriedades aninhadas
@@ -149,3 +150,58 @@ export declare function useEventStream<TEvent, TSnapshot = TEvent>(stream: Event
     closed: Signal<boolean>;
     error: Signal<Error | null>;
 };
+type SocketStatus = "connecting" | "open" | "closed";
+export interface UseSocketOptions {
+    /** Optional channel; appended as `?channel=...` to the socket URL. */
+    channel?: string;
+    /** Called for every incoming message (text frame = string, binary frame = `Uint8Array`). */
+    onMessage?: (msg: string | Uint8Array) => void;
+    /** Called on successful connection. */
+    onOpen?: () => void;
+    /** Called on close (client or server). */
+    onClose?: (evt: CloseEvent) => void;
+    /** Called on socket error. */
+    onError?: (err: Event) => void;
+    /** When false, the connection is not opened. Flip to true to connect later. Default: true. */
+    enabled?: boolean;
+}
+export interface UseSocketApi {
+    /**
+     * Send a message. Strings and `Uint8Array` are sent as-is;
+     * objects are auto-serialized with `JSON.stringify`.
+     *
+     * Buffered if called before the socket is open — dropped once closed.
+     */
+    send: (msg: string | Uint8Array | object) => void;
+    /** Close the socket (client-initiated). */
+    close: (code?: number, reason?: string) => void;
+    /** `"connecting" | "open" | "closed"`. Reactive. */
+    status: Signal<SocketStatus>;
+    /** Last received message. Reactive. */
+    lastMessage: Signal<string | Uint8Array | null>;
+    /** Last socket error, if any. Reactive. */
+    error: Signal<Event | null>;
+}
+/**
+ * Subscribes to a WebSocket declared via the `socket_*` convention.
+ *
+ * The hook opens the connection on mount (when `enabled !== false`) and closes
+ * it on unmount or when `channel` / `stub` / `enabled` change.
+ *
+ * **No auto-reconnect.** If the server closes the socket, `status.value`
+ * becomes `"closed"` and stays that way — user flow decides whether to
+ * reconnect (typically by re-mounting or toggling `enabled`).
+ *
+ * ```tsx
+ * const { send, status, lastMessage } = useSocket(socket_terminal, {
+ *     channel: workerId,
+ *     onMessage: (msg) => { ... },
+ * });
+ *
+ * send({ type: "resize", cols: 80, rows: 24 });
+ * ```
+ */
+export declare function useSocket(stub: SocketStub | {
+    __path: string;
+}, options?: UseSocketOptions): UseSocketApi;
+export {};