@carlos-tzin/tzin 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+## 0.1.0 — first public release
+
+Contract-first TypeScript framework: declare a contract once, get the typed
+handler, the typed client, OpenAPI 3.1, MCP tools and realtime channels.
+
+### Core
+
+- `contract()` / `impl()` — flat route registry with O(1) inference per endpoint
+- Extractor-style handler input: `params`, `query`, `body`, `headers`, `cookies`
+  (declared sections only, validated per request via TypeBox)
+- Status-discriminated response unions enforced by the compiler
+- `HttpError` → mapped to declared statuses; middleware can catch and transform
+- Onion-style middleware with typed per-request context (`defineContext`/`ctx.require`)
+- Light DI: `provide(key, value)` seeds typed singletons into request context
+- Radix-trie router (9.1M lookups/s), static beats param, order-stable tiebreak
+
+### Runtimes
+
+- Node (`listen()` — optimized adapter with streaming SSE + WebSockets)
+- Bun (`serveBun()` — native `Bun.serve` websockets)
+- Cloudflare Workers (`toWorker()`, channels inside a Durable Object via
+  `TzinChannels`; verified against real workerd through miniflare)
+
+### Realtime
+
+- Channels mounted as ordinary routes: SSE down / POST up on every runtime,
+  or native WebSockets (`wsChannels` + `attachChannels` / Bun / Workers DO)
+- Presence with TTL, heartbeats and sweep — ghosts disappear even after crashes
+- Multi-node: wire hubs over any `MessageBus` (Redis PUBLISH/SUBSCRIBE,
+  Postgres LISTEN/NOTIFY, Durable Objects); no echo, lazy per-topic subscriptions
+- Zero-dependency browser client: `joinChannel` with auto-heartbeat
+
+### AI-native
+
+- MCP server over stdio (`startStdioMcp`) and Streamable HTTP (`{ mcp: true }`)
+- `tools/list` / `tools/call` dispatch in-process through validation, middleware
+  and DI; HTTP errors surface as `isError` results
+- `/llms.txt` + `/llms-full.txt` generated from contracts (`{ llms: true }`)
+- OpenAPI 3.1 generation with zero schema conversion (TypeBox is JSON Schema)
+
+### Developer experience
+
+- Typed client with status narrowing: `if (res.status === 200) res.body...`
+- Dev server with hot reload printing the route table from contracts
+- CORS as onion middleware: wildcard or reflected origins, allow-lists,
+  credentials-safe (never combines `*` with credentials), preflight
+  short-circuit before routing

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The tzin authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,348 @@
+# tzin
+
+**Contract-first TypeScript framework. Types that scale. Realtime built in. AI-native from day one.**
+
+> `tzin` — from Nahuatl *-tzin*, an honorific suffix for what is valued and beloved.
+> A pact between client and server, declared once.
+
+[![CI](https://github.com/Charly921/tzin/actions/workflows/ci.yml/badge.svg)](https://github.com/Charly921/tzin/actions/workflows/ci.yml)
+
+**Status: experimental, pre-1.0.** The core works end-to-end and the scaling thesis is
+measured (see [Benchmarks](#benchmarks)), but this is not yet production software.
+
+```sh
+npm install tzin
+```
+
+## Why another framework?
+
+The TypeScript backend landscape is crowded — and still leaves real gaps:
+
+| Gap | Evidence |
+|---|---|
+| Type inference collapses at scale | Hono issues [#2399](https://github.com/honojs/hono/issues/2399), [#3869](https://github.com/honojs/hono/issues/3869); chained route builders force one giant expression per app |
+| No architecture in lightweight frameworks | Hono issue [#4121](https://github.com/honojs/hono/issues/4121) |
+| Extractors don't exist in TS | Only Rust's Axum gets handler input right |
+| OpenAPI is a bolt-on | Every TS framework translates its own schema DSL to JSON Schema at runtime or via codegen |
+| AI-native toolchain | One framework ships an MCP server; the window is closing |
+
+tzin's answer: **declare a contract once**, get everything else for free.
+
+```ts
+import { t } from 'tzin'
+import { contract, impl, createApp } from 'tzin'
+
+const getUser = contract({
+  method: 'GET',
+  path: '/users/:id',
+  params: t.Object({ id: t.String() }),
+  responses: {
+    200: t.Object({ id: t.String(), name: t.String(), tags: t.Array(t.String()) }),
+    404: t.Object({ error: t.String() }),
+  },
+})
+
+export const getUserRoute = impl(getUser, async ({ params }) => {
+  const user = await findUser(params.id)
+  if (!user) throw new HttpError(404, 'user not found')
+  return { status: 200, body: user }
+})
+```
+
+From that single declaration:
+
+- **Handler input is extracted, not guessed**: `{ params }` exists because you declared
+  it; add `query`, `body`, `headers` or `cookies` to the contract and they appear,
+  fully typed and validated per request (cookies are parsed from the header).
+- **The compiler enforces your responses**: returning a shape that doesn't match the
+  declared `200` body is a type error. Thrown `HttpError`s map to their status.
+- **OpenAPI 3.1 is free**: contracts are JSON Schema (TypeBox), so
+  `generateOpenApi(routes)` needs no translation layer.
+
+### Server
+
+Web Standards all the way down — an app is just `fetch(req): Promise<Response>`,
+testable without a socket, deployable on Node, Bun, or edge workers:
+
+```ts
+const app = createApp([getUserRoute])
+
+// Node
+listen(app, 3000)
+// Anywhere else
+export default { fetch: app.fetch }
+```
+
+### Typed client
+
+One call, fully inferred — statuses are a discriminated union:
+
+```ts
+const api = client({ getUser }, 'https://api.example.com')
+
+const res = await api.getUser({ params: { id: 'u1' } })
+if (res.status === 200) {
+  res.body.name // string
+} else {
+  res.body.error // string
+}
+```
+
+## Benchmarks
+
+100 endpoints with distinct schemas, checked by `tsc --extendedDiagnostics`
+(generate with `node scripts/gen-fixtures.mjs <N>`):
+
+| N routes | tzin: types | Hono: types | tzin: instantiations | Hono: instantiations | Check tzin / hono |
+|---|---|---|---|---|---|
+| 20 | 4,851 | 72,368 | 22,472 | 156,054 | 0.25s / 0.31s |
+| 100 | 15,779 | 111,952 | 93,128 | 240k | 0.53s / 0.55s |
+| 300 | 43,099 | 210,912 | 270k | 590k | 1.13s / 1.34s |
+
+tzin grows **strictly linearly** (~130 types/endpoint). Two structural findings about
+the chained-builder model this measures against:
+
+1. Route chains must live in a **single expression** — write routes as separate
+   statements and `typeof app` silently loses every route (intermediate types only
+   flow through the chain).
+2. Registering the same path twice **silently degrades client typing**.
+
+A flat registry of plain objects has neither failure mode by construction.
+
+*Honest caveat: the Hono fixture returns constant JSON without validators; the
+documented blow-ups compound further when `zValidator` inference enters the chain.*
+
+### Runtime throughput
+
+100 routes · `GET /r50/item` · 64 connections · 5s (`npm run bench:http`, autocannon,
+each framework in its own process, 3 rotated rounds, median — order rotates so
+machine drift can't bias any variant; tzin runs from built `dist/`):
+
+| Framework | req/s | p99 |
+|---|---|---|
+| raw node:http (floor) | ~42k | 2–3ms |
+| hono | ~34–36k | 3ms |
+| tzin | ~30–31k | 6ms |
+| express | ~15k | 7ms |
+
+The honest decomposition (`npm run bench:pipeline`, in-process `app.fetch` with
+identical request construction):
+
+| Metric | tzin | hono |
+|---|---|---|
+| in-process dispatch | ~127k req/s | ~118k req/s |
+
+Framework-side, tzin matches hono (routing is a radix trie at 9.1M lookups/s,
+full TypeBox validation costs ≈0.05µs/request). The Node adapter duck-types
+requests, memoizes route matches per `METHOD path`, keeps the abort signal lazy
+(wired only if something reads `ctx.signal`), and skips undici Response
+construction entirely on the JSON hot path via `app.dispatchRaw` — tzin lands
+at ~0.9x of hono over the network.
+
+## AI-native: every API is an MCP server
+
+tzin ships first-class [MCP](https://modelcontextprotocol.io) support — the same
+contracts that generate your OpenAPI document also expose your endpoints as tools
+for AI agents:
+
+```ts
+import { startStdioMcp } from 'tzin'
+
+const app = createApp(routes)
+startStdioMcp(app) // newline-delimited JSON-RPC on stdio
+```
+
+- `tools/list` returns each endpoint with a real JSON Schema `inputSchema` assembled
+  from its declared sections — **no conversion layer**, TypeBox already is JSON Schema.
+- `tools/call` dispatches **in-process** through the full app: validation, middleware
+  and DI all apply; HTTP errors surface as `isError` results.
+- Contract-level `name` and `description` become the tool's identity; OpenAPI reuses
+  them as `operationId`/`description`.
+
+Prefer HTTP? Enable the Streamable HTTP transport on the same app:
+
+```ts
+const app = createApp(routes, { mcp: true }) // POST /mcp speaks JSON-RPC
+```
+
+And give LLMs a map of your API straight from the contracts:
+
+```ts
+const app = createApp(routes, {
+  llms: true,
+  openapi: true,
+  meta: { title: 'My API' },
+})
+// GET /llms.txt       — index of endpoints (method, path, name, description)
+// GET /llms-full.txt  — same index plus every declared JSON Schema inline
+// GET /openapi.json   — OpenAPI 3.1 document (TypeBox == JSON Schema == OpenAPI)
+```
+
+## Realtime channels with presence
+
+Phoenix-style channels, mounted as ordinary routes — SSE down, POST up, so it
+runs on every runtime including Workers:
+
+```ts
+import { Hub, Presence, channelRoutes } from 'tzin'
+
+const hub = new Hub()
+const presence = new Presence(hub, 30_000)
+
+const app = createApp(channelRoutes(hub, { presence }))
+// GET  /channels/:topic?member=alice   → SSE stream; presence joins
+// POST /channels/:topic                → { event, data } broadcast
+// POST /channels/:topic/heartbeat      → keep member listed (TTL-refreshed)
+// POST /channels/:topic/leave          → presence_diff broadcast
+```
+
+Members that stop heartbeating are swept and announced via `presence_diff` —
+ghost clients disappear even after crashes. The in-memory `Hub` is one process;
+multi-node deployments wire hubs together over a message bus:
+
+```ts
+import { Hub } from 'tzin'
+import { LocalBus, type MessageBus } from 'tzin/bus'
+
+// Any PUBLISH/SUBSCRIBE transport maps onto this 2-method interface:
+const bus: MessageBus = redisPubSubAdapter // Redis, Postgres LISTEN/NOTIFY...
+
+const nodeA = new Hub({ bus })
+const nodeB = new Hub({ bus })
+// A publish on node A reaches subscribers of every node; own frames are
+// ignored, so there is no echo. Bus subscriptions are per-topic and lazy.
+```
+
+Presence replicates Phoenix-style: every node merges remote join/leave/sweep
+frames into its local view, so `presence_state` snapshots are complete
+cluster-wide, subscribers get the full roster on connect, and ghosts left by a
+dead node are expired by any surviving node's TTL sweep.
+
+A zero-dependency client ships for browsers (and Node >= 22 with any
+EventSource polyfill) — auto-heartbeat, presence events and reconnection via
+the platform's EventSource:
+
+```ts
+import { joinChannel } from 'tzin/client-browser'
+
+const chat = joinChannel('https://api.example.com', 'lobby', { member: 'ada' })
+chat.on('message', (data) => render(data))
+chat.on('presence_diff', (d) => updateRoster(d))
+await chat.push('message', { text: 'hello' })
+```
+
+### Native WebSockets
+
+Prefer WebSockets over SSE+POST? The same Hub and Presence power a WS route —
+one protocol implementation, thin per-runtime adapters:
+
+```ts
+import { wsChannels } from 'tzin/ws'
+import { attachChannels } from 'tzin/ws-node' // Node adapter (ws package)
+// Bun: serve(app, port, { wsRoutes: [wsChannels(hub, { presence })] })
+
+const server = await listen(createApp(routes), 3000)
+attachChannels(server, [wsChannels(hub, { presence })])
+// ws://host/channels/:topic?member=ada — frames: {type:'push'|'heartbeat'}, receive {event,data}
+```
+
+On Cloudflare Workers, run the whole app inside a Durable Object so every
+connection shares one I/O context — cross-connection broadcast then behaves
+exactly like Node/Bun (workerd drops sends that come from another request's
+context, which is why plain fetch handlers can't relay between sockets):
+
+```ts
+import { toDurableWorker, toWorker, TzinChannels } from 'tzin'
+import { Hub, Presence, channelRoutes, wsChannels, createApp } from 'tzin'
+
+export { TzinChannels } // workerd discovers DO classes among exports
+
+export default toDurableWorker(() => {
+  const hub = new Hub()
+  const presence = new Presence(hub)
+  const app = createApp([...routes, ...channelRoutes(hub, { presence })])
+  return toWorker(app, { wsRoutes: [wsChannels(hub, { presence })] })
+})
+```
+
+```jsonc
+// wrangler config additions:
+"durable_objects": {
+  "bindings": [{ "name": "TZIN_APP", "class_name": "TzinChannels" }]
+},
+"migrations": [{ "tag": "v1", "new_sqlite_classes": ["TzinChannels"] }]
+```
+
+Verified against real workerd via miniflare (`npm run probe:workers`):
+HTTP ✓, WS upgrade ✓, roster ✓, broadcast across connections ✓, leave diff ✓.
+
+## Design principles
+
+- **Contract-first, flat registry.** A route is data (`contract({...})`), not a link
+  in a builder chain. Inference cost stays O(1) per endpoint.
+- **JSON Schema native.** TypeBox schemas double as OpenAPI with zero conversion.
+- **Web Standards runtime.** `Request` in, `Response` out; adapters stay thin.
+- **Extractors over magic.** Handlers receive exactly what the contract declares.
+- **Errors are control flow.** Throw typed errors; the response union already knows.
+- **Light DI without ceremony.** `provide(key, value)` at app level seeds typed
+  singletons into every request's context — handlers just `ctx.require(db)`.
+  Request-scoped middleware can override. No decorators, no reflection, no
+  container configuration files.
+
+## Roadmap
+
+- [x] Spike: contracts, router, server, typed client, OpenAPI generation
+- [x] Middleware composition (onion-style) with typed per-request context
+- [x] Adapters: Node, Bun (verified e2e), Workers (HTTP + DO-backed WebSockets, verified via miniflare/workerd)
+- [x] Streaming/SSE (`sse()` helper + `raw()` escape hatch)
+- [x] Realtime: Hub (pub/sub), Presence (TTL + diffs), mountable channel routes
+- [x] Native WebSockets for channels: Node + Bun verified, Workers via Durable Objects
+- [x] Multi-node realtime over a `MessageBus` (Redis/Postgres/Durable Objects map onto it)
+- [x] Typed client with status-discriminated unions + zero-dep browser channel client
+- [x] Optional light DI layer (`provide()` → typed singleton seeds in request context)
+- [x] AI-native toolchain: MCP (stdio + Streamable HTTP), OpenAPI 3.1, `/llms.txt`
+- [x] Batteries started: CORS middleware, bearer-auth pattern (see `examples/todo-api.ts`)
+- [ ] Phoenix-style presence replication across nodes
+- [ ] `create-tzin` scaffolding
+
+## Development
+
+```sh
+npm install
+npm test          # vitest — runtime + end-to-end client + type assertions
+npm run typecheck # strict tsc across src/test/bench fixtures
+```
+
+### Production-shaped example
+
+`examples/todo-api.ts` is the full story in one runnable file: bearer-token auth
+as onion middleware, typed context DI between middleware and handlers,
+app-scoped injected store, ownership checks, query coercion, and the generated
+`/openapi.json` + `/llms.txt` + `POST /mcp` surface from the same contracts.
+
+```sh
+npx tsx examples/todo-api.ts
+TOKEN=$(curl -s localhost:4644/auth/login -H 'content-type: application/json' \
+  -d '{"username":"ada","password":"lovelace"}' | node -pe 'JSON.parse(require("fs").readFileSync(0)).token')
+curl -s localhost:4644/todos -H "authorization: Bearer $TOKEN"
+```
+
+### Dev server
+
+```sh
+npx tsx src/cli.ts dev examples/node-demo.ts --port 3000
+```
+
+Hot-reloading server (tsx watch) that prints your route table straight from the
+contracts on every reload:
+
+```
+tzin dev · 2 routes
+
+  GET     /users/:id        get_user   Look up a user by id
+  POST    /users            create_user
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/bun.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Bun adapter. NOTE: authored against Bun's documented `Bun.serve` API;
+ * verified locally on Bun 1.4.0 for plain HTTP (examples/bun-demo.ts).
+ */
+import type { App } from './server.js';
+import type { WsRoute } from './ws.js';
+export declare function serve(app: App, port?: number, options?: {
+    wsRoutes?: WsRoute[];
+}): void;

package/dist/bun.js

@@ -0,0 +1,46 @@
+import { createMatcher } from './router.js';
+export function serve(app, port = 3000, options = {}) {
+    const wsRoutes = options.wsRoutes ?? [];
+    const matcher = wsRoutes.length
+        ? createMatcher(wsRoutes.map((r) => ({ method: 'GET', path: r.path, route: r })))
+        : undefined;
+    Bun.serve({
+        port,
+        fetch: (req, server) => {
+            if (matcher && req.headers.get('upgrade')?.toLowerCase() === 'websocket' && server) {
+                const url = new URL(req.url);
+                const hit = matcher('GET', url.pathname);
+                if (hit && 'route' in hit) {
+                    const upgraded = server.upgrade(req, { data: { route: hit.route, url } });
+                    if (upgraded)
+                        return undefined;
+                }
+                return new Response('WebSocket upgrade failed', { status: 400 });
+            }
+            return app.fetch(req);
+        },
+        ...(wsRoutes.length
+            ? {
+                websocket: {
+                    open(ws) {
+                        const { route, url } = ws.data;
+                        if (!route || !url)
+                            return;
+                        ws.data.state = route.open((frame) => ws.send(JSON.stringify(frame)), url);
+                    },
+                    message(ws, message) {
+                        const { route } = ws.data;
+                        if (route && ws.data.state !== undefined) {
+                            route.message(ws.data.state, String(message));
+                        }
+                    },
+                    close(ws) {
+                        const { route } = ws.data;
+                        if (route && ws.data.state !== undefined)
+                            route.close(ws.data.state);
+                    },
+                },
+            }
+            : {}),
+    });
+}

package/dist/bus.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Message bus abstraction for multi-node realtime.
+ *
+ * A bus moves serialized channel frames between nodes. The in-memory Hub
+ * stays the local delivery point on every node; the bus is what makes two
+ * processes behave like one deployment. Redis (PUBLISH/SUBSCRIBE), Postgres
+ * LISTEN/NOTIFY and Cloudflare Durable Objects all map onto this interface.
+ */
+import { Hub } from './hub.js';
+export interface MessageBus {
+    /** Fire-and-forget broadcast to every node subscribed to the channel. */
+    publish(channel: string, message: string): void;
+    /** Receive messages published on any node; returns an unsubscribe fn. */
+    subscribe(channel: string, handler: (message: string) => void): () => void;
+}
+/** In-process bus: wires hubs together inside one runtime (tests, single node). */
+export declare class LocalBus implements MessageBus {
+    #private;
+    publish(channel: string, message: string): void;
+    subscribe(channel: string, handler: (message: string) => void): () => void;
+}
+/**
+ * Create `count` Hubs that behave as one logical deployment over `bus`.
+ * A publish on any hub reaches subscribers of every other hub, exactly as
+ * it would across Redis pub/sub — only the transport differs.
+ */
+export declare function clusterHubs(bus: MessageBus, count?: number): Hub[];

package/dist/bus.js

@@ -0,0 +1,42 @@
+/**
+ * Message bus abstraction for multi-node realtime.
+ *
+ * A bus moves serialized channel frames between nodes. The in-memory Hub
+ * stays the local delivery point on every node; the bus is what makes two
+ * processes behave like one deployment. Redis (PUBLISH/SUBSCRIBE), Postgres
+ * LISTEN/NOTIFY and Cloudflare Durable Objects all map onto this interface.
+ */
+import { Hub } from './hub.js';
+/** In-process bus: wires hubs together inside one runtime (tests, single node). */
+export class LocalBus {
+    #channels = new Map();
+    publish(channel, message) {
+        const set = this.#channels.get(channel);
+        if (!set)
+            return;
+        for (const handler of [...set])
+            handler(message);
+    }
+    subscribe(channel, handler) {
+        let set = this.#channels.get(channel);
+        if (!set) {
+            set = new Set();
+            this.#channels.set(channel, set);
+        }
+        set.add(handler);
+        return () => {
+            set.delete(handler);
+            if (set.size === 0)
+                this.#channels.delete(channel);
+        };
+    }
+}
+/**
+ * Create `count` Hubs that behave as one logical deployment over `bus`.
+ * A publish on any hub reaches subscribers of every other hub, exactly as
+ * it would across Redis pub/sub — only the transport differs.
+ */
+export function clusterHubs(bus, count = 2) {
+    const prefix = 'tzin:ch:';
+    return Array.from({ length: count }, () => new Hub({ bus, channelPrefix: prefix }));
+}

package/dist/channels.d.ts

@@ -0,0 +1,14 @@
+import { type RouteImpl } from './contract.js';
+import type { Hub } from './hub.js';
+import type { Presence } from './presence.js';
+export interface ChannelOptions {
+    presence?: Presence;
+}
+/**
+ * Batteries-included realtime endpoints:
+ *   GET  /channels/:topic            subscribe (SSE); ?member= enables presence
+ *   POST /channels/:topic            publish { event, data? }
+ *   POST /channels/:topic/heartbeat  presence join/refresh { member, meta? }
+ *   POST /channels/:topic/leave      presence leave { member }
+ */
+export declare function channelRoutes(hub: Hub, options?: ChannelOptions): RouteImpl<any>[];

package/dist/channels.js

@@ -0,0 +1,99 @@
+import { t } from './schema.js';
+import { contract, impl } from './contract.js';
+import { sse } from './sse.js';
+/**
+ * Batteries-included realtime endpoints:
+ *   GET  /channels/:topic            subscribe (SSE); ?member= enables presence
+ *   POST /channels/:topic            publish { event, data? }
+ *   POST /channels/:topic/heartbeat  presence join/refresh { member, meta? }
+ *   POST /channels/:topic/leave      presence leave { member }
+ */
+export function channelRoutes(hub, options = {}) {
+    const presence = options.presence;
+    const subscribe = contract({
+        name: 'subscribe_channel',
+        description: 'Subscribe to a channel via SSE. Pass ?member=NAME to appear in presence.',
+        method: 'GET',
+        path: '/channels/:topic',
+        params: t.Object({ topic: t.String() }),
+        query: t.Object({ member: t.Optional(t.String()) }),
+        responses: {
+            200: t.Object({ ok: t.Boolean() }),
+            404: t.Object({ error: t.String() }),
+        },
+    });
+    const publish = contract({
+        name: 'publish_channel',
+        description: 'Broadcast an event to every subscriber of a channel.',
+        method: 'POST',
+        path: '/channels/:topic',
+        params: t.Object({ topic: t.String() }),
+        body: t.Object({ event: t.String(), data: t.Optional(t.Unknown()) }),
+        responses: { 200: t.Object({ delivered: t.Number() }) },
+    });
+    const heartbeat = contract({
+        name: 'channel_heartbeat',
+        description: 'Join a channel or refresh presence for a member.',
+        method: 'POST',
+        path: '/channels/:topic/heartbeat',
+        params: t.Object({ topic: t.String() }),
+        body: t.Object({ member: t.String(), meta: t.Optional(t.Unknown()) }),
+        responses: { 200: t.Object({ ok: t.Boolean() }) },
+    });
+    const leave = contract({
+        name: 'channel_leave',
+        description: 'Leave a channel; triggers a presence_diff broadcast.',
+        method: 'POST',
+        path: '/channels/:topic/leave',
+        params: t.Object({ topic: t.String() }),
+        body: t.Object({ member: t.String() }),
+        responses: { 200: t.Object({ ok: t.Boolean() }) },
+    });
+    const routes = [
+        impl(subscribe, ({ params, query, ctx }) => {
+            const topic = params.topic;
+            const member = query?.member;
+            return sse(async (send) => {
+                send.comment(`subscribed ${topic}`);
+                const unsub = hub.subscribe(topic, (e) => send.event(e.event, e.data));
+                if (member && presence)
+                    presence.join(topic, member);
+                // Initial full view (Phoenix parity): anonymous subscribers get the
+                // room state here; members just got their join broadcast above.
+                if (presence)
+                    send.event('presence_state', { members: presence.snapshot(topic) });
+                const cleanup = () => {
+                    unsub();
+                    if (member && presence)
+                        presence.leave(topic, member);
+                };
+                const signal = ctx.signal;
+                if (!signal) {
+                    return;
+                }
+                if (signal.aborted) {
+                    cleanup();
+                    return;
+                }
+                await new Promise((resolve) => signal.addEventListener('abort', () => {
+                    cleanup();
+                    resolve();
+                }, { once: true }));
+            }, ctx.signal);
+        }),
+        impl(publish, ({ params, body }) => ({
+            status: 200,
+            body: { delivered: hub.publish(params.topic, body.event, body.data ?? null) },
+        })),
+    ];
+    if (presence) {
+        routes.push(impl(heartbeat, ({ params, body }) => {
+            presence.heartbeat(params.topic, body.member, body.meta);
+            return { status: 200, body: { ok: true } };
+        }), impl(leave, ({ params, body }) => {
+            presence.leave(params.topic, body.member);
+            return { status: 200, body: { ok: true } };
+        }));
+    }
+    return routes;
+}

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {};