@diffenderfer-games/hub 2.0.0-next.0 → 2.0.0-next.10

package/src/core/turns/turn-game.ts

@@ -0,0 +1,510 @@
+/**
+ * One online game, as a seated player's page holds it (`hub.turns.open`,
+ * `create`, `join`). The hub runs the game's rules: the page only ever has
+ * its own `view` and sends moves.
+ *
+ * Live changes arrive as the social runtime's `hub:turn` window events
+ * (from `/_ws`): `on('move')` for each move (with its events as this seat may
+ * see them, to animate), `on('turn')` whenever whose move it is or the seats
+ * change, `on('ended')` at the end, `on('chat')` for chat lines. Moves made
+ * while the page was away are replayed from `history` when it comes back
+ * (and, without the runtime, every so often while the page is visible).
+ * A safety net: while the page is visible and it is someone else's move (or
+ * a lobby), a page that has heard nothing for {@link TURN_QUIET_MS} fetches the game
+ * again (a lost live event never leaves it stuck), so games need no
+ * polling of their own.
+ */
+import type { Json, TurnChatLine, TurnGameView, TurnSeat, TurnSummary, TurnTournament } from '@diffenderfer-games/hub-contract';
+import { HubError } from '../errors';
+import { toGameData, type GamePayload } from '../game-data';
+import { isBrowserPage } from '../page';
+import { isJson, parseJsonText } from '../storage/json-guards';
+import { readField } from '../../realtime/cross-bundle';
+import { buzzYourTurn, isNewlyDue } from './your-turn-buzz';
+
+/** The window event the social runtime fires for each `ev:turn`. */
+export const TURN_EVENT = 'hub:turn';
+
+/** The runtime's live connection (re)opened: anything sent while it was down is fetched again. */
+export const TURN_RESYNC_EVENT = 'hub:turn-resync';
+
+/** The window event the social runtime fires for each `ev:turn.chat`. */
+export const TURN_CHAT_EVENT = 'hub:turn-chat';
+
+/** How often a page without the live runtime looks for moves, ms. */
+export const TURN_POLL_MS = 20_000;
+
+/** How long a visible page waiting on another player's move (or in a lobby) may hear nothing before it fetches the game again, ms. */
+export const TURN_QUIET_MS = 15_000;
+
+/** How often the page checks whether it should fetch, ms. */
+const TURN_CHECK_MS = 5_000;
+
+/** A game's end: the winning seats, and optionally places and scores by seat. */
+export type TurnOutcome = NonNullable<TurnGameView['outcome']>;
+
+/** One move as this seat saw it. */
+export interface TurnMoveEvent<View, Ev> {
+  readonly seq: number;
+  readonly seat: number;
+  /** The view after the move (for a replayed move, the view now). */
+  readonly view: View;
+  readonly events: readonly Ev[];
+}
+
+/** What a game's listeners hear. */
+export interface TurnGameEvents<View, Ev> {
+  move: TurnMoveEvent<View, Ev>;
+  turn: TurnSummary;
+  ended: { readonly outcome: TurnOutcome | null; readonly view: View };
+  chat: TurnChatLine;
+}
+
+/** What a game needs from its client: the REST calls, by name. */
+export interface TurnGameHost {
+  get(id: string): Promise<TurnGameView>;
+  start(id: string): Promise<TurnGameView>;
+  move(id: string, seq: number, move: Json): Promise<{ game: TurnGameView; events: Json[] }>;
+  history(id: string, since: number): Promise<{ seq: number; seat: number; events: Json[] }[]>;
+  leave(id: string): Promise<void>;
+  nudge(id: string): Promise<void>;
+  setNotify(id: string, mode: 'on' | 'off'): Promise<void>;
+  rematch(id: string): Promise<TurnGameView>;
+  invite(id: string, userIds: readonly number[]): Promise<TurnGameView>;
+  share(id: string, share: { readonly link?: boolean; readonly public?: boolean }): Promise<TurnGameView>;
+  autoPlay(id: string): Promise<TurnGameView>;
+  chat(id: string, send: { readonly text?: string; readonly quick?: string }): Promise<TurnChatLine>;
+  /** The page has a game open (saves of a run are off while it does). */
+  opened(game: object): void;
+  closed(game: object): void;
+  /** Whether the live runtime is on the page (else the game polls). */
+  isLive(): boolean;
+}
+
+type Listener<Payload> = (payload: Payload) => void;
+
+/** How `hub.turns` sets a game up. */
+export interface TurnGameOptions {
+  /** Whether this page wants the "your turn" buzz (`hub.turns.setYourTurnBuzz`); read at each buzz. Default on. */
+  readonly isBuzzOn?: () => boolean;
+}
+
+/** One online game. `View`, `Move` and `Ev` (its events) are the game's own JSON types from its rules. */
+export class TurnGame<View = GamePayload, Move extends GamePayload = GamePayload, Ev = GamePayload> {
+  readonly id: string;
+  private state: TurnGameView;
+  private readonly host: TurnGameHost;
+  private readonly listeners: { [K in keyof TurnGameEvents<View, Ev>]: Set<Listener<TurnGameEvents<View, Ev>[K]>> } = {
+    move: new Set(), turn: new Set(), ended: new Set(), chat: new Set(),
+  };
+  private readonly stopListening: (() => void)[] = [];
+  private isClosed = false;
+  private catchingUp: Promise<void> | null = null;
+  /** The move count this page's own move in flight will make (its live echo is not another player's move). */
+  private ownSeq: number | null = null;
+  /** When the page last heard from the hub about this game (a live event or an answer), epoch ms. */
+  private heardAt = Date.now();
+  private readonly options: TurnGameOptions;
+  /** This game's own "your turn" buzz switch (`setYourTurnBuzz`). */
+  private isBuzzOn = true;
+
+  constructor(host: TurnGameHost, initial: TurnGameView, options: TurnGameOptions = {}) {
+    this.host = host;
+    this.options = options;
+    this.id = initial.id;
+    this.state = initial;
+    host.opened(this);
+    this.listen();
+  }
+
+  /** Whose move it is, the seats and the deadline. */
+  get summary(): TurnSummary {
+    return this.state.summary;
+  }
+
+  /** This seat's view, from the game's rules (`null` before the game starts). */
+  get view(): View {
+    return toGameData<View>(this.state.view);
+  }
+
+  /** This player's seat, or `null` (they left). */
+  get mySeat(): number | null {
+    return this.state.mySeat;
+  }
+
+  /** The end, once the game is over. */
+  get outcome(): TurnOutcome | null {
+    return this.state.outcome;
+  }
+
+  /** The last chat lines, oldest first. */
+  get chat(): readonly TurnChatLine[] {
+    return this.state.chat;
+  }
+
+  /** `on`: friends may type (moderated); `quick`: quick-chat and emotes only; `off`. */
+  get chatMode(): TurnGameView['chatMode'] {
+    return this.state.chatMode;
+  }
+
+  /** The link others can take a seat with (the creator's, while seats are open), else `null`. */
+  get link(): string | null {
+    return this.state.link === null ? null : new URL(this.state.link, location.origin).href;
+  }
+
+  /** Whether this player may move now without it being their turn (the rules' `mayAct`: a jump-in, calling or catching "UNO"): offer that action. */
+  get mayActNow(): boolean {
+    const { mySeat } = this.state;
+    return mySeat !== null && this.state.summary.phase === 'playing' && (this.state.summary.mayAct ?? []).includes(mySeat);
+  }
+
+  /** The tournament match this game is, or `null` (show it if you like: "Saturday Cup: your match"). */
+  get tournament(): TurnTournament | null {
+    return this.state.tournament ?? null;
+  }
+
+  /**
+   * The "your turn" buzz for this game: a short vibration when this player
+   * becomes due on a live update while the page is visible (never for the
+   * next step of their own turn, a move out of turn, a game just opened or a
+   * catch-up; never when the player turned it off or asks for less motion;
+   * silently nothing where the device can't vibrate). On by default.
+   */
+  setYourTurnBuzz(isOn: boolean): void {
+    this.isBuzzOn = isOn;
+  }
+
+  /** Creator: start the game (empty seats go to the computer when the game allows). */
+  async start(): Promise<void> {
+    this.update(await this.host.start(this.id));
+  }
+
+  /**
+   * Make a move: when it is your turn (`summary.isMyTurn`), or out of turn
+   * when the rules allow it (`mayActNow`). Rejects with a `HubError`: 403
+   * `not_your_turn`, 409 `stale` (the game moved on, or another player's
+   * move got there first: the view is refreshed first), 422 `illegal` with
+   * the rules' own code in `rule`, 500 `rules_error` or 503 `rules_busy`
+   * (the move was not made; the game is fetched again). The answer's `view` is the newest this
+   * page has: moves that arrived live while the answer was on its way (the
+   * computer's, another player's) are never rolled back.
+   */
+  async move(move: Move): Promise<{ seq: number; view: View; events: Ev[] }> {
+    this.ownSeq = this.state.summary.seq + 1;
+    try {
+      const answer = await this.host.move(this.id, this.state.summary.seq, toPayload(move));
+      // A late answer: live events already brought a newer state, which stays.
+      if (answer.game.summary.seq >= this.state.summary.seq) {
+        this.update(answer.game);
+      }
+      return { seq: answer.game.summary.seq, view: this.view, events: answer.events.map((event) => toGameData<Ev>(event)) };
+    } catch (failure) {
+      if (failure instanceof HubError && failure.code === 'stale') {
+        await this.refresh();
+      } else if (failure instanceof HubError && (failure.code === 'rules_error' || failure.code === 'rules_busy')) {
+        // The move was not made (the hub writes nothing when its rules fail), but the page may be behind: fetch the truth.
+        await this.catchUp();
+      }
+      throw failure;
+    } finally {
+      this.ownSeq = null;
+    }
+  }
+
+  /** The moves after `sinceSeq`, with their events as this seat may see them ("what happened while you were away"). */
+  async history(sinceSeq: number): Promise<{ seq: number; seat: number; events: Ev[] }[]> {
+    const moves = await this.host.history(this.id, sinceSeq);
+    return moves.map((move) => ({ seq: move.seq, seat: move.seat, events: move.events.map((event) => toGameData<Ev>(event)) }));
+  }
+
+  /** Leave: the computer plays the seat (or, without bots, the others win). The player can't come back. */
+  async leave(): Promise<void> {
+    await this.host.leave(this.id);
+    this.close();
+  }
+
+  /** Remind whoever must move (once a day). */
+  nudge(): Promise<void> {
+    return this.host.nudge(this.id);
+  }
+
+  /** This game's "your turn" alerts. */
+  setNotify(mode: 'on' | 'off'): Promise<void> {
+    return this.host.setNotify(this.id, mode);
+  }
+
+  /** A finished game: a new one with the same friends (they get an invite). */
+  async rematch(): Promise<TurnGame<View, Move, Ev>> {
+    return new TurnGame<View, Move, Ev>(this.host, await this.host.rematch(this.id), this.options);
+  }
+
+  /** Creator, before the start: add an invite link (`link: true`, then read `link`) or list the open seats for anyone (`public`). */
+  async share(share: { readonly link?: boolean; readonly public?: boolean }): Promise<void> {
+    this.update(await this.host.share(this.id, share));
+  }
+
+  /** Invite friends to free seats (before the start). */
+  async invite(userIds: readonly number[]): Promise<void> {
+    this.update(await this.host.invite(this.id, userIds));
+  }
+
+  /**
+   * Whether "Let the computer play for <name>" may work now: another
+   * player is due, the hub's hand-over wait (`summary.handOverAt`) has
+   * passed and a due player isn't connected (`TurnSeat.connected` false
+   * or unknown), or the turn's `deadline` passed. `false` in a
+   * tournament match, and from a hub too old to say. Re-check it on each
+   * `turn` event (a player coming or going fires one) and when
+   * `handOverAt` comes.
+   */
+  canLetComputerPlay(now: number = Date.now()): boolean {
+    const { summary, mySeat } = this.state;
+    if (summary.phase !== 'playing' || mySeat === null || this.state.tournament !== undefined) {
+      return false;
+    }
+    const due = summary.seats.filter((seat) => summary.toAct.includes(seat.seat) && seat.seat !== mySeat && seat.status === 'joined');
+    if (due.length === 0) {
+      return false;
+    }
+    if (summary.deadline !== null && summary.deadline <= now) {
+      return true;
+    }
+    const { handOverAt } = summary;
+    return handOverAt !== undefined && handOverAt !== null && handOverAt <= now && due.some((seat) => seat.connected !== true);
+  }
+
+  /**
+   * Let the computer play for whoever is due: a turn whose deadline passed
+   * (or whose player is suspended) is played once; otherwise, when that
+   * player has been due a while (2 minutes) and isn't connected at all, the
+   * computer plays their seat for the rest of the game (it shows as `bot`,
+   * named with who chose it) until they open the game again. Rejects with
+   * 409 `deadline_not_passed` when neither (it never says whether they are
+   * online), and 409 `not_supported` in a tournament match.
+   */
+  async letComputerPlay(): Promise<void> {
+    this.update(await this.host.autoPlay(this.id));
+  }
+
+  /** Say something: `{ text }` between friends (moderated), `{ quick }` (a quick-chat phrase id) with anyone. */
+  say(send: { readonly text?: string; readonly quick?: string }): Promise<TurnChatLine> {
+    return this.host.chat(this.id, send);
+  }
+
+  /**
+   * Fetch the game again, and replay moves missed since the last one this
+   * page saw. An answer older than what the page has by then (live moves
+   * arrived while it was on its way) is dropped, never rolled back to, and
+   * a move that arrived live is never replayed twice.
+   */
+  async refresh(): Promise<void> {
+    const fresh = await this.host.get(this.id);
+    const seen = this.state.summary.seq;
+    if (fresh.summary.seq <= seen) {
+      this.update(fresh);
+      return;
+    }
+    const missed = await this.host.history(this.id, seen);
+    const since = this.state.summary.seq;
+    this.update(fresh);
+    for (const move of missed) {
+      if (move.seq > since && move.seq <= fresh.summary.seq) {
+        this.emit('move', { seq: move.seq, seat: move.seat, view: this.view, events: move.events.map((event) => toGameData<Ev>(event)) });
+      }
+    }
+  }
+
+  /** Hear moves, turn changes, the end and chat; returns a function that stops listening. */
+  on<K extends keyof TurnGameEvents<View, Ev>>(eventName: K, listener: Listener<TurnGameEvents<View, Ev>[K]>): () => void {
+    const set: Set<Listener<TurnGameEvents<View, Ev>[K]>> = this.listeners[eventName];
+    set.add(listener);
+    return () => {
+      set.delete(listener);
+    };
+  }
+
+  /** Stop live updates for this page (the game itself goes on). */
+  close(): void {
+    if (this.isClosed) {
+      return;
+    }
+    this.isClosed = true;
+    for (const stop of this.stopListening) {
+      stop();
+    }
+    this.host.closed(this);
+  }
+
+  /** Take a fresh answer from the hub (one older than what the page has is dropped: no rollback); fire `turn` and `ended` when they changed. */
+  private update(next: TurnGameView): void {
+    this.heardAt = Date.now();
+    const previous = this.state;
+    if (next.summary.seq < previous.summary.seq) {
+      return;
+    }
+    this.state = next;
+    const isChanged = previous.summary.seq !== next.summary.seq || previous.summary.phase !== next.summary.phase || !sameSeats(previous.summary, next.summary)
+      || previous.summary.handOverAt !== next.summary.handOverAt || previous.chatMode !== next.chatMode || previous.link !== next.link;
+    if (isChanged) {
+      this.emit('turn', next.summary);
+    }
+    if (previous.summary.phase !== 'ended' && next.summary.phase === 'ended') {
+      this.emit('ended', { outcome: next.outcome, view: this.view });
+    }
+  }
+
+  private emit<K extends keyof TurnGameEvents<View, Ev>>(eventName: K, payload: TurnGameEvents<View, Ev>[K]): void {
+    const set: Set<Listener<TurnGameEvents<View, Ev>[K]>> = this.listeners[eventName];
+    for (const listener of set) {
+      listener(payload);
+    }
+  }
+
+  /** Whether the page is waiting on someone: another player's move, or a lobby. */
+  private isWaitingOnOthers(): boolean {
+    const { summary } = this.state;
+    return summary.phase === 'lobby' || (summary.phase === 'playing' && !summary.isMyTurn);
+  }
+
+  /** A live `hub:turn` for this game: a move (or a missed run of them), or another change. */
+  private onLive(detail: object): void {
+    this.heardAt = Date.now();
+    const seq = readField(detail, 'seq');
+    const view = readField(detail, 'view');
+    const summary = readField(detail, 'summary');
+    if (typeof seq !== 'number' || !isSummary(summary) || view === undefined) {
+      return;
+    }
+    if (seq > this.state.summary.seq + 1) {
+      void this.catchUp();
+      return;
+    }
+    if (seq < this.state.summary.seq) {
+      // Older than what the page has (a late event): nothing to roll back to.
+      return;
+    }
+    const seat = readField(detail, 'seat');
+    const events = readField(detail, 'events');
+    const outcome = readField(detail, 'outcome');
+    const isMove = typeof seat === 'number' && seq === this.state.summary.seq + 1 && seq !== this.ownSeq;
+    if (summary.phase !== this.state.summary.phase || !sameSeating(this.state.summary, summary)) {
+      // Who sits where changed (a join, the start, a leave): the chat mode and link may have too, and the live event doesn't carry them.
+      void this.catchUp();
+    }
+    const before = this.state.summary;
+    this.update({ ...this.state, summary, view: toPayloadJson(view), outcome: isOutcome(outcome) ? outcome : this.state.outcome });
+    if (this.isBuzzOn && (this.options.isBuzzOn?.() ?? true) && isNewlyDue(before, this.state.summary)) {
+      buzzYourTurn();
+    }
+    if (isMove) {
+      this.emit('move', { seq, seat, view: this.view, events: Array.isArray(events) ? events.map((event) => toGameData<Ev>(toPayloadJson(event))) : [] });
+    }
+  }
+
+  /** Replay what was missed (one catch-up at a time). */
+  private catchUp(): Promise<void> {
+    this.catchingUp ??= this.refresh().catch(() => undefined).finally(() => {
+      this.catchingUp = null;
+    });
+    return this.catchingUp;
+  }
+
+  private listen(): void {
+    if (!isBrowserPage()) {
+      return;
+    }
+    const onTurn = (event: Event): void => {
+      if (!(event instanceof CustomEvent) || readField(event.detail, 'id') !== this.id) {
+        return;
+      }
+      // eslint-disable-next-line no-restricted-syntax -- trust boundary: another bundle's event detail, read field by field
+      const detail: unknown = event.detail;
+      if (typeof detail === 'object' && detail !== null) {
+        this.onLive(detail);
+      }
+    };
+    const onChat = (event: Event): void => {
+      if (event instanceof CustomEvent && readField(event.detail, 'id') === this.id) {
+        const line = readField(event.detail, 'line');
+        if (isChatLine(line)) {
+          this.state = { ...this.state, chat: [...this.state.chat, line].slice(-50) };
+          this.emit('chat', line);
+        }
+      }
+    };
+    const onVisible = (): void => {
+      if (document.visibilityState === 'visible') {
+        void this.catchUp();
+      }
+    };
+    const onResync = (): void => { void this.catchUp(); };
+    window.addEventListener(TURN_EVENT, onTurn);
+    window.addEventListener(TURN_CHAT_EVENT, onChat);
+    window.addEventListener(TURN_RESYNC_EVENT, onResync);
+    document.addEventListener('visibilitychange', onVisible);
+    const poll = setInterval(() => {
+      if (document.visibilityState !== 'visible' || this.catchingUp !== null) {
+        return;
+      }
+      const quietMs = Date.now() - this.heardAt;
+      // Without the live runtime: poll. With it: the safety net, while waiting on someone.
+      if (this.host.isLive() ? this.isWaitingOnOthers() && quietMs >= TURN_QUIET_MS : quietMs >= TURN_POLL_MS) {
+        this.heardAt = Date.now();
+        void this.catchUp();
+      }
+    }, TURN_CHECK_MS);
+    this.stopListening.push(
+      () => { window.removeEventListener(TURN_EVENT, onTurn); },
+      () => { window.removeEventListener(TURN_CHAT_EVENT, onChat); },
+      () => { window.removeEventListener(TURN_RESYNC_EVENT, onResync); },
+      () => { document.removeEventListener('visibilitychange', onVisible); },
+      () => { clearInterval(poll); },
+    );
+  }
+}
+
+/** Every seat matches its counterpart by `same`. */
+function eachSeat(a: TurnSummary, b: TurnSummary, same: (seat: TurnSeat, other: TurnSeat) => boolean): boolean {
+  return a.seats.length === b.seats.length && a.seats.every((seat, index) => {
+    const other = b.seats[index];
+    return other !== undefined && same(seat, other);
+  });
+}
+
+/** The same players in the same seats with the same statuses (who sits where). */
+function sameSeating(a: TurnSummary, b: TurnSummary): boolean {
+  return eachSeat(a, b, (seat, other) => seat.status === other.status && seat.userId === other.userId);
+}
+
+/** The same seating, looks and who is connected (a player's new avatar, or a player coming or going, is a change: `turn` fires). */
+function sameSeats(a: TurnSummary, b: TurnSummary): boolean {
+  return sameSeating(a, b) && eachSeat(a, b, (seat, other) => seat.look === other.look && seat.connected === other.connected);
+}
+
+/** A game's move as the JSON the hub takes. */
+function toPayload(move: GamePayload): Json {
+  return toPayloadJson(move);
+}
+
+/** Any JSON-safe value as `Json` (a JSON round trip). */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: a game's own move, or a value from another bundle's event
+function toPayloadJson(value: unknown): Json {
+  const parsed = parseJsonText(JSON.stringify(value ?? null));
+  return isJson(parsed) ? parsed : null;
+}
+
+/** Shape checks for a live event's parts (it comes from another bundle). */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: another bundle's event detail
+function isSummary(value: unknown): value is TurnSummary {
+  return typeof readField(value, 'phase') === 'string' && Array.isArray(readField(value, 'seats')) && Array.isArray(readField(value, 'toAct'));
+}
+
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: another bundle's event detail
+function isOutcome(value: unknown): value is TurnOutcome | null {
+  return value === null || Array.isArray(readField(value, 'winners'));
+}
+
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: another bundle's event detail
+function isChatLine(value: unknown): value is TurnChatLine {
+  return typeof readField(value, 'text') === 'string' && typeof readField(value, 'from') === 'number';
+}

