@q9labsai/chalk-client 5.3.1 → 5.4.0

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-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.1",
+  "version": "5.4.0",
   "license": "MIT",
   "repository": {
     "type": "git",