@q9labsai/chalk-client 5.2.6 → 5.3.1

package/dist/media/viewer-layer.d.ts

@@ -0,0 +1,48 @@
+export type ViewerLayer = "h" | "l";
+export type ViewerLayerSample = {
+    /** Fraction of packets lost since the last sample; undefined when no packet arrived or was lost. */
+    readonly lossFraction: number | undefined;
+    readonly framesPerSecond: number | undefined;
+    readonly newFreezes: number;
+    readonly freezeSeconds: number;
+    /** Rendered tile height in device pixels, when the UI reports it. */
+    readonly tileHeight: number | undefined;
+};
+export declare class ViewerLayerPolicy {
+    #private;
+    get layer(): ViewerLayer;
+    /** Drops fast, rises slowly: a failed attempt at h doubles the wait before the next one. */
+    sample(sample: ViewerLayerSample): ViewerLayer;
+}
+type ViewerStatsRow = {
+    readonly type?: string;
+    readonly kind?: string;
+    readonly trackIdentifier?: string;
+    readonly timestamp?: number;
+    readonly packetsReceived?: number;
+    readonly packetsLost?: number;
+    readonly framesDecoded?: number;
+    readonly freezeCount?: number;
+    readonly totalFreezesDuration?: number;
+};
+/** Turns cumulative inbound-rtp counters into per-interval rates for one video track. */
+export declare class ViewerStatsReader {
+    #private;
+    read(stats: Iterable<ViewerStatsRow>, trackId: string): Pick<ViewerLayerSample, "lossFraction" | "framesPerSecond" | "newFreezes" | "freezeSeconds"> | undefined;
+    forget(trackId: string): void;
+}
+export type ViewerLayerCamera = {
+    readonly publicationId: string;
+    readonly track: MediaStreamTrack;
+};
+export type ViewerLayerChange = ViewerLayerCamera & {
+    readonly layer: ViewerLayer;
+};
+/** One per peer connection: owns a policy for each remote camera and reports the switches still to apply. */
+export declare class ViewerLayerSelector {
+    #private;
+    sample(now: number, report: RTCStatsReport, cameras: readonly ViewerLayerCamera[]): readonly ViewerLayerChange[];
+    applied({ publicationId, track, layer }: ViewerLayerChange): void;
+    failed({ publicationId, track }: ViewerLayerChange, now: number): void;
+}
+export {};

package/dist/public-invites/index.js

@@ -2,12 +2,13 @@ import {
   createChalkPublicClient,
   createChalkPublicInviteClient,
   parseInviteCode
-} from "../chunk-WFRTUBN6.js";
+} from "../chunk-VAJ6XNAA.js";
 import {
   ArrivalInvalidHandleError,
   ArrivalUnavailableError,
   SpacePublicInviteUnavailableError
-} from "../chunk-CJVLTSIO.js";
+} from "../chunk-MHJ4UPM3.js";
+import "../chunk-N4IPKRS6.js";
 export {
   ArrivalInvalidHandleError,
   ArrivalUnavailableError,

package/dist/server/index.cjs

@@ -115,17 +115,31 @@ function parseMediaAccess(value) {
         provider: value.provider,
         clientPayload: {
           connectionId: requireNonEmptyString(payload.connectionId),
-          stunServer: requireNonEmptyString(payload.stunServer)
+          stunServer: requireNonEmptyString(payload.stunServer),
+          ...payload.iceServers === void 0 || payload.iceServers === null ? {} : { iceServers: parseIceServers(payload.iceServers) }
         }
       };
     default:
       throw new AccessGrantError();
   }
 }
