Add explicit Join gate, your-turn state, and at-capacity modal

After waiting in line the conversation no longer auto-starts: reaching the front
holds a slot and shows a "your turn" orb with a "Join now" countdown button, so a
slot is never spent on someone who stepped away, and the click is a fresh gesture
that re-arms the AudioContext on iOS. Leaving or letting the countdown lapse
refunds the reserved budget.

When the whole waiting line is full, a warm "we're at capacity" modal (reusing the
limit-modal shell) explains the wait instead of a terse error. Queue captions and
retry messages reworded to be kinder.

index.html

@@ -132,9 +132,14 @@
 
         <p id="circle-caption" class="circle-caption" role="status">Tap to start</p>
 
-        <button id="leave-queue-btn" class="leave-queue-btn" type="button" hidden>
-          Leave queue
-        </button>
+        <div id="queue-actions" class="queue-actions" hidden>
+          <button id="join-queue-btn" class="join-queue-btn" type="button" hidden>
+            Join now
+          </button>
+          <button id="leave-queue-btn" class="leave-queue-btn" type="button" hidden>
+            Leave queue
+          </button>
+        </div>
       </main>
 
       <footer class="footer">

main.js

@@ -13,7 +13,7 @@
  * client owns its own AudioContext (no `attachOutputTrack`), so we hand
  * it the MediaStream directly.
  *
- * @typedef {"idle" | "connecting" | "queued" | "listening" | "user-speaking" | "processing" | "ai-speaking" | "error"} AppState
+ * @typedef {"idle" | "connecting" | "queued" | "your-turn" | "listening" | "user-speaking" | "processing" | "ai-speaking" | "error"} AppState
  */
 
 import { S2sWsRealtimeClient } from "./ws/s2s-ws-client.js";
