@q9labsai/chalk-client 5.1.0 → 5.2.1

package/dist/space-client/types.d.ts

@@ -1,6 +1,6 @@
 import type { MediaSource, ScreenShareCapture } from "../media/plane";
 import type { ChalkChatAttachment, ChalkChatMessage, ChalkChatReadReceipt, ChalkIncomingMediaRequest, ChalkParticipantMediaState, ChalkReaction, ChalkReactionEvent } from "../collaboration/types";
-import type { ChalkWhiteboardV1Failure } from "../whiteboard/types";
+import type { ChalkWhiteboardDrawPermission, ChalkWhiteboardDrawPolicy, ChalkWhiteboardV1Failure } from "../whiteboard/types";
 import type { AccessGrant } from "../access/grant";
 import type { V1Capability } from "../sync/v1-types";
 import type { ChatControllerEffects } from "./chat-controller";
@@ -52,6 +52,7 @@ export type ClientFailure = {
     readonly code: ErrorCode;
     readonly recoverable: boolean;
     readonly message: string;
+    readonly sync?: import("../sync/connect-diagnostics").SyncConnectDiagnostic;
 };
 export type EpisodeSummary = {
     readonly id: string;
@@ -66,6 +67,7 @@ export type ConnectionSlice = {
     readonly lastError: ClientFailure | null;
     /** The Episode ended while this person was in it. */
     readonly episodeEnded: boolean;
+    readonly episodeEndReason?: import("../sync/v1-types").V1ControlState["endReason"];
     /** The server removed this person from the call; a person's own leave never sets this. */
     readonly removedByHost: boolean;
 };
@@ -203,6 +205,12 @@ export type WhiteboardSlice = {
         readonly presenting: boolean;
         readonly error: ChalkWhiteboardV1Failure | null;
     };
+    /** Who can draw, as Sync last told this person. `canDraw` is false until the board subscription is live. */
+    readonly access: {
+        readonly canDraw: boolean;
+        readonly policy: ChalkWhiteboardDrawPolicy | null;
+        readonly permissions: readonly ChalkWhiteboardDrawPermission[];
+    };
 };
 export type SpaceSnapshot = {
     readonly connection: ConnectionSlice;
@@ -253,6 +261,7 @@ export type ClientEventMap = {
     };
     readonly episodeEnded: {
         readonly episode: EpisodeSummary | null;
+        readonly reason?: ConnectionSlice["episodeEndReason"];
     };
     readonly screenShareStarted: {
         readonly participantId: string;

package/dist/sync/connect-diagnostics.d.ts

@@ -0,0 +1,10 @@
+/** Browsers expose only upgrade/open and hello, never DNS/TCP/TLS progress. */
+export type SyncConnectDiagnostic = {
+    readonly stage: "upgrade" | "hello";
+    readonly opened: boolean;
+    readonly closeCode: number | null;
+    readonly closeReason: string | null;
+    readonly durationMs: number;
+};
+export declare function safeSyncCloseReason(reason: string | undefined): string | null;
+export declare function formatSyncConnectDiagnostic(diagnostic: SyncConnectDiagnostic): string;

package/dist/sync/index.js

@@ -22,7 +22,7 @@ import {
   encodeV1ClientFrame,
   optimisticV1Control,
   restoreV1Snapshot
-} from "../chunk-K7PNW3KI.js";
+} from "../chunk-TVNI2XUZ.js";
 export {
   AsyncStorageV1PendingTargetStore,
   InMemoryV1PendingTargetStore,

package/dist/sync/types.d.ts

@@ -9,6 +9,7 @@ export type SyncSocket = {
     }) => void) | null;
     onclose: ((event: {
         readonly code: number;
+        readonly reason?: string;
     }) => void) | null;
     onerror: (() => void) | null;
     send(data: string): void;

package/dist/sync/v1-client.d.ts

