@owlmeans/client-socket 0.1.18-rc.3 → 0.1.18-rc.30

package/README.md

@@ -1,29 +1,33 @@
 # @owlmeans/client-socket
 
-React hook and factory for WebSocket connections via OwlMeans module routing.
+React hook and factory for WebSocket connections via OwlMeans entrypoint routing.
 
 ## Overview
 
-- `ws(module, request?)` — creates a `Connection` by resolving the module URL and opening a WebSocket
-- `useWs(module, request?)` — React hook wrapping `ws()` with lifecycle management
+- `ws(entrypoint, request?)` — creates a `Connection` from the entrypoint's URL and opens a WebSocket
+- `useWs(entrypoint, request?)` — React hook wrapping `ws()` with lifecycle management; pass a
+  protocol-bound entrypoint directly
 - The returned `Connection` implements `@owlmeans/socket`'s `Connection` interface
 
 ## Installation
 
 ```bash
-bun add @owlmeans/client-socket
+bun add @owlmeans/client-socket@^0.1.18-rc.30
 ```
 
 ## Usage
 
-Connect to a WebSocket module and observe events:
+Connect to a WebSocket entrypoint and observe events:
 
 ```typescript
 import { useWs } from '@owlmeans/client-socket'
 import { MessageType } from '@owlmeans/socket'
+import { useContext } from '@owlmeans/web-client'
+import { appProtocols } from 'my-app-common'
 
 function ThinkingPanel({ storyId }: { storyId: string }) {
-  const conn = useWs('story-thinking', { params: { id: storyId } })
+  const context = useContext()
+  const conn = useWs(context.entrypoint(appProtocols.api.storyThinking), { params: { id: storyId } })
 
   useEffect(() => {
     if (!conn) return
@@ -39,27 +43,29 @@ Direct connection (non-hook):
 
 ```typescript
 import { ws } from '@owlmeans/client-socket'
-import type { ClientModule } from '@owlmeans/client-module'
+import { appProtocols } from 'my-app-common'
 