@@ -151,7 +151,8 @@ function saveTools() {
 const STATE_VIEWS = {
   idle:            { caption: "Tap to start",  disabled: false },
   connecting:      { caption: "Connecting",    disabled: true  },
-  queued:          { caption: "Waiting…",       disabled: true  },
+  queued:          { caption: "Finding you a spot…", disabled: true },
+  "your-turn":     { caption: "You're up! 🎉", disabled: true  },
   listening:       { caption: "",              disabled: false },
   "user-speaking": { caption: "",              disabled: false },
   processing:      { caption: "",              disabled: false },
@@ -164,6 +165,7 @@ const STATE_CLASS = {
   idle: "state-idle",
   connecting: "state-connecting",
   queued: "state-queued",
+  "your-turn": "state-your-turn",
   listening: "state-listening",
   "user-speaking": "state-user-speaking",
   processing: "state-processing",
@@ -184,6 +186,10 @@ const orbWrap = $(".orb-wrap");
 const micBtn = $("#mic-btn");
 /** @type {HTMLButtonElement} */
 const stopBtn = $("#stop-btn");
+/** @type {HTMLElement} */
+const queueActions = $("#queue-actions");
+/** @type {HTMLButtonElement} */
+const joinQueueBtn = $("#join-queue-btn");
 /** @type {HTMLButtonElement} */
 const leaveQueueBtn = $("#leave-queue-btn");
 
@@ -343,10 +349,16 @@ function setState(next) {
   micBtn.tabIndex = live ? 0 : -1;
   stopBtn.tabIndex = live ? 0 : -1;
 
-  // The "Leave queue" button shows only while waiting in line.
-  const queued = next === "queued";
-  leaveQueueBtn.hidden = !queued;
-  leaveQueueBtn.tabIndex = queued ? 0 : -1;
+  // Queue affordances: "Leave queue" whenever we're in line; "Join now" only once
+  // it's our turn (a slot is held for us). Both live under #queue-actions.
+  const yourTurn = next === "your-turn";
+  const inLine = next === "queued" || yourTurn;
+  queueActions.hidden = !inLine;
+  joinQueueBtn.hidden = !yourTurn;
+  joinQueueBtn.tabIndex = yourTurn ? 0 : -1;
+  leaveQueueBtn.hidden = !inLine;
+  leaveQueueBtn.tabIndex = inLine ? 0 : -1;
+  if (!yourTurn) stopJoinCountdown();
 
   updateRestartAvailability();
 }
@@ -355,7 +367,8 @@ function updateRestartAvailability() {
   // Restart works from any settled state — it tears down a live call (if any)
   // and reconnects with the current settings. Only block while mid-connect or
   // while waiting in the queue (restarting from there would just re-queue).
-  restartBtn.disabled = currentState === "connecting" || currentState === "queued";
+  restartBtn.disabled =
+    currentState === "connecting" || currentState === "queued" || currentState === "your-turn";
   restartHint.hidden = false;
   restartHint.textContent = LIVE_STATES.has(currentState)
     ? "Reconnects now with the settings above."
@@ -989,13 +1002,21 @@ async function handleStartError(err) {
   // The user left the queue (close() aborted the wait): teardown already reset
   // the UI to idle, so there's nothing to report.
   if (err && err.code === "aborted") return;
-  // The queue was full or our ticket timed out — recoverable, not a fault. Land
-  // on the retry state with a plain-language reason instead of an error dump.
-  if (err && (err.code === "queue-full" || err.code === "queue-expired")) {
+  // The whole waiting line is full: a warm, reassuring modal rather than an error.
+  if (err && err.code === "queue-full") {
+    await teardown();
+    account.showBusy();
+    return;
+  }
+  // Our place lapsed (ticket reaped, or the join window ran out). Recoverable, not
+  // a fault: land on the retry state with a kind, plain-language reason.
+  if (err && (err.code === "queue-expired" || err.code === "join-expired")) {
     await teardown();
     setState("error");
     setCaption(
-      err.code === "queue-full" ? "All lines busy — tap to retry" : "Queue timed out — tap to retry",
+      err.code === "join-expired"
+        ? "Your spot expired. Tap to rejoin."
+        : "That took a while. Tap to rejoin.",
       "error",
     );
     return;
@@ -1025,6 +1046,13 @@ leaveQueueBtn.addEventListener("click", async () => {
   await teardown();
 });
 
+// "Join now": accept the held slot. The click is a user gesture, so the client
+// re-resumes the AudioContext here (iOS) before dialing.
+joinQueueBtn.addEventListener("click", () => {
+  stopJoinCountdown();
+  if (client) client.join();
+});
+
 const MIC_CONSTRAINTS = {
   audio: { echoCancellation: true, noiseSuppression: true, autoGainControl: true },
 };
@@ -1053,7 +1081,38 @@ async function acquireMicStream() {
 /** @param {number} position Update the queued caption ("You're #N in line"). */
 function onQueuePosition(position) {
   const n = Number(position) || 0;
-  setCaption(n > 0 ? `You're #${n} in line` : "Waiting for a free slot…", "muted");
+  setCaption(n > 0 ? `You're #${n} in line` : "Finding you a spot…", "muted");
+}
+
+// ── "Your turn" join countdown ──────────────────────────────────────────────
+// While a slot is held for us, show how long is left to accept it. The client's
+// join gate expires just before the load balancer reclaims the slot.
+let joinCountdownTimer = 0;
+
+/** @param {number} sec */
+function startJoinCountdown(sec) {
+  stopJoinCountdown();
+  let left = Math.max(0, Math.floor(sec));
+  const paint = () => {
+    joinQueueBtn.textContent = left > 0 ? `Join now (${left}s)` : "Join now";
+  };
+  paint();
+  joinCountdownTimer = window.setInterval(() => {
+    left -= 1;
+    if (left <= 0) {
+      stopJoinCountdown();
+      joinQueueBtn.textContent = "Join now";
+      return;
+    }
+    paint();
+  }, 1000);
+}
+
+function stopJoinCountdown() {
+  if (joinCountdownTimer) {
+    clearInterval(joinCountdownTimer);
+    joinCountdownTimer = 0;
+  }
 }
 
 /**
@@ -1109,6 +1168,19 @@ async function doStart(audioContext = null) {
     onQueuePosition(position);
   });
 
+  c.addEventListener("ready-to-join", (e) => {
+    const { info, expiresSec } = /** @type {CustomEvent<{ info: import("./ws/s2s-ws-client.js").WsSessionInfo; expiresSec: number }>} */ (e).detail;
+    // A slot is held for us. We're out of the queue now, so drop the ticket ref.
+    // Track the granted session id already so that leaving (or letting the timer
+    // lapse) refunds the budget the server reserved at claim, even before we dial.
+    queuedTicketId = "";
+    if (info?.sessionId) {
+      trackedSessionId = info.sessionId;
+      trackedTier = info.tier || "anon";
+    }
+    startJoinCountdown(expiresSec);
+  });
+
   c.addEventListener("status", (e) => {
     const detail = /** @type {CustomEvent<{ status: string }>} */ (e).detail;
     onClientStatus(detail.status);
@@ -1260,6 +1332,9 @@ function onClientStatus(status) {
     case "queued":
       setState("queued");
       break;
+    case "your-turn":
+      setState("your-turn");
+      break;
     case "connected":
       setState("listening");
       break;
@@ -1283,6 +1358,7 @@ function onClientStatus(status) {
 
 async function teardown() {
   stopHeartbeat();
+  stopJoinCountdown();
   endTrackedSession();
   endQueueTicket();
   chat.reset({ dismiss: true });

style.css

@@ -847,10 +847,45 @@ a:hover {
   letter-spacing: 0.08em;
 }
 
-/* "Leave queue": a quiet outlined pill under the caption, shown only while
- * waiting. Understated to match the caption — it's an escape hatch, not a CTA. */
+/* Queue actions sit under the caption: "Join now" (primary, only when it's your
+ * turn) stacked above the quiet "Leave queue" escape hatch. */
+.queue-actions {
+  margin-top: 16px;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 10px;
+}
+.queue-actions[hidden] { display: none; }
+
+/* "Join now": the one call to action in the queue flow, so it reads as inviting
+ * (filled accent) while everything around it stays quiet. */
+.join-queue-btn {
+  padding: 10px 26px;
+  font-family: var(--font-mono);
+  font-size: 12px;
+  font-weight: 600;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+  color: #0b0b10;
+  background: var(--accent);
+  border: none;
+  border-radius: 999px;
+  cursor: pointer;
+  font-variant-numeric: tabular-nums;
+  transition: transform 0.12s ease, filter 0.2s ease;
+}
+.join-queue-btn:hover { filter: brightness(1.08); }
+.join-queue-btn:active { transform: scale(0.97); }
+.join-queue-btn:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 3px;
+}
+.join-queue-btn[hidden] { display: none; }
+
+/* "Leave queue": a quiet outlined pill, understated so it reads as an escape
+ * hatch, not a CTA. */
 .leave-queue-btn {
-  margin-top: 14px;
   padding: 7px 16px;
   font-family: var(--font-mono);
   font-size: 11px;
@@ -1125,6 +1160,10 @@ body.booting *::after {
 .circle.state-queued       { --glow: #94a3b8; }
 .circle.state-queued .ind-spinner { animation-duration: 2.4s; }
 .circle.state-queued .circle-ring { animation: breathe 2.6s ease-in-out infinite; }
+/* Your turn: a slot is held for you — the orb warms to the accent and breathes a
+ * little quicker, an invitation to join. */
+.circle.state-your-turn    { --glow: var(--accent); }
+.circle.state-your-turn .circle-ring { animation: breathe 1.6s ease-in-out infinite; }
 .circle.state-listening,
 .circle.state-user-speaking { --glow: var(--listening); }
 .circle.state-processing   { --glow: var(--processing); }

ui/account.js

@@ -175,4 +175,15 @@ export class Account {
     }
     if (!this._modal.open) this._modal.showModal();
   }
+
+  /** Show a warm "we're at capacity" message when even the waiting line is full.
+   *  Reuses the limit modal shell; no call-to-action, just reassurance. */
+  showBusy() {
+    this._modalTitle.textContent = "We're at capacity right now";
+    this._modalMsg.textContent =
+      "Lots of people are trying the demo, so every spot and the whole waiting line are full. Please give it a minute and try again. Thanks so much for your patience!";
+    this._modalNote.textContent = "A spot usually opens up within a few minutes.";
+    this._modalCta.hidden = true;
+    if (!this._modal.open) this._modal.showModal();
+  }
 }

ws/s2s-ws-client.js

@@ -23,8 +23,9 @@
  * sees high-level lifecycle events (`status`, `transcript`, `error`,
  * `session`), the same shape as the WebRTC client.
  *
- * @typedef {"idle" | "creating-session" | "queued" | "connecting" | "connected" |
- *           "user-speaking" | "processing" | "ai-speaking" | "closed" | "error"
+ * @typedef {"idle" | "creating-session" | "queued" | "your-turn" | "connecting" |
+ *           "connected" | "user-speaking" | "processing" | "ai-speaking" |
+ *           "closed" | "error"
  * } WsStatus
  *
  * @typedef {Object} WsSessionInfo
@@ -135,6 +136,15 @@ export class S2sWsRealtimeClient extends EventTarget {
     this._queueWake = null;
     /** @type {ReturnType<typeof setTimeout> | 0} */
     this._queueTimer = 0;
+    // Join gate: after waiting in line the caller must explicitly `join()` before
+    // we dial, so a slot isn't spent on someone who walked away. Resolved by
+    // join(), rejected on timeout (the LB reclaims the slot) or close().
+    /** @type {(() => void) | null} */
+    this._joinResolve = null;
+    /** @type {((err: Error) => void) | null} */
+    this._joinReject = null;
+    /** @type {ReturnType<typeof setTimeout> | 0} */
+    this._joinTimer = 0;
     /** @type {NoiseGate} Mic noise gate; off by default. */
     this._noiseGate = options.noiseGate ?? { enabled: false, thresholdDb: -45 };
     /** @type {WebSocket | null} */
@@ -237,10 +247,17 @@ export class S2sWsRealtimeClient extends EventTarget {
         throw new Error("No session endpoint or direct URL configured");
       }
       this._setStatus("creating-session");
-      const session = await this._createSessionOrQueue();
+      const { grant, waited } = await this._createSessionOrQueue();
       if (this._closed) throw _codedError("connect aborted", "aborted");
-      this.dispatchEvent(new CustomEvent("session", { detail: { info: session } }));
-      connectUrl = session.connectUrl;
+      // If we waited in line, don't dial until the user explicitly joins — this
+      // keeps a freed slot from being spent on someone who stepped away, and the
+      // click is a fresh gesture (re-arms the AudioContext on iOS).
+      if (waited) {
+        await this._awaitJoin(grant);
+        if (this._closed) throw _codedError("connect aborted", "aborted");
+      }
+      this.dispatchEvent(new CustomEvent("session", { detail: { info: grant } }));
+      connectUrl = grant.connectUrl;
       this._setStatus("connecting");
     }
 
@@ -259,16 +276,62 @@ export class S2sWsRealtimeClient extends EventTarget {
 
   /**
    * POST the session handshake; if the pool is busy, wait in the queue (polling
-   * position) until a slot is claimed. Resolves to a grant either way.
-   * @returns {Promise<WsSessionInfo>}
+   * position) until a slot is claimed. Resolves to a grant plus whether we had to
+   * wait (which decides if an explicit join is required before dialing).
+   * @returns {Promise<{ grant: WsSessionInfo, waited: boolean }>}
    */
   async _createSessionOrQueue() {
     const first = await this._postSession();
     if (first.state === "queued") {
       this._setStatus("queued");
-      return await this._pollQueue(first);
+      const grant = await this._pollQueue(first);
+      return { grant, waited: true };
+    }
+    return { grant: first.grant, waited: false };
+  }
+
+  /**
+   * Hold at the front of the line until the user clicks join (resolves the gate)
+   * or the grant lapses. Announces "your-turn" + a deadline the UI counts down.
+   * @param {WsSessionInfo} grant
+   * @returns {Promise<void>}
+   */
+  _awaitJoin(grant) {
+    // The LB reclaims an unclaimed slot at its pending timeout; expire the gate a
+    // touch earlier so we never dial a session the LB just reaped.
+    const windowS = Math.max(3, (grant.pendingTimeoutS || 60) - 3);
+    this._setStatus("your-turn");
+    this.dispatchEvent(
+      new CustomEvent("ready-to-join", { detail: { info: grant, expiresSec: windowS } }),
+    );
+    return new Promise((resolve, reject) => {
+      this._joinResolve = resolve;
+      this._joinReject = reject;
+      this._joinTimer = setTimeout(() => {
+        this._joinResolve = null;
+        this._joinReject = null;
+        reject(_codedError("Your spot expired", "join-expired"));
+      }, windowS * 1000);
+    });
+  }
+
+  /** Accept the held slot and let connect() proceed to dial. Called from the
+   *  "Join now" click, so it's a user gesture: re-resume the AudioContext, which
+   *  iOS may have suspended while we waited. */
+  join() {
+    if (this._joinTimer) {
+      clearTimeout(this._joinTimer);
+      this._joinTimer = 0;
     }
-    return first.grant;
+    try {
+      void this.options.audioContext?.resume();
+    } catch {
+      // best-effort; _setupAudio resumes again
+    }
+    const resolve = this._joinResolve;
+    this._joinResolve = null;
+    this._joinReject = null;
+    resolve?.();
   }
 
   /**
@@ -978,6 +1041,16 @@ export class S2sWsRealtimeClient extends EventTarget {
       this._queueWake = null;
       wake();
     }
+    if (this._joinTimer) {
+      clearTimeout(this._joinTimer);
+      this._joinTimer = 0;
+    }
+    if (this._joinReject) {
+      const reject = this._joinReject;
+      this._joinResolve = null;
+      this._joinReject = null;
+      reject(_codedError("join aborted", "aborted"));
+    }
     this._visualiser?.stop();
     this._visualiser = null;
     try {