@@ -13,6 +13,8 @@ export declare class V1SyncClient implements V1CollaborationClient {
     restartTransport(): void;
     start(): Promise<void>;
     stop(): void;
+    /** Announces completed startup; transport recovery resends until acknowledged. */
+    confirmEntered(): Promise<void>;
     getSnapshot(): V1EpisodeSnapshot;
     subscribe(listener: (snapshot: V1EpisodeSnapshot) => void): () => void;
     onMediaPause(listener: (pause: V1MediaPause) => void): () => void;

package/dist/sync/v1-types.d.ts

@@ -37,6 +37,10 @@ export type V1ControlState = {
     readonly stateSchemaVersion: number;
     readonly stateDigest: string;
     readonly status: "active" | "ended";
+    readonly endReason?: Extract<SyncV1ServerFrame, {
+        readonly type: "event";
+        readonly name: "episode_ended";
+    }>["payload"]["reason"];
     readonly admissionPolicy: V1AdmissionPolicy;
     readonly deadlineAtMs: number;
     readonly deadlineGeneration: number;
@@ -75,6 +79,8 @@ export type V1EpisodeSnapshot = {
         readonly health?: import("./v1-health").SyncHealth;
         /** Cumulative count retained across successful retries; contains no URL or credentials. */
         readonly dialTimeoutCount?: number;
+        readonly connectAttempt?: import("./connect-diagnostics").SyncConnectDiagnostic;
+        readonly connectFailure?: import("./connect-diagnostics").SyncConnectDiagnostic;
     };
     readonly participantId: string | null;
     readonly participantGeneration: number | null;
@@ -201,6 +207,8 @@ export type V1SyncClientOptions = {
     readonly retryDelayMs?: number;
     readonly collaboration?: V1CollaborationExtensionRequest | false;
     readonly maxPendingCollaborationRequests?: number;
+    /** Asks Sync to hold the entry until `confirmEntered()`; set it only when the caller will call that method. */
+    readonly entryConfirmation?: boolean;
 };
 export type V1Socket = SyncSocket;
 /** Explicit host pause; control revisions do not identify a self-media operation. */

package/dist/whiteboard/index.d.ts

@@ -1,11 +1,8 @@
-/** Bounds for camera rectangles shared with other participants. */
-export declare const ChalkWhiteboardViewBounds: {
-    maxCoordinate: 1000000;
-    maxExtent: 2000000;
-};
+export { ChalkWhiteboardViewBounds } from "./view-bounds";
 export { createChalkWhiteboardV1FileDownloadTransport, type ChalkWhiteboardV1FileDownloadTransportOptions } from "./file-download-transport";
 export * from "./types";
 export { ChalkWhiteboardV1Client } from "./v1-client";
 export { decodeWhiteboardV1ServerFrame, encodeWhiteboardV1ClientFrame } from "./v1-codec";
 export { createChalkWhiteboardV1Client, type CreateChalkWhiteboardV1ClientOptions } from "./v1-create";
 export { InMemoryChalkWhiteboardV1PendingOperationStore } from "./v1-persistence";
+export { ChalkWhiteboardViewVersions } from "./view-versions";

package/dist/whiteboard/types.d.ts

@@ -53,7 +53,15 @@ export type ChalkWhiteboardView = {
     readonly width: number;
     readonly height: number;
     readonly bring: boolean;
+    /** Real move by default; false marks a passive refresh or heartbeat. */
+    readonly lead?: boolean;
 } & ({
+    readonly ownerId: string;
+    readonly ownerSequence: number;
+} | {
+    readonly ownerId?: never;
+    readonly ownerSequence?: never;
+}) & ({
     readonly originParticipantId: string;
     readonly originSequence: number;
     readonly originEpoch?: string;
@@ -67,7 +75,14 @@ export type ChalkWhiteboardV1Commit = {
     readonly sceneId: string;
     readonly revision: string;
 };
-export type ChalkWhiteboardV1Operation = "start_scene_subscription" | "submit_update" | "request_snapshot" | "clear" | "set_draw_permission" | "set_presentation" | "get_file_download";
+export type ChalkWhiteboardV1Operation = "start_scene_subscription" | "submit_update" | "request_snapshot" | "clear" | "set_draw_permission" | "set_draw_policy" | "set_presentation" | "get_file_download";
+/** Who can draw in the call. Hosts, the people whose role can manage the board, can always draw under `hosts` and `picked`. */
+export type ChalkWhiteboardDrawPolicy = WhiteboardV1DrawPolicy;
+/** A host's choice for one person. Under `everyone` it overrides the role default; under `picked` `true` means picked; under `hosts` it is kept but ignored. */
+export type ChalkWhiteboardDrawPermission = {
+    readonly participantId: string;
+    readonly canDraw: boolean;
+};
 export type ChalkWhiteboardV1ErrorCode = "unavailable" | "permission_denied" | "invalid_payload" | "stale_scene" | "cursor_reset_required" | "storage_unavailable" | "file_transfer_failed";
 export type ChalkWhiteboardV1Failure = {
     readonly operation: ChalkWhiteboardV1Operation;
@@ -100,17 +115,20 @@ export type ChalkWhiteboardV1Transport = {
     /** Whether the active subscription negotiated view_v1; remains stable during recovery. */
     readonly supportsViews?: boolean;
     /** Accepts views while subscribed; keeps the latest bring through recovery. False means views are unavailable. */
+    readonly forgetParticipant?: (participantId: string) => void;
     readonly sendView?: (view: ChalkWhiteboardView) => boolean;
     readonly requestSnapshot: () => Promise<void>;
     readonly clear: () => Promise<ChalkWhiteboardV1Commit>;
     readonly setDrawPermission: (participantId: string, canDraw: boolean) => Promise<void>;
+    /** Sets the call-wide drawing policy. Requires manageWhiteboard and a Sync server with draw_policy_v1. */
+    readonly setDrawPolicy?: (policy: ChalkWhiteboardDrawPolicy) => Promise<void>;
     readonly setPresentation?: (presenting: boolean) => Promise<void>;
     readonly files: ChalkWhiteboardV1FileTransport;
 };
 export type ChalkWhiteboardV1PendingOperation = {
     readonly operationId: string;
     readonly frame: Extract<WhiteboardV1ClientFrame, {
-        readonly type: "submit_update" | "clear" | "set_draw_permission" | "set_presentation";
+        readonly type: "submit_update" | "clear" | "set_draw_permission" | "set_draw_policy" | "set_presentation";
     }>;
     readonly createdAt: number;
     readonly bytes: number;
@@ -154,12 +172,17 @@ export type ChalkWhiteboardSummary = {
     readonly sceneId: string | null;
     readonly revision: string | null;
     readonly capabilities: readonly ChalkWhiteboardV1Capability[];
+    /** This person's drawing permission, computed by Sync from the policy, their role and the host's choice for them. */
     readonly canDraw: boolean;
     readonly canClear: boolean;
+    /** The call-wide policy, or null when the Sync server predates draw_policy_v1. */
+    readonly drawPolicy: ChalkWhiteboardDrawPolicy | null;
+    /** The host's per-person choices for people in the call. Empty unless this person is a host. */
+    readonly drawPermissions: readonly ChalkWhiteboardDrawPermission[];
     readonly presenting: boolean;
     readonly error: ChalkWhiteboardV1Failure | null;
 };
-import type { WhiteboardV1ClientFrame } from "../generated/whiteboard-v1";
+import type { WhiteboardV1ClientFrame, WhiteboardV1DrawPolicy } from "../generated/whiteboard-v1";
 import type { ChalkWhiteboardV1Capability } from "../collaboration/types";
 import type { SyncClock, SyncIdGenerator, SyncLifecycle, SyncWebSocketFactory } from "../sync/types";
 export type { ChalkWhiteboardV1Capability } from "../collaboration/types";

package/dist/whiteboard/v1-client.d.ts

@@ -1,4 +1,4 @@
-import { type ChalkWhiteboardV1ClientOptions, type ChalkWhiteboardV1Commit, type ChalkWhiteboardV1Event, type ChalkWhiteboardSummary, type ChalkWhiteboardV1Transport, type ChalkWhiteboardV1UpdateInput, type ChalkWhiteboardView } from "./types";
+import { type ChalkWhiteboardV1ClientOptions, type ChalkWhiteboardV1Commit, type ChalkWhiteboardDrawPolicy, type ChalkWhiteboardV1Event, type ChalkWhiteboardSummary, type ChalkWhiteboardV1Transport, type ChalkWhiteboardV1UpdateInput, type ChalkWhiteboardView } from "./types";
 export declare class ChalkWhiteboardV1Client implements ChalkWhiteboardV1Transport {
     #private;
     readonly files: import("./types").ChalkWhiteboardV1FileTransport;
@@ -13,9 +13,11 @@ export declare class ChalkWhiteboardV1Client implements ChalkWhiteboardV1Transpo
         readonly y: number;
     }): void;
     get supportsViews(): boolean;
+    forgetParticipant(participantId: string): void;
     sendView(view: ChalkWhiteboardView): boolean;
     requestSnapshot(): Promise<void>;
     clear(): Promise<ChalkWhiteboardV1Commit>;
     setDrawPermission(participantId: string, canDraw: boolean): Promise<void>;
+    setDrawPolicy(policy: ChalkWhiteboardDrawPolicy): Promise<void>;
     setPresentation(presenting: boolean): Promise<void>;
 }

package/dist/whiteboard/v1-codec.d.ts

@@ -1,3 +1,7 @@
 import { type WhiteboardV1ServerFrame } from "../generated/whiteboard-v1";
 export declare function encodeWhiteboardV1ClientFrame(frame: unknown): string;
-export declare function decodeWhiteboardV1ServerFrame(wire: string): WhiteboardV1ServerFrame;
+/** Negotiated control frames belong to the connection, not the public 5.1 frame union. */
+export declare function decodeWhiteboardV1ServerFrame(wire: string): Exclude<WhiteboardV1ServerFrame, {
+    readonly type: "view_ack" | "draw_access";
+}>;
+export declare function decodeWhiteboardV1WireFrame(wire: string): WhiteboardV1ServerFrame;

package/dist/whiteboard/v1-multipart.d.ts

@@ -1,6 +1,6 @@
 import { type WhiteboardV1ClientFrame, type WhiteboardV1ServerFrame } from "../generated/whiteboard-v1";
 export type WhiteboardV1LogicalOperationFrame = Extract<WhiteboardV1ClientFrame, {
-    readonly type: "submit_update" | "clear" | "set_draw_permission" | "set_presentation";
+    readonly type: "submit_update" | "clear" | "set_draw_permission" | "set_draw_policy" | "set_presentation";
 }>;
 type UpdatePartFrame = Extract<WhiteboardV1ServerFrame, {
     readonly type: "update_part";

package/dist/whiteboard/view-bounds.d.ts

@@ -0,0 +1,5 @@
+/** Bounds for shared camera rectangles. */
+export declare const ChalkWhiteboardViewBounds: {
+    maxCoordinate: 1000000;
+    maxExtent: 2000000;
+};

package/dist/whiteboard/view-versions.d.ts

@@ -0,0 +1,9 @@
+import type { ChalkWhiteboardView } from "./types";
+/** Owner sequences are compared only within a connection's authoritative snapshot. */
+export declare class ChalkWhiteboardViewVersions {
+    #private;
+    isNew(view: ChalkWhiteboardView, participantId?: string): boolean;
+    remember(view: ChalkWhiteboardView, participantId?: string): void;
+    forgetParticipant(participantId: string): void;
+    clear(): void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@q9labsai/chalk-client",
-  "version": "5.1.0",
+  "version": "5.2.1",
   "license": "MIT",
   "repository": {
     "type": "git",

package/dist/chunk-KHHULLBZ.js

@@ -1,142 +0,0 @@
-import {
-  createChalkEffectClient,
-  parseAccessGrant
-} from "./chunk-3ZN7IXOZ.js";
-
-// src/public-invites/client.ts
-import { Effect } from "effect";
-function createChalkPublicClient(options) {
-  const baseClientOptions = {
-    baseUrl: options.baseUrl,
-    credentials: options.credentials ?? (options.runtime === "react-native" ? void 0 : "include"),
-    fetch: options.fetch
-  };
-  const createClient = (guestCredential, requestInit) => createChalkEffectClient({
-    ...baseClientOptions,
-    ...requestInit ? { fetch: requestInitFetch(options.fetch, requestInit) } : {},
-    headers: requestHeaders(options, guestCredential)
-  });
-  const createPublicSpace = async (input, idempotency) => {
-    const client = await Effect.runPromise(createClient(void 0));
-    const response = await Effect.runPromise(
-      client.spaces.createPublicSpace({
-        headers: { "Idempotency-Key": idempotencyKey(idempotency) },
-        payload: { display_name: required(input.displayName, "displayName") }
-      })
-    );
-    return publicSpaceCreated(response);
-  };
-  const arriveBySpacePublicInvite = async (input, arrival) => {
-    const client = await Effect.runPromise(createClient(arrival?.guestCredential ?? options.guestCredential));
-    const response = await Effect.runPromise(
-      client.spaces.arriveBySpacePublicInvite({
-        headers: {
-          "Idempotency-Key": idempotencyKey(arrival),
-          ...arrival?.arrivalHandle === void 0 ? {} : { "X-Chalk-Arrival-Handle": required(arrival.arrivalHandle, "arrivalHandle") }
-        },
-        payload: {
-          display_name: required(input.displayName, "displayName"),
-          space_invite_token: required(input.spaceInviteToken, "spaceInviteToken")
-        }
-      })
-    );
-    return publicSpaceArrival(response);
-  };
-  const getSpacePublicInviteArrival = async (reference) => {
-    const normalized = arrivalReference(reference);
-    const client = await Effect.runPromise(createClient(normalized.guestCredential ?? options.guestCredential));
-    const response = await Effect.runPromise(
-      client.spaces.getSpacePublicInviteArrival({
-        headers: { "X-Chalk-Arrival-Handle": normalized.arrivalHandle }
-      })
-    );
-    return publicSpaceArrival(response);
-  };
-  const refreshSpacePublicInviteAccess = async (input, arrival) => {
-    const normalized = refreshInput(input, arrival);
-    const client = await Effect.runPromise(createClient(normalized.guestCredential ?? options.guestCredential, normalized.signal ? { signal: normalized.signal } : void 0));
-    const response = await Effect.runPromise(
-      client.spaces.refreshSpacePublicInviteAccess({
-        headers: { "X-Chalk-Arrival-Handle": normalized.arrivalHandle },
-        payload: { media_proof: required(normalized.mediaProof, "mediaProof"), replace_media_connection: normalized.replaceMediaConnection ?? false }
-      })
-    );
-    return parseAccessGrant(response);
-  };
-  const leaveSpacePublicInviteArrival = async (reference, leaveOptions) => {
-    const normalized = arrivalReference(reference);
-    const client = await Effect.runPromise(createClient(normalized.guestCredential ?? options.guestCredential, requestInitForLeave(leaveOptions)));
-    await Effect.runPromise(
-      client.spaces.leaveSpacePublicInviteArrival({
-        headers: { "X-Chalk-Arrival-Handle": normalized.arrivalHandle }
-      })
-    );
-  };
-  return {
-    prepareSpaceEntrance: async (spaceInviteToken) => {
-      const client = await Effect.runPromise(createClient(void 0));
-      await Effect.runPromise(client.spaces.preparePublicSpaceEntrance({ payload: { space_invite_token: required(spaceInviteToken, "spaceInviteToken") } }));
-    },
-    arrive: arriveBySpacePublicInvite,
-    arriveBySpacePublicInvite,
-    create: createPublicSpace,
-    createPublicSpace,
-    getSpacePublicInviteArrival,
-    leave: leaveSpacePublicInviteArrival,
-    leaveSpacePublicInviteArrival,
-    refresh: refreshSpacePublicInviteAccess,
-    refreshSpacePublicInviteAccess,
-    status: getSpacePublicInviteArrival
-  };
-}
-var createChalkPublicInviteClient = createChalkPublicClient;
-function requestHeaders(options, guestCredential) {
-  const headers = { ...options.headers };
-  if (options.runtime === "react-native") {
-    headers["X-Chalk-Client"] = "react-native";
-    const credential = guestCredential ?? options.guestCredential;
-    if (credential !== void 0) headers.Authorization = `ChalkGuest ${required(credential, "guestCredential")}`;
-  }
-  return headers;
-}
-function idempotencyKey(options) {
-  return options?.idempotencyKey === void 0 ? globalThis.crypto.randomUUID() : required(options.idempotencyKey, "idempotencyKey");
-}
-function arrivalReference(reference) {
-  if (typeof reference === "string") return { arrivalHandle: required(reference, "arrivalHandle") };
-  return { arrivalHandle: required(reference.arrivalHandle, "arrivalHandle"), guestCredential: reference.guestCredential };
-}
-function refreshInput(input, arrival) {
-  const values = typeof input === "string" ? { arrivalHandle: arrival?.arrivalHandle, guestCredential: arrival?.guestCredential, mediaProof: input } : { arrivalHandle: input.arrivalHandle ?? arrival?.arrivalHandle, guestCredential: input.guestCredential ?? arrival?.guestCredential, mediaProof: input.mediaProof, replaceMediaConnection: input.replaceMediaConnection, signal: input.signal };
-  return {
-    ...values,
-    arrivalHandle: required(values.arrivalHandle ?? "", "arrivalHandle")
-  };
-}
-function requestInitForLeave(options) {
-  if (options?.keepalive === void 0) return void 0;
-  return { keepalive: options.keepalive };
-}
-function requestInitFetch(fetchImplementation, requestInit) {
-  const implementation = fetchImplementation ?? globalThis.fetch;
-  return (input, init) => implementation(input, { ...init, ...requestInit });
-}
-function publicSpaceCreated(value) {
-  const { arrival, ...created } = value;
-  return { ...created, arrival: publicSpaceArrival(arrival) };
-}
-function publicSpaceArrival(value) {
-  const { access, ...arrival } = value;
-  if (access === void 0) return arrival;
-  return { ...arrival, access: access === null ? null : parseAccessGrant(access) };
-}
-function required(value, name) {
-  const normalized = value.trim();
-  if (!normalized) throw new TypeError(`${name} is required`);
-  return normalized;
-}
-
-export {
-  createChalkPublicClient,
-  createChalkPublicInviteClient
-};