-const wsModule = context.module<ClientModule<string>>('story-thinking')
-const connection = await ws(wsModule, { params: { id: storyId } })
+const wsEntrypoint = context.entrypoint(appProtocols.api.storyThinking)
+const connection = await ws(wsEntrypoint, { params: { id: storyId } })
 ```
 
 ## API
 
-### `ws(module, request?): Promise<Connection>`
+### `ws(entrypoint, request?): Promise<Connection>`
 
-Resolves the module URL, opens a WebSocket, and returns a `Connection` once the socket opens.
+Builds the entrypoint's URL, opens a WebSocket, and returns a `Connection` once the socket opens.
 
-### `useWs(module, request?): Connection | null`
+### `useWs(entrypoint, request?): Connection | null`
 
-React hook version of `ws()`. Returns `null` while connecting. Manages connection lifecycle (opens on mount, closes on unmount).
+React hook version of `ws()`. Returns `null` while connecting. Manages connection lifecycle (opens
+on mount, closes on unmount). Alias input is reserved for a dynamic external boundary; application
+code calls `context.entrypoint(protocol)` first.
 
 ## Related Packages
 
 - [`@owlmeans/socket`](../socket) — `Connection` interface with `notify`, `observe`, `call` methods
 - [`@owlmeans/server-socket`](../server-socket) — server-side connection handler
-- [`@owlmeans/client-module`](../client-module) — `ClientModule` passed to `ws()`
+- [`@owlmeans/client-entrypoint`](../client-entrypoint) — protocol bindings passed to `ws()`
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
@@ -69,7 +75,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills
+npx @owlmeans/agent-skills@^0.1.18-rc.28
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/client-socket",
-  "version": "0.1.18-rc.0",
-  "generatedAt": "2026-08-16T22:20:50.502Z",
+  "version": "0.1.18-rc.30",
+  "generatedAt": "2026-09-17T08:16:11.216Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/client-socket/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: client-socket
-description: How to use @owlmeans/client-socket — client-side WebSocket connection helpers for browsers and native clients. Auto-invoked when importing client socket primitives.
+description: How to use @owlmeans/client-socket — opening a self-restoring WebSocket Connection to a socket entrypoint from browsers and native clients, the reconnect policy and its options, the socket-status aggregator, the useWs hook and the system frames a carrier emits. Auto-invoked when importing client socket primitives or wiring a browser subscription.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,23 +8,166 @@ user-invocable: false
 # @owlmeans/client-socket
 
 **Layer:** Client
-**Install:** `"@owlmeans/client-socket": "^0.1.18-rc.0"` in `dependencies`
+**Install:** `"@owlmeans/client-socket": "^0.1.18-rc.30"` in `dependencies`
+
+The browser carrier for `@owlmeans/socket`. It supplies the four members the connection model
+leaves abstract — `send`, `close`, `prepare`, `authenticate` — and hands back a plain `Connection`,
+so everything a screen does with the socket is the vocabulary of that package — `observe`,
+`notify`, `call`, `listen`. It also restores a dropped WebSocket on its own, on the SAME
+`Connection` model, so nothing a caller registered with `observe`/`listen` needs to be
+re-registered after a network blip.
 
 ## Key Exports
 
 | Export | Description |
 |--------|-------------|
-| `Socket` types | Client socket connection shape |
-| Helpers | Connect, send, subscribe to channels |
+| `ws(entrypoint, request?, options?)` | Open a `Connection` to a socket entrypoint. Resolves once the FIRST attempt opens; rejects with `SocketConnectionError('lost')` if the retry budget elapses first |
+| `useWs(protocol \| alias, request?, options?)` | React hook — `Connection \| null` until it opens (or gives up); re-opens on `alias`/`AUTH_QUERY`/`params` change and closes on unmount |
+| `connect(address, ctx, options?)` | The same machinery with no entrypoint behind it — an `address` callback returning the URL, for an adapter or a test |
+| `appendSocketStatus(ctx, alias?)` / `useSocketStatus()` | The status aggregator — see below |
+| `Config` / `Context` | The client config (`socket?: SocketClientSettings`) and context types this package expects |
+| `ReconnectPolicy` / `SocketClientSettings` / `ConnectOptions` / `WsOptions` | The reconnect policy shape and where it can be set — config, or per-call `options` |
+
+## How the address is built
+
+A socket entrypoint is **addressed, not called**: `entrypointUrl` from
+`@owlmeans/client-entrypoint/utils` turns the declaration plus the asking context into the `wss://`
+URL — `:params` filled in, query appended, protocol and TLS taken from the entrypoint's address —
+and the connection is opened on that. Nothing is hand-concatenated, so the same declaration the
+server binds is the one the client dials. It is re-resolved on EVERY attempt, first one included,
+so a `beforeConnect` hook that mutates the request's query (a refreshed token, most often) reaches
+every reconnect too, not just the first handshake.
+
+Authentication rides on the query, because a WebSocket handshake carries no Authorization header a
+browser can set: the token goes under `AUTH_QUERY`, and the server derives the connection's subject
+from it.
+
+**Take the authenticated hook, not this one.** `@owlmeans/client-auth` exports its own `useWs` that
+wraps this one, fills `AUTH_QUERY` from `ctx.auth().token`, and refreshes it via `beforeConnect` on
+every reconnect — unless the request already carried its own token, in which case that caller's
+value is left alone across reconnects too. Import `useWs` from there for anything a guard
+protects, and from here only for an entrypoint that is open to everyone.
+
+The in-band auth sequence is a different thing from the query token, and only half of it is here.
+`connection.auth(stage, payload)` sends the frame and resolves on the server's reply — that is the
+client-initiated exchange, and it works. This carrier's own `authenticate` is a stub answering an
+empty tuple, so an `Auth` frame the SERVER opens finds no stage to answer with and is dropped
+without a reply: a browser can start an exchange, never answer one.
+
+**A reconnect is a brand-new server-side connection.** If a server sets up subscriptions only
+after an in-band `authenticate` frame (as this platform's own handlers do — see the `socket`
+memory in `viable`), the carrier does NOT replay that frame by itself; it only reopens the pipe.
+A caller that authenticates in-band must listen for `SocketSystemEvent.Reconnected` and resend it
+— `viable`'s `sources/manager-web/src/lib/ws.ts` `useAuthWs` is the worked example.
 
 ## Usage
 
 ```typescript
-import { connectSocket } from '@owlmeans/client-socket'
-const socket = await connectSocket(context, { url: 'wss://api/ws' })
-socket.subscribe('projects', msg => console.log(msg))
+// A guarded entrypoint: this useWs fills AUTH_QUERY from the current session and keeps it fresh
+// across reconnects.
+import { useWs } from '@owlmeans/client-auth'
+
+// An open one: this useWs sends whatever query it is given, and nothing more.
+// import { useWs } from '@owlmeans/client-socket'
+
+const connection = useWs(app.api.project.stream, { params: { id } })
+
+useEffect(() => {
+  if (connection == null) {
+    return
+  }
+  const stop = connection.observe<Update>('update', async msg => apply(msg.payload))
+
+  return () => stop()
+}, [connection])
 ```
 
