@owlmeans/client-socket 0.1.18-rc.47 → 0.1.18-rc.49

package/README.md

@@ -4,7 +4,7 @@ React hook and factory for WebSocket connections via OwlMeans entrypoint routing
 
 ## Overview
 
-- `ws(entrypoint, request?)` — creates a `Connection` from the entrypoint's URL and opens a WebSocket
+- `socketClientHelper.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
@@ -12,7 +12,7 @@ React hook and factory for WebSocket connections via OwlMeans entrypoint routing
 ## Installation
 
 ```bash
-bun add @owlmeans/client-socket@^0.1.18-rc.47
+bun add @owlmeans/client-socket@^0.1.18-rc.49
 ```
 
 ## Usage
@@ -42,16 +42,16 @@ function ThinkingPanel({ storyId }: { storyId: string }) {
 Direct connection (non-hook):
 
 ```typescript
-import { ws } from '@owlmeans/client-socket'
+import { socketClientHelper } from '@owlmeans/client-socket'
 import { appProtocols } from 'my-app-common'
 
 const wsEntrypoint = context.entrypoint(appProtocols.api.storyThinking)
-const connection = await ws(wsEntrypoint, { params: { id: storyId } })
+const connection = await socketClientHelper.ws(wsEntrypoint, { params: { id: storyId } })
 ```
 
 ## API
 
-### `ws(entrypoint, request?): Promise<Connection>`
+### `socketClientHelper.ws(entrypoint, request?): Promise<Connection>`
 
 Builds the entrypoint's URL, opens a WebSocket, and returns a `Connection` once the socket opens.
 
@@ -75,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@^0.1.18-rc.47
+npx @owlmeans/agent-skills@^0.1.18-rc.49
 ```
 
 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.47",
-  "generatedAt": "2026-10-03T20:05:07.590Z",
+  "version": "0.1.18-rc.49",
+  "generatedAt": "2026-10-05T21:03:06.385Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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

@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/client-socket
 
 **Layer:** Client
-**Install:** `"@owlmeans/client-socket": "^0.1.18-rc.47"` in `dependencies`
+**Install:** `"@owlmeans/client-socket": "^0.1.18-rc.49"` 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`,

package/build/consts.d.ts

@@ -4,4 +4,5 @@ import type { ReconnectPolicy } from './types.js';
  * reports the connection lost. See the client-socket skill's "Disconnects" section.
  */
 export declare const DEFAULT_RECONNECT_POLICY: ReconnectPolicy;
+export declare const SOCKET_STATUS = "socket-status";
 //# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -1 +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"}
+{"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;AAED,eAAO,MAAM,aAAa,kBAAkB,CAAA"}

package/build/consts.js

@@ -13,4 +13,5 @@ export const DEFAULT_RECONNECT_POLICY = {
     heartbeat: 30_000,
     pongTimeout: 10_000,
 };
+export const SOCKET_STATUS = 'socket-status';
 //# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -1 +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"}
+{"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;AAED,MAAM,CAAC,MAAM,aAAa,GAAG,eAAe,CAAA"}

package/build/consts.local.d.ts

@@ -0,0 +1,3 @@
+import type { SocketConnectionState } from './types.js';
+export declare const RANK: Record<SocketConnectionState, number>;
+//# sourceMappingURL=consts.local.d.ts.map

package/build/consts.local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.local.d.ts","sourceRoot":"","sources":["../src/consts.local.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AAEvD,eAAO,MAAM,IAAI,EAAE,MAAM,CAAC,qBAAqB,EAAE,MAAM,CAA2C,CAAA"}

package/build/consts.local.js

@@ -0,0 +1,2 @@
+export const RANK = { online: 0, reconnecting: 1, lost: 2 };
+//# sourceMappingURL=consts.local.js.map

package/build/consts.local.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.local.js","sourceRoot":"","sources":["../src/consts.local.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,IAAI,GAA0C,EAAE,MAAM,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAA"}

package/build/helper/types.d.ts

@@ -0,0 +1,22 @@
+import type { ClientEntrypoint } from '@owlmeans/client-entrypoint';
+import type { AbstractRequest } from '@owlmeans/entrypoint';
+import type { Connection } from '@owlmeans/socket';
+import type { ConnectOptions, Context, WsOptions } from '../types.js';
+/** Opens managed sockets that restore themselves after a network failure. */
+export interface SocketClientHelper {
+    /**
+     * 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.
+     */
+    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`).
+     */
+    ws: (module: ClientEntrypoint<string>, request?: AbstractRequest<{
+        token?: string;
+    }>, options?: WsOptions) => Promise<Connection>;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/helper/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/helper/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAA;AACnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAErE,6EAA6E;AAC7E,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,cAAc,KAAK,OAAO,CAAC,UAAU,CAAC,CAAA;IACjH;;;;;OAKG;IACH,EAAE,EAAE,CAAC,MAAM,EAAE,gBAAgB,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,EAAE,eAAe,CAAC;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,EAAE,OAAO,CAAC,EAAE,SAAS,KAAK,OAAO,CAAC,UAAU,CAAC,CAAA;CAClI"}

