@ai-matrx/meet 0.8.1 → 0.10.0

package/dist/index.js

@@ -7,11 +7,18 @@ var MeetError = class extends Error {
   /** What to DO. Rendered to the user for the device codes. */
   remedy;
   cause;
-  constructor(code, message, remedy, cause) {
+  /**
+   * The join gate's reason code (CORE-DESIGN §2.5) when the server named one: `not_found`,
+   * `cancelled`, `ended`, `locked`, `removed`, `lobby_rejects`, `not_invited`… The phase
+   * renders `refused:<reason>` (or `ended`) from it — never from the HTTP status.
+   */
+  reason;
+  constructor(code, message, remedy, cause, reason) {
     super(message);
     this.name = "MeetError";
     this.code = code;
     this.remedy = remedy;
+    this.reason = reason ?? null;
     if (cause !== void 0) this.cause = cause;
   }
   /** True when retrying after the host re-establishes a session is the fix. */
@@ -229,6 +236,17 @@ function createWebRoomTokenStorage(onDiagnostic) {
     }
   };
 }
+function rememberedMeetingPass(roomName, storage = createWebRoomTokenStorage()) {
+  const raw = storage.read(roomName);
+  if (raw === null) return null;
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed.standing !== "guest") return null;
+    return typeof parsed.meetingPass === "string" && parsed.meetingPass.length > 0 ? parsed.meetingPass : null;
+  } catch {
+    return null;
+  }
+}
 var MEET_ROUTES = {
   token: "/api/v1/meet/token",
   recordingStart: "/api/v1/meet/recording/start",
@@ -242,7 +260,7 @@ var MEET_ROUTES = {
   /**
    * THE POST-MEETING RECORD FOR A READER WITH NO DATABASE (MRF-1). A `GET`,
    * authorized by the room token this device already holds, carried in the
-   * `x-meet-room-token` header — never a query parameter, because a bearer
+   * `x-meet-pass` header — never a query parameter, because a bearer
    * credential in a URL lands in access logs, referrers and history.
    */
   record: "/api/v1/meet/record",
@@ -250,7 +268,7 @@ var MEET_ROUTES = {
   recordAccess: "/api/v1/meet/record/access",
   /**
    * KEEP YOUR NOTES (2026-10-01): a guest who just created an account presents
-   * their kept pass in `x-meet-room-token` with their new session, and the
+   * their kept pass in `x-meet-pass` with their new session, and the
    * meeting they attended becomes theirs to read. Idempotent; never a grant.
    */
   claim: "/api/v1/meet/claim",
@@ -272,7 +290,7 @@ var MEET_ROUTES = {
    * Meet wave 2: EVERY in-meeting host power (mute, stop video, mute all, ask to
    * unmute, spotlight, lower hands, co-host, hand over, rename, remove, report).
    * Decided by the server from the meeting itself; a guest's pass rides
-   * `x-meet-room-token`.
+   * `x-meet-pass`.
    */
   moderate: "/api/v1/meet/moderate",
   /** Meet wave 2: the SAVED chat — `POST` sends to everyone, `GET ?meeting_id=` reads history. */
@@ -283,12 +301,26 @@ var MEET_ROUTES = {
    */
   collab: "/api/v1/meet/collab",
   /** Meet wave 5: translate finished caption lines into this viewer's language. */
-  captionsTranslate: "/api/v1/meet/captions/translate"
+  captionsTranslate: "/api/v1/meet/captions/translate",
+  /**
+   * S4 — THE STATE READ (CORE-DESIGN §2.6): `GET ?meeting_id=` with `x-meet-pass`. This
+   * person's admission (lazy expiry applied), whether anyone who can admit is here, the run's
+   * phase. Read every `waiting_poll_seconds` while waiting and on every `mx.state.changed`.
+   */
+  state: "/api/v1/meet/state",
+  /** S4: `withdraw` (stop waiting) or `leave` (close this tab); the pass may ride in the body. */
+  leave: "/api/v1/meet/leave",
+  /** S4: a pass holder (guests included) saw the recording notice, for this run. */
+  consent: "/api/v1/meet/consent"
 };
 function meetingPath(template, meetingId) {
   return template.replace("{meeting_id}", encodeURIComponent(meetingId));
 }
-var ROOM_TOKEN_HEADER = "x-meet-room-token";
+var MEETING_PASS_HEADER = "x-meet-pass";
+function meetingPassHeaders(token) {
+  const pass = token?.meetingPass ?? null;
+  return pass !== null && pass.length > 0 ? { [MEETING_PASS_HEADER]: pass } : {};
+}
 var REFRESH_RATIO = 0.8;
 function readString(source, key) {
   const value = source[key];
@@ -298,7 +330,12 @@ function readBoolean(source, key, fallback) {
   const value = source[key];
   return typeof value === "boolean" ? value : fallback;
 }
-var TOKEN_ROLES = ["host", "cohost", "participant", "guest"];
+var TOKEN_STANDINGS = ["member", "invited", "outsider", "guest"];
+function readStanding(source, key) {
+  const value = source[key];
+  return TOKEN_STANDINGS.includes(value) ? value : null;
+}
+var TOKEN_ROLES = ["host", "cohost", "presenter", "participant", "viewer"];
 function readRole(source, key) {
   const value = source[key];
   return TOKEN_ROLES.includes(value) ? value : null;
@@ -341,8 +378,15 @@ function parseRoomToken(body, roomName) {
     // Deriving the role from what DID arrive keeps a host a host against a
     // server that has not landed MRI-A11 — and never invents a host from
     // silence, because both fallbacks below grant nothing.
-    role: readRole(payload, "role") ?? (isHost ? "host" : identity.startsWith("guest:") ? "guest" : "participant"),
+    // A word this package does not know grants nothing: `participant`, never a host.
+    role: readRole(payload, "role") ?? (isHost ? "host" : "participant"),
+    standing: readStanding(payload, "standing"),
+    meetingPass: readString(payload, "meeting_pass"),
+    meetingPassExpiresAt: readString(payload, "meeting_pass_expires_at"),
+    sessionId: readString(payload, "session_id"),
     lobby: readBoolean(payload, "lobby", false),
+    admissionState: readString(payload, "admission_state") ?? void 0,
+    pollSeconds: typeof payload["poll_seconds"] === "number" ? payload["poll_seconds"] : void 0,
     breakoutRoomId: readString(payload, "breakout_room_id") ?? null
   };
 }
@@ -352,7 +396,7 @@ function createTokenClient(options) {
   const storage = options.storage;
   function remember(token) {
     if (storage === void 0) return;
-    if (!token.identity.startsWith("guest:")) return;
+    if (token.standing !== "guest") return;
     storage.write(token.roomName, JSON.stringify(token));
   }
   function recall(roomName) {
@@ -410,22 +454,28 @@ function createTokenClient(options) {
       throw new MeetError(
         "forbidden",
         said?.message ?? "You can't join this meeting.",
-        said?.remedy ?? "Ask the person who shared the link to let you in, then open the link again."
+        said?.remedy ?? "Ask the person who shared the link to let you in, then open the link again.",
+        void 0,
+        said?.reason ?? null
       );
     }
     if (response.status === 404) {
       throw new MeetError(
         "not-found",
         "meet.token: no such meeting",
-        "The link is wrong or the meeting was deleted. Show the 'meeting not found' screen; a durable link that 404s is never a retry."
+        "The link is wrong or the meeting was deleted. Show the 'meeting not found' screen; a durable link that 404s is never a retry.",
+        void 0,
+        "not_found"
       );
     }
     if (response.status === 410) {
-      const reason = (await serverSentence(response))?.message ?? "This meeting was cancelled.";
+      const said = await serverSentence(response);
       throw new MeetError(
         "cancelled",
-        reason,
-        "Nobody can join a cancelled meeting. Show the cancelled screen with this sentence; ask the host to schedule a new one."
+        said?.message ?? "This meeting was cancelled.",
+        "Nobody can join a cancelled meeting. Show the cancelled screen with this sentence; ask the host to schedule a new one.",
+        void 0,
+        said?.reason ?? "cancelled"
       );
     }
     if (response.status === 423) {
@@ -433,7 +483,9 @@ function createTokenClient(options) {
       throw new MeetError(
         "room-locked",
         said?.message ?? "The meeting is locked.",
-        said?.remedy ?? "The host locked the room. Ask them to unlock it, then join again."
+        said?.remedy ?? "The host locked the room. Ask them to unlock it, then join again.",
+        void 0,
+        said?.reason ?? "locked"
       );
     }
     if (response.status === 503) {
@@ -502,6 +554,10 @@ function placeholder(roomName) {
     canRecord: false,
     isHost: false,
     role: "participant",
+    standing: null,
+    meetingPass: null,
+    meetingPassExpiresAt: null,
+    sessionId: null,
     lobby: false,
     breakoutRoomId: null
   };
@@ -514,7 +570,8 @@ async function serverSentence(response) {
     const message = typeof source.user_message === "string" && source.user_message.trim() !== "" ? source.user_message : typeof source.message === "string" && source.message.trim() !== "" ? source.message : null;
     if (message === null) return null;
     const remedy = typeof source.remedy === "string" && source.remedy.trim() !== "" ? source.remedy : void 0;
-    return { message, remedy };
+    const reason = typeof source.reason === "string" && source.reason !== "" ? source.reason : null;
+    return { message, remedy, reason };
   } catch {
     return null;
   }
@@ -703,7 +760,7 @@ function createMeetAi(options) {
         operation: "meet.ai.ask",
         // A GUEST MAY ASK. The server decides whether it can answer.
         requireAuth: false,
-        ...roomToken !== null ? { headers: { [ROOM_TOKEN_HEADER]: roomToken } } : {},
+        ...roomToken !== null ? { headers: { [MEETING_PASS_HEADER]: roomToken } } : {},
         ...signal !== void 0 ? { signal } : {}
       });
       if (!response.ok) {
@@ -942,14 +999,15 @@ var MEET_EVENTS = {
   cancel: "mx.call.cancel",
   /** You answered (or declined) on another device. Stop ringing here. */
   settled: "mx.call.settled",
-  /** Someone is in the lobby. Hosts render the knock. */
-  knock: "mx.lobby.knock",
-  /** A host decided. The knocker learns it here — they have no DB read. */
-  admission: "mx.lobby.admission",
-  /** The room was locked or unlocked. */
-  lock: "mx.room.lock",
-  /** Recording started or stopped. EVERY participant renders the indicator. */
-  recording: "mx.room.recording"
+  /**
+   * 🚨 S4 (CORE-DESIGN §2.6): the ONE room-channel event — payload-free "something changed,
+   * read again". Nothing a person must see rides it: a waiting person learns admitted /
+   * denied / expired / ended by READING their row (`GET /v1/meet/state`) on a timer and on
+   * every hint. The four payload broadcasts (`mx.lobby.knock`, `mx.lobby.admission`,
+   * `mx.room.lock`, `mx.room.recording`) are gone with their senders and receivers. The
+   * server publishes the same event on the same topic (aidream `admission.room_topic`).
+   */
+  stateChanged: "mx.state.changed"
 };
 
 // src/core/types.ts
@@ -963,14 +1021,19 @@ function isGuest(identity) {
   return identity.userId === null;
 }
 var ROLE_RANK = {
-  host: 3,
-  cohost: 2,
+  host: 4,
+  cohost: 3,
+  presenter: 2,
   participant: 1,
-  guest: 0
+  viewer: 0
 };
+function isLinkFollower(standing) {
+  return standing === "guest" || standing === "outsider";
+}
 function isHostRole(role) {
   return role === "host" || role === "cohost";
 }
+var WAITING_ADMISSION_STATES = ["waiting_host", "knocking"];
 
 // src/core/calls.ts
 var TRANSITIONS = {
@@ -1520,15 +1583,15 @@ var CAPTION_LANGUAGES = [
   { tag: "id", name: "Indonesian" },
   { tag: "sv", name: "Swedish" }
 ];
-async function loadMeetingActivities(api, meetingId, roomToken = null) {
+async function loadMeetingActivities(api, meetingId, meetingPass = null) {
   let response;
   try {
     response = await api.request({
       path: `${MEET_ROUTES.collab}?meeting_id=${encodeURIComponent(meetingId)}`,
       method: "GET",
       operation: "meet.loadMeetingActivities",
-      requireAuth: roomToken === null,
-      ...roomToken !== null ? { headers: { [ROOM_TOKEN_HEADER]: roomToken } } : {}
+      requireAuth: meetingPass === null,
+      ...meetingPass !== null ? { headers: { [MEETING_PASS_HEADER]: meetingPass } } : {}
     });
   } catch (error) {
     return {
@@ -1583,9 +1646,15 @@ var RPCS = {
   getOrCreateMeeting: "meet_get_or_create_meeting",
   /** Resolve a durable public link, before/during/after its scheduled time. */
   meetingBySlug: "meet_meeting_by_slug",
-  admit: "meet_admit_participant",
+  /*
+   * ── S4 ADMISSION (CORE-DESIGN §2.4). Each returns the decided row; the caller then
+   * sends the payload-free `mx.state.changed` hint. Authorized by `who_may_admit`.
+   */
+  admit: "meet_admit",
+  deny: "meet_deny",
+  undeny: "meet_undeny",
+  admitAll: "meet_admit_all",
   setLock: "meet_set_lock",
-  endMeeting: "meet_end_meeting",
   recordConsent: "meet_record_consent",
   /*
    * ── MEET WAVE 1 — management (0.8). Every write is a SECURITY DEFINER door
@@ -1627,13 +1696,13 @@ var RPCS = {
   /** Titles, agendas, current notes and final transcript lines; snippets mark hits with ⟦ ⟧. */
   search: "meet_search"
 };
-var VOID_RPCS = [RPCS.admit, RPCS.recordConsent];
+var VOID_RPCS = [RPCS.recordConsent];
 var MEETING_COLUMNS = "id,organization_id,room_name,slug,title,kind,host_user_id,scheduled_for,scheduled_duration_minutes,started_at,ended_at,locked,lobby_enabled,recording_policy,ai_enabled,metadata,time_zone,agenda,recurrence_rule,join_before_host,cancelled_at,cancellation_reason,deleted_at,calendar_sequence,version";
 var INVITEE_COLUMNS = "id,meeting_id,invitee_user_id,email,display_name,role,rsvp_state,responded_at,rsvp_note,last_sent_sequence,last_sent_at";
 var RECORDING_COLUMNS = "id,meeting_id,state,started_at,ended_at,started_by,file_id,failure_reason";
 var SEGMENT_COLUMNS = "id,meeting_id,identity,speaker,text,started_at,is_final,metadata";
 var NOTE_COLUMNS = "id,meeting_id,text,kind,assignee_user_id,created_at,metadata";
-var ATTENDEE_COLUMNS = "id,meeting_id,identity,participant_user_id,display_name,avatar_url,role,admission_state,is_agent,joined_at,left_at,sessions:metadata->sessions";
+var ATTENDEE_COLUMNS = "id,meeting_id,identity,participant_user_id,display_name,avatar_url,role,admission_state,knocked_at,knock_expires_at,is_agent,joined_at,left_at,sessions:metadata->sessions";
 function projectStays(value) {
   if (!Array.isArray(value)) return [];
   const stays = [];
@@ -1999,8 +2068,17 @@ function createMeetRepository(options) {
     const operation = "meet.projectAttendee";
     const role = text(row, "role");
     const admission = text(row, "admission_state");
-    const known = ["host", "cohost", "participant", "guest"];
-    const states = ["knocking", "admitted", "denied", "removed"];
+    const known = ["host", "cohost", "presenter", "participant", "viewer"];
+    const states = [
+      "waiting_host",
+      "knocking",
+      "admitted",
+      "denied",
+      "expired",
+      "withdrawn",
+      "removed",
+      "ended"
+    ];
     const userId = text(row, "participant_user_id");
     const identity = requireText(row, "identity", operation);
     return {
@@ -2014,6 +2092,8 @@ function createMeetRepository(options) {
       userId: userId === null ? null : asUserId(userId),
       role: known.includes(role) ? role : "participant",
       admissionState: states.includes(admission) ? admission : "admitted",
+      knockedAt: text(row, "knocked_at"),
+      knockExpiresAt: text(row, "knock_expires_at"),
       isAgent: bool(row, "is_agent", false),
       joinedAt: text(row, "joined_at"),
       leftAt: text(row, "left_at"),
@@ -2292,16 +2372,26 @@ function createMeetRepository(options) {
         hasMore: rows.length > limit
       };
     },
-    async admit({ meetingId, identity, admitted, byUserId }) {
-      await guardVoid(
-        "meet.admit",
-        () => db.rpc(RPCS.admit, {
+    async decideAdmission({ meetingId, identity, decision, byUserId }) {
+      const fn = decision === "admit" ? RPCS.admit : decision === "deny" ? RPCS.deny : RPCS.undeny;
+      const row = await guard(
+        `meet.${decision}`,
+        () => db.rpc(fn, {
           p_meeting_id: meetingId,
           p_identity: identity,
-          p_admitted: admitted,
           p_by_user_id: byUserId
         })
       );
+      return projectAttendee(row);
+    },
+    async admitAll(meetingId, byUserId) {
+      const response = await db.rpc(RPCS.admitAll, {
+        p_meeting_id: meetingId,
+        p_by_user_id: byUserId
+      });
+      if (response.error !== null) throw normalizeMeetError(response.error, "meet.admitAll");
+      const rows = Array.isArray(response.data) ? response.data : [];
+      return rows.map(projectAttendee);
     },
     async setLock(meetingId, locked, byUserId) {
       const row = await guard(
@@ -2314,16 +2404,6 @@ function createMeetRepository(options) {
       );
       return projectMeeting(row);
     },
-    async endMeeting(meetingId, byUserId) {
-      const row = await guard(
-        "meet.endMeeting",
-        () => db.rpc(RPCS.endMeeting, {
-          p_meeting_id: meetingId,
-          p_by_user_id: byUserId
-        })
-      );
-      return projectMeeting(row);
-    },
     async transcript(meetingId, limit = 1e3) {
       const response = await db.from(TABLES.transcripts).select(SEGMENT_COLUMNS).eq("meeting_id", meetingId).order("started_at", { ascending: true }).order("id", { ascending: true }).limit(limit);
       if (response.error !== null) throw normalizeMeetError(response.error, "meet.transcript");
@@ -2652,12 +2732,14 @@ var DEFAULT_EFFECTS = {
 };
 var NO_GRANTS = {
   role: "participant",
+  standing: null,
   canRecord: false,
   canPublish: false,
   canSubscribe: false
 };
 var EMPTY = {
   phase: "idle",
+  waiting: null,
   meeting: null,
   localIdentity: null,
   grants: NO_GRANTS,
@@ -2698,6 +2780,11 @@ function effectiveRole(snapshot) {
   const fromToken = snapshot.grants.role;
   return ROLE_RANK[fromRoster] >= ROLE_RANK[fromToken] ? fromRoster : fromToken;
 }
+function effectiveStanding(snapshot) {
+  if (snapshot.grants.standing != null) return snapshot.grants.standing;
+  const me = snapshot.participants.find((p) => p.identity === snapshot.localIdentity);
+  return me?.standing ?? null;
+}
 var REACTION_TTL_MS = 5e3;
 var CHAT_LIMIT = 200;
 function createMeetStore(initial = {}) {
@@ -3190,7 +3277,7 @@ function applyModeration(store, payload, now) {
       return ignored(`a moderation kind this version does not know: ${String(kind)}`);
   }
 }
-var ROLES = ["host", "cohost", "participant", "guest"];
+var ROLES = ["host", "cohost", "presenter", "participant", "viewer"];
 
 // src/core/devices.ts
 var KINDS = ["audioinput", "videoinput", "audiooutput"];
@@ -3930,19 +4017,25 @@ function roleOf(participants, identity) {
   return participants.find((p) => p.identity === identity)?.role ?? "participant";
 }
 var END_MEETING_NOT_SERVED = "Ending a meeting is not available on this server yet";
-function lobbyEntryFrom(attendee) {
-  if (attendee.admissionState !== "knocking") return null;
+function lobbyEntryFrom(attendee, now = Date.now()) {
+  if (!WAITING_ADMISSION_STATES.includes(attendee.admissionState)) return null;
+  const expires = attendee.knockExpiresAt ? Date.parse(attendee.knockExpiresAt) : Number.NaN;
+  if (!Number.isNaN(expires) && expires <= now) return null;
   return {
     identity: attendee.identity,
     displayName: attendee.displayName,
     avatarUrl: attendee.avatarUrl,
     userId: attendee.userId,
     state: "knocking",
-    knockedAt: attendee.joinedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+    knockedAt: attendee.knockedAt ?? attendee.joinedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+    knockExpiresAt: attendee.knockExpiresAt ?? null,
     decidedAt: null,
     decidedBy: null
   };
 }
+function decidedState(state) {
+  return WAITING_ADMISSION_STATES.includes(state) ? "expired" : state;
+}
 function createMeetingSession(options) {
   const { manager, repository, store, identity } = options;
   let channel = null;
@@ -3966,11 +4059,6 @@ function createMeetingSession(options) {
     }
     return identity.userId;
   }
-  function knockIdentity() {
-    return asParticipantIdentity(
-      identity.userId !== null ? `user:${identity.userId}` : `guest:${identity.deviceId}`
-    );
-  }
   function requireMeeting(operation) {
     const meeting = store.snapshot().meeting;
     if (meeting === null) {
@@ -3982,6 +4070,191 @@ function createMeetingSession(options) {
     }
     return meeting;
   }
+  let polling = false;
+  let pollTimer = null;
+  let reading = null;
+  let admittedOnce = false;
+  let unlisten = null;
+  function report(level, message, remedy) {
+    options.onDiagnostic?.(remedy === void 0 ? { level, message } : { level, message, remedy });
+  }
+  function pollMs() {
+    const seconds = store.snapshot().waiting?.pollSeconds ?? 3;
+    return Math.max(1, Math.min(60, seconds)) * 1e3;
+  }
+  function schedule(ms2) {
+    if (pollTimer !== null) clearTimeout(pollTimer);
+    if (!polling) return;
+    pollTimer = setTimeout(() => {
+      pollTimer = null;
+      void readState2().finally(() => schedule(pollMs()));
+    }, ms2);
+  }
+  function listen() {
+    if (unlisten !== null || typeof window === "undefined") return;
+    const nudge = () => {
+      if (typeof document !== "undefined" && document.visibilityState === "hidden") return;
+      void readState2();
+    };
+    const goodbye = () => {
+      const meeting = store.snapshot().meeting;
+      const pass = options.resolvePass?.() ?? null;
+      const waiting = store.snapshot().waiting;
+      if (meeting === null || pass === null || waiting === null) return;
+      if (!WAITING_ADMISSION_STATES.includes(waiting.admission)) return;
+      try {
+        navigator.sendBeacon?.(
+          options.api.url(MEET_ROUTES.leave),
+          new Blob([JSON.stringify({ meeting_id: meeting.id, intent: "withdraw", meeting_pass: pass })], {
+            type: "application/json"
+          })
+        );
+      } catch {
+      }
+    };
+    window.addEventListener("online", nudge);
+    window.addEventListener("pagehide", goodbye);
+    document.addEventListener("visibilitychange", nudge);
+    unlisten = () => {
+      window.removeEventListener("online", nudge);
+      window.removeEventListener("pagehide", goodbye);
+      document.removeEventListener("visibilitychange", nudge);
+    };
+  }
+  function stopWaiting() {
+    polling = false;
+    if (pollTimer !== null) clearTimeout(pollTimer);
+    pollTimer = null;
+    unlisten?.();
+    unlisten = null;
+  }
+  function patchWaiting(next) {
+    const current = store.snapshot().waiting;
+    const base = current ?? {
+      admission: "knocking",
+      admittersPresent: null,
+      reknockAllowed: true,
+      knockExpiresAt: null,
+      pollSeconds: 3,
+      liveVersion: 0
+    };
+    store.patch({ waiting: { ...base, ...next } });
+  }
+  function apply(read) {
+    const snapshot = store.snapshot();
+    if (snapshot.phase !== "lobby") return;
+    const admission = read.admission_state ?? null;
+    const ended = admission === "ended" || read.session_phase === "ended" || read.meeting_phase === "ended";
+    if (admission === "admitted" && !ended) {
+      if (admittedOnce) return;
+      admittedOnce = true;
+      stopWaiting();
+      options.onAdmitted?.();
+      return;
+    }
+    if (ended) {
+      stopWaiting();
+      patchWaiting({ admission: "ended" });
+      const meeting = snapshot.meeting;
+      if (read.meeting_phase === "ended" && meeting !== null && meeting.endedAt === null) {
+        store.patch({ meeting: { ...meeting, endedAt: (/* @__PURE__ */ new Date()).toISOString() } });
+      }
+      return;
+    }
+    if (admission === null) return;
+    patchWaiting({
+      admission,
+      admittersPresent: read.admitters_present ?? null,
+      reknockAllowed: read.reknock_allowed ?? true,
+      knockExpiresAt: read.knock_expires_at ?? null,
+      pollSeconds: read.poll_seconds ?? snapshot.waiting?.pollSeconds ?? 3,
+      liveVersion: read.live_version ?? 0
+    });
+    if (admission === "denied" || admission === "expired" || admission === "withdrawn" || admission === "removed") {
+      stopWaiting();
+    }
+  }
+  async function readState2() {
+    if (reading !== null) return reading;
+    const meeting = store.snapshot().meeting;
+    const pass = options.resolvePass?.() ?? null;
+    if (meeting === null || pass === null) return;
+    reading = (async () => {
+      try {
+        const response = await options.api.request({
+          path: `${MEET_ROUTES.state}?meeting_id=${encodeURIComponent(meeting.id)}`,
+          method: "GET",
+          requireAuth: false,
+          operation: "meet.state",
+          headers: { [MEETING_PASS_HEADER]: pass }
+        });
+        if (!response.ok) {
+          let body = null;
+          try {
+            body = await response.json();
+          } catch {
+            body = null;
+          }
+          const refusal2 = readServerRefusal(body);
+          report(
+            "warn",
+            refusal2?.reason ?? `meet.state: the server answered ${response.status}`,
+            refusal2?.remedy ?? "The waiting room keeps asking; nothing on this screen changes until the server answers."
+          );
+          return;
+        }
+        apply(await response.json());
+      } catch (error) {
+        report("info", `meet.state: ${String(error)}`, "Waiting continues; the state is read again shortly.");
+      } finally {
+        reading = null;
+      }
+    })();
+    return reading;
+  }
+  async function postLeave(intent) {
+    const meeting = requireMeeting(`meet.${intent}`);
+    const pass = options.resolvePass?.() ?? null;
+    const response = await options.api.request({
+      path: MEET_ROUTES.leave,
+      method: "POST",
+      requireAuth: false,
+      operation: `meet.${intent}`,
+      body: { meeting_id: meeting.id, intent },
+      ...pass !== null ? { headers: { [MEETING_PASS_HEADER]: pass } } : {}
+    });
+    if (!response.ok) {
+      let body = null;
+      try {
+        body = await response.json();
+      } catch {
+        body = null;
+      }
+      const refusal2 = readServerRefusal(body);
+      throw new MeetError(
+        "transport",
+        refusal2?.reason ?? `meet.${intent}: the server answered ${response.status}`,
+        refusal2?.remedy ?? "You are still in the waiting room. Try again."
+      );
+    }
+  }
+  function hint() {
+    channel?.send(MEET_EVENTS.stateChanged, { v: null });
+  }
+  async function refreshQueue() {
+    const meeting = store.snapshot().meeting;
+    if (meeting === null || isGuest(identity) || !isHostRole(effectiveRole(store.snapshot()))) return;
+    try {
+      const attendees = await repository.attendees(meeting.id);
+      store.learn(attendees);
+      for (const attendee of attendees) {
+        const entry = lobbyEntryFrom(attendee);
+        if (entry !== null) store.upsertLobby(entry);
+        else store.setAdmission(attendee.identity, decidedState(attendee.admissionState), null);
+      }
+    } catch {
+    }
+  }
   return {
     watch(roomName) {
       channel?.close();
@@ -3989,58 +4262,22 @@ function createMeetingSession(options) {
         topic: roomTopic(roomName),
         broadcast: [
           {
-            event: MEET_EVENTS.knock,
-            onMessage: (message) => {
-              store.upsertLobby(message.data);
-            }
-          },
-          {
-            event: MEET_EVENTS.admission,
-            onMessage: (message) => {
-              const verdict = message.data;
-              const decided = asParticipantIdentity(verdict.identity);
-              store.setAdmission(
-                decided,
-                verdict.admitted ? "admitted" : "denied",
-                verdict.by === null ? null : verdict.by
-              );
-              if (decided === knockIdentity()) {
-                if (verdict.admitted) options.onAdmitted?.();
-                else options.onDenied?.();
-              }
-            }
-          },
-          {
-            event: MEET_EVENTS.lock,
-            onMessage: (message) => {
-              const { locked } = message.data;
-              const meeting = store.snapshot().meeting;
-              store.patch({
-                locked,
-                ...meeting !== null ? { meeting: { ...meeting, locked } } : {}
-              });
-            }
-          },
-          {
-            event: MEET_EVENTS.recording,
-            onMessage: (message) => {
-              const payload = message.data;
-              store.setRecording(
-                payload.state,
-                payload.by === null ? null : payload.by,
-                "room"
-              );
+            // 🚨 PAYLOAD-FREE. Every receiver reads again; a spoofed hint only causes a read.
+            event: MEET_EVENTS.stateChanged,
+            onMessage: () => {
+              if (store.snapshot().phase === "lobby") void readState2();
+              void refreshQueue();
             }
           }
         ],
-        // THE BACKFILL DOOR. A host whose socket blipped must not miss a knock:
-        // re-reading the meeting restores lock/recording truth, and knockers
-        // re-announce on their own timer.
+        // THE BACKFILL DOOR. A socket blip must not lose a decision: re-read the meeting
+        // row, and a waiting tab re-reads its own state.
         onBackfill: async () => {
           const meeting = store.snapshot().meeting;
           if (meeting === null) return;
           const fresh = isGuest(identity) ? await repository.meetingBySlug(meeting.slug) : await readMeeting(meeting.id);
           store.patch({ meeting: fresh, locked: fresh.locked });
+          if (store.snapshot().phase === "lobby") void readState2();
         }
       });
     },
@@ -4101,7 +4338,7 @@ function createMeetingSession(options) {
                 store.upsertLobby(entry);
                 return;
               }
-              store.setAdmission(attendee.identity, attendee.admissionState, null);
+              store.setAdmission(attendee.identity, decidedState(attendee.admissionState), null);
             }
           },
           {
@@ -4153,62 +4390,75 @@ function createMeetingSession(options) {
             if (entry !== null) {
               store.upsertLobby(entry);
             } else {
-              store.setAdmission(attendee.identity, attendee.admissionState, null);
+              store.setAdmission(attendee.identity, decidedState(attendee.admissionState), null);
             }
           }
         }
       });
       meetingChannel.requestBackfill("manual");
     },
-    knock(roomName) {
-      const handle = channel ?? manager.open({ topic: roomTopic(roomName) });
-      channel = handle;
-      const entry = {
-        identity: knockIdentity(),
-        displayName: identity.displayName,
-        avatarUrl: identity.avatarUrl,
-        userId: identity.userId,
-        state: "knocking",
-        knockedAt: (/* @__PURE__ */ new Date()).toISOString(),
-        decidedAt: null,
-        decidedBy: null
-      };
-      store.upsertLobby(entry);
-      handle.send(MEET_EVENTS.knock, entry);
-    },
     async admit(entry, admitted) {
       const by = requireHostUser("meet.admit");
       const meeting = requireMeeting("meet.admit");
-      await repository.admit({
+      const row = await repository.decideAdmission({
         meetingId: meeting.id,
         identity: entry.identity,
-        admitted,
+        decision: admitted ? "admit" : "deny",
         byUserId: by
       });
       store.upsertLobby({
         ...entry,
-        state: admitted ? "admitted" : "denied",
+        state: decidedState(row.admissionState),
         decidedAt: (/* @__PURE__ */ new Date()).toISOString(),
         decidedBy: by
       });
-      channel?.send(MEET_EVENTS.admission, {
+      hint();
+    },
+    async undeny(entry) {
+      const by = requireHostUser("meet.undeny");
+      const meeting = requireMeeting("meet.undeny");
+      const row = await repository.decideAdmission({
+        meetingId: meeting.id,
         identity: entry.identity,
-        admitted,
-        by
+        decision: "undeny",
+        byUserId: by
       });
+      store.upsertLobby({ ...entry, state: decidedState(row.admissionState), decidedAt: (/* @__PURE__ */ new Date()).toISOString(), decidedBy: by });
+      hint();
     },
     async admitAll() {
-      const knocking = store.snapshot().lobby.filter((entry) => entry.state === "knocking");
-      for (const entry of knocking) {
-        await this.admit(entry, true);
+      const by = requireHostUser("meet.admitAll");
+      const meeting = requireMeeting("meet.admitAll");
+      const rows = await repository.admitAll(meeting.id, by);
+      for (const row of rows) {
+        store.setAdmission(row.identity, row.admissionState, by);
       }
+      hint();
+    },
+    startWaiting() {
+      if (polling) return;
+      polling = true;
+      admittedOnce = false;
+      listen();
+      schedule(0);
+    },
+    stopWaiting,
+    readState: readState2,
+    async withdraw() {
+      stopWaiting();
+      await postLeave("withdraw");
+      patchWaiting({ admission: "withdrawn" });
+      hint();
+    },
+    async askAgain() {
+      await options.rejoin?.();
     },
     async setLock(locked) {
       const by = requireHostUser("meet.setLock");
       const meeting = requireMeeting("meet.setLock");
       const updated = await repository.setLock(meeting.id, locked, by);
       store.patch({ meeting: updated, locked: updated.locked });
-      channel?.send(MEET_EVENTS.lock, { locked: updated.locked });
+      hint();
       return updated;
     },
     /**
@@ -4266,6 +4516,7 @@ function createMeetingSession(options) {
       return { endedAt, served: true };
     },
     dispose() {
+      stopWaiting();
       channel?.close();
       channel = null;
       meetingChannel?.close();
@@ -4385,7 +4636,6 @@ function kindOf(person) {
   if (person.isAgent) return "assistant";
   if (person.role === "host") return "host";
   if (person.role === "cohost") return "cohost";
-  if (person.role === "guest") return person.userId !== null ? "signed-in guest" : "guest";
   if (person.userId === null) return "guest";
   return "member";
 }
@@ -4670,7 +4920,7 @@ function meetingLength(meeting) {
   if (start === null || end === null || end < start) return null;
   return formatDurationMs(end - start, { style: "long" });
 }
-async function loadMeetingChat(api, meetingId, roomToken = null) {
+async function loadMeetingChat(api, meetingId, meetingPass = null) {
   const operation = "meet.loadMeetingChat";
   let response;
   try {
@@ -4678,8 +4928,8 @@ async function loadMeetingChat(api, meetingId, roomToken = null) {
       path: `${MEET_ROUTES.chat}?meeting_id=${encodeURIComponent(meetingId)}`,
       method: "GET",
       operation,
-      requireAuth: roomToken === null,
-      ...roomToken !== null ? { headers: { [ROOM_TOKEN_HEADER]: roomToken } } : {}
+      requireAuth: meetingPass === null,
+      ...meetingPass !== null ? { headers: { [MEETING_PASS_HEADER]: meetingPass } } : {}
     });
   } catch (error) {
     return {
@@ -4823,7 +5073,12 @@ async function pushMeetingToGoogleCalendar(api, meetingId, target) {
 // src/core/room.ts
 var PARTICIPANT_ROLE_ATTRIBUTE = "matrx.participant.role";
 var PARTICIPANT_CAN_RECORD_ATTRIBUTE = "matrx.participant.can_record";
-var KNOWN_ROLES = ["host", "cohost", "participant", "guest"];
+var PARTICIPANT_STANDING_ATTRIBUTE = "matrx.participant.standing";
+var KNOWN_STANDINGS = ["member", "invited", "outsider", "guest"];
+function parseStanding(value) {
+  return KNOWN_STANDINGS.includes(value) ? value : null;
+}
+var KNOWN_ROLES = ["host", "cohost", "presenter", "participant", "viewer"];
 function parseRole(value) {
   return KNOWN_ROLES.includes(value) ? value : "participant";
 }
@@ -4857,6 +5112,9 @@ function projectParticipant(driver, joinedAt) {
     // ATTRIBUTE FIRST, metadata second — see the constants above. Both are the
     // server's; the attribute is simply the one that always arrives.
     role: parseRole(driver.attributes[PARTICIPANT_ROLE_ATTRIBUTE] ?? metadata.role),
+    standing: parseStanding(
+      driver.attributes[PARTICIPANT_STANDING_ATTRIBUTE] ?? metadata.standing
+    ),
     canRecord: driver.attributes[PARTICIPANT_CAN_RECORD_ATTRIBUTE] === "true" || metadata.can_record === true,
     isLocal: driver.isLocal,
     isAgent: metadata.is_agent === true,
@@ -4929,7 +5187,7 @@ function createRoomEngine(options) {
     const normalized = normalizeMeetError(error, operation);
     store.patch({
       phase: "failed",
-      failure: { message: normalized.message, remedy: normalized.remedy }
+      failure: { message: normalized.message, remedy: normalized.remedy, reason: normalized.reason }
     });
     report(
       normalized.code === "session-unavailable" ? "warn" : "error",
@@ -5119,7 +5377,7 @@ function createRoomEngine(options) {
     }
   };
   async function connect(request) {
-    store.patch({ phase: "requesting-token", failure: null });
+    store.patch({ phase: "requesting-token", failure: null, waiting: null });
     const token = await tokens.get({
       roomName: request.roomName,
       identity,
@@ -5133,16 +5391,27 @@ function createRoomEngine(options) {
       breakoutRoomId: token.breakoutRoomId ?? null,
       grants: {
         role: token.role,
+        standing: token.standing,
         canRecord: token.canRecord,
         canPublish: token.canPublish,
         canSubscribe: token.canSubscribe
       }
     });
-    if (token.lobby) {
-      store.patch({ phase: "lobby" });
+    if (token.lobby || !token.canSubscribe) {
+      store.patch({
+        phase: "lobby",
+        waiting: {
+          admission: token.admissionState !== void 0 && token.admissionState !== "admitted" ? token.admissionState : "knocking",
+          admittersPresent: null,
+          reknockAllowed: true,
+          knockExpiresAt: null,
+          pollSeconds: token.pollSeconds ?? 3,
+          liveVersion: 0
+        }
+      });
       return;
     }
-    store.patch({ phase: "connecting" });
+    store.patch({ phase: "connecting", waiting: null });
     const created = await options.driverFactory(handlers);
     if (disposed) {
       await created.disconnect();
@@ -5478,7 +5747,7 @@ function createInRoomClient(options) {
   }
   function headers() {
     const token = options.resolveRoomToken();
-    return token === null ? void 0 : { [ROOM_TOKEN_HEADER]: token };
+    return token === null ? void 0 : { [MEETING_PASS_HEADER]: token };
   }
   function refusal2(response, operation, remedy) {
     return refusalFromResponse(response, operation, remedy);
@@ -5959,7 +6228,7 @@ function summarizeMeetingRecordRestrictions(restrictions) {
 async function loadGuestMeetingRecord(args) {
   const { api, repository, meetingId, meeting, roomToken } = args;
   const session = args.session === true;
-  if (roomToken === null && !session) {
+  if (roomToken?.meetingPass == null && !session) {
     return refusedBundle(
       meeting,
       "This meeting's record is only readable by the people who were in it.",
@@ -5969,12 +6238,12 @@ async function loadGuestMeetingRecord(args) {
   let response;
   try {
     response = await api.request({
-      path: `${MEET_ROUTES.record}?meeting_id=${encodeURIComponent(meetingId)}`,
+      path: `${MEET_ROUTES.record}?meeting_id=${encodeURIComponent(meetingId)}` + (args.sessionId ? `&session_id=${encodeURIComponent(args.sessionId)}` : ""),
       method: "GET",
       // A GUEST HAS NO SESSION AND IS STILL A FIRST-CLASS READER (D6).
       requireAuth: session,
       operation: "meet.record",
-      headers: roomToken === null ? {} : { [ROOM_TOKEN_HEADER]: roomToken.token }
+      headers: roomToken?.meetingPass != null ? { [MEETING_PASS_HEADER]: roomToken.meetingPass } : {}
     });
   } catch (error) {
     return refusedBundle(
@@ -6362,6 +6631,10 @@ function takeMoveRequest(store) {
 }
 
 // src/core/observation.ts
+function observedRole(role, standing) {
+  if (role === "host" || role === "cohost") return role;
+  return isLinkFollower(standing) ? "guest" : "participant";
+}
 function observedDevice(track) {
   if (track.enabled) return "on";
   const refused = track.unavailable;
@@ -6389,13 +6662,15 @@ function observedPhase(input) {
   const raw = snapshot.phase;
   const live = raw === "connected" || raw === "reconnecting";
   if (endedRecord(snapshot, input.meeting ?? null) && !live) return "ended";
+  const reason = raw === "failed" ? snapshot.failure?.reason ?? null : null;
+  if (reason !== null) return reason === "ended" ? "ended" : `refused:${reason}`;
   switch (raw) {
     case "idle":
     case "failed":
     case "left":
       return "prejoin";
     case "lobby":
-      return "waiting:knocking";
+      return waitingPhase(snapshot);
     case "requesting-token":
     case "connecting":
       return "joining";
@@ -6404,20 +6679,39 @@ function observedPhase(input) {
       return "in_call";
   }
 }
+function waitingPhase(snapshot) {
+  switch (snapshot.waiting?.admission) {
+    case "waiting_host":
+      return "waiting:host_not_started";
+    case "denied":
+      return "denied";
+    case "expired":
+      return "knock_expired";
+    case "withdrawn":
+      return "left";
+    case "ended":
+      return "ended";
+    case "removed":
+      return "refused:removed";
+    default:
+      return "waiting:knocking";
+  }
+}
 var ADMITTER_ROLES = /* @__PURE__ */ new Set(["host", "cohost"]);
 function observe(input) {
   const { snapshot } = input;
   const phase = observedPhase(input);
   const inCall = phase === "in_call";
-  const role = inCall && snapshot !== null ? effectiveRole(snapshot) : "none";
-  const canAdmit = role !== "none" && ADMITTER_ROLES.has(role);
+  const actual = inCall && snapshot !== null ? effectiveRole(snapshot) : "none";
+  const canAdmit = actual !== "none" && ADMITTER_ROLES.has(actual);
+  const role = actual === "none" || snapshot === null ? "none" : observedRole(actual, effectiveStanding(snapshot));
   const deviceInPlay = phase === "joining" || inCall;
   return {
     phase,
-    reason: null,
+    reason: phase.startsWith("refused:") ? phase.slice("refused:".length) : null,
     role,
     connection: snapshot?.phase === "reconnecting" ? "reconnecting" : "stable",
-    hostPresent: inCall && snapshot !== null ? snapshot.participants.some((p) => ADMITTER_ROLES.has(p.role)) : null,
+    hostPresent: inCall && snapshot !== null ? snapshot.participants.some((p) => ADMITTER_ROLES.has(p.role)) : snapshot?.phase === "lobby" ? snapshot.waiting?.admittersPresent ?? null : null,
     lobbyCount: canAdmit && snapshot !== null ? snapshot.lobby.filter((entry) => entry.state === "knocking").length : 0,
     recording: snapshot?.recording === "recording" || snapshot?.recording === "stopping",
     audioBlocked: null,
@@ -6480,7 +6774,7 @@ function participantAttributes(p) {
     "data-meet-participant": "",
     "data-meet-participant-identity": p.identity,
     "data-meet-participant-name": p.displayName,
-    "data-meet-participant-role": p.role,
+    "data-meet-participant-role": observedRole(p.role, p.standing),
     "data-meet-participant-self": String(p.isLocal)
   };
   const quality = observedQuality(p.quality);
@@ -6513,6 +6807,7 @@ export {
   LISTEN_ONLY_NOTICE,
   MEETING_INVITE_KIND,
   MEETING_INVITE_VERSION,
+  MEETING_PASS_HEADER,
   MEETING_RECORD_GRACE_MS,
   MEET_ANSWER_CONTEXT_EVENT,
   MEET_ANSWER_EVENTS,
@@ -6528,12 +6823,12 @@ export {
   ORGANIZATION_HEADER,
   PARTICIPANT_CAN_RECORD_ATTRIBUTE,
   PARTICIPANT_ROLE_ATTRIBUTE,
+  PARTICIPANT_STANDING_ATTRIBUTE,
   REACTION_TTL_MS,
   REFUSED_ABSENCE,
   ROLE_RANK,
   ROOM_EVENTS,
   ROOM_EVENT_PREFIX,
-  ROOM_TOKEN_HEADER,
   RPCS,
   TABLES,
   TRANSCRIPTION_ATTRIBUTES,
@@ -6604,6 +6899,7 @@ export {
   isGuest,
   isGuestIdentity,
   isHostRole,
+  isLinkFollower,
   isListenOnly,
   isNoteTaker,
   isRealName,
@@ -6622,6 +6918,7 @@ export {
   meetingInviteAction,
   meetingLength,
   meetingLink,
+  meetingPassHeaders,
   meetingPath,
   meetingSlug,
   meetingTopic,
@@ -6665,6 +6962,7 @@ export {
   recordingLabel,
   recordingNotice,
   recordingOffsetMs,
+  rememberedMeetingPass,
   roleOf,
   roomTopic,
   rootAttributes,