+Pass the immutable socket protocol declaration in application code. A string alias is reserved
+for an adapter whose remote declaration is unavailable to import. Both hooks re-open when the
+protocol, `AUTH_QUERY` value, or params change — the params are compared by content, so a fresh
+object literal each render does not re-open. Both close the connection when the component unmounts,
+and both answer `null` until the socket is open, so every effect that touches one guards on that.
+
+## Disconnects and reconnects
+
+The carrier keeps the same `Connection` MODEL for the life of the hook/call and swaps only the
+underlying `WebSocket` underneath it — every `observe`/`listen` a caller registered survives a
+reconnect, because it was registered on the model, not on the socket.
+
+**The retry policy** (`ReconnectPolicy`, defaults in `DEFAULT_RECONNECT_POLICY`):
+
+| Field | Default | Meaning |
+|---|---|---|
+| `minDelay` | 200ms | First retry delay |
+| `maxDelay` | 3000ms | Delay ceiling — backoff never grows past this |
+| `factor` | 2 | Geometric growth per failed attempt |
+| `jitter` | 0.1 | ±10% randomization on each computed delay |
+| `budget` | 600000ms (10 min) | Total retry time before the carrier gives up |
+| `stableAfter` | 10000ms | How long a reopened socket must stay up before the attempt count and the outage clock reset |
+| `heartbeat` | 30000ms | Ping interval — runs even with `reconnect: false` |
+| `pongTimeout` | 10000ms | No frame of ANY kind since the last ping past this long ⇒ the carrier force-closes the socket itself (code 4000, `SOCKET_HEARTBEAT_TIMEOUT_CODE`) — the only way a silently half-open TCP connection is noticed before the OS would, minutes later |
+
+Set it on `ctx.cfg.socket.reconnect` (app-wide) or per call via `options.reconnect` (which wins).
+`reconnect: false` disables retries — a drop is reported once and stays dropped, the
+pre-reconnect-support behaviour — while the heartbeat/liveness check above still runs. Use it for
+a stateful one-shot handshake a reconnect could never resume correctly (the wallet-tunnel rely
+session in `client-auth` sets it for exactly this reason).
+
+**System frames** (`SocketSystemEvent`, from `@owlmeans/socket`) reach every `connection.listen`
+subscriber:
+
+| Event | When |
+|---|---|
+| `disconnected` | The socket dropped and a retry IS scheduled — `{ code }` |
+| `reconnecting` | Before each retry attempt — `{ attempt, delay }` |
+| `reconnected` | A retry succeeded — `{ attempts }` |
+| `lost` | The retry budget elapsed with no success — no payload |
+| `close` | The connection is gone for GOOD: a client-initiated close, a terminal server code (1000/1008), `reconnect: false` and the one attempt failed, or right after `lost` |
+
+```typescript
+connection.listen(async message => {
+  const msg = message as EventMessage<unknown>
+  if (typeof message !== 'object' || msg.type !== 'system') return
+  if (msg.event === SocketSystemEvent.Reconnected) await resubscribe()
+  if (msg.event === SocketSystemEvent.Close) await release()
+})
+```
+
+**The status aggregator.** `appendSocketStatus(ctx)` registers a shared service every
+`ws()`/`useWs()` connection reports its state into; `useSocketStatus()` reads the WORST state
+across all of them (`'online' | 'reconnecting' | 'lost'`). A connection that ends in `'lost'` is
+NOT released from the aggregate — there is no `Connection` for the caller to close, since `ws()`
+rejected — so the aggregate latches at `'lost'` until the page reloads. That is deliberate: it is
+what `@owlmeans/web-panel`'s `SocketReloadDialog` reads to put up a global, blocking "reload the
+page" prompt once every socket in the app has given up (`cfg.socket.reloadDialog`). Calling
+`appendSocketStatus` unconditionally is cheap and safe for a host package — nothing reports into
+it unless something calls `ws()`/`useWs()`, so an app that never does behaves exactly as before.
+
+`useSocketStatus()` tolerates being called before the context's own `configure()`/`init()` has
+run (it defaults to `'online'` and re-attaches once `ctx.waitForInitialized()` resolves) — a
+component mounted as a sibling of the router, as `SocketReloadDialog` is, renders on React's
+first commit, before the router's effect has had a chance to initialize the context.
+
+Outbound frames are stamped with `dt` and dropped rather than queued while the socket is not
+`OPEN`, so a `notify` issued while the socket is down is lost rather than delivered late. Nothing
+here replays events the SERVER sent while the socket was down either — a caller that cannot
+tolerate a gap re-syncs its own state on `reconnected` (viable's file-watch editor re-lists files;
+its thinking/slot socket relies on a separate periodic API push for the same reason).
+
 ## Depends On
 
