@marianmeres/ws 0.2.0

package/AGENTS.md

@@ -0,0 +1,161 @@
+# @marianmeres/ws — Agent Guide
+
+WebSocket client with namespaces, rooms, presence and reconnect, plus a
+demino-mountable reference server.
+
+## Quick Reference
+
+```yaml
+name: "@marianmeres/ws"
+runtime: "deno (primary), browser/node/bun/workers (client)"
+entry: "./src/mod.ts"
+exports: [".", "./server", "./protocol"]
+test: "deno task test"
+```
+
+| Task                         | File                      | Key export                            |
+| ---------------------------- | ------------------------- | ------------------------------------- |
+| Client                       | `src/client/ws-client.ts` | `createWSClient`, `WSClient`          |
+| Reconnect curve              | `src/client/backoff.ts`   | `backoffDelay`                        |
+| Outbox + pending acks        | `src/client/outbox.ts`    | `Outbox`                              |
+| Room refcounting             | `src/client/rooms.ts`     | `RoomRegistry`                        |
+| Liveness probe               | `src/client/heartbeat.ts` | `Heartbeat`                           |
+| Server factory               | `src/server/mod.ts`       | `createWSApp`                         |
+| Connections, rooms, delivery | `src/server/service.ts`   | `WSService`                           |
+| Wire definitions             | `src/protocol/*`          | `ClientFrame`, `ServerFrame`, `CLOSE` |
+
+## Project Structure
+
+```
+src/
+├── mod.ts                 # client entry
+├── server.ts              # ./server entry  -> server/mod.ts
+├── protocol.ts            # ./protocol entry -> protocol/mod.ts
+├── protocol/              # dependency-free; imported by BOTH sides
+│   ├── constants.ts       # PROTOCOL_VERSION, FRAME, CLOSE, ERROR_CODE, PRESENCE
+│   ├── frames.ts          # ClientFrame / ServerFrame unions, WSMessage
+│   └── errors.ts          # typed errors
+├── client/
+└── server/
+    └── adapters/          # cross-instance fan-out seam (local only today)
+
+example/                   # standalone reference app — `deno task example`
+├── server.ts              # demino apps: /ws (createWSApp), /api, / (static)
+├── history.ts             # WSPubSubAdapter decorator -> in-memory backlog
+├── shared.ts              # the APPLICATION protocol (what goes in `payload`)
+├── client/                # @marianmeres/vanilla views + store, bundled by
+│                          # @marianmeres/deno-build to public/dist/bundle.js
+└── public/                # index.html + design-tokens CSS (theme.css is
+                           # generated by build-theme.ts and IS committed;
+                           # dist/ is not)
+```
+
+`src/server.ts` and `src/protocol.ts` exist because the npm build maps subpath
+exports to `src/{name}.ts`. Do not inline them away.
+
+## Critical Conventions
+
+**Protocol type is not application type.** The protocol owns a closed set of
+frame types; `payload` is opaque and must never be inspected or mutated. The
+predecessor (`stack-sse`) conflated them and had to `delete message.payload.type`
+to compensate — do not reintroduce that.
+
+**`protocol/` is the single source of truth.** Both sides import it. Changing a
+frame shape means changing it there, and bumping `PROTOCOL_VERSION` if the
+change is breaking.
+
+**Ordering on reconnect is load-bearing.** `#onHello` must re-subscribe _before_
+flushing the outbox, and the server must handle `sub`/`unsub` **synchronously**.
+Together these guarantee a buffered publish cannot land in a room the server has
+not registered yet. There is a test that fails if you break it
+(`buffered publishes flush *after* re-subscribe`).
+
+**`sub`/`unsub` bypass the outbox.** They are replayed wholesale by the
+re-subscribe step, so buffering them too would apply them twice.
+
+**Every send carries one deadline** spanning queue + flight + ack — not an
+ack-only timeout. Combining acks with infinite retry otherwise produces promises
+that pend forever.
+
+**The pong deadline is not restarted by later pings.** It measures time since
+the _oldest_ unanswered ping. Restarting it means any `pingInterval <=
+pongTimeout` silently disables half-open detection. This was a real bug; there
+is a regression test.
+
+**Superseded sockets are ignored via `#generation`.** Every socket callback
+checks its captured generation. Without it a slow `onclose` from a dead socket
+cancels the reconnect that replaced it.
+
+**Safe defaults are deny.** `allowBroadcast` denies; HTTP injection routes are
+not mounted without `httpAuth`. Do not "helpfully" relax either.
+
+**Delivery is at-most-once.** Transmitted-but-unacked sends are never resent.
+If that changes, the server needs deduplication first.
+
+## Publishing (JSR + npm)
+
+This package publishes to **both** JSR and npm, and JSR's constraints are the
+binding ones. Anything added to a public API surface must satisfy:
+
+| Requirement           | Rule                                                                           |
+| --------------------- | ------------------------------------------------------------------------------ |
+| Explicit return types | Every exported function, method and getter — no inferred returns               |
+| No slow types         | Nothing in a public signature whose type JSR cannot resolve without inference  |
+| Module docs           | A `/** … @module */` block at the top of **every** file, entry point or not    |
+| Symbol docs           | Every export **and its members** — fields, methods, getters, ctors, const keys |
+| `@param` / `@returns` | On anything non-obvious; `@throws` wherever a typed error can surface          |
+| `@example`            | On entry-point modules and the primary factories                               |
+
+Two commands enforce all of it — run both, they check different things:
+
+```bash
+deno doc --lint src/mod.ts src/server.ts src/protocol.ts   # JSDoc + return types
+deno publish --dry-run --allow-dirty                       # slow types + packaging
+```
+
+`deno doc --lint` is the strict one. Note it does **not** accept a JSDoc block
+containing only tags — `/** @param x - … */` still counts as undocumented. Lead
+with a description sentence, then the tags.
+
+Version and publish via `deno task rp` (patch) / `deno task rpm` (minor); both
+run `deno publish` then the npm build.
+
+## Before Making Changes
+
+1. `deno task test` — 39 tests, all real sockets against a real server
+2. `deno lint && deno fmt --check && deno check src/mod.ts src/server.ts src/protocol.ts`
+3. Touched a public signature? `deno doc --lint src/mod.ts src/server.ts
+   src/protocol.ts` **and** `deno publish --dry-run --allow-dirty`
+4. Touching the wire? Update `src/protocol/` first, then both sides
+5. Touching reconnect, outbox or heartbeat? Read `tests/resilience.test.ts`
+   first — those tests encode the failure modes the design exists to handle
+6. `deno task npm:build` if packaging changed (npm ships the **client only**;
+   the server is Deno-only and excluded via `sourceFiles`) — a new file under
+   `src/client/` or `src/protocol/` must be added to `sourceFiles` by hand
+7. Adding or changing a public export? Update `API.md` — it documents **all**
+   of them, and that completeness is the contract
+8. Changing the client or server API? Run `deno task example` and click through
+   it — the example is the only place the whole stack runs together
+
+## Known Gaps
+
+- No server-side replay, so no at-least-once delivery
+- `recipients` counts are instance-local; they stay that way under a
+  distributed adapter
+- Only `WSPubSubLocal` exists — Redis/Deno-KV adapters are an unimplemented seam
+- Presence is scoped to `(room, namespace)`; broadcast crosses namespaces but
+  presence does not
+- Node/Bun cannot run the server (`Deno.upgradeWebSocket`)
+
+## Documentation Index
+
+| Document            | Purpose                                          |
+| ------------------- | ------------------------------------------------ |
+| `README.md`         | Human-facing overview and usage                  |
+| `API.md`            | Complete API reference — every public export     |
+| `example/README.md` | The reference app: what it demonstrates, and how |
+
+`tmp/spec.md` (design spec and decision log) is referenced in some commits but
+is **untracked** — `tmp/*` is gitignored, so it does not exist in a fresh clone.
+The rationale that matters is duplicated as JSDoc on the symbol it explains;
+read that rather than reconstructing it.