@pithy-sh/core 0.13.0 → 0.14.0

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"}

package/dist/presence/http/routes.js

@@ -0,0 +1,127 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { ForbiddenError, InternalError, NotFoundError, PresenceTicketInvalidError } from "../../error/pithyError.js";
+import { remedy } from "../../cli/command.js";
+import { PRESENCE_ROOMS_BINDING, participantCap, presenceRoomPath, presenceSocketPath, presenceTicketPath, resolveTicketKeys, sessionParticipantName } from "../declaration.js";
+import { PresenceRoomParams, PresenceSessionTicketRequest } from "./schemas.js";
+import { describeRoute } from "../../http/routeSpec.js";
+import { requireSameOrigin } from "../../http/sameOrigin.js";
+import { SUBPROTOCOL_HEADER } from "../../http/subprotocol.js";
+import { validate } from "../../http/validation.js";
+import { PRESENCE_ADMISSION_HEADER } from "../room.js";
+import { mintPresenceTicket, ticketFromOffer, verifyPresenceTicket } from "../ticket.js";
+import { requireAuth } from "./guard.js";
+import { PresenceTicket } from "./responses.js";
+//#region src/presence/http/routes.ts
+/**
+* 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. */
+function roomKind(presence, kind) {
+	const room = presence.rooms.find((candidate) => candidate.kind === kind);
+	if (!room) throw new NotFoundError({
+		message: "That room kind does not exist.",
+		params: { kind }
+	});
+	return room;
+}
+/** Mint the ticket a door answers with. */
+async function issuePresenceTicket(c, presence, request) {
+	const keys = await resolveTicketKeys(presence.ticketKey, c.env);
+	const { ticket, claims } = await mintPresenceTicket(request, keys);
+	return {
+		ticket,
+		expiresAt: (/* @__PURE__ */ new Date(claims.exp * 1e3)).toISOString(),
+		kind: claims.kind,
+		recordId: claims.recordId,
+		socketPath: presenceRoomPath(presence.basePath, claims.kind, claims.recordId),
+		protocol: "pithy.presence.v1"
+	};
+}
+/** The room kinds a declaration serves, as the manifest reports them. */
+function describePresenceRooms(presence) {
+	return presence.rooms.map((room) => ({
+		kind: room.kind,
+		scope: room.scope,
+		activities: [...room.activities],
+		maxParticipants: participantCap(room),
+		sessionTicketPath: room.session ? presenceTicketPath(presence.basePath) : null,
+		socketPath: presenceSocketPath(presence.basePath)
+	}));
+}
+function registerPresenceRoutes(app, presence) {
+	app.post(presenceTicketPath(presence.basePath), describeRoute({
+		summary: "Mint a presence ticket for the signed-in user.",
+		description: "Admits the caller to one room of a kind this capability declares, when the capability's own read permission admits them to the record. Single use, for 60 seconds. Open the socket at `socketPath`, offering `protocol` and `pithy.ticket.<ticket>` in `Sec-WebSocket-Protocol`.",
+		verification: ["bearer", "session"],
+		responses: { 201: PresenceTicket }
+	}), requireAuth(), requireSameOrigin(), validate("json", PresenceSessionTicketRequest), async (c) => {
+		const body = c.req.valid("json");
+		const room = roomKind(presence, body.kind);
+		const auth = c.var.auth;
+		if (!auth) throw new InternalError({ detail: "presence session ticket reached without auth" });
+		const grant = room.session ? await room.session(c, body.recordId) : null;
+		if (!grant) throw new ForbiddenError({
+			message: "You cannot join that room.",
+			detail: room.session ? `session gate refused ${body.kind}/${body.recordId}` : `${body.kind} admits management clients only`
+		});
+		const ticket = await issuePresenceTicket(c, presence, {
+			kind: room.kind,
+			recordId: body.recordId,
+			ref: auth.userId,
+			name: sessionParticipantName(grant.name, auth.userId),
+			origin: "session"
+		});
+		return c.json(ticket, 201);
+	});
+	app.get(presenceSocketPath(presence.basePath), describeRoute({
+		summary: "Open a presence room's socket.",
+		description: "Send `Upgrade: websocket` and offer `pithy.presence.v1` and `pithy.ticket.<ticket>` in `Sec-WebSocket-Protocol`; the ticket is the credential, minted by either ticket route for this room. The socket receives who is in the room, then joins, leaves and activity changes as they happen. The frames are in the AsyncAPI contract.",
+		verification: "public",
+		responses: { 101: { description: "Switches to a WebSocket. The room pushes presence frames as JSON text." } }
+	}), validate("param", PresenceRoomParams), async (c) => {
+		const { kind, recordId } = c.req.valid("param");
+		const room = roomKind(presence, kind);
+		const ticket = ticketFromOffer(c.req.header(SUBPROTOCOL_HEADER));
+		if (ticket === void 0) throw new PresenceTicketInvalidError({ detail: "no single ticket in the offer" });
+		const keys = await resolveTicketKeys(presence.ticketKey, c.env);
+		const claims = await verifyPresenceTicket(ticket, {
+			kind,
+			recordId
+		}, keys);
+		const admission = {
+			kind,
+			recordId,
+			ref: claims.ref,
+			name: claims.name,
+			origin: claims.origin,
+			ticket: {
+				id: claims.id,
+				exp: claims.exp
+			},
+			activities: [...room.activities],
+			maxParticipants: participantCap(room)
+		};
+		const request = new Request(c.req.url, c.req.raw);
+		request.headers.set(PRESENCE_ADMISSION_HEADER, JSON.stringify(admission));
+		return roomStub(c, kind, recordId).fetch(request);
+	});
+}
+/** The one room for this record. */
+function roomStub(c, kind, recordId) {
+	const ns = c.env[PRESENCE_ROOMS_BINDING];
+	if (!ns) throw new InternalError({
+		message: "Presence is not available right now.",
+		action: `Bind the ${PRESENCE_ROOMS_BINDING} Durable Object. ${remedy("upgrade", {}, { runtime: true }).say((command) => `${command} writes it.`)}`,
+		detail: `no ${PRESENCE_ROOMS_BINDING} binding`
+	});
+	return ns.get(ns.idFromName(`${kind}:${recordId}`));
+}
+//#endregion
+export { describePresenceRooms, issuePresenceTicket, registerPresenceRoutes, roomKind };

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

