@owlmeans/client-socket 0.1.18-rc.4 → 0.1.18-rc.41

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.41
 ```
 
 ## 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.40
 ```
 
 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.41",
+  "generatedAt": "2026-09-25T21:19:37.961Z",
   "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,188 @@ 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.41"` 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()` / `useSocketRetry()` | The status aggregator and its retry — 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 |
+| `reviveBudget` | 15000ms | Retry window `retry()` gives a lost socket (and the minimum it leaves one still retrying) — short, so a retry that cannot succeed reports `'lost'` again while someone is still looking |
+| `stableAfter` | 10000ms | How long a reopened socket must stay up before the attempt count, the outage clock and the budget (back to `budget`) reset |
+| `heartbeat` | 30000ms | Ping interval — runs even with `reconnect: false` |
+| `pongTimeout` | 10000ms | Checked at the next heartbeat tick: the ping still unanswered 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. Measured from the PING, never from the last frame: a hidden tab's timers are throttled to roughly one wake-up a minute, and "nothing for a whole interval" is what throttling looks like, not what a dead socket looks like. Any inbound frame answers the ping; `server-socket` replies `{"type":"pong"}` |
+
+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 }` (`delay: 0` for a revive's immediate attempt) |
+| `reconnected` | A retry succeeded, a revived one included — `{ attempts }` |
+| `lost` | The retry budget elapsed with no success — no payload. The connection is NOT closed: it stays revivable (below) until its owner closes it |
+| `close` | The connection is gone for GOOD: a client-initiated close, a terminal server code (1000/1008), or `reconnect: false` and the one attempt failed. Never follows `lost` by itself |
+
+```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 `'lost'` connection stays in the
+aggregate — that is what `@owlmeans/web-panel`'s `SocketReloadDialog` reads to put up its global
+prompt (`cfg.socket.reloadDialog`) — until something revives or closes it. 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.
+
+**Retry.** `socketStatus().retry()` revives every `'lost'` connection and hurries every
+`'reconnecting'` one (attempt at once instead of after the backoff, and at least `reviveBudget`
+left) — without that, a sibling whose older budget runs out a moment later reports `'lost'` right
+after the retry and puts the dialog straight back. It fires `onRetry` listeners and returns `true`
+only when something was lost, so calling it freely is safe.
+The service calls it by itself when the tab becomes visible, the window gains focus, or the
+browser goes back `online` — a background tab is where sockets die unnoticed (throttled timers, a
+sleeping machine), so the moment it is looked at again is when to retry. How a lost connection
+comes back depends on whether it ever opened:
+
+- **Opened before** — revived in place: one attempt at once, then the normal backoff within
+  `reviveBudget`. Same `Connection` model, and success emits `reconnected`, so the re-auth / re-sync
+  listeners every caller already has for a network blip cover this too. Failing again reports
+  `lost` again.
+- **Never opened** — `ws()` already rejected and nobody holds it, so it is closed for good and
+  released. `useWs` re-dials by itself on `onRetry` (a fresh `ws()`, full `budget`); a direct
+  `ws()` caller re-opens on its own terms.
+- A terminal close (1000/1008, `reconnect: false`) is never revived.
+
+`useSocketRetry()` gives a UI `{ retry, retrying }` — `retrying` is true from any retry (the
+button, or the service's own on activation) until the aggregate settles on `'online'` or `'lost'`.
+
+`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()` /
+  `useSocketRetry()`

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,eAUtC,CAAA"}

package/build/consts.js

@@ -0,0 +1,16 @@
+/**
+ * 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,
+    reviveBudget: 15_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,YAAY,EAAE,MAAM;IACpB,WAAW,EAAE,MAAM;IACnB,SAAS,EAAE,MAAM;IACjB,WAAW,EAAE,MAAM;CACpB,CAAA"}

package/build/helper.d.ts

@@ -1,8 +1,33 @@
 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 — dialed afresh on the next
+ * `SocketStatusService.retry()`. 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;AA6ExH;;;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;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,KAAK,WACR,mBAAmB,GAAG,MAAM,YAAY,OAAO,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,YAAY,SAAS,KACjG,UAAU,GAAG,IAiDf,CAAA"}

package/build/helper.js

@@ -1,47 +1,144 @@
 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 { 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 { entrypointUrl } from '@owlmeans/client-entrypoint/utils';
+import { useEffect, useMemo, useState } from 'react';
+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;
+    let opened = false;
+    let lost = false;
+    const managed = makeConnection({
+        policy, retry, open, onStatus: state => {
+            lost = state === 'lost';
+            status?.report(statusId, state, state === 'online' ? undefined : revive);
+        }
+    });
+    const { connection, ready } = managed;
+    const baseClose = connection.close;
+    connection.close = async () => {
+        await baseClose();
+        status?.release(statusId);
+    };
+    const revive = () => {
+        if (opened || !lost) {
+            managed.revive();
+            return;
+        }
+        // Never opened, so `ws()` already rejected and nobody holds this connection to hand a revived
+        // socket to: drop it for good and leave re-dialing to its owner (`useWs` does, on `onRetry`).
+        void baseClose();
+        status?.release(statusId);
+    };
+    // A rejection leaves this id reporting `'lost'` rather than releasing it — there is no
+    // `Connection` to hand back for a caller to close, and the aggregate is what puts
+    // `SocketReloadDialog` up. It is released by `revive` above, on the next `retry()`.
+    await ready;
+    opened = true;
+    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()));
+};
+/**
+ * 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);
     });
 };
-export const useWs = (module, request) => {
+/**
+ * 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 — dialed afresh on the next
+ * `SocketStatusService.retry()`. 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 [failed, setFailed] = useState(false);
+    const [dial, setDial] = useState(0);
+    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 {
+            if (!cancel?.current)
+                setFailed(true);
+            return null;
+        }
     }, [
-        mod.getAlias(),
+        mod.alias,
         request?.query?.[AUTH_QUERY],
-        request?.params ? JSON.stringify(request.params) : undefined
+        request?.params ? JSON.stringify(request.params) : undefined,
+        dial
     ]);
+    useEffect(() => {
+        if (!failed || !ctx.hasService(SOCKET_STATUS))
+            return;
+        return ctx.socketStatus().onRetry(() => {
+            setFailed(false);
+            setDial(n => n + 1);
+        });
+    }, [failed]);
     useEffect(() => {
         if (connection != null) {
             return () => {

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,31 @@
+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;
+/**
+ * `retry` revives every lost connection now (`SocketStatusService.retry()`); `retrying` is true
+ * from any retry — this one, or the service's own on tab activation — until the aggregate settles
+ * back on `'online'` or `'lost'`.
+ */
+export declare const useSocketRetry: () => {
+    retry: () => void;
+    retrying: boolean;
+};
+//# sourceMappingURL=status.d.ts.map