@dojo-ng/websocket 0.1.0

package/README.md

@@ -0,0 +1,111 @@
+# @dojo-ng/websocket
+
+A framework-agnostic WebSocket client: a raw-socket wrapper (`WSocket`) and a convenience
+dispatcher on top of it (`WSDispatcher`) with request/response correlation, an offline send
+queue, reconnect with backoff, and a heartbeat watchdog. Ported from app3's `core/socket`,
+de-Holmesed — see `websocket-spec.md` in the project root for the full task-by-task history and
+the reasoning behind every non-obvious decision below.
+
+Part of the [Dojo NG framework](../../README.md) monorepo (the non-Lit runtime that complements
+`components`). BSD-3-Clause.
+
+## Install
+
+```bash
+npm install @dojo-ng/websocket
+```
+
+## `WSocket`
+
+Canonicalizes differences across `WebSocket` implementations: out-of-sync detection (a live
+re-check of `socket.readyState` on every send, since the browser's own state can move before its
+event fires), backpressure (`bufferedAmount > 0` returns `BUFFERING` instead of sending),
+listener teardown before close (the reconnect-storm fix), and `open(force)` semantics.
+
+```ts
+import { WSocket, SendState } from "@dojo-ng/websocket";
+
+const ws = new WSocket("wss://example.test");
+ws.addEventListener("open", () => console.log("open"));
+ws.addEventListener("message", (e) => console.log(e.detail.data));
+ws.open();
+
+const state = ws.send("hello"); // SendState.OKAY | NOT_READY | BUFFERING | SEND_ERROR
+```
+
+Most apps want `WSDispatcher`, below, rather than `WSocket` directly — it's the layer that
+carries the actual value (queueing, correlation, reconnect, heartbeat). `WSocket` is exported
+because it's a complete, independently useful primitive on its own, not because most callers need
+to reach for it.
+
+## `WSDispatcher`
+
+```ts
+import { WSDispatcher } from "@dojo-ng/websocket";
+
+const dispatcher = new WSDispatcher({
+	url: "wss://example.test/ws",
+	// Sent on every (re)connect, before the offline queue flushes. The app owns what identity
+	// means here — this package has no opinion beyond "send these frames first."
+	onConnect: () => [{ action: "event", id: 0, data: { event: "identify", params: { sessionId } } }],
+});
+
+dispatcher.open();
+
+// A correlated request/response, queued if the socket isn't open yet and flushed on connect.
+const result = await dispatcher.call({ method: "getUser", args: [42] });
+
+// Events flow through pub/sub in both directions — dispatcher.pubsub is a @dojo-ng/pubsub
+// instance (the caller's own, if one was passed via options.pubsub, otherwise a private one).
+// Inbound "event" frames publish under their own name; publishing to options.outboundTopic
+// (default "notify:event") sends one outbound. No new subscription concept invented.
+dispatcher.pubsub.subscribe("chat:message", (payload) => render(payload));
+dispatcher.pubsub.publish("notify:event", { event: "chat:message", params: { text: "hi" } });
+```
+
+What it carries, and why each exists, is documented at length in the header comment of
+`src/wsdispatcher.ts` — request/response correlation via `Promise.withResolvers()`, an offline
+send queue that peeks and dequeues only on a confirmed send, Fibonacci-backoff reconnect (reset
+only on a successful open, suppressed entirely by an explicit `close()`), and a heartbeat
+watchdog that closes and reopens — through the same backoff path, not a bypass — if the server
+goes quiet for 40s. `dispatcher.simulate("disconnect" | "connect")` is a deliberate testing
+affordance; the playground (below) uses it.
+
+## The wire format
+
+`schema/envelope.schema.json` (JSON Schema draft-07) specifies the `{action, id, data}` frame
+`WSDispatcher` sends and receives, independently of the TypeScript `Envelope` type that binds it
+— the schema is the source of truth, the type is one binding of it. Chosen over app3's original
+positional-array form by measurement, not argument: compressed (raw DEFLATE, context carried
+across a session — the realistic case), the object form is only 3.4% larger than positional over
+a representative session. See `websocket-spec.md` T5's dated note for the full byte counts and
+methodology.
+
+## Playground
+
+A live connection against a local echo server, demonstrating queued sends while disconnected, a
+real reconnect with Fibonacci backoff, and the heartbeat watchdog — each one driven by a control
+a real client can't perform on itself (the server dropping the connection with no handshake;
+the server going silent without closing the socket), because `simulate("disconnect")` alone
+proves the opposite case: an explicit close schedules no reconnect at all.
+
+```bash
+npm run playground
+# → http://localhost:8901/packages/websocket/playground/index.html
+```
+
+See the comment at the top of `playground/index.html` for exactly what each button demonstrates.
+
+## Testing
+
+| Command | What it runs |
+|---|---|
+| `npm test` | `node --test` over `test/*.test.mjs` — `Queue`, `WSocket`, `WSDispatcher`, and the envelope schema, against fake sockets and (for the reconnect/heartbeat cases) `node:test`'s built-in fake timers |
+| `npm run typecheck` | `tsc --noEmit` |
+
+No real network in any test — `test/helpers/fake-websocket.mjs` is a synchronous fake shared
+across the `WSocket` and `WSDispatcher` suites.
+
+## License
+
+BSD-3-Clause. See [LICENSE](../../LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { WSocket, ReadyState, SendState } from "./wsocket.js";
+export type { WSocketEventMap } from "./wsocket.js";
+export { WSDispatcher } from "./wsdispatcher.js";
+export type { WSDispatcherOptions } from "./wsdispatcher.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+// Public entry point for @dojo-ng/websocket. `queue.ts`'s Queue is deliberately not re-exported
+// from this file (websocket-spec.md T2) — everything else built here is meant to be used directly.
+export { WSocket, ReadyState, SendState } from "./wsocket.js";
+export { WSDispatcher } from "./wsdispatcher.js";

package/dist/queue.d.ts

@@ -0,0 +1,22 @@
+/** A FIFO queue backed by a singly linked list: enqueue, dequeue, and pushfront are all O(1). */
+export declare class Queue<T> {
+    private head;
+    private tail;
+    private length;
+    /** Inserts the element at the end of the queue. Returns false if `elem` is undefined. */
+    enqueue(elem: T): boolean;
+    /** Same as `enqueue` — kept because app3 call sites use both names. */
+    add(elem: T): boolean;
+    /** Inserts the element at the front of the queue. Returns false if `elem` is undefined. */
+    pushfront(elem: T): boolean;
+    /** Removes and returns the head of the queue, or undefined if empty. */
+    dequeue(): T | undefined;
+    /** Returns the head of the queue without removing it, or undefined if empty. */
+    peek(): T | undefined;
+    size(): number;
+    count(): number;
+    isEmpty(): boolean;
+    clear(): void;
+    /** Visits each element FIFO order. A callback returning `false` stops the iteration. */
+    forEach(callback: (elem: T) => boolean | void): void;
+}

package/dist/queue.js

@@ -0,0 +1,80 @@
+// Internal module. Ported from app3/core/collections/src/Queue.ts (websocket-spec.md T2), as a
+// self-contained singly linked list rather than importing LinkedList.ts — LinkedList has no other
+// consumer in this tree, and the T2 decision is to port only what Queue itself needs, not the rest
+// of app3's collections module (lodash-es included). Never re-export this module from index.ts:
+// that is the whole of the T2 decision (framework-monorepo-spec.md B3, websocket-spec.md T2).
+/** A FIFO queue backed by a singly linked list: enqueue, dequeue, and pushfront are all O(1). */
+export class Queue {
+    constructor() {
+        this.head = null;
+        this.tail = null;
+        this.length = 0;
+    }
+    /** Inserts the element at the end of the queue. Returns false if `elem` is undefined. */
+    enqueue(elem) {
+        return this.add(elem);
+    }
+    /** Same as `enqueue` — kept because app3 call sites use both names. */
+    add(elem) {
+        if (elem === undefined)
+            return false;
+        const node = { value: elem, next: null };
+        if (this.tail) {
+            this.tail.next = node;
+        }
+        else {
+            this.head = node;
+        }
+        this.tail = node;
+        this.length++;
+        return true;
+    }
+    /** Inserts the element at the front of the queue. Returns false if `elem` is undefined. */
+    pushfront(elem) {
+        if (elem === undefined)
+            return false;
+        this.head = { value: elem, next: this.head };
+        if (!this.tail)
+            this.tail = this.head;
+        this.length++;
+        return true;
+    }
+    /** Removes and returns the head of the queue, or undefined if empty. */
+    dequeue() {
+        const node = this.head;
+        if (!node)
+            return undefined;
+        this.head = node.next;
+        if (!this.head)
+            this.tail = null;
+        this.length--;
+        return node.value;
+    }
+    /** Returns the head of the queue without removing it, or undefined if empty. */
+    peek() {
+        return this.head?.value;
+    }
+    size() {
+        return this.length;
+    }
+    count() {
+        return this.length;
+    }
+    isEmpty() {
+        return this.length === 0;
+    }
+    clear() {
+        this.head = null;
+        this.tail = null;
+        this.length = 0;
+    }
+    /** Visits each element FIFO order. A callback returning `false` stops the iteration. */
+    forEach(callback) {
+        let node = this.head;
+        while (node !== null) {
+            if (callback(node.value) === false)
+                break;
+            node = node.next;
+        }
+    }
+}

package/dist/wsdispatcher.d.ts

@@ -0,0 +1,31 @@
+import { type PubSub } from "@dojo-ng/pubsub";
+import { WSocket } from "./wsocket.js";
+export interface WSDispatcherOptions {
+    url: string;
+    /** Frames to send first on every (re)connect, before the offline queue flushes. */
+    onConnect?: () => unknown[];
+    /** Shared with the rest of the app if given; otherwise a private instance is created. */
+    pubsub?: PubSub;
+    /** Publishing here sends an outbound "event" frame. Default `"notify:event"`. */
+    outboundTopic?: string;
+}
+/**
+ * WebSocket message dispatch: frames are routed by `action`. Messages sent while the socket isn't
+ * open are queued and flushed on connect. See the file header for the full behavior list.
+ */
+export declare class WSDispatcher {
+    #private;
+    constructor(options: WSDispatcherOptions);
+    get url(): string;
+    /** The underlying `WSocket`, for connection-state inspection. */
+    get socket(): WSocket;
+    /** The pub/sub instance in use — the caller's own if supplied, otherwise the private default. */
+    get pubsub(): PubSub;
+    isOpen(): boolean;
+    open(force?: boolean): void;
+    close(): void;
+    /** A correlated request: resolves with the `data` of the response frame carrying the same id. */
+    call(data: unknown): Promise<unknown>;
+    /** A deliberate testing affordance — reconnect logic is otherwise nearly untestable. */
+    simulate(action: "disconnect" | "connect"): void;
+}

package/dist/wsdispatcher.js

@@ -0,0 +1,200 @@
+// Ported from app3/core/socket/src/socket.ts (350 lines, websocket-spec.md T4). This is the task
+// that carries the value — everything in the proposal's carry list lands here except the
+// transport/envelope registries (Phase 2, deliberately unwritten until Phase 1 meets a real
+// backend). Carried behaviors, each with its own reason:
+//
+// - Request/response correlation (`call`): `#nextId++` into a callback map, resolved by id on the
+//   matching inbound frame. No timeout/reject path — app3 never had one either, and it's not on
+//   the carry list, so a pending call can wait forever on a connection that never responds. Not a
+//   bug to "fix" here; a deliberate fidelity choice, revisit only if Bill asks for it.
+// - Offline send queue (`#drain`): peeks and sends, dequeuing only on a confirmed OKAY send, so a
+//   failed send never drops the message. BUFFERING retries at 50ms; a confirmed send immediately
+//   tries the next one.
+// - Reconnect with Fibonacci backoff (`#scheduleReopen`): `TIMEOUT_BASE` 15s plus the step table,
+//   counter reset only on a successful open, suppressed entirely while `#closing` is true.
+// - Heartbeat watchdog (`#armHeartbeat`): each inbound "ping" frame arms a 40s timer. On expiry:
+//   close, wait 2s, then go through the SAME backoff-aware reopen path as any other reconnect —
+//   not a bypass. `TIMEOUT_STEP`'s reset-only-on-success rule means a heartbeat failure right after
+//   a fresh open still reopens promptly, but a string of them backs off like any other flapping
+//   connection.
+// - Identity handshake (`onConnect`): app3 hardcoded a SESSID frame built from
+//   `window.hcstatic.sessionid`. Generalized into a caller-supplied hook returning frames to send
+//   first, before the queue flush — the app owns what identity means (DYNLS separation lesson),
+//   this package doesn't know what "who this is" means for any given backend.
+// - Events over pub/sub, not a bespoke API: an inbound "event" frame publishes under its own name;
+//   publishing to `outboundTopic` sends an "event" frame. No new subscription concept invented —
+//   pub/sub is the whole app-facing surface, in both directions.
+// - `simulate("disconnect" | "connect")`: a deliberate testing affordance. Reconnect logic is
+//   otherwise nearly untestable against a real backend.
+//
+// Dropped, not carried: the `queue_available` Defer-based gate around the send queue. It only ever
+// guarded synchronous code (`Queue`'s ops don't await anything), so in single-threaded JS it
+// serialized nothing that wasn't already serial — every method here runs to completion before the
+// next scheduled one starts, so there's no reentrancy hazard for it to guard against. Also dropped:
+// `createDefer` (→ `Promise.withResolvers()`), the `WeakMap` private-props pattern (→ `#private`
+// fields), `Evented`/`ws.on()` (→ `WSocket`'s `EventTarget`, from T3), lodash-es `defer`/`delay` (→
+// native `setTimeout`), all `window.hcstatic.*` coupling, and the MANHOLE/CDPPUSH actions
+// (Holmes-specific). JSON-RPC's header/response-object wrapping is also dropped — that's `core/rpc`
+// territory, out of scope for this package per the proposal's layering.
+//
+// The envelope shape below (`{ action, id, data }`) is a T4-local working assumption, not T5's
+// decision. websocket-spec.md T5 measures compressed bytes on the wire and picks the shape for
+// real; until then this object form (matching the proposal's standing lean) is what dispatch and
+// the tests here operate on.
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _WSDispatcher_instances, _WSDispatcher_url, _WSDispatcher_ws, _WSDispatcher_pubsub, _WSDispatcher_onConnect, _WSDispatcher_msgQueue, _WSDispatcher_cbqueue, _WSDispatcher_closing, _WSDispatcher_reopenCount, _WSDispatcher_nextId, _WSDispatcher_pingTimer, _WSDispatcher_scheduleReopen, _WSDispatcher_flushQueue, _WSDispatcher_enqueue, _WSDispatcher_drain, _WSDispatcher_dispatch, _WSDispatcher_armHeartbeat;
+import { createPubSub } from "@dojo-ng/pubsub";
+import { Queue } from "./queue.js";
+import { WSocket, SendState } from "./wsocket.js";
+const TIMEOUT_BASE = 15;
+const TIMEOUT_STEP = [0, 0, 0, 0, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233];
+const PING_TIMEOUT_MS = 40000;
+const PING_RECOVERY_DELAY_MS = 2000;
+/**
+ * WebSocket message dispatch: frames are routed by `action`. Messages sent while the socket isn't
+ * open are queued and flushed on connect. See the file header for the full behavior list.
+ */
+export class WSDispatcher {
+    constructor(options) {
+        _WSDispatcher_instances.add(this);
+        _WSDispatcher_url.set(this, void 0);
+        _WSDispatcher_ws.set(this, void 0);
+        _WSDispatcher_pubsub.set(this, void 0);
+        _WSDispatcher_onConnect.set(this, void 0);
+        _WSDispatcher_msgQueue.set(this, new Queue());
+        _WSDispatcher_cbqueue.set(this, new Map());
+        _WSDispatcher_closing.set(this, false);
+        _WSDispatcher_reopenCount.set(this, 0);
+        _WSDispatcher_nextId.set(this, 1);
+        _WSDispatcher_pingTimer.set(this, null);
+        __classPrivateFieldSet(this, _WSDispatcher_url, options.url, "f");
+        __classPrivateFieldSet(this, _WSDispatcher_onConnect, options.onConnect, "f");
+        __classPrivateFieldSet(this, _WSDispatcher_pubsub, options.pubsub ?? createPubSub(), "f");
+        __classPrivateFieldSet(this, _WSDispatcher_ws, new WSocket(__classPrivateFieldGet(this, _WSDispatcher_url, "f")), "f");
+        __classPrivateFieldGet(this, _WSDispatcher_ws, "f").addEventListener("message", (event) => {
+            __classPrivateFieldGet(this, _WSDispatcher_instances, "m", _WSDispatcher_dispatch).call(this, event.detail.data);
+        });
+        __classPrivateFieldGet(this, _WSDispatcher_ws, "f").addEventListener("open", () => {
+            __classPrivateFieldSet(this, _WSDispatcher_reopenCount, 0, "f");
+            __classPrivateFieldGet(this, _WSDispatcher_instances, "m", _WSDispatcher_flushQueue).call(this);
+        });
+        __classPrivateFieldGet(this, _WSDispatcher_ws, "f").addEventListener("close", () => {
+            __classPrivateFieldGet(this, _WSDispatcher_instances, "m", _WSDispatcher_scheduleReopen).call(this);
+        });
+        const outboundTopic = options.outboundTopic ?? "notify:event";
+        __classPrivateFieldGet(this, _WSDispatcher_pubsub, "f").subscribe(outboundTopic, (payload) => __classPrivateFieldGet(this, _WSDispatcher_instances, "m", _WSDispatcher_enqueue).call(this, { action: "event", id: 0, data: payload }), { replay: false });
+    }
+    get url() {
+        return __classPrivateFieldGet(this, _WSDispatcher_url, "f");
+    }
+    /** The underlying `WSocket`, for connection-state inspection. */
+    get socket() {
+        return __classPrivateFieldGet(this, _WSDispatcher_ws, "f");
+    }
+    /** The pub/sub instance in use — the caller's own if supplied, otherwise the private default. */
+    get pubsub() {
+        return __classPrivateFieldGet(this, _WSDispatcher_pubsub, "f");
+    }
+    isOpen() {
+        return __classPrivateFieldGet(this, _WSDispatcher_ws, "f").isOpen();
+    }
+    open(force = false) {
+        __classPrivateFieldSet(this, _WSDispatcher_closing, false, "f");
+        __classPrivateFieldGet(this, _WSDispatcher_ws, "f").open(force);
+    }
+    close() {
+        __classPrivateFieldSet(this, _WSDispatcher_closing, true, "f");
+        __classPrivateFieldGet(this, _WSDispatcher_ws, "f").close();
+    }
+    /** A correlated request: resolves with the `data` of the response frame carrying the same id. */
+    call(data) {
+        var _a, _b;
+        const id = (__classPrivateFieldSet(this, _WSDispatcher_nextId, (_b = __classPrivateFieldGet(this, _WSDispatcher_nextId, "f"), _a = _b++, _b), "f"), _a);
+        const { promise, resolve, reject } = Promise.withResolvers();
+        __classPrivateFieldGet(this, _WSDispatcher_cbqueue, "f").set(id, { resolve, reject });
+        __classPrivateFieldGet(this, _WSDispatcher_instances, "m", _WSDispatcher_enqueue).call(this, { action: "call", id, data });
+        return promise;
+    }
+    /** A deliberate testing affordance — reconnect logic is otherwise nearly untestable. */
+    simulate(action) {
+        if (action === "disconnect") {
+            if (!__classPrivateFieldGet(this, _WSDispatcher_closing, "f"))
+                this.close();
+        }
+        else if (!this.isOpen()) {
+            this.open();
+        }
+    }
+}
+_WSDispatcher_url = new WeakMap(), _WSDispatcher_ws = new WeakMap(), _WSDispatcher_pubsub = new WeakMap(), _WSDispatcher_onConnect = new WeakMap(), _WSDispatcher_msgQueue = new WeakMap(), _WSDispatcher_cbqueue = new WeakMap(), _WSDispatcher_closing = new WeakMap(), _WSDispatcher_reopenCount = new WeakMap(), _WSDispatcher_nextId = new WeakMap(), _WSDispatcher_pingTimer = new WeakMap(), _WSDispatcher_instances = new WeakSet(), _WSDispatcher_scheduleReopen = function _WSDispatcher_scheduleReopen() {
+    var _a;
+    if (__classPrivateFieldGet(this, _WSDispatcher_closing, "f"))
+        return;
+    const step = Math.min(__classPrivateFieldGet(this, _WSDispatcher_reopenCount, "f"), TIMEOUT_STEP.length - 1);
+    const timeoutSeconds = TIMEOUT_STEP[step] + TIMEOUT_BASE;
+    __classPrivateFieldSet(this, _WSDispatcher_reopenCount, (_a = __classPrivateFieldGet(this, _WSDispatcher_reopenCount, "f"), _a++, _a), "f");
+    setTimeout(() => {
+        this.open();
+    }, timeoutSeconds * 1000);
+}, _WSDispatcher_flushQueue = function _WSDispatcher_flushQueue() {
+    for (const frame of __classPrivateFieldGet(this, _WSDispatcher_onConnect, "f")?.call(this) ?? []) {
+        __classPrivateFieldGet(this, _WSDispatcher_ws, "f").send(JSON.stringify(frame));
+    }
+    __classPrivateFieldGet(this, _WSDispatcher_instances, "m", _WSDispatcher_drain).call(this);
+}, _WSDispatcher_enqueue = function _WSDispatcher_enqueue(frame) {
+    __classPrivateFieldGet(this, _WSDispatcher_msgQueue, "f").enqueue(frame);
+    __classPrivateFieldGet(this, _WSDispatcher_instances, "m", _WSDispatcher_drain).call(this);
+}, _WSDispatcher_drain = function _WSDispatcher_drain() {
+    if (!__classPrivateFieldGet(this, _WSDispatcher_ws, "f").isOpen() || __classPrivateFieldGet(this, _WSDispatcher_msgQueue, "f").isEmpty())
+        return;
+    const frame = __classPrivateFieldGet(this, _WSDispatcher_msgQueue, "f").peek();
+    const sendState = __classPrivateFieldGet(this, _WSDispatcher_ws, "f").send(JSON.stringify(frame));
+    if (sendState === SendState.OKAY) {
+        __classPrivateFieldGet(this, _WSDispatcher_msgQueue, "f").dequeue();
+    }
+    if (!__classPrivateFieldGet(this, _WSDispatcher_msgQueue, "f").isEmpty() && (sendState === SendState.OKAY || sendState === SendState.BUFFERING)) {
+        const delayMs = sendState === SendState.OKAY ? 0 : 50;
+        setTimeout(() => __classPrivateFieldGet(this, _WSDispatcher_instances, "m", _WSDispatcher_drain).call(this), delayMs);
+    }
+}, _WSDispatcher_dispatch = function _WSDispatcher_dispatch(raw) {
+    const frame = JSON.parse(raw);
+    switch (frame.action) {
+        case "ping":
+            __classPrivateFieldGet(this, _WSDispatcher_instances, "m", _WSDispatcher_armHeartbeat).call(this);
+            break;
+        case "event": {
+            const { event, params } = frame.data;
+            __classPrivateFieldGet(this, _WSDispatcher_pubsub, "f").publish(event, params);
+            break;
+        }
+        case "call": {
+            const pending = __classPrivateFieldGet(this, _WSDispatcher_cbqueue, "f").get(frame.id);
+            if (pending) {
+                __classPrivateFieldGet(this, _WSDispatcher_cbqueue, "f").delete(frame.id);
+                pending.resolve(frame.data);
+            }
+            break;
+        }
+    }
+}, _WSDispatcher_armHeartbeat = function _WSDispatcher_armHeartbeat() {
+    if (__classPrivateFieldGet(this, _WSDispatcher_pingTimer, "f"))
+        clearTimeout(__classPrivateFieldGet(this, _WSDispatcher_pingTimer, "f"));
+    __classPrivateFieldSet(this, _WSDispatcher_pingTimer, setTimeout(() => {
+        __classPrivateFieldSet(this, _WSDispatcher_pingTimer, null, "f");
+        this.close();
+        setTimeout(() => {
+            __classPrivateFieldSet(this, _WSDispatcher_closing, false, "f");
+            __classPrivateFieldGet(this, _WSDispatcher_instances, "m", _WSDispatcher_scheduleReopen).call(this);
+        }, PING_RECOVERY_DELAY_MS);
+    }, PING_TIMEOUT_MS), "f");
+};

package/dist/wsocket.d.ts

@@ -0,0 +1,40 @@
+export declare enum ReadyState {
+    CONNECTING = 0,
+    OPEN = 1,
+    CLOSING = 2,
+    CLOSED = 3
+}
+export declare enum SendState {
+    OKAY = 0,
+    NOT_READY = 1,
+    BUFFERING = 2,
+    SEND_ERROR = 3
+}
+export interface WSocketEventMap {
+    open: CustomEvent<{
+        event: Event;
+    }>;
+    close: CustomEvent<{
+        event: CloseEvent | Record<string, unknown>;
+    }>;
+    message: CustomEvent<{
+        data: unknown;
+    }>;
+    error: CustomEvent<{
+        event: Event;
+    }>;
+}
+/** Canonicalizes differences across `WebSocket` implementations. See the file header for why. */
+export declare class WSocket extends EventTarget {
+    #private;
+    constructor(url: string);
+    get state(): ReadyState;
+    get url(): string;
+    get socket(): WebSocket | null;
+    /** Our own tracked state, not a live re-check of `socket.readyState` — see `send()` for why. */
+    isOpen(): boolean;
+    /** With no existing socket, or `force: true`, tears down any prior socket and opens a fresh one. */
+    open(force?: boolean): void;
+    close(code?: number, reason?: string): void;
+    send(message: string | Blob | BufferSource): SendState;
+}

package/dist/wsocket.js

@@ -0,0 +1,146 @@
+// Ported from app3/core/socket/src/WebSocket.ts (216 lines, websocket-spec.md T3), de-Holmesed:
+// `logSystem` calls dropped, `Evented` replaced with `EventTarget`, and `getWS.ts`'s
+// `MozWebSocket` fallback dropped entirely (dead for over a decade). `WebSocket` is read as the
+// global, at call time rather than a module-scope import — that's also what lets a test substitute
+// a fake one via `globalThis.WebSocket` with no constructor injection seam to design around.
+//
+// Four behaviors carried forward on purpose. Each is a real bug someone would otherwise
+// reintroduce by "simplifying" this file once it looks like it's just wrapping `new WebSocket()`:
+//
+// - Out-of-sync detection (`send`, below): app3's `is_open()` re-checked `socket.readyState` on
+//   every call, which made its own out-of-sync check in `send()` unreachable dead code — `is_open`
+//   already returned false for the same reason before `send()` ever got there. Fixed here by
+//   making `isOpen()` reflect only OUR tracked state (set on `onopen`, cleared by `#handleClose`),
+//   so `send()`'s live re-check of `socket.readyState` is the one thing that actually catches a
+//   socket whose `readyState` moved to CLOSING/CLOSED before its own `onclose`/`onerror` fired —
+//   which is legal per the WebSocket spec and is exactly the state this check exists to catch.
+// - Backpressure: `bufferedAmount > 0` returns BUFFERING rather than sending, so a caller can back
+//   off instead of piling messages into the OS send buffer.
+// - Listener teardown before close: `#handleClose`, when IT decides to actively close a still-open
+//   socket (as opposed to a close already in progress), nulls `onclose`/`onerror`/`onmessage`
+//   before calling the underlying `close()`. Skip that and `close()` re-fires the still-wired
+//   native `onclose`, which re-enters `#handleClose`, which closes again — the reconnect-storm bug.
+// - `open(force)` semantics and handler wiring inside `onopen`: with no existing socket, or with
+//   `force: true`, any prior socket is torn down and a fresh one opened. `message`/`error`/`close`
+//   handlers are wired only once `onopen` fires, which is also why a pre-open error goes straight
+//   to `#handleClose` with no `error` event — the original's asymmetry, preserved because a caller
+//   distinguishing "never connected" from "connected, then errored" depends on it.
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _WSocket_instances, _WSocket_state, _WSocket_socket, _WSocket_url, _WSocket_handleClose;
+export var ReadyState;
+(function (ReadyState) {
+    ReadyState[ReadyState["CONNECTING"] = 0] = "CONNECTING";
+    ReadyState[ReadyState["OPEN"] = 1] = "OPEN";
+    ReadyState[ReadyState["CLOSING"] = 2] = "CLOSING";
+    ReadyState[ReadyState["CLOSED"] = 3] = "CLOSED";
+})(ReadyState || (ReadyState = {}));
+export var SendState;
+(function (SendState) {
+    SendState[SendState["OKAY"] = 0] = "OKAY";
+    SendState[SendState["NOT_READY"] = 1] = "NOT_READY";
+    SendState[SendState["BUFFERING"] = 2] = "BUFFERING";
+    SendState[SendState["SEND_ERROR"] = 3] = "SEND_ERROR";
+})(SendState || (SendState = {}));
+/** Canonicalizes differences across `WebSocket` implementations. See the file header for why. */
+export class WSocket extends EventTarget {
+    constructor(url) {
+        super();
+        _WSocket_instances.add(this);
+        _WSocket_state.set(this, ReadyState.CLOSED);
+        _WSocket_socket.set(this, null);
+        _WSocket_url.set(this, void 0);
+        __classPrivateFieldSet(this, _WSocket_url, url, "f");
+    }
+    get state() {
+        return __classPrivateFieldGet(this, _WSocket_state, "f");
+    }
+    get url() {
+        return __classPrivateFieldGet(this, _WSocket_url, "f");
+    }
+    get socket() {
+        return __classPrivateFieldGet(this, _WSocket_socket, "f");
+    }
+    /** Our own tracked state, not a live re-check of `socket.readyState` — see `send()` for why. */
+    isOpen() {
+        return __classPrivateFieldGet(this, _WSocket_socket, "f") !== null && __classPrivateFieldGet(this, _WSocket_state, "f") === ReadyState.OPEN;
+    }
+    /** With no existing socket, or `force: true`, tears down any prior socket and opens a fresh one. */
+    open(force = false) {
+        if (__classPrivateFieldGet(this, _WSocket_socket, "f")) {
+            if (!force)
+                return;
+            const stale = __classPrivateFieldGet(this, _WSocket_socket, "f");
+            stale.onclose = null;
+            stale.onerror = null;
+            stale.onmessage = null;
+            if (stale.readyState < WebSocket.CLOSING)
+                stale.close();
+            __classPrivateFieldSet(this, _WSocket_socket, null, "f");
+        }
+        __classPrivateFieldSet(this, _WSocket_state, ReadyState.CONNECTING, "f");
+        const socket = (__classPrivateFieldSet(this, _WSocket_socket, new WebSocket(__classPrivateFieldGet(this, _WSocket_url, "f")), "f"));
+        // Pre-open error: straight to close, no `error` event — see the file header.
+        socket.onerror = () => __classPrivateFieldGet(this, _WSocket_instances, "m", _WSocket_handleClose).call(this, {});
+        socket.onopen = (event) => {
+            __classPrivateFieldSet(this, _WSocket_state, ReadyState.OPEN, "f");
+            this.dispatchEvent(new CustomEvent("open", { detail: { event } }));
+            socket.onmessage = (event) => {
+                this.dispatchEvent(new CustomEvent("message", { detail: { data: event.data } }));
+            };
+            socket.onerror = (event) => {
+                this.dispatchEvent(new CustomEvent("error", { detail: { event } }));
+                __classPrivateFieldGet(this, _WSocket_instances, "m", _WSocket_handleClose).call(this, {});
+            };
+            socket.onclose = (event) => __classPrivateFieldGet(this, _WSocket_instances, "m", _WSocket_handleClose).call(this, event);
+        };
+    }
+    close(code, reason) {
+        __classPrivateFieldSet(this, _WSocket_state, ReadyState.CLOSING, "f");
+        __classPrivateFieldGet(this, _WSocket_socket, "f")?.close(code, reason);
+    }
+    send(message) {
+        if (!this.isOpen() || __classPrivateFieldGet(this, _WSocket_socket, "f") === null) {
+            return SendState.NOT_READY;
+        }
+        const socket = __classPrivateFieldGet(this, _WSocket_socket, "f");
+        // Out-of-sync detection — see the file header.
+        if (socket.readyState !== WebSocket.OPEN) {
+            __classPrivateFieldGet(this, _WSocket_instances, "m", _WSocket_handleClose).call(this, { reason: "readyState out of sync with tracked state" });
+            return SendState.NOT_READY;
+        }
+        if (socket.bufferedAmount > 0) {
+            return SendState.BUFFERING;
+        }
+        try {
+            socket.send(message);
+            return SendState.OKAY;
+        }
+        catch {
+            __classPrivateFieldGet(this, _WSocket_instances, "m", _WSocket_handleClose).call(this, { reason: "send threw" });
+            return SendState.SEND_ERROR;
+        }
+    }
+}
+_WSocket_state = new WeakMap(), _WSocket_socket = new WeakMap(), _WSocket_url = new WeakMap(), _WSocket_instances = new WeakSet(), _WSocket_handleClose = function _WSocket_handleClose(event) {
+    __classPrivateFieldSet(this, _WSocket_state, ReadyState.CLOSED, "f");
+    const socket = __classPrivateFieldGet(this, _WSocket_socket, "f");
+    if (socket && socket.readyState < WebSocket.CLOSING) {
+        // Teardown before close — see the file header; this is the reconnect-storm fix.
+        socket.onclose = null;
+        socket.onerror = null;
+        socket.onmessage = null;
+        socket.close();
+    }
+    this.dispatchEvent(new CustomEvent("close", { detail: { event } }));
+    __classPrivateFieldSet(this, _WSocket_socket, null, "f");
+};

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@dojo-ng/websocket",
+  "version": "0.1.0",
+  "description": "Dojo NG websocket client",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "schema"
+  ],
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@dojo-ng/pubsub": "^0.1.0"
+  },
+  "devDependencies": {
+    "ajv": "^8.20.0",
+    "ws": "^8.21.3"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "playground": "node playground/echo-server.mjs"
+  }
+}