package/src/core/turns/your-turn-buzz.ts

@@ -0,0 +1,69 @@
+/**
+ * "Your turn" buzz: a short vibration when this player becomes due in an
+ * online game whose page they have open and visible (a phone held while
+ * waiting). Every online game gets it from `TurnGame`, with no game code.
+ *
+ * It buzzes only when the player **becomes** due on a live update: not for
+ * the next step of their own turn, not for a move they may make out of turn
+ * (`mayAct`), not for a game they just opened or a catch-up after being
+ * away, and not in a game they muted. It stays quiet when the player turned
+ * it off (the menu's Settings, stored on this device), when the page asks
+ * for less motion (the hub's `data-hub-motion="reduce"` or the system's
+ * reduced motion), and where `navigator.vibrate` doesn't exist (iOS Safari).
+ * A page can turn it off for itself (`hub.turns.setYourTurnBuzz(false)`) or
+ * for one game (`TurnGame.setYourTurnBuzz(false)`).
+ */
+import type { TurnSummary } from '@diffenderfer-games/hub-contract';
+
+/** The pattern: two short pulses, ms. */
+export const YOUR_TURN_BUZZ: readonly number[] = [60, 40, 60];
+
+/** Where this device keeps the player's choice (`off` turns it off). */
+export const YOUR_TURN_BUZZ_KEY = 'dg:your-turn-buzz';
+
+/** Whether going from `previous` to `next` makes this player newly due (the moment to buzz). */
+export function isNewlyDue(previous: Pick<TurnSummary, 'phase' | 'isMyTurn'>, next: Pick<TurnSummary, 'phase' | 'isMyTurn' | 'isMuted'>): boolean {
+  const wasDue = previous.phase === 'playing' && previous.isMyTurn;
+  return next.phase === 'playing' && next.isMyTurn && !wasDue && !next.isMuted;
+}
+
+/** The player's own switch on this device (on unless they turned it off). */
+export function readYourTurnBuzz(): boolean {
+  try {
+    return localStorage.getItem(YOUR_TURN_BUZZ_KEY) !== 'off';
+  } catch {
+    return true;
+  }
+}
+
+/** Save the player's switch on this device. */
+export function saveYourTurnBuzz(isOn: boolean): void {
+  try {
+    localStorage.setItem(YOUR_TURN_BUZZ_KEY, isOn ? 'on' : 'off');
+  } catch {
+    // No storage: it stays on.
+  }
+}
+
+/** Whether the page asks for less motion (the hub's setting, else the system's). */
+function prefersLessMotion(): boolean {
+  if (typeof document !== 'undefined' && document.documentElement.dataset.hubMotion === 'reduce') {
+    return true;
+  }
+  return typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+
+/** Buzz now, when this page is visible and nothing says not to; fails silently. Answers whether it buzzed. */
+export function buzzYourTurn(): boolean {
+  if (typeof document === 'undefined' || document.visibilityState !== 'visible' || !readYourTurnBuzz() || prefersLessMotion()) {
+    return false;
+  }
+  if (typeof navigator === 'undefined' || typeof navigator.vibrate !== 'function') {
+    return false;
+  }
+  try {
+    return navigator.vibrate([...YOUR_TURN_BUZZ]);
+  } catch {
+    return false;
+  }
+}