-- `@owlmeans/socket`, `@owlmeans/client-context`
+- `@owlmeans/socket` — `createBasicConnection`, `MessageType`, `SocketSystemEvent`,
+  `SOCKET_HEARTBEAT_TIMEOUT_CODE`, `SocketConnectionError`, the `Connection` contract
+- `@owlmeans/client-entrypoint` — `entrypointUrl`, `provideRequest`
+- `@owlmeans/client` — `useContext`, `useValue`; `@owlmeans/client-context` — the config type
+- `@owlmeans/auth` — `AUTH_QUERY`, `AuthenticationStage`
+- `@owlmeans/basic-ids` — `createIdOfLength`, for the per-connection status-tracking id
+- `react` (peer)
+
+## Related
+
+- `socket` — the message model every verb here belongs to, and the `SocketSystemEvent` vocabulary
+- `server-socket` — the far side: guard enforcement, and what it stamps on a frame
+- `client-auth` — the `useWs` that carries the token and refreshes it across reconnects;
+  `client-job` — `useJobFeed`, a worked subscription built on it
+- `web-panel` — `SocketReloadDialog`, the global blocking prompt built on `useSocketStatus()`

package/build/consts.d.ts

@@ -0,0 +1,7 @@
+import type { ReconnectPolicy } from './types.js';
+/**
+ * 0.2s → 3s geometric backoff, retried for up to 10 minutes before the carrier gives up and
+ * reports the connection lost. See the client-socket skill's "Disconnects" section.
+ */
+export declare const DEFAULT_RECONNECT_POLICY: ReconnectPolicy;
+//# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,eAStC,CAAA"}

package/build/consts.js

@@ -0,0 +1,15 @@
+/**
+ * 0.2s → 3s geometric backoff, retried for up to 10 minutes before the carrier gives up and
+ * reports the connection lost. See the client-socket skill's "Disconnects" section.
+ */
+export const DEFAULT_RECONNECT_POLICY = {
+    minDelay: 200,
+    maxDelay: 3_000,
+    factor: 2,
+    jitter: 0.1,
+    budget: 600_000,
+    stableAfter: 10_000,
+    heartbeat: 30_000,
+    pongTimeout: 10_000,
+};
+//# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAoB;IACvD,QAAQ,EAAE,GAAG;IACb,QAAQ,EAAE,KAAK;IACf,MAAM,EAAE,CAAC;IACT,MAAM,EAAE,GAAG;IACX,MAAM,EAAE,OAAO;IACf,WAAW,EAAE,MAAM;IACnB,SAAS,EAAE,MAAM;IACjB,WAAW,EAAE,MAAM;CACpB,CAAA"}

package/build/helper.d.ts

@@ -1,8 +1,32 @@
 import type { ClientEntrypoint } from '@owlmeans/client-entrypoint';
 import type { AbstractRequest } from '@owlmeans/entrypoint';
 import type { Connection } from '@owlmeans/socket';
+import type { EntrypointReference } from '@owlmeans/context';
+import type { Context, ConnectOptions, WsOptions } from './types.js';
+/**
+ * Open a socket with no declared entrypoint behind it — the primitive `ws()` builds on, and what
+ * a test drives directly against a bare WebSocket server.
+ */
+export declare const connect: (address: () => Promise<string> | string, ctx: Context, options?: ConnectOptions) => Promise<Connection>;
+/**
+ * Open a socket through a declared entrypoint protocol, restoring it on its own after a network
+ * failure — see the client-socket skill's "Disconnects" section for the full policy. Resolves
+ * once the first attempt opens; rejects with `SocketConnectionError('lost')` if the retry budget
+ * elapses before that ever happens (or the single attempt fails, with `reconnect: false`).
+ */
 export declare const ws: (module: ClientEntrypoint<string>, request?: AbstractRequest<{
     token?: string;
-}>) => Promise<Connection>;
-export declare const useWs: (module: string | ClientEntrypoint<any>, request?: Partial<AbstractRequest<any>>) => Connection | null;
+}>, options?: WsOptions) => Promise<Connection>;
+/**
+ * Open a socket through a declared entrypoint protocol.
+ *
+ * String aliases remain an adapter input for dynamically addressed integrations, while
+ * application callers pass their immutable protocol declaration and receive its bound client
+ * entrypoint here at the transport boundary.
+ *
+ * Re-opens on its own after a network drop (see `ws()`). `null` until the first attempt opens,
+ * and again once the retry budget elapses without one ever opening — a screen that must tell
+ * those two apart reads `useSocketStatus()` (from `./status.js`) alongside this.
+ */
+export declare const useWs: (module: EntrypointReference | string, request?: Partial<AbstractRequest<any>>, options?: WsOptions) => Connection | null;
 //# sourceMappingURL=helper.d.ts.map