package/schema/envelope.schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://dojo-ng.dev/schemas/websocket-envelope.schema.json",
+  "title": "Dojo NG WebSocket envelope",
+  "description": "The wire frame WSDispatcher (websocket-spec.md T4) sends and receives, specified independently of the TypeScript types that bind it (src/wsdispatcher.ts's Envelope interface is one binding of this, not the source of truth). Documented as a T4-local working assumption pending T5's own measurement — see the dated note in websocket-spec.md T5 for the byte-count comparison against a positional-array alternative and why this object shape was kept. Every field is always present; there is no undefined-vs-missing distinction on the wire, only JSON-representable values, so this survives JSON.stringify/json.loads round-trips without losing meaning.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["action", "id", "data"],
+  "properties": {
+    "action": {
+      "description": "Routes dispatch. \"ping\" arms the heartbeat watchdog (inbound only). \"event\" carries a named payload published on pub/sub in either direction. \"call\" is a correlated request/response, matched by id.",
+      "type": "string",
+      "enum": ["ping", "event", "call"]
+    },
+    "id": {
+      "description": "0 for \"ping\" and \"event\" frames, which aren't correlated. A positive integer for \"call\", assigned by the caller and echoed back unchanged on the matching response.",
+      "type": "integer",
+      "minimum": 0
+    },
+    "data": {
+      "description": "Action-specific payload. Any JSON value for \"ping\" and \"call\"; a fixed shape for \"event\", refined below."
+    }
+  },
+  "if": {
+    "properties": { "action": { "const": "event" } }
+  },
+  "then": {
+    "properties": {
+      "data": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["event", "params"],
+        "properties": {
+          "event": {
+            "description": "The pub/sub topic this frame publishes to (inbound) or was published from (outbound).",
+            "type": "string"
+          },
+          "params": {
+            "description": "The payload delivered to pub/sub subscribers under `event`. Any JSON value."
+          }
+        }
+      }
+    }
+  }
+}