@ai-matrx/meet 0.11.32 → 0.11.34

package/dist/core.d.cts

@@ -35,7 +35,12 @@ declare class MeetError extends Error {
      * renders `refused:<reason>` (or `ended`) from it — never from the HTTP status.
      */
     readonly reason: string | null;
-    constructor(code: MeetErrorCode, message: string, remedy: string, cause?: unknown, reason?: string | null);
+    /**
+     * A refusal that lifts by itself says when: whole seconds from the moment the server answered
+     * (a denial's cooldown, `reknock_cooldown_seconds`). Null for every refusal that does not.
+     */
+    readonly retryAfterSeconds: number | null;
+    constructor(code: MeetErrorCode, message: string, remedy: string, cause?: unknown, reason?: string | null, retryAfterSeconds?: number | null);
     /** True when retrying after the host re-establishes a session is the fix. */
     get isRetryable(): boolean;
     /** True when the user, not the code, must act — the UI shows `remedy`. */
@@ -342,6 +347,13 @@ type PhaseEvent =
  | {
     readonly type: "connected";
 }
+/**
+ * S7: the server answered the join with a QUESTION — this person is already in the meeting on
+ * another tab or device — so `joining` goes back to `prejoin`, which offers the choice.
+ */
+ | {
+    readonly type: "second_device";
+}
 /** The join itself failed: a gate reason (→ `refused:*` / `ended`) or none (→ `disconnected`). */
  | {
     readonly type: "join_failed";
@@ -375,9 +387,15 @@ type PhaseEvent =
     readonly type: "call_outcome";
     readonly outcome: CallOutcomePhase;
 }
-/** Back to the start: a different meeting mounted, the call surface was dismissed, or dispose. */
+/**
+ * Back to the start: a different meeting mounted or the call surface was dismissed (refused
+ * from a live phase — leave first). `teardown: true` is the engine's own dispose: it has
+ * already closed the connection, so nothing live remains to protect and the reset applies from
+ * any phase.
+ */
  | {
     readonly type: "reset";
+    readonly teardown?: true;
 };
 type PhaseEventType = PhaseEvent["type"];
 /** Phases in which this tab holds (or is getting) a live media connection. */
@@ -582,8 +600,8 @@ interface MeetGrants {
 declare const NO_GRANTS: MeetGrants;
 /**
  * S4 — THIS PERSON'S WAIT, as the server's state read (`GET /v1/meet/state`) last said it
- * (CORE-DESIGN §2.6). Set while `phase === "lobby"`; the waiting screens read it, never a
- * broadcast. `admission` is the row's own word: `waiting_host` · `knocking` · `denied` ·
+ * (CORE-DESIGN §2.6). Set while the phase is a waiting one (`waiting:*`, `denied`,
+ * `knock_expired`); the waiting screens read it, never a broadcast. `admission` is the row's own word: `waiting_host` · `knocking` · `denied` ·
  * `expired` · `withdrawn` · `ended` (`admitted` is never held here — it is a join).
  */
 interface MeetWaiting {
@@ -593,6 +611,8 @@ interface MeetWaiting {
     /** May a denied person ask again (`reknock_after_deny`)? */
     readonly reknockAllowed: boolean;
     readonly knockExpiresAt: string | null;
+    /** While a denial's cooldown runs: the epoch-ms moment the person may ask again; else null. */
+    readonly reknockAt?: number | null;
     /** How often the core reads while waiting (`waiting_poll_seconds`). */
     readonly pollSeconds: number;
     /** The run's `live_version` at the last read. */
@@ -647,6 +667,14 @@ interface MeetSnapshot {
     readonly waiting: MeetWaiting | null;
     readonly meeting: MeetingRecord | null;
     readonly localIdentity: ParticipantIdentity | null;
+    /**
+     * S7: this person is already in this meeting on another tab or device, and the pre-join offers
+     * the meeting's choice — `rule` is the `second_device` knob (`ask_switch_or_join` · Meet: Switch
+     * here / Join here too; `ask_transfer_or_add` · Teams: Transfer / Add). Null otherwise.
+     */
+    readonly secondDevice: {
+        readonly rule: string;
+    } | null;
     /** The server's word on what THIS joiner may do. See `MeetGrants`. */
     readonly grants: MeetGrants;
     readonly participants: readonly MeetParticipant[];
@@ -756,6 +784,11 @@ interface MeetSnapshot {
         readonly remedy: string;
         /** The join gate's reason code, when the server named one (CORE-DESIGN §2.5). */
         readonly reason?: string | null;
+        /**
+         * When a refusal lifts by itself (a denial's cooldown): the epoch-ms moment the person may
+         * ask again. Absent for every refusal that does not lift (CORE-DESIGN §11 `wr-denied-reknock`).
+         */
+        readonly retryAt?: number | null;
     } | null;
     /**
      * Meet wave 5: polls, Q&A, the shared whiteboard and the breakout plan — what the
@@ -2163,7 +2196,7 @@ interface MeetingSession {
      * §3.4 ER: what the server recorded for THIS connection's exit, and the run's phase. null =
      * the read failed (offline / unreachable); undefined = no meeting or no pass to ask with.
      */
-    readExit(connection: string): Promise<ExitServerWord | null | undefined>;
+    readExit(connection: string, pass?: string | null): Promise<ExitServerWord | null | undefined>;
     /** Stop waiting: the row becomes `withdrawn` (`POST /v1/meet/leave {intent: "withdraw"}`). */
     withdraw(): Promise<void>;
     /** Ask again after a denial or an expired knock (only offered when allowed). */
@@ -2347,6 +2380,17 @@ interface MediaSupervisor {
 }
 declare function createMediaSupervisor(options: MediaSupervisorOptions): MediaSupervisor;
 
+interface TabClaim {
+    /** This page's claimed tab id (resolves once the claim settles). */
+    readonly tabId: Promise<string>;
+    /** Announce that this tab is in `room` as `person` (until `left`); answers presence questions. */
+    inRoom(room: string, person: string): void;
+    left(): void;
+    /** Is `person` in `room` on ANOTHER tab of this browser? Answers within `TAB_ANSWER_MS`. */
+    presentElsewhere(room: string, person: string): Promise<boolean>;
+    dispose(): void;
+}
+
 /**
  * THE ROOM ENGINE — the object a host mounts once and never reasons about.
  *
@@ -2387,12 +2431,20 @@ interface JoinRequest {
     readonly breakoutRoomId?: string | null | undefined;
     /** HR-360 wave 2 (MD-16): ask to join as a silent observer. The server decides. */
     readonly observe?: boolean | undefined;
+    /**
+     * S7: the person's answer when they are already in this meeting on another tab or device
+     * (`snapshot.secondDevice`): `switch_here` moves the call here, `join_too` adds this tab as a
+     * companion (no microphone, speaker off).
+     */
+    readonly secondDevice?: SecondDeviceAnswer | undefined;
 }
 interface RoomEngineOptions {
     store: MeetStore;
     tokens: TokenClient;
     identity: MeetIdentity;
     driverFactory: RoomDriverFactory;
+    /** S7: this page's tab claim (`core/tab-claim.ts`); absent = one connection per person. */
+    tabClaim?: TabClaim | undefined;
     /** Canonical public metadata read; room packets alone never authorize teardown. */
     resolveMeeting?: ((slug: string) => Promise<MeetingRecord>) | undefined;
     onDiagnostic?: ((event: {
@@ -2417,7 +2469,7 @@ interface RoomEngineOptions {
      * read what happened to THIS connection (`GET /v1/meet/state?connection=`). Resolves null when
      * the read failed (offline / unreachable), undefined when this room has no state read (a call).
      */
-    readExit?: ((connection: string) => Promise<ExitServerWord | null | undefined>) | undefined;
+    readExit?: ((connection: string, pass?: string | null) => Promise<ExitServerWord | null | undefined>) | undefined;
     /** Was the page frozen when the connection dropped (Page Lifecycle)? → `inactive`. */
     wasFrozen?: (() => boolean) | undefined;
     /**
@@ -2717,7 +2769,18 @@ interface RoomToken {
     readonly token: string;
     readonly serverUrl: string;
     readonly roomName: RoomName;
+    /** S7: the PERSON key (`user:<id>` · `guest:<device>`) — what every roster tile and row uses. */
     readonly identity: ParticipantIdentity;
+    /** S7: this tab's LiveKit identity, `<person>~<tab>` (the person key from an older server). */
+    readonly connectionIdentity?: string | undefined;
+    /** S7: `companion` for a "join here too" connection (no audio publish, speaker off). */
+    readonly connectionKind?: "main" | "companion" | undefined;
+    /**
+     * S7: set when the person is ALREADY in the room on another tab or device and has not chosen
+     * yet — the meeting's `second_device` rule (`ask_switch_or_join` · `ask_transfer_or_add`). No
+     * LiveKit token was issued (`token` is empty); the pre-join offers the choice.
+     */
+    readonly secondDeviceChoice?: string | null | undefined;
     readonly displayName: string;
     /** ISO. The package refreshes at 80% of the remaining life. */
     readonly expiresAt: string;
@@ -2818,7 +2881,13 @@ interface TokenRequest {
     readonly breakoutRoomId?: string | null | undefined;
     /** HR-360 wave 2 (MD-16): ask to join as a silent observer. The server decides. */
     readonly observe?: boolean | undefined;
+    /** S7: this tab's claimed id (`core/tab-claim.ts`) — the LiveKit identity is `<person>~<tab>`. */
+    readonly tabId?: string | undefined;
+    /** S7: the person's answer when they are already in this meeting on another tab or device. */
+    readonly secondDevice?: SecondDeviceAnswer | undefined;
 }
+/** S7: what a person already in the meeting elsewhere chose (CORE-DESIGN §2.1). */
+type SecondDeviceAnswer = "switch_here" | "join_too";
 interface TokenClient {
     /** A currently-valid token, minting or refreshing only when it must. */
     get(request: TokenRequest): Promise<RoomToken>;

package/dist/core.d.ts

@@ -35,7 +35,12 @@ declare class MeetError extends Error {
      * renders `refused:<reason>` (or `ended`) from it — never from the HTTP status.
      */
     readonly reason: string | null;
-    constructor(code: MeetErrorCode, message: string, remedy: string, cause?: unknown, reason?: string | null);
+    /**
+     * A refusal that lifts by itself says when: whole seconds from the moment the server answered
+     * (a denial's cooldown, `reknock_cooldown_seconds`). Null for every refusal that does not.
+     */
+    readonly retryAfterSeconds: number | null;
+    constructor(code: MeetErrorCode, message: string, remedy: string, cause?: unknown, reason?: string | null, retryAfterSeconds?: number | null);
     /** True when retrying after the host re-establishes a session is the fix. */
     get isRetryable(): boolean;
     /** True when the user, not the code, must act — the UI shows `remedy`. */
@@ -342,6 +347,13 @@ type PhaseEvent =
  | {
     readonly type: "connected";
 }
+/**
+ * S7: the server answered the join with a QUESTION — this person is already in the meeting on
+ * another tab or device — so `joining` goes back to `prejoin`, which offers the choice.
+ */
+ | {
+    readonly type: "second_device";
+}
 /** The join itself failed: a gate reason (→ `refused:*` / `ended`) or none (→ `disconnected`). */
  | {
     readonly type: "join_failed";
@@ -375,9 +387,15 @@ type PhaseEvent =
     readonly type: "call_outcome";
     readonly outcome: CallOutcomePhase;
 }
-/** Back to the start: a different meeting mounted, the call surface was dismissed, or dispose. */
+/**
+ * Back to the start: a different meeting mounted or the call surface was dismissed (refused
+ * from a live phase — leave first). `teardown: true` is the engine's own dispose: it has
+ * already closed the connection, so nothing live remains to protect and the reset applies from
+ * any phase.
+ */
  | {
     readonly type: "reset";
+    readonly teardown?: true;
 };
 type PhaseEventType = PhaseEvent["type"];
 /** Phases in which this tab holds (or is getting) a live media connection. */
@@ -582,8 +600,8 @@ interface MeetGrants {
 declare const NO_GRANTS: MeetGrants;
 /**
  * S4 — THIS PERSON'S WAIT, as the server's state read (`GET /v1/meet/state`) last said it
- * (CORE-DESIGN §2.6). Set while `phase === "lobby"`; the waiting screens read it, never a
- * broadcast. `admission` is the row's own word: `waiting_host` · `knocking` · `denied` ·
+ * (CORE-DESIGN §2.6). Set while the phase is a waiting one (`waiting:*`, `denied`,
+ * `knock_expired`); the waiting screens read it, never a broadcast. `admission` is the row's own word: `waiting_host` · `knocking` · `denied` ·
  * `expired` · `withdrawn` · `ended` (`admitted` is never held here — it is a join).
  */
 interface MeetWaiting {
@@ -593,6 +611,8 @@ interface MeetWaiting {
     /** May a denied person ask again (`reknock_after_deny`)? */
     readonly reknockAllowed: boolean;
     readonly knockExpiresAt: string | null;
+    /** While a denial's cooldown runs: the epoch-ms moment the person may ask again; else null. */
+    readonly reknockAt?: number | null;
     /** How often the core reads while waiting (`waiting_poll_seconds`). */
     readonly pollSeconds: number;
     /** The run's `live_version` at the last read. */
@@ -647,6 +667,14 @@ interface MeetSnapshot {
     readonly waiting: MeetWaiting | null;
     readonly meeting: MeetingRecord | null;
     readonly localIdentity: ParticipantIdentity | null;
+    /**
+     * S7: this person is already in this meeting on another tab or device, and the pre-join offers
+     * the meeting's choice — `rule` is the `second_device` knob (`ask_switch_or_join` · Meet: Switch
+     * here / Join here too; `ask_transfer_or_add` · Teams: Transfer / Add). Null otherwise.
+     */
+    readonly secondDevice: {
+        readonly rule: string;
+    } | null;
     /** The server's word on what THIS joiner may do. See `MeetGrants`. */
     readonly grants: MeetGrants;
     readonly participants: readonly MeetParticipant[];
@@ -756,6 +784,11 @@ interface MeetSnapshot {
         readonly remedy: string;
         /** The join gate's reason code, when the server named one (CORE-DESIGN §2.5). */
         readonly reason?: string | null;
+        /**
+         * When a refusal lifts by itself (a denial's cooldown): the epoch-ms moment the person may
+         * ask again. Absent for every refusal that does not lift (CORE-DESIGN §11 `wr-denied-reknock`).
+         */
+        readonly retryAt?: number | null;
     } | null;
     /**
      * Meet wave 5: polls, Q&A, the shared whiteboard and the breakout plan — what the
@@ -2163,7 +2196,7 @@ interface MeetingSession {
      * §3.4 ER: what the server recorded for THIS connection's exit, and the run's phase. null =
      * the read failed (offline / unreachable); undefined = no meeting or no pass to ask with.
      */
-    readExit(connection: string): Promise<ExitServerWord | null | undefined>;
+    readExit(connection: string, pass?: string | null): Promise<ExitServerWord | null | undefined>;
     /** Stop waiting: the row becomes `withdrawn` (`POST /v1/meet/leave {intent: "withdraw"}`). */
     withdraw(): Promise<void>;
     /** Ask again after a denial or an expired knock (only offered when allowed). */
@@ -2347,6 +2380,17 @@ interface MediaSupervisor {
 }
 declare function createMediaSupervisor(options: MediaSupervisorOptions): MediaSupervisor;
 
+interface TabClaim {
+    /** This page's claimed tab id (resolves once the claim settles). */
+    readonly tabId: Promise<string>;
+    /** Announce that this tab is in `room` as `person` (until `left`); answers presence questions. */
+    inRoom(room: string, person: string): void;
+    left(): void;
+    /** Is `person` in `room` on ANOTHER tab of this browser? Answers within `TAB_ANSWER_MS`. */
+    presentElsewhere(room: string, person: string): Promise<boolean>;
+    dispose(): void;
+}
+
 /**
  * THE ROOM ENGINE — the object a host mounts once and never reasons about.
  *
@@ -2387,12 +2431,20 @@ interface JoinRequest {
     readonly breakoutRoomId?: string | null | undefined;
     /** HR-360 wave 2 (MD-16): ask to join as a silent observer. The server decides. */
     readonly observe?: boolean | undefined;
+    /**
+     * S7: the person's answer when they are already in this meeting on another tab or device
+     * (`snapshot.secondDevice`): `switch_here` moves the call here, `join_too` adds this tab as a
+     * companion (no microphone, speaker off).
+     */
+    readonly secondDevice?: SecondDeviceAnswer | undefined;
 }
 interface RoomEngineOptions {
     store: MeetStore;
     tokens: TokenClient;
     identity: MeetIdentity;
     driverFactory: RoomDriverFactory;
+    /** S7: this page's tab claim (`core/tab-claim.ts`); absent = one connection per person. */
+    tabClaim?: TabClaim | undefined;
     /** Canonical public metadata read; room packets alone never authorize teardown. */
     resolveMeeting?: ((slug: string) => Promise<MeetingRecord>) | undefined;
     onDiagnostic?: ((event: {
@@ -2417,7 +2469,7 @@ interface RoomEngineOptions {
      * read what happened to THIS connection (`GET /v1/meet/state?connection=`). Resolves null when
      * the read failed (offline / unreachable), undefined when this room has no state read (a call).
      */
-    readExit?: ((connection: string) => Promise<ExitServerWord | null | undefined>) | undefined;
+    readExit?: ((connection: string, pass?: string | null) => Promise<ExitServerWord | null | undefined>) | undefined;
     /** Was the page frozen when the connection dropped (Page Lifecycle)? → `inactive`. */
     wasFrozen?: (() => boolean) | undefined;
     /**
@@ -2717,7 +2769,18 @@ interface RoomToken {
     readonly token: string;
     readonly serverUrl: string;
     readonly roomName: RoomName;
+    /** S7: the PERSON key (`user:<id>` · `guest:<device>`) — what every roster tile and row uses. */
     readonly identity: ParticipantIdentity;
+    /** S7: this tab's LiveKit identity, `<person>~<tab>` (the person key from an older server). */
+    readonly connectionIdentity?: string | undefined;
+    /** S7: `companion` for a "join here too" connection (no audio publish, speaker off). */
+    readonly connectionKind?: "main" | "companion" | undefined;
+    /**
+     * S7: set when the person is ALREADY in the room on another tab or device and has not chosen
+     * yet — the meeting's `second_device` rule (`ask_switch_or_join` · `ask_transfer_or_add`). No
+     * LiveKit token was issued (`token` is empty); the pre-join offers the choice.
+     */
+    readonly secondDeviceChoice?: string | null | undefined;
     readonly displayName: string;
     /** ISO. The package refreshes at 80% of the remaining life. */
     readonly expiresAt: string;
@@ -2818,7 +2881,13 @@ interface TokenRequest {
     readonly breakoutRoomId?: string | null | undefined;
     /** HR-360 wave 2 (MD-16): ask to join as a silent observer. The server decides. */
     readonly observe?: boolean | undefined;
+    /** S7: this tab's claimed id (`core/tab-claim.ts`) — the LiveKit identity is `<person>~<tab>`. */
+    readonly tabId?: string | undefined;
+    /** S7: the person's answer when they are already in this meeting on another tab or device. */
+    readonly secondDevice?: SecondDeviceAnswer | undefined;
 }
+/** S7: what a person already in the meeting elsewhere chose (CORE-DESIGN §2.1). */
+type SecondDeviceAnswer = "switch_here" | "join_too";
 interface TokenClient {
     /** A currently-valid token, minting or refreshing only when it must. */
     get(request: TokenRequest): Promise<RoomToken>;