package/build/helper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAA;AACnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAG3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAUlD,eAAO,MAAM,EAAE,WAAkB,gBAAgB,CAAC,MAAM,CAAC,YAAY,eAAe,CAAC;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,KAAG,OAAO,CAAC,UAAU,CA0B5H,CAAA;AAED,eAAO,MAAM,KAAK,WAAY,MAAM,GAAG,gBAAgB,CAAC,GAAG,CAAC,YAAY,OAAO,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,KAAG,UAAU,GAAG,IAyBpH,CAAA"}
+{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAA;AACnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAE3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAIlD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AAC5D,OAAO,KAAK,EAAU,OAAO,EAAE,cAAc,EAA8C,SAAS,EAAE,MAAM,YAAY,CAAA;AA8DxH;;;GAGG;AACH,eAAO,MAAM,OAAO,YACT,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,OAAO,OAAO,YAAY,cAAc,KAC9E,OAAO,CAAC,UAAU,CAGpB,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,EAAE,WACL,gBAAgB,CAAC,MAAM,CAAC,YAAY,eAAe,CAAC;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,YAAY,SAAS,KACnG,OAAO,CAAC,UAAU,CAUpB,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK,WACR,mBAAmB,GAAG,MAAM,YAAY,OAAO,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,YAAY,SAAS,KACjG,UAAU,GAAG,IAqCf,CAAA"}

package/build/helper.js

@@ -1,44 +1,113 @@
 import { provideRequest } from '@owlmeans/client-entrypoint';
-import { EntrypointOutcome } from '@owlmeans/entrypoint';
-import { SocketInitializationError } from '@owlmeans/socket';
+import { SocketConnectionError } from '@owlmeans/socket';
 import { makeConnection } from './utils/connection.js';
 import { assertContext } from '@owlmeans/context';
 import { useContext, useValue } from '@owlmeans/client';
 import { AUTH_QUERY } from '@owlmeans/auth';
-import { urlCall } from '@owlmeans/client-entrypoint/utils';
+import { entrypointUrl } from '@owlmeans/client-entrypoint/utils';
 import { useEffect, useMemo } from 'react';
-export const ws = async (module, request) => {
-    const ctx = assertContext(module.ctx, 'client-ws');
-    request = request ?? provideRequest(module.getAlias(), module.getPath());
-    const [url, state] = await urlCall({ ref: module })(request);
-    if (state !== EntrypointOutcome.Ok) {
-        throw new SocketInitializationError;
-    }
+import { createIdOfLength } from '@owlmeans/basic-ids';
+import { DEFAULT_RECONNECT_POLICY } from './consts.js';
+import { SOCKET_STATUS } from './status.js';
+const resolvePolicy = (ctx, options) => {
+    const requested = options?.reconnect !== undefined ? options.reconnect : ctx.cfg.socket?.reconnect;
+    const retry = requested !== false;
+    const overrides = requested === false || requested == null ? {} : requested;
+    return { policy: { ...DEFAULT_RECONNECT_POLICY, ...overrides }, retry };
+};
+const openRawSocket = async (url) => {
     const socket = new WebSocket(url);
-    return new Promise(resolve => {
-        socket.onopen = () => {
-            const heartbeat = setInterval(() => {
-                if (socket.readyState === WebSocket.OPEN) {
-                    socket.send(JSON.stringify({ type: 'ping' }));
-                }
-            }, 30_000);
-            socket.addEventListener('close', () => {
-                console.info('WebSocket connection closed, clearing heartbeat interval.');
-                clearInterval(heartbeat);
-            });
-            resolve(makeConnection(socket, ctx));
+    return await new Promise((resolve, reject) => {
+        const cleanup = () => {
+            socket.removeEventListener('open', onOpen);
+            socket.removeEventListener('error', onFail);
+            socket.removeEventListener('close', onFail);
         };
+        const onOpen = () => { cleanup(); resolve(socket); };
+        const onFail = () => { cleanup(); reject(new SocketConnectionError('handshake')); };
+        socket.addEventListener('open', onOpen);
+        socket.addEventListener('error', onFail);
+        socket.addEventListener('close', onFail);
+    });
+};
+const establish = async (ctx, policy, retry, open) => {
+    const statusId = createIdOfLength(8);
+    const status = ctx.hasService(SOCKET_STATUS)
+        ? ctx.socketStatus() : null;
+    const { connection, ready } = makeConnection({
+        policy, retry, open, onStatus: state => status?.report(statusId, state)
     });
+    const baseClose = connection.close;
+    connection.close = async () => {
+        await baseClose();
+        status?.release(statusId);
+    };
+    // A rejection here means `finish()` already ran and reported this id's terminal state —
+    // `'lost'` in every case, since the budget-exhausted path is the only one that rejects
+    // `ready`. Deliberately NOT released: there is no `Connection` to hand back for a caller to
+    // close, so the aggregate stays `'lost'` — the whole reason `SocketReloadDialog` exists — until
+    // the page reloads. Only a connection this function actually returns can be released, and only
+    // by the caller closing it on purpose.
+    await ready;
+    return connection;
+};
+/**
+ * Open a socket with no declared entrypoint behind it — the primitive `ws()` builds on, and what
+ * a test drives directly against a bare WebSocket server.
+ */
+export const connect = async (address, ctx, options) => {
+    const { policy, retry } = resolvePolicy(ctx, options);
+    return await establish(ctx, policy, retry, async () => openRawSocket(await address()));
 };
-export const useWs = (module, request) => {
+/**
+ * Open a socket through a declared entrypoint protocol, restoring it on its own after a network
+ * failure — see the client-socket skill's "Disconnects" section for the full policy. Resolves
+ * once the first attempt opens; rejects with `SocketConnectionError('lost')` if the retry budget
+ * elapses before that ever happens (or the single attempt fails, with `reconnect: false`).
+ */
+export const ws = async (module, request, options) => {
+    const ctx = assertContext(module.ctx, 'client-ws');
+    request = request ?? provideRequest(module.alias, module.path());
+    const { policy, retry } = resolvePolicy(ctx, options);
+    return await establish(ctx, policy, retry, async () => {
+        await options?.beforeConnect?.(request);
+        const url = await entrypointUrl({ ref: module }, request);
+        return await openRawSocket(url);
+    });
+};
+/**
+ * Open a socket through a declared entrypoint protocol.
+ *
+ * String aliases remain an adapter input for dynamically addressed integrations, while
+ * application callers pass their immutable protocol declaration and receive its bound client
+ * entrypoint here at the transport boundary.
+ *
+ * Re-opens on its own after a network drop (see `ws()`). `null` until the first attempt opens,
+ * and again once the retry budget elapses without one ever opening — a screen that must tell
+ * those two apart reads `useSocketStatus()` (from `./status.js`) alongside this.
+ */
+export const useWs = (module, request, options) => {
     const ctx = useContext();
-    const mod = useMemo(() => typeof module === 'string' ? ctx.entrypoint(module) : module, [module]);
-    const connection = useValue(async () => {
-        const _request = provideRequest(mod.getAlias(), mod.getPath());
+    const mod = useMemo(() => ctx.entrypoint(module), [module]);
+    const connection = useValue(async (cancel) => {
+        const _request = provideRequest(mod.alias, mod.path());
         Object.assign(_request, request);
-        return await ws(mod, _request);
+        try {
+            const conn = await ws(mod, _request, options);
+            if (cancel?.current) {
+                // The component unmounted while the handshake (or its retries) were still in flight —
+                // there is no `useEffect` cleanup coming for this value, so close it here instead of
+                // leaving a live socket and its retry timers attached to nothing.
+                void conn.close();
+                return null;
+            }
+            return conn;
+        }
+        catch {
+            return null;
+        }
     }, [
-        mod.getAlias(),
+        mod.alias,
         request?.query?.[AUTH_QUERY],
         request?.params ? JSON.stringify(request.params) : undefined
     ]);

package/build/helper.js.map

@@ -1 +1 @@
-{"version":3,"file":"helper.js","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"helper.js","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"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"}

package/build/index.d.ts

@@ -1,3 +1,5 @@
 export type * from './types.js';
+export * from './consts.js';
 export * from './helper.js';
+export * from './status.js';
 //# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA"}

package/build/index.js

@@ -1,2 +1,4 @@
+export * from './consts.js';
 export * from './helper.js';
+export * from './status.js';
 //# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,cAAc,aAAa,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA"}

package/build/status.d.ts

@@ -0,0 +1,22 @@
+import type { Config, Context, SocketConnectionState, SocketStatusService, SocketStatusServiceAppend } from './types.js';
+export declare const SOCKET_STATUS = "socket-status";
+/**
+ * Aggregates the coarse health of every `ws()`/`useWs()` connection an app has open into one
+ * worst-of-all state. A page with several sockets (thinking stream, file watch, notifications…)
+ * still shows one dialog, not one per socket — so the aggregate, not any single connection, is
+ * what a UI like `SocketReloadDialog` reads.
+ */
+export declare const createSocketStatusService: (alias?: string) => SocketStatusService;
+/**
+ * Register the shared socket-status aggregator. Idempotent, and cheap enough for a host package
+ * (`@owlmeans/web-panel`) to call unconditionally on every context: every `ws()`/`useWs()`
+ * connection reports itself here if — and only if — the context carries this service, so an app
+ * that never calls this behaves exactly as it did before reconnect support existed.
+ */
+export declare const appendSocketStatus: <C extends Config = Config, T extends Context<C> = Context<C>>(ctx: T, alias?: string) => T & SocketStatusServiceAppend;
+/**
+ * The worst state across every live `ws()`/`useWs()` connection, or `'online'` if the app never
+ * registered the status service (`appendSocketStatus`) or has not finished initializing yet.
+ */
+export declare const useSocketStatus: () => SocketConnectionState;
+//# sourceMappingURL=status.d.ts.map

package/build/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,MAAM,EAAE,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,yBAAyB,EACvF,MAAM,YAAY,CAAA;AAEnB,eAAO,MAAM,aAAa,kBAAkB,CAAA;AAI5C;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,WAAW,MAAM,KAAmB,mBAyBzE,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,CAAC,SAAS,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,OACxF,CAAC,UAAS,MAAM,KACpB,CAAC,GAAG,yBAON,CAAA;AAiBD;;;GAGG;AACH,eAAO,MAAM,eAAe,QAAO,qBA2BlC,CAAA"}