@zerotal/arch 1.7.0

package/docs/broadcasting/channels.md

@@ -0,0 +1,170 @@
+---
+title: Broadcasting Channels
+description: Public, private, presence, and typed channels — and authorizing access to them.
+---
+
+# Channels
+
+`broadcastOn()` returns a channel name (or an array of them). Pick the channel type with one of
+three helpers — they prefix the name so the server and client agree on it:
+
+```ts
+// in an event's broadcastOn()
+import { channel, privateChannel, presenceChannel, isPrivateChannel } from "@zerotal/broadcasting";
+
+channel("posts"); // public   — anyone may subscribe;    name: "posts"
+privateChannel("orders.42"); // private  — requires authorization;  name: "private-orders.42"
+presenceChannel("chat.room1"); // presence — private + member tracking; name: "presence-chat.room1"
+```
+
+| Helper                  | Channel kind | Authorization        | Name prefix |
+| ----------------------- | ------------ | -------------------- | ----------- |
+| `channel(name)`         | Public       | None                 | _(none)_    |
+| `privateChannel(name)`  | Private      | Boolean callback     | `private-`  |
+| `presenceChannel(name)` | Presence     | Member-data callback | `presence-` |
+
+The helpers are idempotent — `privateChannel("private-orders.42")` returns the name unchanged, so
+it's safe to wrap an already-prefixed channel. `isPrivateChannel(name)` is a guard that's `true`
+for both `private-` and `presence-` names.
+
+Private and presence channels are authorized in
+[`routes/channels.ts`](#authorizing-channels); public channels need no auth.
+
+## Authorizing channels
+
+Private and presence channels require server-side authorization before a client can subscribe.
+Define the rules in `routes/channels.ts` with `Broadcast.channel(pattern, callback)` — the
+broadcasting analogue of `routes/web.ts`. It's loaded automatically at boot.
+
+Patterns use the file-routing **`[param]` placeholder syntax**. Each `[param]` matches one channel
+segment and is passed to the callback positionally after the authenticated user.
+
+```ts
+// routes/channels.ts
+import { Broadcast } from "@zerotal/broadcasting";
+import { Order } from "../app/models/Order.ts";
+import type { User } from "../app/models/User.ts";
+
+// Private channel — return a boolean.
+Broadcast.channel("orders.[orderId]", async (user: User, orderId: string) => {
+  return user.id === (await Order.findOrNew(orderId)).userId;
+});
+
+// Presence channel — return member data to authorize + publish presence, or null to deny.
+Broadcast.channel("chat.[roomId]", (user: User, roomId: string) => {
+  if (!user.canJoin(roomId)) return null;
+  return { id: user.id, name: user.name };
+});
+```
+
+- **The authenticated user** is whatever your auth middleware put on the request (`http.user`);
+  guests are denied automatically.
+- **Return value is the signal**: `boolean` for private channels; a member-data object for
+  presence channels (`false`/`null` to deny).
+- **No matching rule = denied.** A private/presence channel with no registered pattern is rejected.
+- Patterns are registered **without** the `private-`/`presence-` prefix (it's stripped before
+  matching), so one `orders.[orderId]` rule covers both private and presence variants.
+
+> **Danger** — The authorization callback is the only thing between a client and another user's
+> data. Return `true`/member data only after you've confirmed the authenticated user may access
+> that exact channel — never trust the channel name alone.
+
+Authorization is enforced on the `POST /broadcasting/auth` path. List every registered rule with:
+
+```bash
+# in your project root
+bun zt channel:list
+```
+
+### Scaffolding
+
+```bash
+# in your project root
+# Add a private channel rule to routes/channels.ts (creates the file if missing).
+bun zt make:channel Order             # -> orders.[id]
+bun zt make:channel orders.[orderId]  # -> orders.[orderId]
+bun zt make:channel chat.[roomId] -p  # -p / --presence: presence-channel stub
+
+# Generate a broadcastable event class (extends BroadcastingEvent).
+bun zt make:event OrderShipped --broadcast   # or -b
+```
+
+`make:channel` appends a `Broadcast.channel(...)` block (private by default, presence with
+`--presence`); a bare model name like `Order` expands to `orders.[id]`. `make:event --broadcast`
+writes an `app/events/*.ts` with `broadcastOn()`/`broadcastWith()` stubbed.
+
+## Presence channels
+
+Presence channels track who is currently subscribed, enabling "who's online" lists. The
+authorization rule for a presence channel returns the **member data** instead of a boolean:
+
+```ts
+// routes/channels.ts
+Broadcast.channel("chat.[roomId]", (user: User, roomId: string) => {
+  if (!user.canJoin(Number(roomId))) return null;
+  return { id: user.id, name: user.name, avatar: user.avatar ?? null };
+});
+```
+
+Read the current members anywhere with `Broadcast.getMembers("presence-chat.room1")`.
+
+### Presence wire events
+
+The server emits these protocol events on a presence channel. Names are shown as they appear on
+the wire; a Pusher-protocol client surfaces them to your code under the `pusher:` prefix
+(e.g. `pusher:subscription_succeeded`).
+
+| Wire event (pusher driver)               | Payload                  | Description                                         |
+| ---------------------------------------- | ------------------------ | --------------------------------------------------- |
+| `pusher_internal:subscription_succeeded` | `{ presence }`           | Sent to the joining client with all current members |
+| `pusher_internal:member_added`           | `{ user_id, user_info }` | Broadcast to other members when someone joins       |
+| `pusher_internal:member_removed`         | `{ user_id }`            | Broadcast to other members when someone leaves      |
+
+> **Note** — The native `ws`/`redis` drivers use the equivalent
+> `subscription_succeeded` / `presence:member_added` / `presence:member_removed` events; the
+> first-party `Socket` client maps them to Echo's `here`/`joining`/`leaving` callbacks for you.
+
+## Typed channels
+
+For end-to-end type safety, declare a channel map and use `TypedBroadcastManager`.
+Keys are channel patterns (with optional `[param]` placeholders); values map event
+names to their payload types. The compiler then enforces that every `to()` /
+`toChannel()` call uses a valid channel, a known event name, and a matching payload.
+
+```ts
+// app/broadcasting/channels.ts
+import { TypedBroadcastManager } from "@zerotal/broadcasting";
+import type { BroadcastChannelMap } from "@zerotal/broadcasting";
+
+export interface Channels extends BroadcastChannelMap {
+  posts: {
+    PostCreated: { id: number; title: string };
+    PostDeleted: { id: number };
+  };
+  "private-orders.[orderId]": {
+    OrderShipped: { orderId: number; trackingCode: string };
+    OrderCancelled: { orderId: number; reason: string };
+  };
+}
+
+const manager = new TypedBroadcastManager<Channels>();
+
+// Static channel — event name + payload are checked against the map
+manager.to("posts", "PostCreated", { id: 1, title: "Hello" });
+
+// Parameterised channel — pass the pattern, its params, then event + payload
+manager.toChannel("private-orders.[orderId]", { orderId: 42 }, "OrderShipped", {
+  orderId: 42,
+  trackingCode: "UPS-123",
+});
+```
+
+A wrong event name, a missing payload field, or an unknown channel is a
+**compile-time error** — nothing reaches the wire. Passing a parameter that the
+pattern doesn't declare (or omitting one) throws `MissingChannelParameterError` at
+runtime.
+
+## Next steps
+
+- [Broadcasting overview](/docs/broadcasting) — the guide's front page and the rest of the sections.
+- [Reference](/docs/broadcasting/references) — the full API surface in one table.

package/docs/broadcasting/client.md

@@ -0,0 +1,108 @@
+---
+title: Broadcasting on the Client
+description: Subscribe from the browser and react to events as they arrive.
+---
+
+# Client-side
+
+## First-party Socket
+
+`@zerotal/client` ships a small, dependency-free `Socket` that speaks the native broadcast
+protocol and exposes a familiar realtime-client API — no external client library, and it works
+with the lightweight `ws` and `redis` drivers (no Pusher credentials needed). It's also a drop-in
+for `window.Echo`, so Flow's [`@on('echo:…')`](/docs/flow/events) listeners work against it.
+
+```ts
+// in your client code
+import { Socket } from "@zerotal/client";
+
+const socket = new Socket(); // ws(s)://<host>/app/ws (matches the `path` config)
+
+// Public channel
+socket.channel("posts").listen("PostPublished", (e) => {
+  console.log("New post:", e.title);
+});
+
+// Private channel (the `private-` prefix is added for you; the WS connection carries the user)
+socket.private(`orders.${id}`).listen("OrderUpdated", (e) => render(e.order));
+
+// Presence channel — who's online
+socket
+  .presence(`chat.${roomId}`)
+  .here((members) => setOnline(members))
+  .joining((m) => addOnline(m))
+  .leaving((m) => removeOnline(m))
+  .listen("Message", (e) => append(e));
+
+// Use it as Echo for Flow @on('echo:…') listeners:
+window.Echo = socket;
+```
+
+Private and presence channels are authorized with a **per-subscription HMAC signature** (the same
+model as Pusher): the client POSTs `{ socket_id, channel_name }` to `authEndpoint` (default
+`/broadcasting/auth`), the server runs the [`routes/channels.ts`](/docs/broadcasting/channels)
+rules and signs the result with the app's `APP_KEY`, and the client echoes the signature in its
+`subscribe`. It's automatically re-fetched on reconnect (the signature is socket-bound). Pass CSRF
+or other headers via `auth.headers`, or set `authEndpoint: false` to skip the fetch and rely on
+connection-level authorization instead:
+
+```ts
+// in your client code
+const socket = new Socket({
+  auth: { headers: { "X-CSRF-TOKEN": csrf } }, // sent on POST /broadcasting/auth
+});
+```
+
+Connection state is observable via `socket.on("connected" | "disconnected" | "reconnecting" |
+"error", cb)`; the client auto-reconnects and re-subscribes. Use `socket.socketId()` as the
+`X-Socket-ID` header on your HTTP requests so server `toOthers()` broadcasts skip the originating
+client.
+
+## Pusher-protocol clients
+
+The server is also Pusher-protocol compatible, so the reference
+[pusher-js](https://github.com/pusher/pusher-js) client works unchanged:
+
+```ts
+// in your client code
+import Pusher from "pusher-js";
+
+const pusher = new Pusher("my-app-key", {
+  wsHost: window.location.hostname,
+  wsPort: 3000,
+  wssPort: 3000,
+  forceTLS: false,
+  disableStats: true,
+  enabledTransports: ["ws"],
+  // Private/presence channel auth — matches POST /broadcasting/auth
+  authEndpoint: "/broadcasting/auth",
+  auth: {
+    headers: {
+      "X-CSRF-TOKEN": document.querySelector('meta[name="csrf-token"]')?.content ?? "",
+    },
+  },
+});
+
+// Subscribe to a public channel
+const postsChannel = pusher.subscribe("posts");
+postsChannel.bind("PostPublished", (data: { title: string; slug: string }) => {
+  console.log("New post:", data.title);
+});
+
+// Subscribe to a private channel
+const ordersChannel = pusher.subscribe("private-orders.42");
+ordersChannel.bind("OrderUpdated", (data) => {
+  console.log("Order updated:", data);
+});
+
+// Subscribe to a presence channel
+const chatChannel = pusher.subscribe("presence-chat.room1");
+chatChannel.bind("pusher:subscription_succeeded", (members) => {
+  console.log("Online members:", members);
+});
+```
+
+## Next steps
+
+- [Broadcasting overview](/docs/broadcasting) — the guide's front page and the rest of the sections.
+- [Reference](/docs/broadcasting/references) — the full API surface in one table.

package/docs/broadcasting/events.md

@@ -0,0 +1,190 @@
+---
+title: Broadcasting Events
+description: Write a broadcast event, dispatch it, and broadcast model changes automatically.
+---
+
+# Writing broadcast events
+
+You only have to implement `broadcastOn()`; the rest default sensibly.
+
+```ts
+// app/events/OrderShipmentStatusUpdated.ts
+import { BroadcastingEvent, privateChannel } from "@zerotal/broadcasting";
+import type { Order } from "../models/Order.ts";
+
+export class OrderShipmentStatusUpdated extends BroadcastingEvent {
+  constructor(public readonly order: Order) {
+    super();
+  }
+
+  broadcastOn() {
+    return privateChannel(`orders.${this.order.id}`);
+  }
+
+  // Optional — all default sensibly:
+  broadcastAs() {
+    return "OrderShipmentStatusUpdated"; // default: the class name
+  }
+  broadcastWith() {
+    return { id: this.order.id, status: this.order.status }; // default: the event's own props
+  }
+  broadcastWhen() {
+    return this.order.total > 100; // default: true
+  }
+}
+```
+
+| Method            | Required | Default               | Description                                     |
+| ----------------- | -------- | --------------------- | ----------------------------------------------- |
+| `broadcastOn()`   | Yes      | —                     | Channel name(s). Use the channel helpers.       |
+| `broadcastAs()`   | No       | the class name        | The wire event name clients listen for.         |
+| `broadcastWith()` | No       | the event's own props | The payload object.                             |
+| `broadcastWhen()` | No       | `true`                | Gate — broadcast only when this returns `true`. |
+
+> **Note** — The lower-level `BroadcastEvent` _interface_ (`broadcastOn`/`broadcastAs?`/`broadcastWith?`)
+> is also exported if you'd rather implement it structurally; `BroadcastingEvent` implements it.
+
+## Dispatching events
+
+Three ways to broadcast, in order of ergonomics:
+
+```ts
+// in a controller
+import { broadcast, Broadcast } from "@zerotal/broadcasting";
+
+// 1. Static dispatch — constructs the event, runs any app-event listeners, AND broadcasts:
+OrderShipmentStatusUpdated.dispatch(order);
+
+// 2. The broadcast() helper — fluent, for excluding the current socket:
+broadcast(new OrderShipmentStatusUpdated(order)).toOthers();
+await broadcast(new OrderShipmentStatusUpdated(order)); // awaitable; sends automatically
+
+// 3. The Broadcast facade — explicit send:
+Broadcast.send(new OrderShipmentStatusUpdated(order));
+```
+
+`broadcast(event).toOthers()` excludes the connection that triggered the request (read from the
+`X-Socket-ID` header your Echo client sends), so the user who just made an optimistic UI update
+doesn't receive a duplicate.
+
+`broadcast()` returns a `PendingBroadcast` — a thenable that sends itself on the next
+microtask, or immediately when awaited. That is what lets `.toOthers()` configure it
+first without you having to remember a `.send()`: both lines above deliver, one
+fire-and-forget and one awaited. Hold the value only if you want to configure it across
+several statements; otherwise treat `broadcast(...)` as the whole call.
+
+A broadcastable event emitted on the [event bus](/docs/events) is broadcast automatically:
+
+```ts
+// in a controller
+import { Events } from "zerotal";
+
+Events.emit(new OrderShipmentStatusUpdated(order)); // runs listeners AND broadcasts
+```
+
+Broadcast to multiple channels by returning an array from `broadcastOn()`:
+
+```ts
+// in an event's broadcastOn()
+broadcastOn() {
+  return [privateChannel(`orders.${this.order.id}`), privateChannel(`users.${this.order.userId}`)];
+}
+```
+
+### Anonymous broadcasts
+
+When a full event class is overkill, broadcast inline:
+
+```ts
+// in a controller
+Broadcast.on(`orders.${order.id}`).as("OrderPlaced").with(order).toOthers().send();
+Broadcast.private(`orders.${order.id}`).as("OrderPlaced").with({ id: order.id }).send();
+Broadcast.presence(`chat.${room.id}`).with({ userId: user.id }).send();
+
+// Or the lowest-level form — push a raw event straight to a channel:
+Broadcast.to("posts", "PostViewed", { id: post.id, viewedAt: Date.now() });
+```
+
+### Reading presence members
+
+Get the members currently subscribed to a presence channel (real driver only —
+returns `[]` under the fake/null driver):
+
+```ts
+// in a controller
+const members = Broadcast.getMembers("presence-chat.room1");
+// → [{ id, info }, …]
+```
+
+## Broadcasting model changes
+
+Broadcast a model's lifecycle changes by mapping them to a `BroadcastingEvent` through the ORM's
+`dispatchesEvents`. When the model fires the event on the [event bus](/docs/events), it is
+broadcast automatically (see [dispatching](#dispatching-events)) — no manual broadcast call.
+
+```ts
+// app/events/PostCreated.ts
+import { BroadcastingEvent, privateChannel } from "@zerotal/broadcasting";
+import type { Post } from "../models/Post.ts";
+
+export class PostCreated extends BroadcastingEvent {
+  constructor(public readonly post: Post) {
+    super();
+  }
+  broadcastOn() {
+    return privateChannel(`posts.${this.post.id}`);
+  }
+  broadcastWith() {
+    return { id: this.post.id, title: this.post.title };
+  }
+}
+```
+
+```ts
+// app/models/Post.ts
+@table("posts")
+export class Post extends Model {
+  static dispatchesEvents = { created: PostCreated, updated: PostUpdated };
+}
+```
+
+Now `await Post.create({ … })` fires `PostCreated`, which broadcasts to `private-posts.[id]`.
+See [ORM Lifecycle & Events](/docs/orm/lifecycle).
+
+### Shortcut: broadcastsModelEvents
+
+When you only need to broadcast the change (no custom event class), `broadcastsModelEvents()`
+wires `created`/`updated`/`deleted` for you. It generates the `BroadcastingEvent`s and populates
+`dispatchesEvents` — the same bridge, less boilerplate. Call it once, below the model:
+
+```ts
+// app/models/Order.ts
+import { Model, column, table } from "@zerotal/orm";
+import { broadcastsModelEvents, privateChannel } from "@zerotal/broadcasting";
+
+@table("orders")
+export class Order extends Model {
+  @column() id!: number;
+  @column() status!: string;
+}
+
+broadcastsModelEvents(Order, {
+  channels: (order) => privateChannel(`orders.${order.id}`),
+  // events: ["created", "updated", "deleted"],   // default
+  // as: (modelName, event) => `${modelName}${event}`,  // wire name; default "OrderUpdated"
+  // with: (order) => ({ id: order.id, status: order.status }), // payload; default { order }
+});
+```
+
+The wire event name defaults to `${ModelName}${Event}` (e.g. `OrderUpdated`) and the payload to
+`{ order }` (the model under its camel-cased name). On the client:
+
+```ts
+// in your client code
+Echo.private(`orders.${id}`).listen("OrderUpdated", (e) => render(e.order));
+```
+
+## Next steps
+
+- [Broadcasting overview](/docs/broadcasting) — the guide's front page and the rest of the sections.
+- [Reference](/docs/broadcasting/references) — the full API surface in one table.

package/docs/broadcasting/index.md

@@ -0,0 +1,163 @@
+---
+title: Broadcasting
+description: Push server-side events to subscribed clients in real time over WebSockets, with Pusher-protocol compatibility built in.
+---
+
+# Broadcasting
+
+Real-time WebSocket broadcasting with a Pusher-compatible server built into the Zerotal
+application process — no separate service required. Define a `BroadcastingEvent`, dispatch it,
+and every subscribed client receives the payload over a live WebSocket connection. Any
+Pusher-protocol client works unchanged.
+
+## Getting Started
+
+```bash
+# in your project root
+bun add @zerotal/broadcasting
+```
+
+## Register the provider
+
+Add `BroadcastProvider` to the providers array in `bootstrap/providers.ts`:
+
+```ts
+// bootstrap/providers.ts
+import { BroadcastProvider } from "@zerotal/broadcasting";
+
+const providers = [
+  // …your other providers
+  BroadcastProvider,
+];
+
+export default providers;
+```
+
+Registering the provider switches on the following (only the hooks it actually uses, in
+lifecycle order):
+
+- `onRegister` — reads `config/broadcasting.ts`, builds the configured driver's
+  `BroadcastManager`, binds it to the container as `broadcast`, wires the auto-broadcast hook so
+  any `BroadcastingEvent` emitted on the [event bus](/docs/events) is broadcast, attaches the
+  WebSocket handlers via `app.withWebSocket()`, and registers the `POST /broadcasting/auth`
+  channel-auth route (for the `ws`, `redis`, and `pusher` drivers).
+- `onBooting` — boots the Redis driver (when active) and side-effect-imports `routes/channels.ts`
+  so its authorization rules are registered before the first auth request.
+- `onBooted` — registers the `channel:list` and `make:channel` CLI commands.
+- `onStopping` — stops the Redis driver, so nothing leaks between boots or test suites.
+
+The provider exposes one HTTP route and one WebSocket upgrade path:
+
+- `POST /broadcasting/auth` — the private/presence channel auth endpoint (a real `Router` route).
+- The WebSocket upgrade is served at the configured `path` (default `/app/ws`) via Bun's
+  WebSocket handler — it is _not_ a separate `Router` route. Pusher/Echo clients connect to
+  `ws://host/app/{appKey}`.
+
+## Configuration
+
+Create `config/broadcasting.ts` with the `BroadcastConfig()` helper so every field stays
+type-checked while literal values stay inferred. All options below are shown with their defaults;
+`redis` and `pusher` are only required for their respective drivers.
+
+```ts
+// config/broadcasting.ts
+import { BroadcastConfig } from "@zerotal/broadcasting";
+import { env } from "zerotal";
+
+export default BroadcastConfig({
+  path: "/app/ws", // WebSocket upgrade path
+  driver: "null", // 'null' | 'ws' | 'redis' | 'pusher'
+
+  // Required when driver is 'redis':
+  redis: { url: env("REDIS_URL", "redis://localhost:6379") },
+
+  // Required when driver is 'pusher':
+  pusher: {
+    appKey: env("PUSHER_APP_KEY", ""),
+    appSecret: env("PUSHER_APP_SECRET", ""),
+  },
+});
+```
+
+| Field    | Required        | Default     | Description                                                                |
+| -------- | --------------- | ----------- | -------------------------------------------------------------------------- |
+| `path`   | no              | `"/app/ws"` | WebSocket upgrade path. Pusher clients connect to `/app/{appKey}` instead. |
+| `driver` | no              | `"null"`    | `'null'` \| `'ws'` \| `'redis'` \| `'pusher'` — how broadcasts are sent.   |
+| `redis`  | with `'redis'`  | —           | `{ url }` Redis connection. Falls back to `redis://localhost:6379`.        |
+| `pusher` | with `'pusher'` | —           | `{ appKey, appSecret }` Pusher/Reverb credentials.                         |
+
+### Which driver should I use?
+
+The active driver decides _how_ a broadcast is delivered. Switch drivers per environment via the
+`driver` key — your event classes never change.
+
+| Driver   | Class                  | Delivery                                       | Use for                                          |
+| -------- | ---------------------- | ---------------------------------------------- | ------------------------------------------------ |
+| `null`   | —                      | Discards everything (default)                  | Local dev / tests where you don't need real WS   |
+| `ws`     | —                      | In-process WebSocket, Zerotal native protocol  | Single-server deployments                        |
+| `redis`  | `RedisBroadcastDriver` | Redis Pub/Sub fan-out, Zerotal native protocol | Horizontally-scaled deployments (many instances) |
+| `pusher` | `PusherCompatManager`  | Pusher-compatible wire protocol                | Existing Pusher-protocol clients                 |
+
+You select a driver through the `driver` key rather than constructing one. The classes
+are exported for the cases that need the instance itself — a test asserting on
+fan-out, or a custom driver wrapping one rather than reimplementing it.
+
+> **Tip** — Start on `null` in tests and local dev; switch to `ws` for a single server, `redis`
+> once you run more than one instance, and `pusher` only when you must speak the Pusher wire
+> protocol to existing clients.
+
+## Basic usage
+
+Import the surface you need from `@zerotal/broadcasting`:
+
+```ts
+// in a controller or event file
+import {
+  Broadcast,
+  BroadcastingEvent,
+  broadcast,
+  channel,
+  privateChannel,
+  presenceChannel,
+} from "@zerotal/broadcasting";
+```
+
+Extend `BroadcastingEvent`, implement `broadcastOn()`, and dispatch — every subscribed client on
+that channel receives the payload:
+
+```ts
+// app/events/OrderShipmentStatusUpdated.ts
+import { BroadcastingEvent, privateChannel } from "@zerotal/broadcasting";
+import type { Order } from "../models/Order.ts";
+
+export class OrderShipmentStatusUpdated extends BroadcastingEvent {
+  constructor(public readonly order: Order) {
+    super();
+  }
+
+  broadcastOn() {
+    return privateChannel(`orders.${this.order.id}`);
+  }
+}
+
+// elsewhere — construct, run listeners, and broadcast in one call:
+OrderShipmentStatusUpdated.dispatch(order);
+```
+
+## The rest of the guide
+
+| Page                                               | What it covers                                                                   |
+| -------------------------------------------------- | -------------------------------------------------------------------------------- |
+| [Events](/docs/broadcasting/events)                | Write a broadcast event, dispatch it, and broadcast model changes automatically. |
+| [Channels](/docs/broadcasting/channels)            | Public, private, presence, and typed channels — and authorizing access to them.  |
+| [on the Client](/docs/broadcasting/client)         | Subscribe from the browser and react to events as they arrive.                   |
+| [Testing Broadcasting](/docs/broadcasting/testing) | Fake the broadcaster and assert on what would have been sent.                    |
+| [References](/docs/broadcasting/references)        | The Broadcast facade, channel APIs, errors, and commands.                        |
+
+## Next steps
+
+- [Events](/docs/events) — the in-process event bus; emitting a `BroadcastingEvent` broadcasts it.
+- [Notifications](/docs/notifications) — real-time notifications over the `'broadcast'` channel.
+- [Authentication](/docs/authentication) — how `http.user` is populated for the
+  `routes/channels.ts` authorization callbacks.
+- [ORM Lifecycle](/docs/orm/lifecycle) — the `dispatchesEvents` bridge that auto-broadcasts model changes.