@spacefast/common 0.0.13 → 0.0.17

package/dist/contracts/archives.js

@@ -12,7 +12,7 @@ export const spaceExportRequestSchema = z
     includeFiles: z
         .boolean()
         .default(true)
-        .describe("Include version file trees and compiled serving artifacts. `false` produces a config-only archive that is not self-servable and cannot be re-imported."),
+        .describe("Pass `true` to include version file trees and compiled serving artifacts. Pass `false` for a config-only archive that is not self-servable and cannot be re-imported."),
 })
     .strict();
 export const spaceExportArchiveSchema = z.object({
@@ -33,8 +33,8 @@ export const spaceExportArchiveSchema = z.object({
         .describe("SHA-256 of the archive bytes (64 lowercase hex characters), for verification."),
 });
 export const spaceExportSchema = z.object({
-    id: z.string().describe("Export handle id (exp_…)."),
-    spaceId: z.string().describe("Source space id (spc_…)."),
+    id: z.string().describe("The export handle id (`exp_…`)."),
+    spaceId: z.string().describe("The source space id (`spc_…`)."),
     status: z
         .enum(["queued", "running", "ready", "failed", "expired"])
         .describe("Export lifecycle. `expired` means the archive download window has passed."),
@@ -52,8 +52,8 @@ export const spaceExportSchema = z.object({
         .string()
         .nullable()
         .describe("Operation (op_…) tracking the asynchronous export work."),
-    createdAt: z.string().datetime().describe("When the export handle was created."),
-    updatedAt: z.string().datetime().describe("When the export handle last changed."),
+    createdAt: z.string().datetime().describe("Instant when the export handle was created."),
+    updatedAt: z.string().datetime().describe("Instant when the export handle last changed."),
 });
 export const spaceExportListResponseSchema = z.object({
     data: z.array(spaceExportSchema),
@@ -81,11 +81,11 @@ export const spaceImportRequestSchema = z.object({
     publish: z
         .boolean()
         .default(false)
-        .describe("Promote the newest imported version to the live channel once materialized. Imported versions never go public implicitly."),
+        .describe("Pass `true` to promote the newest imported version to the live channel after it materializes. Imported versions never go public implicitly."),
 });
 export const spaceImportSchema = z.object({
-    id: z.string().describe("Import handle id (imp_…)."),
-    targetSpaceId: z.string().describe("Target space id (spc_…) the import materializes into."),
+    id: z.string().describe("The import handle id (`imp_…`)."),
+    targetSpaceId: z.string().describe("The target space id (`spc_…`) the import materializes into."),
     status: z
         .enum([
         "created",
@@ -99,7 +99,7 @@ export const spaceImportSchema = z.object({
         .describe("Import lifecycle. Upload-kind imports wait in `waiting_for_archive` until the archive is uploaded and the import is finalized."),
     archiveUpload: uploadInstructionsSchema
         .optional()
-        .describe("Archive upload instructions — the same upload contract as publish. Present while status is `waiting_for_archive`: PUT the archive to `{baseUrl}/{files[0]}` with the session token, then POST `links.finalize`. Each fetch of the import re-mints a fresh token."),
+        .describe("Archive upload instructions. This is the same upload contract as publish. Present while status is `waiting_for_archive`: PUT the archive to `{baseUrl}/{files[0]}` with the session token, then POST `links.finalize`. Each fetch of the import mints a fresh token."),
     draftVersionIds: z
         .array(z.string())
         .describe("Version ids (ver_…) minted and owned by this import."),
@@ -111,8 +111,8 @@ export const spaceImportSchema = z.object({
         .string()
         .nullable()
         .describe("Operation (op_…) tracking the asynchronous import work."),
-    createdAt: z.string().datetime().describe("When the import handle was created."),
-    updatedAt: z.string().datetime().describe("When the import handle last changed."),
+    createdAt: z.string().datetime().describe("Instant when the import handle was created."),
+    updatedAt: z.string().datetime().describe("Instant when the import handle last changed."),
 });
 export const spaceImportListResponseSchema = z.object({
     data: z.array(spaceImportSchema),

package/dist/contracts/beta.js

@@ -91,7 +91,7 @@ export const SuperadminBetaSignupSchema = z.object({
     invitedBy: z
         .string()
         .nullable()
-        .describe("Inviting operator's user id; null = auto-approved (Automattician signup)."),
+        .describe("Inviting operator user id; null when auto-approved (Automattician signup)."),
     enrolledUserId: z.string().nullable(),
     createdAt: z.string().datetime(),
 });

package/dist/contracts/builds.js

@@ -27,7 +27,7 @@ export const BuildSettingsSchema = z
     allowUnsupportedPlatformFeatures: z.boolean().default(false),
     timeoutSeconds: buildTimeoutSecondsSchema,
 })
-    .describe("Resolved build settings. Builds persist this as an immutable settingsSnapshot.");
+    .describe("Resolved build settings. Builds persist this as an immutable `settingsSnapshot`.");
 export const BuildTargetSchema = z
     .object({
     channel: z
@@ -39,7 +39,7 @@ export const BuildTargetSchema = z
         .describe("Channel to promote when the build succeeds; null means no automatic promotion."),
     preview: z.boolean().default(false).describe("Whether the build targets preview behavior."),
 })
-    .describe("Where a successful build should publish or preview.");
+    .describe("Where a successful build should publish or run in preview mode.");
 // Shared by InternalBuildSourceSchema and InternalBuildInputSchema: both carry
 // this exact archive-source member in their `kind` discriminated union.
 const internalArchiveBuildSourceSchema = z.object({
@@ -48,7 +48,7 @@ const internalArchiveBuildSourceSchema = z.object({
     sourceMetadata: z
         .record(z.string(), z.unknown())
         .optional()
-        .describe("Internal source provenance copied to the produced Version."),
+        .describe("Internal source provenance copied to the produced version."),
     objectKey: z.string().optional().describe("Internal staged archive object key."),
     uploadedAt: z.string().datetime().optional().describe("When the archive finished staging."),
     recoveredAt: z
@@ -76,7 +76,7 @@ const InternalBuildSourceSchema = z
     }),
     internalArchiveBuildSourceSchema,
 ])
-    .describe("Legacy internal build source shape retained while build routes migrate to input.");
+    .describe("Legacy internal build source shape, retained while build routes migrate to input.");
 const InternalBuildInputSchema = z
     .discriminatedUnion("kind", [
     internalArchiveBuildSourceSchema,
@@ -126,7 +126,7 @@ export const PublicBuildInputSchema = z
     })
         .strict(),
 ])
-    .describe("Public build input. Internal clone URLs and staged object keys are not exposed.");
+    .describe("Public build input. Internal clone URLs and staged object keys are hidden.");
 export const BuildCreateInputSchema = z
     .discriminatedUnion("kind", [
     z
@@ -135,7 +135,7 @@ export const BuildCreateInputSchema = z
         sourceMetadata: z
             .record(z.string(), z.unknown())
             .optional()
-            .describe("Optional source provenance for the produced Version."),
+            .describe("Optional source provenance for the produced version."),
     })
         .strict(),
     z.object({
@@ -153,7 +153,7 @@ export const BuildCreateInputSchema = z
 // plain string here since the runner's specific phase vocabulary is an
 // app-level concern, not a shared contract.
 const buildExecutionPhaseSchema = z.object({
-    phase: z.string().min(1).describe("Build phase name; see BUILD_PHASES in builds/runner.ts."),
+    phase: z.string().min(1).describe("Build phase name. See `BUILD_PHASES` in `builds/runner.ts`."),
     at: z.string().datetime(),
 });
 const buildExecutionLaunchSchema = z.object({
@@ -188,11 +188,11 @@ const InternalBuildExecutionSchema = z
     phases: z
         .array(buildExecutionPhaseSchema)
         .optional()
-        .describe("Phase timeline the runner appends to via recordBuildPhase."),
+        .describe("Phase timeline that the runner appends to with `recordBuildPhase`."),
 })
     .describe("Internal runner execution metadata surfaced only where appropriate.");
 export const BuildSchema = z.object({
-    id: z.string().describe("Build id (`bld_`); opaque, never derived from a version id."),
+    id: z.string().describe("Build id (`bld_`); opaque and never derived from a version id."),
     spaceId: z.string().describe("Space (`spc_`) the build produces a version for."),
     status: buildStatus.describe("Build lifecycle status."),
     input: PublicBuildInputSchema,
@@ -206,12 +206,12 @@ export const BuildSchema = z.object({
     producedVersionId: z
         .string()
         .nullable()
-        .describe("Version (`ver_`) minted by a succeeded build; null otherwise."),
+        .describe("Version (`ver_`) minted by a successful build; null otherwise."),
     reusedVersionId: z
         .string()
         .nullable()
         .default(null)
-        .describe("Existing version reused by a succeeded no-change build; null otherwise."),
+        .describe("Existing version reused by a successful no-change build; null otherwise."),
     diagnostics: z.array(baseDiagnosticSchema).default([]),
     createdAt: z.string().datetime(),
     startedAt: z.string().datetime().nullable().describe("When the runner picked the build up."),
@@ -221,7 +221,7 @@ export const buildCreateRequestSchema = z.object({
     input: BuildCreateInputSchema,
     settings: BuildSettingsSchema.partial()
         .optional()
-        .describe("Per-run settings overrides; persisted as settingsSnapshot after resolution."),
+        .describe("Per-run settings overrides, persisted as `settingsSnapshot` after resolution."),
     target: BuildTargetSchema.partial().optional(),
     diagnostics: z
         .array(baseDiagnosticSchema)
@@ -253,9 +253,9 @@ export const spaceBuildIntegrationSchema = z
     .object({
     branchChannels: z
         .record(z.string().min(1).describe("Git branch or ref name."), z.literal("live").describe("Channel the branch's builds promote to."))
-        .describe("Exact branch/ref name to channel name, e.g. { main: 'live' }."),
+        .describe("Exact branch or ref name to channel name, for example `{ main: 'live' }`."),
 })
-    .describe("Per-space build integration config: where repository builds promote.");
+    .describe("Per-space build integration config that defines where repository builds promote.");
 /** Channel a repository build promotes to, or null when the ref is unmapped (default channel applies). */
 export function resolveBuildChannel(integration, ref) {
     return integration?.branchChannels[ref] ?? null;

package/dist/contracts/channels.js

@@ -21,7 +21,7 @@ export const channelListItemSchema = z.object({
         .nullable()
         .optional()
         .describe("Last version this channel served before the current pointer (rollback target)."),
-    updatedAt: z.string().datetime().describe("When this channel pointer last moved."),
+    updatedAt: z.string().datetime().describe("Instant when this channel pointer last moved."),
 });
 // One entry of a channel's promotion history (the deploy log): a single
 // `channel.promoted` event, newest first. This is the audit trail of every
@@ -40,7 +40,7 @@ export const channelHistoryEntrySchema = z.object({
         .optional()
         .describe("Kind of actor that performed the promotion."),
     actorId: z.string().nullable().optional().describe("Identifier of the promoting actor."),
-    at: z.string().datetime().describe("When the promotion happened."),
+    at: z.string().datetime().describe("Instant when the promotion happened."),
 });
 export const channelListResponseSchema = z.object({
     data: z.array(channelListItemSchema),

package/dist/contracts/comments.d.ts

@@ -28,9 +28,26 @@ export declare const collaborationGuestProjectionSchema: z.ZodObject<{
     }>>;
 }, z.core.$strip>;
 export type CollaborationGuestProjection = z.infer<typeof collaborationGuestProjectionSchema>;
+export declare const commentsGuestIdentitySchema: z.ZodObject<{
+    name: z.ZodString;
+    anonymousId: z.ZodString;
+    namedByUser: z.ZodBoolean;
+}, z.core.$strip>;
+export declare function commentCapabilitiesOf(capabilities: readonly string[]): CommentCapabilities;
+export declare const collaborationPublicProfileSchema: z.ZodObject<{
+    name: z.ZodNullable<z.ZodString>;
+    username: z.ZodNullable<z.ZodString>;
+    avatar_url: z.ZodNullable<z.ZodURL>;
+}, z.core.$strict>;
+export type CollaborationPublicProfile = z.infer<typeof collaborationPublicProfileSchema>;
 export declare const collaborationTicketClaimsSchema: z.ZodObject<{
     sub: z.ZodString;
     email: z.ZodOptional<z.ZodString>;
+    profile: z.ZodOptional<z.ZodObject<{
+        name: z.ZodNullable<z.ZodString>;
+        username: z.ZodNullable<z.ZodString>;
+        avatar_url: z.ZodNullable<z.ZodURL>;
+    }, z.core.$strict>>;
     role: z.ZodEnum<{
         viewer: "viewer";
         commenter: "commenter";
@@ -41,12 +58,14 @@ export declare const collaborationTicketClaimsSchema: z.ZodObject<{
         user: "user";
         guest: "guest";
     }>;
+    authorities: z.ZodOptional<z.ZodArray<z.ZodString>>;
     capabilities: z.ZodArray<z.ZodEnum<{
         "page.view": "page.view";
         "comments.read": "comments.read";
         "comments.write": "comments.write";
     }>>;
     anonymousId: z.ZodOptional<z.ZodString>;
+    grantId: z.ZodOptional<z.ZodString>;
     namedByUser: z.ZodOptional<z.ZodBoolean>;
     admittedBy: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"anyone">, z.ZodTemplateLiteral<`link:${string}`>, z.ZodTemplateLiteral<`password:${string}`>]>>;
     emailVerified: z.ZodOptional<z.ZodBoolean>;
@@ -74,6 +93,7 @@ export declare const collaborationSettingsSchema: z.ZodObject<{
 }, z.core.$strict>;
 export declare const collaborationSchema: z.ZodObject<{
     spaceId: z.ZodString;
+    revision: z.ZodNumber;
     enabled: z.ZodBoolean;
     castResourceId: z.ZodNullable<z.ZodString>;
     castResourceKey: z.ZodNullable<z.ZodString>;
@@ -90,15 +110,16 @@ export declare const collaborationSchema: z.ZodObject<{
     updatedAt: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
 export declare const collaborationUpdateSchema: z.ZodObject<{
-    enabled: z.ZodBoolean;
+    expectedRevision: z.ZodNumber;
+    enabled: z.ZodOptional<z.ZodBoolean>;
     settings: z.ZodOptional<z.ZodObject<{
         spamFilterEnabled: z.ZodOptional<z.ZodBoolean>;
         publishedComments: z.ZodOptional<z.ZodBoolean>;
         notificationPreferences: z.ZodOptional<z.ZodObject<{
-            newThreads: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
-            newReplies: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
-            statusChanges: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
-        }, z.core.$strip>>;
+            newThreads: z.ZodOptional<z.ZodBoolean>;
+            newReplies: z.ZodOptional<z.ZodBoolean>;
+            statusChanges: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
     }, z.core.$strict>>;
 }, z.core.$strip>;
 export declare const commentsTicketRequestSchema: z.ZodObject<{
@@ -106,6 +127,11 @@ export declare const commentsTicketRequestSchema: z.ZodObject<{
     pagePath: z.ZodDefault<z.ZodString>;
     origin: z.ZodString;
     versionId: z.ZodOptional<z.ZodString>;
+    identity: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        anonymousId: z.ZodString;
+        namedByUser: z.ZodBoolean;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const commentsTicketResponseSchema: z.ZodObject<{
     token: z.ZodString;
@@ -150,15 +176,6 @@ export declare const noticePublishResponseSchema: z.ZodObject<{
     event: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     broadcast: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>;
-export declare const collabOverlayConfigQuerySchema: z.ZodObject<{
-    path: z.ZodOptional<z.ZodString>;
-    versionId: z.ZodOptional<z.ZodString>;
-    host: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-export declare const collabOverlayConfigSchema: z.ZodObject<{
-    enabled: z.ZodBoolean;
-    surface_url: z.ZodNullable<z.ZodString>;
-}, z.core.$strip>;
 export declare const COLLAB_VERSION_URLS_MAX_IDS = 50;
 export declare const collabVersionUrlSchema: z.ZodObject<{
     id: z.ZodString;
@@ -169,10 +186,37 @@ export declare const collabVersionUrlSchema: z.ZodObject<{
 export declare const commentAuthorSchema: z.ZodObject<{
     kind: z.ZodNullable<z.ZodString>;
     id: z.ZodNullable<z.ZodString>;
+    profileId: z.ZodNullable<z.ZodString>;
     name: z.ZodNullable<z.ZodString>;
+    username: z.ZodNullable<z.ZodString>;
+    avatarUrl: z.ZodNullable<z.ZodURL>;
     color: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
 export declare const commentTargetSchema: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+export declare const commentReactionActorSchema: z.ZodObject<{
+    name: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export declare const commentReactionEntrySchema: z.ZodObject<{
+    count: z.ZodNumber;
+    actors: z.ZodRecord<z.ZodString, z.ZodObject<{
+        name: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const COMMENT_REACTION_EMOJIS: readonly ["👍", "❤️", "🎉", "👀", "🚀", "🙏"];
+export declare const commentReactionUpdateSchema: z.ZodObject<{
+    emoji: z.ZodEnum<{
+        "\uD83D\uDC4D": "👍";
+        "\u2764\uFE0F": "❤️";
+        "\uD83C\uDF89": "🎉";
+        "\uD83D\uDC40": "👀";
+        "\uD83D\uDE80": "🚀";
+        "\uD83D\uDE4F": "🙏";
+    }>;
+    op: z.ZodEnum<{
+        remove: "remove";
+        add: "add";
+    }>;
+}, z.core.$strip>;
 export declare const commentThreadSchema: z.ZodObject<{
     id: z.ZodString;
     castThreadId: z.ZodString;
@@ -196,10 +240,19 @@ export declare const commentThreadSchema: z.ZodObject<{
     author: z.ZodNullable<z.ZodObject<{
         kind: z.ZodNullable<z.ZodString>;
         id: z.ZodNullable<z.ZodString>;
+        profileId: z.ZodNullable<z.ZodString>;
         name: z.ZodNullable<z.ZodString>;
+        username: z.ZodNullable<z.ZodString>;
+        avatarUrl: z.ZodNullable<z.ZodURL>;
         color: z.ZodNullable<z.ZodString>;
     }, z.core.$strip>>;
     target: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    reactions: z.ZodRecord<z.ZodString, z.ZodObject<{
+        count: z.ZodNumber;
+        actors: z.ZodRecord<z.ZodString, z.ZodObject<{
+            name: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
     comments: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     permalink: z.ZodNullable<z.ZodString>;
     updatedAt: z.ZodNullable<z.ZodString>;
@@ -247,6 +300,16 @@ export declare const commentScreenshotSchema: z.ZodObject<{
     url: z.ZodString;
     expiresAt: z.ZodString;
 }, z.core.$strip>;
+export declare const commentScreenshotRefreshSchema: z.ZodObject<{
+    versionId: z.ZodString;
+    pagePath: z.ZodDefault<z.ZodString>;
+    key: z.ZodString;
+}, z.core.$strip>;
+export declare const commentScreenshotRefreshResponseSchema: z.ZodObject<{
+    key: z.ZodString;
+    url: z.ZodString;
+    expiresAt: z.ZodString;
+}, z.core.$strip>;
 export declare const commentReplySchema: z.ZodObject<{
     body: z.ZodString;
     idempotencyKey: z.ZodOptional<z.ZodString>;
@@ -291,10 +354,19 @@ export declare const commentListResponseSchema: z.ZodObject<{
         author: z.ZodNullable<z.ZodObject<{
             kind: z.ZodNullable<z.ZodString>;
             id: z.ZodNullable<z.ZodString>;
+            profileId: z.ZodNullable<z.ZodString>;
             name: z.ZodNullable<z.ZodString>;
+            username: z.ZodNullable<z.ZodString>;
+            avatarUrl: z.ZodNullable<z.ZodURL>;
             color: z.ZodNullable<z.ZodString>;
         }, z.core.$strip>>;
         target: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        reactions: z.ZodRecord<z.ZodString, z.ZodObject<{
+            count: z.ZodNumber;
+            actors: z.ZodRecord<z.ZodString, z.ZodObject<{
+                name: z.ZodNullable<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
         comments: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         permalink: z.ZodNullable<z.ZodString>;
         updatedAt: z.ZodNullable<z.ZodString>;
@@ -313,6 +385,5 @@ export declare const commentExportResponseSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type Collaboration = z.infer<typeof collaborationSchema>;
 export type CollaborationUpdate = z.infer<typeof collaborationUpdateSchema>;
-export type CollabOverlayConfig = z.infer<typeof collabOverlayConfigSchema>;
 export type CollabVersionUrl = z.infer<typeof collabVersionUrlSchema>;
 export type CommentThread = z.infer<typeof commentThreadSchema>;

package/dist/contracts/comments.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { accessRoleSchema } from "./access.js";
+import { accessRoleSchema, authorityReferenceSchema } from "./access.js";
 import { CursorPaginationSchema, cursorListQuerySchema } from "./common.js";
 export const commentThreadStatusSchema = z.enum(["open", "archived"]);
 export const COMMENT_SEARCH_QUERY_MAX_LENGTH = 160;
@@ -32,7 +32,14 @@ export const commentCapabilitiesSchema = z
 });
 export const collaborationGuestProjectionSchema = z.object({
     anonymousId: z.string().min(8).max(160),
-    name: z.string().trim().min(1).max(160),
+    // No control or format characters: newlines, bidi overrides, and zero-width
+    // joiners in a self-asserted display name are only ever spoofing material.
+    name: z
+        .string()
+        .trim()
+        .min(1)
+        .max(160)
+        .regex(/^[^\p{Cc}\p{Cf}]+$/u),
     namedByUser: z.boolean(),
     grantId: z.string().min(1).max(128),
     admittedBy: z.union([
@@ -43,14 +50,41 @@ export const collaborationGuestProjectionSchema = z.object({
     emailVerified: z.boolean().default(false),
     capabilities: commentCapabilitiesSchema,
 });
+// The identity a browser asserts when requesting a guest ticket — the
+// self-asserted subset of the guest projection.
+export const commentsGuestIdentitySchema = collaborationGuestProjectionSchema.pick({
+    anonymousId: true,
+    name: true,
+    namedByUser: true,
+});
+export function commentCapabilitiesOf(capabilities) {
+    return capabilities.filter((capability) => COMMENT_CAPABILITIES.includes(capability));
+}
+// The only account metadata exposed to Comments clients. Keep this shape
+// deliberately smaller than the private account record carried server-side.
+export const collaborationPublicProfileSchema = z
+    .object({
+    name: z.string().trim().min(1).max(120).nullable(),
+    username: z.string().trim().min(1).max(160).nullable(),
+    avatar_url: z
+        .url({ protocol: /^https?$/ })
+        .max(2_048)
+        .nullable(),
+})
+    .strict();
 export const collaborationTicketClaimsSchema = z
     .object({
     sub: z.string().min(1),
     email: z.string().email().optional(),
+    profile: collaborationPublicProfileSchema.optional(),
     role: accessRoleSchema,
+    // The session's principal, never the class of authority that admitted it:
+    // a signed-in account is "user" even when a share Link carried it in.
     actorKind: z.enum(["user", "guest"]),
+    authorities: z.array(authorityReferenceSchema).max(16).optional(),
     capabilities: commentCapabilitiesSchema,
     anonymousId: z.string().min(8).max(160).optional(),
+    grantId: z.string().min(1).max(128).optional(),
     namedByUser: z.boolean().optional(),
     admittedBy: z
         .union([
@@ -73,7 +107,18 @@ export const collaborationTicketClaimsSchema = z
     .superRefine((claims, context) => {
     if (claims.actorKind !== "guest")
         return;
-    for (const field of ["anonymousId", "namedByUser", "admittedBy", "emailVerified"]) {
+    // A guest ticket names an anonymous browser identity, and one grant always
+    // admitted it: the guest projection the mint builds carries all five of
+    // these or it is not a guest at all. Capabilities still come from the union
+    // of every authority the session holds — the admitting grant describes the
+    // admission, not the reach.
+    for (const field of [
+        "anonymousId",
+        "grantId",
+        "namedByUser",
+        "admittedBy",
+        "emailVerified",
+    ]) {
         if (claims[field] === undefined) {
             context.addIssue({
                 code: "custom",
@@ -82,6 +127,18 @@ export const collaborationTicketClaimsSchema = z
             });
         }
     }
+    // Identity never follows from an authority, but the reverse still holds:
+    // an anonymous principal can only ever have acquired credential-class
+    // authorities. Account-class references on a guest ticket are a forgery.
+    for (const [index, authority] of (claims.authorities ?? []).entries()) {
+        if (!authority.startsWith("link:") && !authority.startsWith("password:")) {
+            context.addIssue({
+                code: "custom",
+                path: ["authorities", index],
+                message: "a guest ticket carries only link or password authorities",
+            });
+        }
+    }
 });
 export const collaborationSettingsSchema = z
     .object({
@@ -89,7 +146,8 @@ export const collaborationSettingsSchema = z
     // Whether comments are surfaced on the live/published host (vs preview-only).
     // The published loader (SPACEFAST-CAST-PLAN §4.2) mounts the orb on a live
     // host only when this is true; toggling it never requires a republish — the
-    // always-injected inert tag reads behavior from the ETag'd overlay-config.
+    // always-injected inert tag re-reads it through the runtime's same-origin
+    // Comments config exchange on every load.
     publishedComments: z.boolean().optional(),
     notificationPreferences: z
         .object({
@@ -101,8 +159,23 @@ export const collaborationSettingsSchema = z
         .optional(),
 })
     .strict();
+const collaborationSettingsPatchSchema = z
+    .object({
+    spamFilterEnabled: z.boolean().optional(),
+    publishedComments: z.boolean().optional(),
+    notificationPreferences: z
+        .object({
+        newThreads: z.boolean().optional(),
+        newReplies: z.boolean().optional(),
+        statusChanges: z.boolean().optional(),
+    })
+        .strict()
+        .optional(),
+})
+    .strict();
 export const collaborationSchema = z.object({
     spaceId: z.string(),
+    revision: z.number().int().nonnegative(),
     enabled: z.boolean(),
     castResourceId: z.string().nullable(),
     castResourceKey: z.string().nullable(),
@@ -110,15 +183,21 @@ export const collaborationSchema = z.object({
     createdAt: z.string().datetime().nullable(),
     updatedAt: z.string().datetime().nullable(),
 });
-export const collaborationUpdateSchema = z.object({
-    enabled: z.boolean(),
-    settings: collaborationSettingsSchema.optional(),
+export const collaborationUpdateSchema = z
+    .object({
+    expectedRevision: z.number().int().nonnegative(),
+    enabled: z.boolean().optional(),
+    settings: collaborationSettingsPatchSchema.optional(),
+})
+    .refine((update) => update.enabled !== undefined || update.settings !== undefined, {
+    message: "At least one collaboration field is required",
 });
 export const commentsTicketRequestSchema = z.object({
     spaceId: z.string().min(1),
     pagePath: z.string().min(1).max(COMMENT_PAGE_PATH_MAX_LENGTH).default("/"),
     origin: z.string().url(),
     versionId: z.string().min(1).optional(),
+    identity: commentsGuestIdentitySchema.optional(),
 });
 export const commentsTicketResponseSchema = z.object({
     token: z.string(),
@@ -155,19 +234,7 @@ export const noticePublishResponseSchema = z.object({
     event: z.record(z.string(), z.unknown()).nullable(),
     broadcast: z.record(z.string(), z.unknown()).nullable(),
 });
-export const collabOverlayConfigQuerySchema = z.object({
-    path: z.string().min(1).max(COMMENT_PAGE_PATH_MAX_LENGTH).optional(),
-    versionId: z.string().min(1).optional(),
-    host: z.string().min(1).optional(),
-});
-// Customer pages receive launcher state only. Room ids, Cast endpoints, resource
-// keys, tickets, and platform session state never cross the customer-origin
-// boundary.
-export const collabOverlayConfigSchema = z.object({
-    enabled: z.boolean(),
-    surface_url: z.string().url().nullable(),
-});
-// Cross-version navigation directory: the platform Comments page asks for the
+// Cross-version navigation directory: the Comments overlay asks for the
 // immutable URLs of version ids present in a room's threads.
 export const COLLAB_VERSION_URLS_MAX_IDS = 50;
 export const collabVersionUrlSchema = z.object({
@@ -181,10 +248,28 @@ export const collabVersionUrlSchema = z.object({
 export const commentAuthorSchema = z.object({
     kind: z.string().nullable(),
     id: z.string().nullable(),
+    profileId: z.string().nullable(),
     name: z.string().nullable(),
+    username: z.string().max(160).nullable(),
+    avatarUrl: z
+        .url({ protocol: /^https?$/ })
+        .max(2_048)
+        .nullable(),
     color: z.string().max(64).nullable(),
 });
 export const commentTargetSchema = z.record(z.string(), z.unknown()).nullable();
+export const commentReactionActorSchema = z.object({
+    name: z.string().nullable(),
+});
+export const commentReactionEntrySchema = z.object({
+    count: z.number().int().min(0),
+    actors: z.record(z.string(), commentReactionActorSchema),
+});
+export const COMMENT_REACTION_EMOJIS = ["👍", "❤️", "🎉", "👀", "🚀", "🙏"];
+export const commentReactionUpdateSchema = z.object({
+    emoji: z.enum(COMMENT_REACTION_EMOJIS),
+    op: z.enum(["add", "remove"]),
+});
 export const commentThreadSchema = z.object({
     id: z.string(),
     castThreadId: z.string(),
@@ -201,6 +286,7 @@ export const commentThreadSchema = z.object({
     body: z.string().nullable(),
     author: commentAuthorSchema.nullable(),
     target: commentTargetSchema,
+    reactions: z.record(z.string(), commentReactionEntrySchema),
     comments: z.array(z.record(z.string(), z.unknown())),
     permalink: z.string().nullable(),
     updatedAt: z.string().datetime().nullable(),
@@ -237,6 +323,16 @@ export const commentScreenshotSchema = z.object({
     url: z.string().url(),
     expiresAt: z.string().datetime(),
 });
+export const commentScreenshotRefreshSchema = z.object({
+    versionId: z.string().min(1),
+    pagePath: z.string().min(1).max(COMMENT_PAGE_PATH_MAX_LENGTH).default("/"),
+    key: z.string().min(1).max(2_048),
+});
+export const commentScreenshotRefreshResponseSchema = z.object({
+    key: z.string(),
+    url: z.string().url(),
+    expiresAt: z.string().datetime(),
+});
 export const commentReplySchema = z.object({
     body: z.string().min(1).max(16_000),
     idempotencyKey: z.string().min(1).max(320).optional(),