@@ -0,0 +1,29 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+/** `POST {base}/presence/tickets` — a signed-in user asks to join a room. The participant is that user. */
+export declare const PresenceSessionTicketRequest: z.ZodObject<{
+    kind: z.ZodString;
+    recordId: z.ZodString;
+}, z.core.$strip>;
+export type PresenceSessionTicketRequest = z.infer<typeof PresenceSessionTicketRequest>;
+/**
+ * `POST /control-plane/presence/tickets` — a management client asks to join a room, naming its participant.
+ * The body is signed with the call, which is what makes the participant the client's own claim.
+ */
+export declare const ControlPlanePresenceTicketRequest: z.ZodObject<{
+    kind: z.ZodString;
+    recordId: z.ZodString;
+    participant: z.ZodObject<{
+        ref: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type ControlPlanePresenceTicketRequest = z.infer<typeof ControlPlanePresenceTicketRequest>;
+/** The socket route's path parameters. */
+export declare const PresenceRoomParams: z.ZodObject<{
+    kind: z.ZodString;
+    recordId: z.ZodString;
+}, z.core.$strip>;
+export type PresenceRoomParams = z.infer<typeof PresenceRoomParams>;
+//# sourceMappingURL=schemas.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../../src/presence/http/schemas.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAUxB,2GAA2G;AAC3G,eAAO,MAAM,4BAA4B;;;iBAE0D,CAAC;AACpG,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAExF;;;GAGG;AACH,eAAO,MAAM,iCAAiC;;;;;;;iBAU2C,CAAC;AAC1F,MAAM,MAAM,iCAAiC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iCAAiC,CAAC,CAAC;AAElG,0CAA0C;AAC1C,eAAO,MAAM,kBAAkB;;;iBAAwF,CAAC;AACxH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/presence/http/schemas.js

@@ -0,0 +1,28 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { PresenceRecordId, PresenceRoomKindName } from "../names.js";
+import { PresenceParticipantName, PresenceParticipantRef } from "../frames.js";
+import { z } from "zod";
+//#region src/presence/http/schemas.ts
+/** The room a ticket is for. */
+const room = {
+	kind: PresenceRoomKindName.describe("The room kind, as the manifest lists it — `support.thread`."),
+	recordId: PresenceRecordId.describe("The record the room is about.")
+};
+/** `POST {base}/presence/tickets` — a signed-in user asks to join a room. The participant is that user. */
+const PresenceSessionTicketRequest = z.object(room).describe("The room a signed-in user asks a presence ticket for. The participant is the caller.");
+/**
+* `POST /control-plane/presence/tickets` — a management client asks to join a room, naming its participant.
+* The body is signed with the call, which is what makes the participant the client's own claim.
+*/
+const ControlPlanePresenceTicketRequest = z.object({
+	...room,
+	participant: z.object({
+		ref: PresenceParticipantRef,
+		name: PresenceParticipantName
+	}).describe("Who joins: the client's own opaque reference for them, and the name the others see.")
+}).describe("The room a management client asks a presence ticket for, and who joins it.");
+/** The socket route's path parameters. */
+const PresenceRoomParams = z.object(room).describe("The room a presence socket joins: its kind and its record.");
+//#endregion
+export { ControlPlanePresenceTicketRequest, PresenceRoomParams, PresenceSessionTicketRequest };

package/dist/presence/names.d.ts

@@ -0,0 +1,23 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+/**
+ * The three names a presence room is made of, as Zod schemas and nothing else.
+ *
+ * A leaf on purpose: the manifest's room descriptor, the ticket responses and the frames all read these, and
+ * a management client holds those in a browser. So this module imports zod and no other thing — never the
+ * declaration, which names the Hono context a session gate runs in.
+ */
+/** A room kind's name: the declaring capability's name, a dot, and a noun — `support.thread`. */
+export declare const PresenceRoomKindName: z.ZodString;
+export type PresenceRoomKindName = z.infer<typeof PresenceRoomKindName>;
+/** One activity a participant may announce — `viewing`, `replying`. A closed vocabulary per room kind, never free text. */
+export declare const PresenceActivity: z.ZodString;
+export type PresenceActivity = z.infer<typeof PresenceActivity>;
+/**
+ * The record a room is about — the id the declaring capability's own routes take. Constrained to what fits a
+ * path segment and a Durable Object name without escaping.
+ */
+export declare const PresenceRecordId: z.ZodString;
+export type PresenceRecordId = z.infer<typeof PresenceRecordId>;
+//# sourceMappingURL=names.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"names.d.ts","sourceRoot":"","sources":["../../src/presence/names.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;GAMG;AAEH,iGAAiG;AACjG,eAAO,MAAM,oBAAoB,aAS9B,CAAC;AACJ,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE,2HAA2H;AAC3H,eAAO,MAAM,gBAAgB,aAIsF,CAAC;AACpH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;GAGG;AACH,eAAO,MAAM,gBAAgB,aAKyE,CAAC;AACvG,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC"}

package/dist/presence/names.js

@@ -0,0 +1,22 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+//#region src/presence/names.ts
+/**
+* The three names a presence room is made of, as Zod schemas and nothing else.
+*
+* A leaf on purpose: the manifest's room descriptor, the ticket responses and the frames all read these, and
+* a management client holds those in a browser. So this module imports zod and no other thing — never the
+* declaration, which names the Hono context a session gate runs in.
+*/
+/** A room kind's name: the declaring capability's name, a dot, and a noun — `support.thread`. */
+const PresenceRoomKindName = z.string().regex(/^[a-z][a-z0-9]*(?:\.[a-z][a-z0-9_]*)+$/, "A room kind is the capability's name, a dot, and a lowercase noun — `support.thread`.").max(64).describe("A room kind: the declaring capability's name, a dot, and a noun — `support.thread`. The first segment is always the capability that declares it, so two capabilities cannot declare the same kind.");
+/** One activity a participant may announce — `viewing`, `replying`. A closed vocabulary per room kind, never free text. */
+const PresenceActivity = z.string().regex(/^[a-z][a-z0-9_]*$/, "An activity is one lowercase word — `viewing`, `replying`.").max(32).describe("What a participant is doing in the room — one of the values its room kind declares, never free text.");
+/**
+* The record a room is about — the id the declaring capability's own routes take. Constrained to what fits a
+* path segment and a Durable Object name without escaping.
+*/
+const PresenceRecordId = z.string().min(1).max(128).regex(/^[A-Za-z0-9._:-]+$/, "A record id is letters, digits, `.`, `_`, `:` and `-`.").describe("The record the room is about — the id the declaring capability's own routes use for it.");
+//#endregion
+export { PresenceActivity, PresenceRecordId, PresenceRoomKindName };