+function parseIceServers(value) {
+  if (!Array.isArray(value)) throw new AccessGrantError();
+  return value.map((entry) => {
+    if (!isRecord(entry) || !Array.isArray(entry.urls) || entry.urls.length === 0) throw new AccessGrantError();
+    const urls = entry.urls.map(requireNonEmptyString);
+    if (entry.username === void 0 && entry.credential === void 0) return { urls };
+    return { urls, username: requireNonEmptyString(entry.username), credential: requireNonEmptyString(entry.credential) };
+  });
+}
 function mediaClientPayload(value) {
   switch (value.provider) {
     case "cloudflare_sfu":
-      return { connectionId: value.clientPayload.connectionId, stunServer: value.clientPayload.stunServer };
+      return {
+        connectionId: value.clientPayload.connectionId,
+        stunServer: value.clientPayload.stunServer,
+        ...value.clientPayload.iceServers ? { iceServers: value.clientPayload.iceServers } : {}
+      };
   }
 }
 function requireCredential(value, audience) {
@@ -602,6 +616,7 @@ function participantAdmissionRequest(input) {
     name: input.name,
     role: input.role,
     ...input.identityId === void 0 ? {} : { identity_id: input.identityId },
+    ...input.identityExternalId === void 0 ? {} : { identity_external_id: input.identityExternalId },
     ...input.metadata === void 0 ? {} : { metadata: input.metadata },
     ...input.participantId === void 0 ? {} : { participant_id: input.participantId }
   };
@@ -699,9 +714,9 @@ function accessGrant(value) {
 function mediaClientPayload2(media) {
   switch (media.provider) {
     case "cloudflare_sfu": {
-      const { connectionId, stunServer } = media.client_payload;
+      const { connectionId, stunServer, iceServers } = media.client_payload;
       if (typeof connectionId !== "string" || typeof stunServer !== "string") throw invalidResponse(201);
-      return { connectionId, stunServer };
+      return { connectionId, stunServer, ...iceServers === void 0 ? {} : { iceServers } };
     }
     default:
       throw invalidResponse(201);

package/dist/server/index.js

@@ -93,17 +93,31 @@ function parseMediaAccess(value) {
         provider: value.provider,
         clientPayload: {
           connectionId: requireNonEmptyString(payload.connectionId),
-          stunServer: requireNonEmptyString(payload.stunServer)
+          stunServer: requireNonEmptyString(payload.stunServer),
+          ...payload.iceServers === void 0 || payload.iceServers === null ? {} : { iceServers: parseIceServers(payload.iceServers) }
         }
       };
     default:
       throw new AccessGrantError();
   }
 }
+function parseIceServers(value) {
+  if (!Array.isArray(value)) throw new AccessGrantError();
+  return value.map((entry) => {
+    if (!isRecord(entry) || !Array.isArray(entry.urls) || entry.urls.length === 0) throw new AccessGrantError();
+    const urls = entry.urls.map(requireNonEmptyString);
+    if (entry.username === void 0 && entry.credential === void 0) return { urls };
+    return { urls, username: requireNonEmptyString(entry.username), credential: requireNonEmptyString(entry.credential) };
+  });
+}
 function mediaClientPayload(value) {
   switch (value.provider) {
     case "cloudflare_sfu":
-      return { connectionId: value.clientPayload.connectionId, stunServer: value.clientPayload.stunServer };
+      return {
+        connectionId: value.clientPayload.connectionId,
+        stunServer: value.clientPayload.stunServer,
+        ...value.clientPayload.iceServers ? { iceServers: value.clientPayload.iceServers } : {}
+      };
   }
 }
 function requireCredential(value, audience) {
@@ -504,6 +518,7 @@ function participantAdmissionRequest(input) {
     name: input.name,
     role: input.role,
     ...input.identityId === void 0 ? {} : { identity_id: input.identityId },
+    ...input.identityExternalId === void 0 ? {} : { identity_external_id: input.identityExternalId },
     ...input.metadata === void 0 ? {} : { metadata: input.metadata },
     ...input.participantId === void 0 ? {} : { participant_id: input.participantId }
   };
@@ -601,9 +616,9 @@ function accessGrant(value) {
 function mediaClientPayload2(media) {
   switch (media.provider) {
     case "cloudflare_sfu": {
-      const { connectionId, stunServer } = media.client_payload;
+      const { connectionId, stunServer, iceServers } = media.client_payload;
       if (typeof connectionId !== "string" || typeof stunServer !== "string") throw invalidResponse(201);
-      return { connectionId, stunServer };
+      return { connectionId, stunServer, ...iceServers === void 0 ? {} : { iceServers } };
     }
     default:
       throw invalidResponse(201);

package/dist/server/types.d.cts

@@ -104,6 +104,8 @@ export type EpisodeEnd = {
     readonly status: string;
 };
 export type AdmitParticipantInput = {
+    /** Stable person key scoped to this tenant. Mutually exclusive with identityId. */
+    readonly identityExternalId?: string;
     readonly identityId?: string;
     readonly metadata?: unknown;
     readonly name: string;

package/dist/server/types.d.ts

@@ -104,6 +104,8 @@ export type EpisodeEnd = {
     readonly status: string;
 };
 export type AdmitParticipantInput = {
+    /** Stable person key scoped to this tenant. Mutually exclusive with identityId. */
+    readonly identityExternalId?: string;
     readonly identityId?: string;
     readonly metadata?: unknown;
     readonly name: string;

package/dist/session/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The session is one run of a Chalk app on one device: a browser tab, or an app launch on mobile. Its ID is the
+ * OpenTelemetry attribute `session.id` and travels with the trace context as W3C baggage on every Chalk API request and
+ * Sync connection. It is unrelated to an Episode and to Cloudflare track or dashboard login `sessionId`s.
+ */
+export declare const SESSION_ID_KEY = "session.id";
+export type SessionSource = () => string | undefined;
+/** Platforms with their own session rules, such as React Native, install their source once at startup. */
+export declare function setSessionSource(next: SessionSource): void;
+/** The current session ID, or undefined where no app session exists, such as a Node server. */
+export declare function currentSessionId(): string | undefined;
+export declare function newSessionId(): string;
+/** The W3C baggage value that carries the session, or undefined where no app session exists. */
+export declare function sessionBaggage(): string | undefined;
+/** `baggage` and a fresh `traceparent` for one Chalk API request; empty where there is no app session. */
+export declare function requestContextHeaders(): Record<string, string>;
+/** Wraps a fetch so every request carries the session; headers the caller already set win. Use only for Chalk API origins. */
+export declare function withRequestContext(fetchImplementation?: typeof globalThis.fetch): typeof globalThis.fetch;

package/dist/space-client/same-identity.d.ts

@@ -0,0 +1,6 @@
+import type { Participant } from "./types";
+import type { V1EpisodeSnapshot } from "../sync/v1-types";
+type PersonSeat = Pick<Participant, "participantId" | "identityId">;
+export declare function otherDevices<Seat extends PersonSeat>(participants: readonly Seat[], participantId: string | null, ownIdentityId?: string): readonly Seat[];
+export declare function otherDeviceHasMicrophone(snapshot: V1EpisodeSnapshot, participants: readonly PersonSeat[]): boolean;
+export {};

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

@@ -77,6 +77,8 @@ export type ConnectionSlice = {
 };
 export type SelfSlice = {
     readonly participantId: string | null;
+    /** Verified person association, including before this seat confirms entry. */
+    readonly identityId?: string;
     readonly displayName: string | null;
     readonly role: string | null;
     readonly capabilities: readonly Capability[];
@@ -89,6 +91,9 @@ export type ParticipantPresence = {
     readonly activeSpeaker: boolean;
 };
 export type Participant = {
+    /** Stable person identity, independent of the per-device participant ID. */
+    readonly identityId?: string;
+    readonly deviceType?: "phone" | "tablet" | "computer";
     readonly participantId: string;
     readonly displayName: string;
     readonly role: string;
@@ -128,6 +133,7 @@ export type RemoteMedia = {
 export type IncomingMediaRequest = ChalkIncomingMediaRequest;
 export type { ScreenShareSurface, ScreenShareOptions, ScreenShareCapture } from "../media/plane";
 export type MediaSlice = {
+    readonly microphoneMutedByOtherDevice?: boolean;
     readonly devices: {
         readonly microphones: readonly MediaDevice[];
         readonly cameras: readonly MediaDevice[];

package/dist/sync/index.js

@@ -22,7 +22,8 @@ import {
   encodeV1ClientFrame,
   optimisticV1Control,
   restoreV1Snapshot
-} from "../chunk-5YPQNMJE.js";
+} from "../chunk-FD7ZSDTM.js";
+import "../chunk-N4IPKRS6.js";
 export {
   AsyncStorageV1PendingTargetStore,
   InMemoryV1PendingTargetStore,

package/dist/sync/v1-command-scheduler.d.ts

@@ -22,6 +22,10 @@ type V1CommandSchedulerOptions = {
     readonly ackHeadIsProven: (ack: Extract<V1CommandResult, {
         readonly outcome: "committed" | "satisfied";
     }>) => boolean;
+    readonly controlHead: () => {
+        readonly revision: number;
+        readonly state_digest: string;
+    };
 };
 export declare class V1CommandScheduler {
     #private;

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

@@ -52,6 +52,10 @@ export type V1ControlState = {
 };
 export type V1MediaPublication = MediaPublication;
 export type V1Presence = {
+    readonly admissionRevision?: number;
+    /** Stable person identity, independent of the per-device participant ID. */
+    readonly identityId?: string;
+    readonly deviceType?: "phone" | "tablet" | "computer";
     readonly participantId: string;
     readonly state: "connected" | "disconnected";
     readonly speaking: boolean;
@@ -86,6 +90,8 @@ export type V1EpisodeSnapshot = {
     };
     readonly participantId: string | null;
     readonly participantGeneration: number | null;
+    /** Verified own-seat identity, available before admission confirmation on negotiated servers. */
+    readonly participantIdentityId?: string;
     readonly control: V1ControlState | null;
     readonly optimisticControl: V1ControlState | null;
     readonly media: V1Projection<V1MediaPublication> | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@q9labsai/chalk-client",
-  "version": "5.2.6",
+  "version": "5.3.1",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -221,6 +221,8 @@
     "test": "node ../../../scripts/test/run.mjs pnpm exec vitest run",
     "test:webhooks-package": "pnpm run build && node ./scripts/check-webhook-package.mjs",
     "test:server-package": "pnpm run build && node ./scripts/check-server-package.mjs",
+    "test:receive-stall-sfu": "node ./scripts/real-sfu-receive-stall.mjs",
+    "test:viewer-layer-sfu": "node ./scripts/real-sfu-viewer-layer.mjs",
     "test:sync-browser": "pnpm run build && node ./scripts/real-browser-sync.mjs",
     "test:sync-node-restart": "pnpm run build && node ./scripts/real-node-restart-sync.mjs",
     "check-types": "tsc-rs --project tsconfig.check-types.json --noEmit",