@q9labsai/chalk-client 5.3.0 → 5.4.0

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) {
@@ -700,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) {
@@ -602,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/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/sync/index.js

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

package/dist/sync/link-watch.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Decides whether a Sync drop is proven short. Contact is proven only by a ping and the pong that answers it: the pong proves
+ * contact at the moment the ping was SENT, and only when the round trip took 0 to `ROUND_TRIP_MS` on both the wall clock and the
+ * monotonic clock, with no page freeze, resume or discard in between. A pong that was buffered through a suspend shows a long round
+ * trip, a clock step back shows a negative one, and neither proves anything. No other frame proves contact, because a frame says
+ * when the page processed it, not when Sync sent it.
+ *
+ * A pong answers the oldest ping in flight, and no ping is ever evicted. A ping or pong that is lost therefore only makes later
+ * pongs pair with an older ping, which records an earlier contact and a longer round trip: it fails closed, and proof stops once the
+ * pairing skew passes `ROUND_TRIP_MS`. The one assumption is that Sync sends exactly one pong per ping; a duplicate pong is the only
+ * way to pair with a newer ping, and a ping sequence number would remove it. A late pong proves nothing and changes nothing else.
+ * When the oldest ping has gone unanswered for over `UNANSWERED_LIMIT_MS`, the old heartbeat timeout, `pinged()` returns false and
+ * the client replaces the socket; `restart()` empties the queue on the next one.
+ *
+ * A drop is long when any of these holds, and nothing else makes it long (a hidden tab, throttled timers and a slow network do not):
+ * - no contact was ever proven;
+ * - either clock went backwards since the last proven contact;
+ * - either clock advanced `LONG_DROP_MS` or more since the last proven contact;
+ * - the page was frozen, resumed or discarded since then.
+ *
+ * Known gap: a tab hidden for over 5 minutes with no live WebRTC connection runs its timers once a minute, so it sends one ping a
+ * minute and its last proof can be nearly 60 s old when the link drops. A short drop then reads long and the source turns off.
+ * That errs toward off, and Chrome exempts a page that holds a live WebRTC connection.
+ *
+ * On a quiet call the last ping can be up to 20 s older than the loss, so down time can read up to 20 s too long and the
+ * effective cutoff is 40 to 60 s. That errs toward turning the source off.
+ */
+export declare const LONG_DROP_MS = 60000;
+export type LinkReading = {
+    readonly wall: number;
+    readonly mono: number;
+    readonly suspends: number;
+};
+export type LinkJudge = {
+    /** The last proof of contact, or null before the first answered ping. */
+    readonly proof: () => LinkReading | null;
+    /** True unless the time since `proof` is proven short; a missing proof is long. */
+    readonly longSince: (proof: LinkReading | null) => boolean;
+};
+export type LinkClock = {
+    readonly wall: () => number;
+    readonly mono: () => number;
+};
+/** The browser document, or any target that fires the Page Lifecycle `freeze` and `resume` events. */
+export type PageLifecycle = {
+    readonly addEventListener: (type: "freeze" | "resume", listener: () => void) => void;
+    readonly removeEventListener: (type: "freeze" | "resume", listener: () => void) => void;
+    readonly wasDiscarded?: boolean;
+};
+export declare class LinkWatch implements LinkJudge {
+    #private;
+    constructor(clock: LinkClock, page: PageLifecycle | null);
+    /** Listens for page suspension. Idempotent, and paired with `close`. */
+    open(): void;
+    close(): void;
+    /** Call when a connection goes live: the previous socket's pings will not be answered. */
+    restart(): void;
+    /**
+     * Call as a ping goes out, in the same order as the pings. False means the oldest ping has gone unanswered for over
+     * `UNANSWERED_LIMIT_MS`: the socket is dead and this ping must not be sent on it.
+     */
+    pinged(): boolean;
+    /** Call as a pong is received. It answers the oldest ping in flight, and proves contact only if the round trip was short. */
+    ponged(): void;
+    proof(): LinkReading | null;
+    longSince(proof: LinkReading | null): boolean;
+}

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

@@ -1,3 +1,4 @@
+import { type LinkJudge } from "./link-watch";
 import type { ChalkChatReactionInput, ChalkChatReactions, ChalkChatMessage, ChalkChatPageResult, ChalkChatReadReceipt, ChalkReaction, ChalkReactionEvent, ChalkSendChatMessageInput, ChalkSyncV1CollaborationCapability } from "../collaboration/types";
 import type { V1AdmissionTarget, V1AssignableRole, V1CommandResult, V1DirectedRequest, V1DirectedRequestResult, V1MediaPause, V1CollaborationEvent, V1CollaborationClient, V1CollaborationExtensionState, V1EpisodeSnapshot, V1SelfMediaTargetResult, V1SyncClientOptions } from "./v1-types";
 type CommandOptions = {
@@ -9,12 +10,16 @@ type RequestOptions = {
 export { V1SyncError } from "./v1-error";
 export declare class V1SyncClient implements V1CollaborationClient {
     #private;
+    /** Tells a recovery whether the drop was proven short. */
+    readonly link: LinkJudge;
     constructor(options: V1SyncClientOptions);
     restartTransport(): void;
     start(): Promise<void>;
     stop(): void;
     /** Announces completed startup; transport recovery resends until acknowledged. */
     confirmEntered(): Promise<void>;
+    /** True when the connected Sync advertised `media_off_reason` in its welcome, so media items may carry `off_reason`. */
+    offReasonNegotiated(): boolean;
     getSnapshot(): V1EpisodeSnapshot;
     subscribe(listener: (snapshot: V1EpisodeSnapshot) => void): () => void;
     onMediaPause(listener: (pause: V1MediaPause) => void): () => void;

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

@@ -1,4 +1,5 @@
 import type { ConnectionReportTransportEvent } from "../transport-diagnostics";
+import type { PageLifecycle } from "./link-watch";
 import type { SetAdmissionPolicyCommandFrame, SyncV1ServerFrame } from "../generated/sync";
 import type { ClientMediaPlane, MediaPlaneOutcome, MediaPlaneResult, MediaPlaneTarget, MediaPublication, MediaSource } from "../media/plane";
 import type { ChalkChatReactionInput, ChalkChatReactions, ChalkChatMessage, ChalkChatPageResult, ChalkChatReadReceipt, ChalkReaction, ChalkReactionEvent, ChalkSendChatMessageInput, ChalkSyncV1CollaborationCapability } from "../collaboration/types";
@@ -50,7 +51,13 @@ export type V1ControlState = {
     readonly participants: readonly V1Participant[];
     readonly admissionRequests: readonly V1AdmissionRequest[];
 };
-export type V1MediaPublication = MediaPublication;
+/** Why Sync shows a media item as off. A missing reason is no evidence, never "off". */
+export type V1MediaOffReason = "host" | "self" | "dead";
+export type V1MediaPublication = MediaPublication & {
+    readonly offReason?: V1MediaOffReason;
+    /** The control revision of the host stop; only with `offReason: "host"`. */
+    readonly offRevision?: number;
+};
 export type V1Presence = {
     readonly admissionRevision?: number;
     /** Stable person identity, independent of the per-device participant ID. */
@@ -206,6 +213,10 @@ export type V1SyncClientOptions = {
     readonly ids?: SyncIdGenerator;
     readonly requestIds?: SyncIdGenerator;
     readonly clock?: SyncClock;
+    /** Monotonic milliseconds, `performance.now()` by default. */
+    readonly monotonic?: () => number;
+    /** The page whose `freeze` and `resume` events show a suspend; the browser document by default, null for none. */
+    readonly page?: PageLifecycle | null;
     readonly lifecycle?: SyncLifecycle;
     readonly reconnectDelayMs?: number;
     /** Per-attempt WebSocket opening allowance, clamped to 10–60 seconds; defaults to 10 seconds. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@q9labsai/chalk-client",
-  "version": "5.3.0",
+  "version": "5.4.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -222,6 +222,7 @@
     "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",