@pithy-sh/core 0.12.0 → 0.14.0

package/dist/presence/durableObject.js

@@ -0,0 +1,257 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { PithyError, PresenceRoomFullError, PresenceTicketInvalidError, ValidationError, fromZodError } from "../error/pithyError.js";
+import { PRESENCE_ROOM_VERSIONS, PresenceRoomClientFrame, PresenceRoomPing, PresenceRoomPong } from "./frames.js";
+import { PRESENCE_MAX_FRAME_BYTES } from "./declaration.js";
+import { SUBPROTOCOL_HEADER, negotiateSubprotocol } from "../http/subprotocol.js";
+import { PRESENCE_ADMISSION_HEADER, PresenceAdmission, PresenceAttachment, admit, carrySpent, declaresActivity, inheritSpent } from "./room.js";
+import { clientError } from "../error/client.js";
+import { DurableObject } from "cloudflare:workers";
+//#region src/presence/durableObject.ts
+/**
+* **One presence room: who has one record open, and what they are doing.** Addressed by `<kind>:<recordId>`,
+* so each record has its own object.
+*
+* The Hibernation API only: `ctx.acceptWebSocket`, never `ws.accept()`, and no registry of sockets in
+* memory — the participants are read back from `getWebSockets()`, each from its own attachment, so a room
+* that hibernates and wakes knows exactly who is in it. Nothing is written to Durable Object storage: the
+* room holds nothing but who is here, and when the last socket closes it is gone.
+*
+* The upgrade is forwarded by the Worker's socket route, which has verified the ticket and states the
+* admission on {@link PRESENCE_ADMISSION_HEADER}. The room trusts that header — a Durable Object is reached
+* only through its binding — and decides the two things only it can: whether the ticket is already spent, and
+* whether the room is full.
+*/
+var PresenceRoom = class extends DurableObject {
+	/**
+	* Tickets redeemed by sockets that closed while no other socket was left to carry them. Memory, not
+	* storage, and only while the room is empty: the next socket to join takes them into its attachment, and
+	* until one does, {@link awake} keeps the room from hibernating and losing them.
+	*/
+	remembered = [];
+	/**
+	* The timer that holds an empty room awake until the last remembered ticket would expire. A Durable Object
+	* with no socket hibernates after about ten seconds idle and loses its memory, which would let a spent
+	* ticket in again; a pending timer is one of the things that stops it. With no timer, an idle object that
+	* cannot hibernate is evicted only after 70 seconds or more — past a 60-second ticket's life. A deploy or a
+	* restart still clears it, and drops every socket with it.
+	*/
+	awake = null;
+	async fetch(request) {
+		if (request.headers.get("upgrade") !== "websocket") return new Response("Expected a WebSocket upgrade.", { status: 426 });
+		try {
+			const admission = this.admission(request);
+			const version = negotiateSubprotocol(request.headers.get(SUBPROTOCOL_HEADER), PRESENCE_ROOM_VERSIONS);
+			if (version === null) throw new ValidationError({ message: "Offer pithy.presence.v1." });
+			const now = /* @__PURE__ */ new Date();
+			const nowSeconds = Math.floor(now.getTime() / 1e3);
+			const present = this.attachments();
+			const leaving = this.leavingAttachments().flatMap((attachment) => [attachment.ticket, ...attachment.spent]);
+			const refusal = admit(admission, present, [...this.remembered, ...leaving], nowSeconds);
+			if (refusal === "spent") throw new PresenceTicketInvalidError({ detail: `ticket ${admission.ticket.id} is spent` });
+			if (refusal === "full") throw new PresenceRoomFullError({ detail: `${admission.kind}/${admission.recordId} at ${admission.maxParticipants}` });
+			const participant = {
+				id: crypto.randomUUID(),
+				ref: admission.ref,
+				name: admission.name,
+				origin: admission.origin,
+				activity: admission.activities[0],
+				joinedAt: now.toISOString()
+			};
+			const pair = new WebSocketPair();
+			const [client, server] = [pair[0], pair[1]];
+			this.ctx.acceptWebSocket(server);
+			server.serializeAttachment({
+				participant,
+				version,
+				ticket: admission.ticket,
+				activities: admission.activities,
+				spent: inheritSpent(this.remembered, admission.ticket.id, nowSeconds)
+			});
+			this.remembered = [];
+			this.stayAwake(nowSeconds);
+			const everyone = [...present.map((attachment) => attachment.participant), participant].sort((a, b) => a.joinedAt.localeCompare(b.joinedAt));
+			server.send(render({
+				type: "init",
+				self: participant.id,
+				participants: everyone
+			}));
+			this.broadcast({
+				type: "joined",
+				participant
+			}, server);
+			return new Response(null, {
+				status: 101,
+				webSocket: client,
+				headers: { [SUBPROTOCOL_HEADER]: version }
+			});
+		} catch (error) {
+			if (!(error instanceof PithyError)) throw error;
+			return Response.json({ error: clientError(error.payload) }, { status: error.payload.status });
+		}
+	}
+	/**
+	* One frame from a participant: `ping`, or `set_activity` naming an activity the room kind declares. A frame
+	* past the size limit, one that does not parse, and an undeclared activity are each answered with an error
+	* frame and change nothing.
+	*/
+	async webSocketMessage(ws, message) {
+		const attachment = this.attachmentOf(ws);
+		if (!attachment) return;
+		const bytes = typeof message === "string" ? new TextEncoder().encode(message).byteLength : message.byteLength;
+		try {
+			if (bytes > 1024) throw new ValidationError({
+				message: `A frame is at most ${PRESENCE_MAX_FRAME_BYTES} bytes.`,
+				detail: `${bytes} bytes`
+			});
+			const text = typeof message === "string" ? message : new TextDecoder().decode(message);
+			if (PresenceRoomPing.safeParse(text).success) {
+				ws.send(PresenceRoomPong.value);
+				return;
+			}
+			let json;
+			try {
+				json = JSON.parse(text);
+			} catch {
+				throw new ValidationError({ message: "This socket accepts `ping` and JSON frames." });
+			}
+			const parsed = PresenceRoomClientFrame.safeParse(json);
+			if (!parsed.success) throw fromZodError(parsed.error, { message: "This socket accepts `set_activity`." });
+			const frame = parsed.data;
+			if (!declaresActivity(attachment, frame.activity)) throw new ValidationError({
+				message: `This room's activities are ${attachment.activities.join(", ")}.`,
+				params: { activity: frame.activity }
+			});
+			if (frame.activity === attachment.participant.activity) return;
+			const participant = {
+				...attachment.participant,
+				activity: frame.activity
+			};
+			ws.serializeAttachment({
+				...attachment,
+				participant
+			});
+			this.broadcast({
+				type: "activity",
+				participantId: participant.id,
+				activity: frame.activity
+			}, ws);
+		} catch (error) {
+			if (!(error instanceof PithyError)) throw error;
+			try {
+				ws.send(render({
+					type: "error",
+					error: clientError(error.payload)
+				}));
+			} catch {}
+		}
+	}
+	async webSocketClose(ws) {
+		this.leave(ws);
+	}
+	async webSocketError(ws) {
+		this.leave(ws);
+	}
+	/** A socket leaves: everyone else hears it, and the ticket it spent stays spent. */
+	leave(ws) {
+		const closing = this.attachmentOf(ws);
+		if (closing) {
+			const nowSeconds = Math.floor(Date.now() / 1e3);
+			const [carrier] = this.sockets().filter((other) => other !== ws);
+			const carried = carrier ? this.attachmentOf(carrier) : void 0;
+			if (carrier && carried) {
+				const spent = carrySpent(carried, closing, nowSeconds);
+				if (spent) carrier.serializeAttachment({
+					...carried,
+					spent
+				});
+			} else {
+				this.remembered = [
+					...this.remembered,
+					closing.ticket,
+					...closing.spent
+				];
+				this.stayAwake(nowSeconds);
+			}
+			ws.serializeAttachment(null);
+			this.broadcast({
+				type: "left",
+				participantId: closing.participant.id
+			}, ws);
+		}
+		try {
+			ws.close();
+		} catch {}
+	}
+	/**
+	* Hold the room awake until the last remembered ticket would expire, or let it sleep when there is none.
+	* The timer wakes once that has passed and lets go.
+	*/
+	stayAwake(nowSeconds) {
+		this.remembered = this.remembered.filter((ticket) => ticket.exp > nowSeconds);
+		const until = Math.max(0, ...this.remembered.map((ticket) => ticket.exp));
+		if (this.awake && this.remembered.length > 0 && this.awake.until >= until) return;
+		if (this.awake) clearTimeout(this.awake.timer);
+		this.awake = null;
+		if (this.remembered.length === 0) return;
+		const timer = setTimeout(() => {
+			this.awake = null;
+			this.stayAwake(Math.floor(Date.now() / 1e3));
+		}, (until - nowSeconds + 1) * 1e3);
+		this.awake = {
+			until,
+			timer
+		};
+	}
+	/** Send a frame to every participant but one. One dead socket never blocks the rest. */
+	broadcast(frame, except) {
+		const text = render(frame);
+		for (const ws of this.sockets()) {
+			if (ws === except || !this.attachmentOf(ws)) continue;
+			try {
+				ws.send(text);
+			} catch {}
+		}
+	}
+	/** The open sockets the runtime holds for this room. */
+	sockets() {
+		return this.ctx.getWebSockets().filter((ws) => ws.readyState === WebSocket.OPEN);
+	}
+	/** The attachments of sockets the runtime still holds but that are no longer open. */
+	leavingAttachments() {
+		return this.ctx.getWebSockets().flatMap((ws) => {
+			if (ws.readyState === WebSocket.OPEN) return [];
+			const attachment = this.attachmentOf(ws);
+			return attachment ? [attachment] : [];
+		});
+	}
+	/** Every participant's attachment, read back from the runtime. */
+	attachments() {
+		return this.sockets().flatMap((ws) => {
+			const attachment = this.attachmentOf(ws);
+			return attachment ? [attachment] : [];
+		});
+	}
+	attachmentOf(ws) {
+		const parsed = PresenceAttachment.safeParse(ws.deserializeAttachment());
+		return parsed.success ? parsed.data : void 0;
+	}
+	/** The admission the Worker forwarded. Missing or malformed is a request that did not come through the route. */
+	admission(request) {
+		const raw = request.headers.get(PRESENCE_ADMISSION_HEADER);
+		let json;
+		try {
+			json = raw === null ? null : JSON.parse(raw);
+		} catch {
+			json = null;
+		}
+		const parsed = PresenceAdmission.safeParse(json);
+		if (!parsed.success) throw new PresenceTicketInvalidError({ detail: "no admission on the forwarded upgrade" });
+		return parsed.data;
+	}
+};
+function render(frame) {
+	return JSON.stringify(frame);
+}
+//#endregion
+export { PresenceRoom };