package/build/helper/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/helper/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/helper/types.ts"],"names":[],"mappings":""}

package/build/helper.d.ts

@@ -1,33 +1,12 @@
-import type { ClientEntrypoint } from '@owlmeans/client-entrypoint';
+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`).
- */
+import { type Connection } from '@owlmeans/socket';
+import type { WsOptions } from './types.js';
+import type { SocketClientHelper } from './helper/types.js';
+export declare const createSocketClientHelper: () => SocketClientHelper;
+export declare const socketClientHelper: SocketClientHelper;
+/** @deprecated compat:factory-refactor — use `socketClientHelper.ws(…)` */
 export declare const ws: (module: ClientEntrypoint<string>, request?: AbstractRequest<{
     token?: string;
 }>, 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;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"}
+{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,gBAAgB,EAAuB,MAAM,6BAA6B,CAAA;AACxF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,EAAE,KAAK,UAAU,EAAyB,MAAM,kBAAkB,CAAA;AAGzE,OAAO,KAAK,EAA+E,SAAS,EAAE,MAAM,YAAY,CAAA;AACxH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAK3D,eAAO,MAAM,wBAAwB,QAAO,kBA2F3C,CAAA;AAED,eAAO,MAAM,kBAAkB,oBAA6B,CAAA;AAE5D,2EAA2E;AAC3E,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,CAAoD,CAAA"}

package/build/helper.js

@@ -1,151 +1,84 @@
-import { provideRequest } from '@owlmeans/client-entrypoint';
+import { clientRequestHelper } from '@owlmeans/client-entrypoint';
 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 { entrypointUrl } from '@owlmeans/client-entrypoint/utils';
-import { useEffect, useMemo, useState } from 'react';
+import { makeApiCallHelper } from '@owlmeans/client-entrypoint/utils';
 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 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);
+import { DEFAULT_RECONNECT_POLICY, SOCKET_STATUS } from './consts.js';
+export const createSocketClientHelper = () => {
+    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 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);
+    const openRawSocket = async (url) => {
+        const socket = new WebSocket(url);
+        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);
+        });
     };
-    // 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);
-    });
-};
-/**
- * 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(() => 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);
-        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;
+    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);
             }
-            return conn;
-        }
-        catch {
-            if (!cancel?.current)
-                setFailed(true);
-            return null;
-        }
-    }, [
-        mod.alias,
-        request?.query?.[AUTH_QUERY],
-        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 () => {
-                void connection.close();
-            };
-        }
-    }, [connection]);
-    return connection;
+        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;
+    };
+    const connect = async (address, ctx, options) => {
+        const { policy, retry } = resolvePolicy(ctx, options);
+        return await establish(ctx, policy, retry, async () => openRawSocket(await address()));
+    };
+    const ws = async (module, request, options) => {
+        const ctx = assertContext(module.ctx, 'client-ws');
+        request = request ?? clientRequestHelper.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 makeApiCallHelper({ ref: module }).entrypointUrl(request);
+            return await openRawSocket(url);
+        });
+    };
+    return { connect, ws };
 };
+export const socketClientHelper = createSocketClientHelper();
+/** @deprecated compat:factory-refactor — use `socketClientHelper.ws(…)` */
+export const ws = (module, request, options) => socketClientHelper.ws(module, request, options);
 //# sourceMappingURL=helper.js.map

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":"AAAA,OAAO,EAAyB,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AAExF,OAAO,EAAmB,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AACzE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAGjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAA;AACrE,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AACtD,OAAO,EAAE,wBAAwB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAErE,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAuB,EAAE;IAC/D,MAAM,aAAa,GAAG,CACpB,GAAY,EAAE,OAAwB,EACO,EAAE;QAC/C,MAAM,SAAS,GAAG,OAAO,EAAE,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,CAAA;QAClG,MAAM,KAAK,GAAG,SAAS,KAAK,KAAK,CAAA;QACjC,MAAM,SAAS,GAAG,SAAS,KAAK,KAAK,IAAI,SAAS,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAA;QAC3E,OAAO,EAAE,MAAM,EAAE,EAAE,GAAG,wBAAwB,EAAE,GAAG,SAAS,EAAE,EAAE,KAAK,EAAE,CAAA;IACzE,CAAC,CAAA;IAED,MAAM,aAAa,GAAG,KAAK,EAAE,GAAW,EAAsB,EAAE;QAC9D,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,GAAG,CAAC,CAAA;QACjC,OAAO,MAAM,IAAI,OAAO,CAAY,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACtD,MAAM,OAAO,GAAG,GAAG,EAAE;gBACnB,MAAM,CAAC,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;gBAC1C,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;gBAC3C,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;YAC7C,CAAC,CAAA;YACD,MAAM,MAAM,GAAG,GAAG,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA,CAAC,CAAC,CAAA;YACnD,MAAM,MAAM,GAAG,GAAG,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,qBAAqB,CAAC,WAAW,CAAC,CAAC,CAAA,CAAC,CAAC,CAAA;YAClF,MAAM,CAAC,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;YACvC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;YACxC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;QAC1C,CAAC,CAAC,CAAA;IACJ,CAAC,CAAA;IAED,MAAM,SAAS,GAAG,KAAK,EACrB,GAAY,EAAE,MAAuB,EAAE,KAAc,EAAE,IAA8B,EAChE,EAAE;QACvB,MAAM,QAAQ,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAA;QACpC,MAAM,MAAM,GAAG,GAAG,CAAC,UAAU,CAAC,aAAa,CAAC;YAC1C,CAAC,CAAE,GAA4C,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,IAAI,CAAA;QAEvE,IAAI,MAAM,GAAG,KAAK,CAAA;QAClB,IAAI,IAAI,GAAG,KAAK,CAAA;QAChB,MAAM,OAAO,GAAG,cAAc,CAAC;YAC7B,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE;gBACrC,IAAI,GAAG,KAAK,KAAK,MAAM,CAAA;gBACvB,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE,KAAK,EAAE,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAA;YAC1E,CAAC;SACF,CAAC,CAAA;QACF,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,OAAO,CAAA;QAErC,MAAM,SAAS,GAAG,UAAU,CAAC,KAAK,CAAA;QAClC,UAAU,CAAC,KAAK,GAAG,KAAK,IAAI,EAAE;YAC5B,MAAM,SAAS,EAAE,CAAA;YACjB,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAA;QAC3B,CAAC,CAAA;QAED,MAAM,MAAM,GAAG,GAAG,EAAE;YAClB,IAAI,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;gBACpB,OAAO,CAAC,MAAM,EAAE,CAAA;gBAChB,OAAM;YACR,CAAC;YACD,8FAA8F;YAC9F,8FAA8F;YAC9F,KAAK,SAAS,EAAE,CAAA;YAChB,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAA;QAC3B,CAAC,CAAA;QAED,uFAAuF;QACvF,kFAAkF;QAClF,oFAAoF;QACpF,MAAM,KAAK,CAAA;QACX,MAAM,GAAG,IAAI,CAAA;QAEb,OAAO,UAAU,CAAA;IACnB,CAAC,CAAA;IAED,MAAM,OAAO,GAAG,KAAK,EACnB,OAAuC,EAAE,GAAY,EAAE,OAAwB,EAC1D,EAAE;QACvB,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,aAAa,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;QACrD,OAAO,MAAM,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,IAAI,EAAE,CAAC,aAAa,CAAC,MAAM,OAAO,EAAE,CAAC,CAAC,CAAA;IACxF,CAAC,CAAA;IAED,MAAM,EAAE,GAAG,KAAK,EACd,MAAgC,EAAE,OAA6C,EAAE,OAAmB,EAC/E,EAAE;QACvB,MAAM,GAAG,GAAG,aAAa,CAAkB,MAAM,CAAC,GAAc,EAAE,WAAW,CAAC,CAAA;QAC9E,OAAO,GAAG,OAAO,IAAI,mBAAmB,CAAC,cAAc,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAA;QACpF,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,aAAa,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;QAErD,OAAO,MAAM,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,IAAI,EAAE;YACpD,MAAM,OAAO,EAAE,aAAa,EAAE,CAAC,OAAQ,CAAC,CAAA;YACxC,MAAM,GAAG,GAAG,MAAM,iBAAiB,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC,aAAa,CAAC,OAAO,CAAC,CAAA;YAC3E,OAAO,MAAM,aAAa,CAAC,GAAG,CAAC,CAAA;QACjC,CAAC,CAAC,CAAA;IACJ,CAAC,CAAA;IAED,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,CAAA;AACxB,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,kBAAkB,GAAG,wBAAwB,EAAE,CAAA;AAE5D,2EAA2E;AAC3E,MAAM,CAAC,MAAM,EAAE,GAAG,CAChB,MAAgC,EAAE,OAA6C,EAAE,OAAmB,EAC/E,EAAE,CAAC,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA"}

package/build/hooks.d.ts

@@ -0,0 +1,18 @@
+import type { AbstractRequest } from '@owlmeans/entrypoint';
+import type { Connection } from '@owlmeans/socket';
+import type { EntrypointReference } from '@owlmeans/context';
+import type { WsOptions } from './types.js';
+/**
+ * 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=hooks.d.ts.map

package/build/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAClD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AAC5D,OAAO,KAAK,EAA6B,SAAS,EAAE,MAAM,YAAY,CAAA;AAOtE;;;;;;;;;;;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/hooks.js

@@ -0,0 +1,66 @@
+import { clientRequestHelper } from '@owlmeans/client-entrypoint';
+import { useContext, useValue } from '@owlmeans/client';
+import { AUTH_QUERY } from '@owlmeans/auth';
+import { useEffect, useMemo, useState } from 'react';
+import { SOCKET_STATUS } from './consts.js';
+import { socketClientHelper } from './helper.js';
+/**
+ * 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(() => ctx.entrypoint(module), [module]);
+    const [failed, setFailed] = useState(false);
+    const [dial, setDial] = useState(0);
+    const connection = useValue(async (cancel) => {
+        const _request = clientRequestHelper.provideRequest(mod.alias, mod.path());
+        Object.assign(_request, request);
+        try {
+            const conn = await socketClientHelper.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.alias,
+        request?.query?.[AUTH_QUERY],
+        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 () => {
+                void connection.close();
+            };
+        }
+    }, [connection]);
+    return connection;
+};
+//# sourceMappingURL=hooks.js.map

package/build/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AAKxF,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAC3C,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAEhD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CACnB,MAAoC,EAAE,OAAuC,EAAE,OAAmB,EAC/E,EAAE;IACrB,MAAM,GAAG,GAAG,UAAU,EAAE,CAAA;IACxB,MAAM,GAAG,GAAG,OAAO,CACjB,GAAG,EAAE,CAAC,GAAG,CAAC,UAAU,CAAmB,MAAM,CAAC,EAC9C,CAAC,MAAM,CAAC,CACT,CAAA;IACD,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAA;IAC3C,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAA;IACnC,MAAM,UAAU,GAAG,QAAQ,CAAoB,KAAK,EAAE,MAAM,EAAE,EAAE;QAC9D,MAAM,QAAQ,GAAG,mBAAmB,CAAC,cAAc,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC,CAAA;QAC1E,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAA;QAChC,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,kBAAkB,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAA;YAChE,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;gBACpB,sFAAsF;gBACtF,qFAAqF;gBACrF,kEAAkE;gBAClE,KAAK,IAAI,CAAC,KAAK,EAAE,CAAA;gBACjB,OAAO,IAAI,CAAA;YACb,CAAC;YACD,OAAO,IAAI,CAAA;QACb,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,CAAC,MAAM,EAAE,OAAO;gBAAE,SAAS,CAAC,IAAI,CAAC,CAAA;YACrC,OAAO,IAAI,CAAA;QACb,CAAC;IACH,CAAC,EAAE;QACD,GAAG,CAAC,KAAK;QACT,OAAO,EAAE,KAAK,EAAE,CAAC,UAAU,CAAC;QAC5B,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS;QAC5D,IAAI;KACL,CAAC,CAAA;IAEF,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,aAAa,CAAC;YAAE,OAAM;QACrD,OAAQ,GAA4C,CAAC,YAAY,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE;YAC/E,SAAS,CAAC,KAAK,CAAC,CAAA;YAChB,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;QACrB,CAAC,CAAC,CAAA;IACJ,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAA;IAEZ,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,UAAU,IAAI,IAAI,EAAE,CAAC;YACvB,OAAO,GAAG,EAAE;gBACV,KAAK,UAAU,CAAC,KAAK,EAAE,CAAA;YACzB,CAAC,CAAA;QACH,CAAC;IACH,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAA;IAEhB,OAAO,UAAU,CAAA;AACnB,CAAC,CAAA"}

package/build/index.d.ts

@@ -1,5 +1,7 @@
 export type * from './types.js';
+export type * from './helper/types.js';
 export * from './consts.js';
 export * from './helper.js';
+export * from './hooks.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;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,mBAAmB,YAAY,CAAA;AAC/B,mBAAmB,mBAAmB,CAAA;AACtC,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA"}

package/build/index.js

@@ -1,4 +1,5 @@
 export * from './consts.js';
 export * from './helper.js';
+export * from './hooks.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;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA"}

package/build/status.d.ts

@@ -1,5 +1,4 @@
 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…)

package/build/status.d.ts.map

@@ -1 +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,mBA6DzE,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;AAgCD;;;GAGG;AACH,eAAO,MAAM,eAAe,QAAO,qBAWlC,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,QAAO;IAAE,KAAK,EAAE,MAAM,IAAI,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAcvE,CAAA"}
+{"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;AAInB;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,WAAW,MAAM,KAAmB,mBA6DzE,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;AAgCD;;;GAGG;AACH,eAAO,MAAM,eAAe,QAAO,qBAWlC,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,QAAO;IAAE,KAAK,EAAE,MAAM,IAAI,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAcvE,CAAA"}

package/build/status.js

@@ -1,8 +1,8 @@
 import { createService } from '@owlmeans/context';
 import { useContext } from '@owlmeans/client';
 import { useCallback, useEffect, useState } from 'react';
-export const SOCKET_STATUS = 'socket-status';
-const RANK = { online: 0, reconnecting: 1, lost: 2 };
+import { RANK } from './consts.local.js';
+import { SOCKET_STATUS } from './consts.js';
 /**
  * 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…)