package/dist/presence/frames.d.ts

@@ -0,0 +1,166 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+import type { SocketVersions } from "../http/subprotocol";
+/**
+ * **Every frame on a presence room socket, as the Zod schema it is sent and parsed with.**
+ *
+ * Pure: zod and core's leaf modules. A browser imports it to type the socket, and the AsyncAPI document
+ * reads the same schemas through the declaring capability's `sockets`, so the document and the Durable
+ * Object cannot disagree.
+ *
+ * **How a client reads a frame, stated once** (`docs/SOCKETS.md`). A field added to a frame later is
+ * optional. A client ignores a `type` and a key it does not know. A change no client could ignore is a new
+ * subprotocol, and the Worker keeps serving the one before it.
+ *
+ * **The keepalive is plain text**, the one exception to JSON: a client sends `ping`, the Worker answers
+ * `pong`. The only JSON frame a client sends is `set_activity`.
+ */
+/** The subprotocols a room serves. There is no unversioned room: a ticket can only arrive in the offer. */
+export declare const PRESENCE_ROOM_VERSIONS: SocketVersions;
+/** Which door a participant came in by. */
+export declare const PresenceOrigin: z.ZodEnum<{
+    "control-plane": "control-plane";
+    session: "session";
+}>;
+export type PresenceOrigin = z.infer<typeof PresenceOrigin>;
+/** Who a participant is, as the minting door states it. */
+export declare const PresenceParticipantRef: z.ZodString;
+/** The longest participant name, in UTF-16 code units — what zod's `.max` counts. */
+export declare const PRESENCE_PARTICIPANT_NAME_MAX = 80;
+/** How the others see a participant. */
+export declare const PresenceParticipantName: z.ZodString;
+/** One participant in a room. */
+export declare const PresenceParticipant: z.ZodObject<{
+    id: z.ZodString;
+    ref: z.ZodString;
+    name: z.ZodString;
+    origin: z.ZodEnum<{
+        "control-plane": "control-plane";
+        session: "session";
+    }>;
+    activity: z.ZodString;
+    joinedAt: z.ZodISODateTime;
+}, z.core.$strip>;
+export type PresenceParticipant = z.infer<typeof PresenceParticipant>;
+/** The first frame on every room socket. */
+export declare const PresenceRoomInitFrame: z.ZodObject<{
+    type: z.ZodLiteral<"init">;
+    self: z.ZodString;
+    participants: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        ref: z.ZodString;
+        name: z.ZodString;
+        origin: z.ZodEnum<{
+            "control-plane": "control-plane";
+            session: "session";
+        }>;
+        activity: z.ZodString;
+        joinedAt: z.ZodISODateTime;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PresenceRoomInitFrame = z.infer<typeof PresenceRoomInitFrame>;
+/** Someone joined. */
+export declare const PresenceJoinedFrame: z.ZodObject<{
+    type: z.ZodLiteral<"joined">;
+    participant: z.ZodObject<{
+        id: z.ZodString;
+        ref: z.ZodString;
+        name: z.ZodString;
+        origin: z.ZodEnum<{
+            "control-plane": "control-plane";
+            session: "session";
+        }>;
+        activity: z.ZodString;
+        joinedAt: z.ZodISODateTime;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type PresenceJoinedFrame = z.infer<typeof PresenceJoinedFrame>;
+/** Someone left, or their socket dropped. */
+export declare const PresenceLeftFrame: z.ZodObject<{
+    type: z.ZodLiteral<"left">;
+    participantId: z.ZodString;
+}, z.core.$strip>;
+export type PresenceLeftFrame = z.infer<typeof PresenceLeftFrame>;
+/** Someone changed what they are doing. */
+export declare const PresenceActivityFrame: z.ZodObject<{
+    type: z.ZodLiteral<"activity">;
+    participantId: z.ZodString;
+    activity: z.ZodString;
+}, z.core.$strip>;
+export type PresenceActivityFrame = z.infer<typeof PresenceActivityFrame>;
+/** A frame the room could not accept. */
+export declare const PresenceRoomErrorFrame: z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    error: z.ZodObject<{
+        code: z.ZodString;
+        status: z.ZodNumber;
+        message: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        issues: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type PresenceRoomErrorFrame = z.infer<typeof PresenceRoomErrorFrame>;
+/** Every JSON frame the Worker sends on a room socket. `pong` is the plain-text exception. */
+export declare const PresenceRoomServerFrame: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"init">;
+    self: z.ZodString;
+    participants: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        ref: z.ZodString;
+        name: z.ZodString;
+        origin: z.ZodEnum<{
+            "control-plane": "control-plane";
+            session: "session";
+        }>;
+        activity: z.ZodString;
+        joinedAt: z.ZodISODateTime;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"joined">;
+    participant: z.ZodObject<{
+        id: z.ZodString;
+        ref: z.ZodString;
+        name: z.ZodString;
+        origin: z.ZodEnum<{
+            "control-plane": "control-plane";
+            session: "session";
+        }>;
+        activity: z.ZodString;
+        joinedAt: z.ZodISODateTime;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"left">;
+    participantId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"activity">;
+    participantId: z.ZodString;
+    activity: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    error: z.ZodObject<{
+        code: z.ZodString;
+        status: z.ZodNumber;
+        message: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        issues: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    }, z.core.$strip>;
+}, z.core.$strip>], "type">;
+export type PresenceRoomServerFrame = z.infer<typeof PresenceRoomServerFrame>;
+/** Announce a different activity. */
+export declare const PresenceSetActivityFrame: z.ZodObject<{
+    type: z.ZodLiteral<"set_activity">;
+    activity: z.ZodString;
+}, z.core.$strip>;
+export type PresenceSetActivityFrame = z.infer<typeof PresenceSetActivityFrame>;
+/** Every JSON frame a client may send on a room socket. `ping` is the plain-text exception. */
+export declare const PresenceRoomClientFrame: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"set_activity">;
+    activity: z.ZodString;
+}, z.core.$strip>], "type">;
+export type PresenceRoomClientFrame = z.infer<typeof PresenceRoomClientFrame>;
+/** The keepalive a client sends, as plain text. */
+export declare const PresenceRoomPing: z.ZodLiteral<"ping">;
+/** The Worker's answer to `ping`, as plain text. */
+export declare const PresenceRoomPong: z.ZodLiteral<"pong">;
+//# sourceMappingURL=frames.d.ts.map

package/dist/presence/frames.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frames.d.ts","sourceRoot":"","sources":["../../src/presence/frames.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAG1D;;;;;;;;;;;;;GAaG;AAEH,2GAA2G;AAC3G,eAAO,MAAM,sBAAsB,EAAE,cAAiE,CAAC;AAEvG,2CAA2C;AAC3C,eAAO,MAAM,cAAc;;;EAIxB,CAAC;AACJ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,2DAA2D;AAC3D,eAAO,MAAM,sBAAsB,aAMhC,CAAC;AAEJ,qFAAqF;AACrF,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAEhD,wCAAwC;AACxC,eAAO,MAAM,uBAAuB,aAK6E,CAAC;AAElH,iCAAiC;AACjC,eAAO,MAAM,mBAAmB;;;;;;;;;;iBAYmC,CAAC;AACpE,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEtE,4CAA4C;AAC5C,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;iBAQuC,CAAC;AAC1E,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE1E,sBAAsB;AACtB,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;iBAKmB,CAAC;AACpD,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEtE,6CAA6C;AAC7C,eAAO,MAAM,iBAAiB;;;iBAK4C,CAAC;AAC3E,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE,2CAA2C;AAC3C,eAAO,MAAM,qBAAqB;;;;iBAMgC,CAAC;AACnE,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE1E,yCAAyC;AACzC,eAAO,MAAM,sBAAsB;;;;;;;;;iBAOhC,CAAC;AACJ,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE5E,8FAA8F;AAC9F,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAQmC,CAAC;AACxE,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAE9E,qCAAqC;AACrC,eAAO,MAAM,wBAAwB;;;iBAKsB,CAAC;AAC5D,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEhF,+FAA+F;AAC/F,eAAO,MAAM,uBAAuB;;;2BAEiC,CAAC;AACtE,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAE9E,mDAAmD;AACnD,eAAO,MAAM,gBAAgB,sBAAyE,CAAC;AAEvG,oDAAoD;AACpD,eAAO,MAAM,gBAAgB,sBAAiE,CAAC"}

package/dist/presence/frames.js

@@ -0,0 +1,90 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { ErrorBody } from "../error/wire.js";
+import { PresenceActivity } from "./names.js";
+import { z } from "zod";
+//#region src/presence/frames.ts
+/**
+* **Every frame on a presence room socket, as the Zod schema it is sent and parsed with.**
+*
+* Pure: zod and core's leaf modules. A browser imports it to type the socket, and the AsyncAPI document
+* reads the same schemas through the declaring capability's `sockets`, so the document and the Durable
+* Object cannot disagree.
+*
+* **How a client reads a frame, stated once** (`docs/SOCKETS.md`). A field added to a frame later is
+* optional. A client ignores a `type` and a key it does not know. A change no client could ignore is a new
+* subprotocol, and the Worker keeps serving the one before it.
+*
+* **The keepalive is plain text**, the one exception to JSON: a client sends `ping`, the Worker answers
+* `pong`. The only JSON frame a client sends is `set_activity`.
+*/
+/** The subprotocols a room serves. There is no unversioned room: a ticket can only arrive in the offer. */
+const PRESENCE_ROOM_VERSIONS = {
+	current: "pithy.presence.v1",
+	previous: null
+};
+/** Which door a participant came in by. */
+const PresenceOrigin = z.enum(["control-plane", "session"]).describe("Which door the participant came in by: `control-plane`, a management client such as the dashboard, or `session`, a signed-in user of the app.");
+/** Who a participant is, as the minting door states it. */
+const PresenceParticipantRef = z.string().min(1).max(128).describe("Who the participant is. A management client's own opaque reference, which it chose; or the signed-in user's id, which the Worker chose.");
+/** The longest participant name, in UTF-16 code units — what zod's `.max` counts. */
+const PRESENCE_PARTICIPANT_NAME_MAX = 80;
+/** How the others see a participant. */
+const PresenceParticipantName = z.string().trim().min(1).max(80).describe("How the other participants see this one. A label, never an identity — `ref` and `origin` are that.");
+/** One participant in a room. */
+const PresenceParticipant = z.object({
+	id: z.string().uuid().describe("This participant's id in the room — one per socket, so one person in two tabs is two participants."),
+	ref: PresenceParticipantRef,
+	name: PresenceParticipantName,
+	origin: PresenceOrigin,
+	activity: PresenceActivity.describe("What they are doing now, one of the room kind's declared activities."),
+	joinedAt: z.iso.datetime().describe("When this socket joined, ISO-8601.")
+}).describe("One participant in a presence room: one open socket.");
+/** The first frame on every room socket. */
+const PresenceRoomInitFrame = z.object({
+	type: z.literal("init").describe("Always `init`."),
+	self: z.string().uuid().describe("This socket's own participant id, so a client can find itself in the list."),
+	participants: z.array(PresenceParticipant).describe("Everyone in the room now, this socket included, in the order they joined.")
+}).describe("Who is in the room, sent once as soon as the socket opens.");
+/** Someone joined. */
+const PresenceJoinedFrame = z.object({
+	type: z.literal("joined").describe("Always `joined`."),
+	participant: PresenceParticipant.describe("Who joined.")
+}).describe("Another participant joined the room.");
+/** Someone left, or their socket dropped. */
+const PresenceLeftFrame = z.object({
+	type: z.literal("left").describe("Always `left`."),
+	participantId: z.string().uuid().describe("The participant who left.")
+}).describe("Another participant left the room, or their socket dropped.");
+/** Someone changed what they are doing. */
+const PresenceActivityFrame = z.object({
+	type: z.literal("activity").describe("Always `activity`."),
+	participantId: z.string().uuid().describe("The participant whose activity changed."),
+	activity: PresenceActivity.describe("What they are doing now.")
+}).describe("Another participant announced a different activity.");
+/** A frame the room could not accept. */
+const PresenceRoomErrorFrame = z.object({
+	type: z.literal("error").describe("Always `error`."),
+	error: ErrorBody.shape.error
+}).describe("The room could not accept a frame — not one it reads, an activity the room kind does not declare, or past the size limit. The error is the one an HTTP response would carry.");
+/** Every JSON frame the Worker sends on a room socket. `pong` is the plain-text exception. */
+const PresenceRoomServerFrame = z.discriminatedUnion("type", [
+	PresenceRoomInitFrame,
+	PresenceJoinedFrame,
+	PresenceLeftFrame,
+	PresenceActivityFrame,
+	PresenceRoomErrorFrame
+]).describe("A JSON frame the Worker sends on a presence room socket.");
+/** Announce a different activity. */
+const PresenceSetActivityFrame = z.object({
+	type: z.literal("set_activity").describe("Always `set_activity`."),
+	activity: PresenceActivity.describe("What this participant is doing now. One of the room kind's declared values.")
+}).describe("Announce what this participant is doing now.");
+/** Every JSON frame a client may send on a room socket. `ping` is the plain-text exception. */
+const PresenceRoomClientFrame = z.discriminatedUnion("type", [PresenceSetActivityFrame]).describe("A JSON frame a client sends on a presence room socket.");
+/** The keepalive a client sends, as plain text. */
+const PresenceRoomPing = z.literal("ping").describe("The plain-text keepalive a client sends.");
+/** The Worker's answer to `ping`, as plain text. */
+const PresenceRoomPong = z.literal("pong").describe("The plain-text answer to `ping`.");
+//#endregion
+export { PRESENCE_PARTICIPANT_NAME_MAX, PRESENCE_ROOM_VERSIONS, PresenceActivityFrame, PresenceJoinedFrame, PresenceLeftFrame, PresenceOrigin, PresenceParticipant, PresenceParticipantName, PresenceParticipantRef, PresenceRoomClientFrame, PresenceRoomErrorFrame, PresenceRoomInitFrame, PresenceRoomPing, PresenceRoomPong, PresenceRoomServerFrame, PresenceSetActivityFrame };

package/dist/presence/http/guard.d.ts

@@ -0,0 +1,11 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { MiddlewareHandler } from "hono";
+import type { PithyHonoEnv } from "../../capability/capability";
+/**
+ * Require a signed-in user of the app, over the `AuthContext` seam. Kept here rather than imported from
+ * `@pithy-sh/auth`, which core may not depend on — and without auth composed `c.var.auth` is null, so the
+ * session ticket route denies rather than stands open.
+ */
+export declare function requireAuth(): MiddlewareHandler<PithyHonoEnv>;
+//# sourceMappingURL=guard.d.ts.map

package/dist/presence/http/guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../../src/presence/http/guard.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAGhE;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,iBAAiB,CAAC,YAAY,CAAC,CAU7D"}

package/dist/presence/http/guard.js

@@ -0,0 +1,20 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { UnauthorizedError } from "../../error/pithyError.js";
+//#region src/presence/http/guard.ts
+/**
+* Require a signed-in user of the app, over the `AuthContext` seam. Kept here rather than imported from
+* `@pithy-sh/auth`, which core may not depend on — and without auth composed `c.var.auth` is null, so the
+* session ticket route denies rather than stands open.
+*/
+function requireAuth() {
+	return async (c, next) => {
+		if (!c.var.auth) throw new UnauthorizedError({
+			message: "Authentication required.",
+			action: "Sign in and retry with a valid session or bearer token."
+		});
+		await next();
+	};
+}
+//#endregion
+export { requireAuth };

package/dist/presence/http/responses.d.ts

@@ -0,0 +1,31 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+/**
+ * A minted presence ticket and where to spend it. Both ticket routes answer it.
+ *
+ * Read across a version boundary like every response schema, so a field added here later is `.optional()`.
+ */
+export declare const PresenceTicket: z.ZodObject<{
+    ticket: z.ZodString;
+    expiresAt: z.ZodISODateTime;
+    kind: z.ZodString;
+    recordId: z.ZodString;
+    socketPath: z.ZodString;
+    protocol: z.ZodLiteral<string>;
+}, z.core.$strip>;
+export type PresenceTicket = z.infer<typeof PresenceTicket>;
+/**
+ * One room kind, as `GET /control-plane/manifest` reports it under the capability that declares it. Built
+ * from the capability's resolved `basePath`, so a client never assumes where a socket is.
+ */
+export declare const PresenceRoomDescriptor: z.ZodObject<{
+    kind: z.ZodString;
+    scope: z.ZodString;
+    activities: z.ZodArray<z.ZodString>;
+    maxParticipants: z.ZodNumber;
+    sessionTicketPath: z.ZodNullable<z.ZodString>;
+    socketPath: z.ZodString;
+}, z.core.$strip>;
+export type PresenceRoomDescriptor = z.infer<typeof PresenceRoomDescriptor>;
+//# sourceMappingURL=responses.d.ts.map

package/dist/presence/http/responses.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"responses.d.ts","sourceRoot":"","sources":["../../../src/presence/http/responses.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;;GAIG;AACH,eAAO,MAAM,cAAc;;;;;;;iBAmBgF,CAAC;AAC5G,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D;;;GAGG;AACH,eAAO,MAAM,sBAAsB;;;;;;;iBAsB4D,CAAC;AAChG,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC"}

package/dist/presence/http/responses.js

@@ -0,0 +1,34 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { ControlPlaneScope } from "../../controlPlane/scope/scope.js";
+import { PresenceActivity, PresenceRecordId, PresenceRoomKindName } from "../names.js";
+import { PRESENCE_ROOM_VERSIONS } from "../frames.js";
+import { z } from "zod";
+//#region src/presence/http/responses.ts
+/**
+* A minted presence ticket and where to spend it. Both ticket routes answer it.
+*
+* Read across a version boundary like every response schema, so a field added here later is `.optional()`.
+*/
+const PresenceTicket = z.object({
+	ticket: z.string().min(1).describe("The ticket. Offer it in `Sec-WebSocket-Protocol` as `pithy.ticket.<ticket>`, beside `protocol`. Single use."),
+	expiresAt: z.iso.datetime().describe("When the ticket stops being honored, ISO-8601 — 60 seconds after minting."),
+	kind: PresenceRoomKindName.describe("The room kind the ticket admits to."),
+	recordId: PresenceRecordId.describe("The record the room is about."),
+	socketPath: z.string().min(1).describe("The path to open the socket at, on this Worker — this room's, already filled in."),
+	protocol: z.literal(PRESENCE_ROOM_VERSIONS.current).describe("The subprotocol to offer beside the ticket. The Worker answers with it.")
+}).describe("A single-use, 60-second ticket into one presence room, and where to open the socket with it.");
+/**
+* One room kind, as `GET /control-plane/manifest` reports it under the capability that declares it. Built
+* from the capability's resolved `basePath`, so a client never assumes where a socket is.
+*/
+const PresenceRoomDescriptor = z.object({
+	kind: PresenceRoomKindName.describe("The room kind — `support.thread`."),
+	scope: ControlPlaneScope.describe("The scope that reads the record, and so joins its room. A management client mints its ticket with exactly this scope."),
+	activities: z.array(PresenceActivity).min(1).describe("What a participant may announce. The first is what everyone starts as."),
+	maxParticipants: z.number().int().positive().describe("How many participants the room admits at once."),
+	sessionTicketPath: z.string().nullable().describe("Where a signed-in user of the app mints a ticket for this kind, or null when the kind admits management clients only."),
+	socketPath: z.string().min(1).describe("The socket route, with `:kind` and `:recordId` to fill in — the path as the Worker mounted it.")
+}).describe("One presence room kind this capability serves, and how to join one of its rooms.");
+//#endregion
+export { PresenceRoomDescriptor, PresenceTicket };

package/dist/presence/http/routes.d.ts

@@ -0,0 +1,24 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { Context, Hono } from "hono";
+import type { PithyHonoEnv } from "../../capability/capability";
+import { type PresenceDeclaration, type PresenceRoomKind } from "../declaration";
+import { type PresenceTicketRequest } from "../ticket";
+import { type PresenceRoomDescriptor, PresenceTicket } from "./responses";
+/**
+ * A capability's presence routes, mounted by `createBackend` under the `basePath` it declared:
+ *
+ *   POST {base}/presence/tickets                   → a ticket for a signed-in user   (bearer | session)
+ *   GET  {base}/presence/rooms/:kind/:recordId     → the room's socket               (a ticket)
+ *
+ * The control-plane door is the seam's own, `POST /control-plane/presence/tickets`, because one management
+ * client reaches every capability's rooms through it; both doors answer the same {@link PresenceTicket}.
+ */
+/** Find a declared room kind, or the 404 an undeclared one is. */
+export declare function roomKind(presence: PresenceDeclaration, kind: string): PresenceRoomKind;
+/** Mint the ticket a door answers with. */
+export declare function issuePresenceTicket(c: Context<PithyHonoEnv>, presence: PresenceDeclaration, request: PresenceTicketRequest): Promise<PresenceTicket>;
+/** The room kinds a declaration serves, as the manifest reports them. */
+export declare function describePresenceRooms(presence: PresenceDeclaration): PresenceRoomDescriptor[];
+export declare function registerPresenceRoutes(app: Hono<PithyHonoEnv>, presence: PresenceDeclaration): void;
+//# sourceMappingURL=routes.d.ts.map

package/dist/presence/http/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../../src/presence/http/routes.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAOhE,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EAOtB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAsB,KAAK,qBAAqB,EAAyC,MAAM,WAAW,CAAC;AAElH,OAAO,EAAE,KAAK,sBAAsB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAG1E;;;;;;;;GAQG;AAEH,kEAAkE;AAClE,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,EAAE,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAItF;AAED,2CAA2C;AAC3C,wBAAsB,mBAAmB,CACvC,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,EACxB,QAAQ,EAAE,mBAAmB,EAC7B,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,cAAc,CAAC,CAWzB;AAED,yEAAyE;AACzE,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,sBAAsB,EAAE,CAS7F;AAED,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,EAAE,QAAQ,EAAE,mBAAmB,GAAG,IAAI,CA2EnG"}