@diffenderfer-games/hub 2.0.0-next.7 → 2.0.0-next.9

package/src/avatar/render/walker.ts

@@ -0,0 +1,199 @@
+/**
+ * The world walker (`figure: 'walker'`): a small full-body character for
+ * maps and crowds, with legs, arms, a shirt, trousers and shoes, and the
+ * head drawn smaller on top ({@link WALKER_HEAD_SCALE}). It takes the blob's
+ * pose names: `walk` and `run` swing the legs and arms along the facing,
+ * `sit` folds the legs over a seat, `idle` breathes, `wave` and `cheer` lift
+ * the arms.
+ *
+ * Standing, the origin is the feet. Sitting (`sit`, `play`), the origin is
+ * the seat: the hips rest on it and the feet hang {@link WALKER_SEAT_DROP}
+ * units below, on the floor in front of it.
+ */
+import { ellipse, type SceneNode } from '../scene';
+import type { BodyLayout } from './body';
+import type { Colours } from './colours';
+import type { BodyPose } from './types';
+import { hand, hips, limb, neck, outfitFor, shirt, shoe, type Outfit, type Vec } from './walker-parts';
+
+/** The head's scale on a walker (the blob draws it at 1). */
+export const WALKER_HEAD_SCALE = 0.58;
+
+/** How far below the seat a sitter's feet reach (rig units). */
+export const WALKER_SEAT_DROP = 26;
+
+/** Heights of the hips, shoulders and head centre above the origin. */
+interface Heights {
+  readonly hip: number;
+  readonly shoulder: number;
+  readonly head: number;
+}
+
+const STANDING: Heights = { hip: -35, shoulder: -72, head: -103 };
+const SEATED: Heights = { hip: -3, shoulder: -40, head: -71 };
+const LEG = 32;
+const UPPER_ARM = 13;
+const FOREARM = 12;
+const LEG_W = 10.5;
+const SLEEVE_W = 10;
+const ARM_W = 7.5;
+const DEG = Math.PI / 180;
+
+/** A walker's layout: the blob's fields plus where the head goes and its scale. */
+export interface WalkerLayout extends BodyLayout {
+  readonly headY: number;
+  readonly headScale: number;
+}
+
+/** One side of the body: −1 is the character's right, +1 its left. */
+type Side = -1 | 1;
+
+/** The view of a facing: how far it is turned, which way is forward on screen. */
+interface View {
+  /** sin of the turn: 0 front or back, ~1 side on. */
+  readonly side: number;
+  /** cos of the turn: 1 front, −1 back. */
+  readonly front: number;
+  /** Forward on the floor, in screen units per unit (y is foreshortened). */
+  readonly forward: Vec;
+  readonly isBack: boolean;
+  /** The torso's width factor. */
+  readonly width: number;
+}
+
+function viewOf(angleDeg: number): View {
+  const side = Math.sin(angleDeg * DEG);
+  const front = Math.cos(angleDeg * DEG);
+  return { side, front, forward: [side, front * 0.45], isBack: angleDeg > 90, width: 1 - 0.36 * Math.abs(side) };
+}
+
+/** A body side's screen x for a lateral distance (sides overlap when turned). */
+const lateralX = (v: View, sideOf: Side, distance: number): number => sideOf * distance * v.front;
+
+/** How near the viewer a side is (> 0: drawn in front when turned). */
+const nearness = (v: View, sideOf: Side): number => -sideOf * v.side;
+
+const add = (a: Vec, b: Vec, k = 1): Vec => [a[0] + b[0] * k, a[1] + b[1] * k];
+
+/** What each limb does in a pose. */
+interface Limbs {
+  /** Foot (standing) or knee-then-foot (sitting) per side. */
+  readonly leg: (sideOf: Side) => readonly [Vec, Vec, Vec];
+  readonly arm: (sideOf: Side) => readonly [Vec, Vec, Vec];
+}
+
+function standingLimbs(v: View, h: Heights, pose: BodyPose, phase: number, bob: number): Limbs {
+  const isRun = pose === 'run';
+  const isWalking = pose === 'walk' || isRun || pose === 'dance';
+  const stride = isRun ? 38 : 27;
+  const swingOf = (sideOf: Side): number => (isWalking ? Math.sin((phase + (sideOf === 1 ? 0 : 0.5)) * Math.PI * 2) : 0);
+  return {
+    leg: (sideOf) => {
+      const hip: Vec = [lateralX(v, sideOf, 6), h.hip + bob];
+      const swing = swingOf(sideOf);
+      const lift = isWalking ? Math.max(0, Math.cos((phase + (sideOf === 1 ? 0 : 0.5)) * Math.PI * 2)) * (isRun ? 7 : 4.5) : 0;
+      const reach = Math.sin(stride * DEG) * LEG * swing;
+      const foot: Vec = [hip[0] + v.forward[0] * reach, -bob * 0.2 + v.forward[1] * reach - lift];
+      const knee: Vec = [(hip[0] + foot[0]) / 2 + v.forward[0] * lift * 0.9, (hip[1] + foot[1]) / 2 + v.forward[1] * lift * 0.9];
+      return [hip, knee, foot];
+    },
+    arm: (sideOf) => {
+      const shoulder: Vec = [lateralX(v, sideOf, 15.5 * v.width) + v.forward[0] * 1.5, h.shoulder + 4 + bob];
+      const out = sideOf * v.front * 2.2;
+      if (pose === 'cheer' || (pose === 'wave' && sideOf === -1)) {
+        const wave = pose === 'wave' ? Math.sin(phase * Math.PI * 2) * 4 : 0;
+        const elbow: Vec = [shoulder[0] + out * 3, shoulder[1] - 10];
+        return [shoulder, elbow, [elbow[0] + out * 1.5 + wave, elbow[1] - 12]];
+      }
+      const swing = isWalking ? -swingOf(sideOf) * (isRun ? 1.3 : 1) : Math.sin(phase * Math.PI * 2) * 0.06;
+      const reach = Math.sin(24 * DEG) * swing;
+      const elbow: Vec = [shoulder[0] + out + v.forward[0] * UPPER_ARM * reach * 0.6, shoulder[1] + UPPER_ARM + v.forward[1] * UPPER_ARM * reach];
+      const wrist: Vec = [elbow[0] + out * 0.4 + v.forward[0] * FOREARM * reach * 1.6, elbow[1] + FOREARM - Math.abs(reach) * 3 + v.forward[1] * FOREARM * reach];
+      return [shoulder, elbow, wrist];
+    },
+  };
+}
+
+function seatedLimbs(v: View, h: Heights, pose: BodyPose): Limbs {
+  const thigh: Vec = [v.forward[0] * 15, v.forward[1] * 16];
+  return {
+    leg: (sideOf) => {
+      const hip: Vec = [lateralX(v, sideOf, 6), h.hip];
+      const knee = add(hip, thigh);
+      return [hip, knee, [knee[0] + v.forward[0] * 3, WALKER_SEAT_DROP - 2]];
+    },
+    arm: (sideOf) => {
+      const shoulder: Vec = [lateralX(v, sideOf, 15.5 * v.width) + v.forward[0] * 1.5, h.shoulder + 4];
+      const elbow: Vec = [shoulder[0] + sideOf * v.front * 2 + v.forward[0] * 3, shoulder[1] + UPPER_ARM];
+      const lap = add([lateralX(v, sideOf, pose === 'play' ? 4 : 7), h.hip - 4], thigh, pose === 'play' ? 0.9 : 0.6);
+      return [shoulder, elbow, lap];
+    },
+  };
+}
+
+/** The walker's drawing for a pose, at a facing angle (0 = S, 180 = N; west facings are mirrored by the caller). */
+export function walkerLayout(c: Colours, pose: BodyPose, angleDeg: number, phase: number, outfit: Outfit = outfitFor(c)): WalkerLayout {
+  const v = viewOf(angleDeg);
+  const isSitting = pose === 'sit' || pose === 'play';
+  const h = isSitting ? SEATED : STANDING;
+  const cycle = Math.sin(phase * Math.PI * 2);
+  const isWalking = pose === 'walk' || pose === 'run' || pose === 'dance';
+  const hop = pose === 'jump' || pose === 'cheer' ? Math.abs(Math.sin(phase * Math.PI)) * (pose === 'jump' ? 16 : 8) : 0;
+  const bob = isWalking ? -2.2 * (1 - Math.abs(cycle)) : pose === 'idle' ? cycle * 0.6 : 0;
+  const limbs = isSitting ? seatedLimbs(v, h, pose) : standingLimbs(v, h, pose, phase, bob);
+  const o = outfit;
+  const [farSide, nearSide]: readonly [Side, Side] = nearness(v, 1) > nearness(v, -1) ? [-1, 1] : [1, -1];
+  const isTurned = Math.abs(v.side) > 0.3;
+  const lean = v.side * (isSitting ? 0.6 : 1);
+  const armNodes = (sideOf: Side): SceneNode[] => {
+    const [shoulder, elbow, wrist] = limbs.arm(sideOf);
+    return [...limb([shoulder, elbow, wrist], ARM_W, c.skin, c.skinInk), ...limb([shoulder, add(shoulder, [elbow[0] - shoulder[0], elbow[1] - shoulder[1]], 0.62)], SLEEVE_W, c.body, c.bodyInk), hand(c, wrist)];
+  };
+  const legNodes = (sideOf: Side): SceneNode[] => {
+    const points = limbs.leg(sideOf);
+    const foot = points[2];
+    return [...limb(points, LEG_W, o.trousers, o.trousersInk), shoe(foot, v.forward, o)];
+  };
+  const torso = shirt(c, v.width, h.shoulder + (isWalking ? bob : 0), h.hip + 3 + (isWalking ? bob : 0), lean, v.isBack);
+  // Seated with our back to us, the arms reach forward and the legs are under the seat: both hide behind the back.
+  const isTucked = isSitting && v.isBack;
+  const behind: SceneNode[] = isTucked ? [...armNodes(farSide), ...armNodes(nearSide)] : isTurned ? armNodes(farSide) : [];
+  // Sitting facing us, the thighs come toward the viewer over the shirt's hem.
+  const isLegsFirst = v.isBack || !isSitting;
+  const legs = isTucked ? [] : [...legNodes(farSide), ...legNodes(nearSide)];
+  const body: SceneNode[] = [
+    ...(isLegsFirst ? legs : []),
+    hips(o, v.width, h.hip + (isWalking ? bob : 0)),
+    neck(c, h.shoulder + bob, v.forward[0] * 2),
+    ...torso,
+    ...(isLegsFirst ? [] : legs),
+    ...(isTucked ? [] : isTurned ? armNodes(nearSide) : [...armNodes(-1), ...armNodes(1)]),
+  ];
+  const prop = add([0, h.hip - 12], v.forward, 8);
+  return {
+    behind, body, front: [],
+    headDx: v.forward[0] * 1.5, headDy: 0, headY: h.head + bob * 1.1, headScale: WALKER_HEAD_SCALE,
+    tilt: isWalking ? v.side * 2 : 0, lift: hop, prop: { x: prop[0], y: prop[1] },
+  };
+}
+
+const GREY = '#6f7787';
+const GREY_INK = '#5c6474';
+
+/** Every colour slot in the silhouette grey. */
+const GREY_COLOURS: Colours = {
+  skin: GREY, skinShade: GREY, skinLight: GREY, skinInk: GREY_INK, eyeRim: GREY, hair: GREY, hairShade: GREY, hairLight: GREY,
+  hairInk: GREY_INK, hairBuzz: GREY, brow: GREY, beard: GREY, beardShade: GREY, beardInk: GREY_INK, stubble: GREY, eye: GREY,
+  eyeDark: GREY, body: GREY, bodyShade: GREY, bodyLight: GREY, bodyInk: GREY_INK,
+};
+
+/** The grey walker shown before the art loads (or for a hidden player): its nodes, head centre and top. */
+export function walkerSilhouette(): { readonly nodes: readonly SceneNode[]; readonly headY: number; readonly top: number } {
+  const b = walkerLayout(GREY_COLOURS, 'idle', 0, 0, { trousers: GREY, trousersInk: GREY_INK, shoes: GREY, shoesInk: GREY_INK });
+  const r = 46 * WALKER_HEAD_SCALE;
+  return {
+    nodes: [...b.behind, ...b.body, ellipse(0, b.headY, r, r * 1.05, { fill: GREY })],
+    headY: b.headY,
+    top: b.headY - r - 4,
+  };
+}

package/src/avatar.ts

@@ -43,12 +43,13 @@ export { overlays, type ActivityIcon, type Overlay, type ReactionGlyph } from '.
 export { overlaySvg, paintOverlay } from './avatar/outputs/overlay-svg';
 export { catalog } from './avatar/catalog-view';
 export { composeAvatar, HEAD_Y, type Composed } from './avatar/render/compose';
+export { WALKER_HEAD_SCALE, WALKER_SEAT_DROP } from './avatar/render/walker';
 export { paintNodes, type Ctx2D } from './avatar/outputs/canvas-paint';
 export { sceneToSvg } from './avatar/outputs/svg-markup';
 export { toCode, toLook } from './avatar/look-like';
 export { contrast, deltaE, lightness } from './avatar/colour';
 export type { SceneNode } from './avatar/scene';
-export type { Anchor, BodyPose, Facing, Frame, LookDir, LookLike, Point, Pose, RenderOptions, StatusProp, View } from './avatar/render/types';
+export type { Anchor, BodyPose, Facing, Figure, Frame, LookDir, LookLike, Point, Pose, RenderOptions, StatusProp, View } from './avatar/render/types';
 export { AvatarAtlas, createAtlas, type AtlasFrame, type AtlasOptions } from './avatar/atlas';
 
 /** Every output: SVG markup, a live element, Canvas 2D, a bitmap or a data URL. */

package/src/core/rest/routes.gen.ts

@@ -139,6 +139,7 @@ export const ROUTES = {
   getTurnGameHistory: { method: 'GET', path: '/turns/:id/history', query: ['since'], offline: null },
   listOpenTurnGames: { method: 'GET', path: '/open-turns', query: ['game'], offline: null },
   listMyTurnGames: { method: 'GET', path: '/turns', query: ['game'], offline: null },
+  getWorldMap: { method: 'GET', path: '/world/maps/:key', query: ['rev'], offline: null },
 } as const;
 
 /** The request header that carries an offline operation key (the contract's `OFFLINE_OP_HEADER`). */

package/src/core/turns/hub-turns.ts

@@ -17,7 +17,8 @@ import type { CreateTurnGame, OpenTurnGame, TurnDeadline } from '@diffenderfer-g
 import { toStoredJson, type GamePayload } from '../game-data';
 import { isBrowserPage } from '../page';
 import type { SavedEntry } from '../saved/saved-types';
-import { TurnGame, type TurnGameHost } from './turn-game';
+import { TurnGame, type TurnGameHost, type TurnGameOptions } from './turn-game';
+import { readYourTurnBuzz, saveYourTurnBuzz } from './your-turn-buzz';
 
 /** The query parameter an invite link carries (`/<slug>/?hub_turn_link=<key>`); the client strips it. */
 export const TURN_LINK_PARAM = 'hub_turn_link';
@@ -89,11 +90,31 @@ function isGameId(idOrKey: string): boolean {
 /** `hub.turns`. */
 export class HubTurns {
   private readonly host: TurnsHost;
+  private isBuzzOn = true;
+  private readonly gameOptions: TurnGameOptions = { isBuzzOn: () => this.isBuzzOn };
 
   constructor(host: TurnsHost) {
     this.host = host;
   }
 
+  /**
+   * This page's "your turn" buzz (a short vibration when the player becomes
+   * due in an open game, see `TurnGame.setYourTurnBuzz`): pass `false` if
+   * your game gives its own signal. On by default.
+   */
+  setYourTurnBuzz(isOn: boolean): void {
+    this.isBuzzOn = isOn;
+  }
+
+  /** The player's own "Buzz when it's my turn" switch on this device (the menu's Settings show it too). */
+  get playerYourTurnBuzz(): boolean {
+    return readYourTurnBuzz();
+  }
+
+  set playerYourTurnBuzz(isOn: boolean) {
+    saveYourTurnBuzz(isOn);
+  }
+
   /** The invite link key this page was opened with (`?hub_turn_link=`), taken out of the address bar; `null` when none. Synchronous. */
   get link(): string | null {
     return linkOnPage();
@@ -114,18 +135,18 @@ export class HubTurns {
       ...(options.deadline === undefined ? {} : { deadline: options.deadline }),
       ...(options.autoStart === undefined ? {} : { autoStart: options.autoStart }),
     };
-    return new TurnGame<View, Move, Event>(this.host, await this.host.create(body));
+    return new TurnGame<View, Move, Event>(this.host, await this.host.create(body), this.gameOptions);
   }
 
   /** Take a seat: by the game's id (an invite, an open seat) or by an invite link's key. */
   async join<View = GamePayload, Move extends GamePayload = GamePayload, Event = GamePayload>(idOrLinkKey: string): Promise<TurnGame<View, Move, Event>> {
     const joined = isGameId(idOrLinkKey) ? await this.host.join(idOrLinkKey) : await this.host.joinByLink(idOrLinkKey);
-    return new TurnGame<View, Move, Event>(this.host, joined);
+    return new TurnGame<View, Move, Event>(this.host, joined, this.gameOptions);
   }
 
   /** Open a game the player sits in (from `hub.saved.opened`, the Continue list, an invite). */
   async open<View = GamePayload, Move extends GamePayload = GamePayload, Event = GamePayload>(id: string): Promise<TurnGame<View, Move, Event>> {
-    return new TurnGame<View, Move, Event>(this.host, await this.host.get(id));
+    return new TurnGame<View, Move, Event>(this.host, await this.host.get(id), this.gameOptions);
   }
 
   /** This game's online games the player sits in (the same rows as `hub.saved.list({ kinds: ['turns'] })`). */

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

@@ -9,13 +9,18 @@
  * 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, 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 } from '@diffenderfer-games/hub-contract';
+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';
@@ -29,6 +34,12 @@ 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 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']>;
 
@@ -72,6 +83,12 @@ export interface TurnGameHost {
 
 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;
@@ -85,9 +102,15 @@ export class TurnGame<View = GamePayload, Move extends GamePayload = GamePayload
   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) {
+  constructor(host: TurnGameHost, initial: TurnGameView, options: TurnGameOptions = {}) {
     this.host = host;
+    this.options = options;
     this.id = initial.id;
     this.state = initial;
     host.opened(this);
@@ -129,25 +152,58 @@ export class TurnGame<View = GamePayload, Move extends GamePayload = GamePayload
     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. Rejects with a `HubError`: 403 `not_your_turn`, 409
-   * `stale` (the game moved on: the view is refreshed first), 422 `illegal`
-   * with the rules' own code in `rule`.
+   * 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));
-      this.update(answer.game);
+      // 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 {
@@ -179,7 +235,7 @@ export class TurnGame<View = GamePayload, Move extends GamePayload = GamePayload
 
   /** 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));
+    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`). */
@@ -192,7 +248,40 @@ export class TurnGame<View = GamePayload, Move extends GamePayload = GamePayload
     this.update(await this.host.invite(this.id, userIds));
   }
 
-  /** The turn's deadline passed (or its player is suspended): let the computer play it. */
+  /**
+   * 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));
   }
@@ -202,18 +291,26 @@ export class TurnGame<View = GamePayload, Move extends GamePayload = GamePayload
     return this.host.chat(this.id, send);
   }
 
-  /** Fetch the game again, and replay moves missed since the last one this page saw. */
+  /**
+   * 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 before = this.state.summary.seq;
     const fresh = await this.host.get(this.id);
-    if (fresh.summary.seq > before) {
-      const missed = await this.host.history(this.id, before);
+    const seen = this.state.summary.seq;
+    if (fresh.summary.seq <= seen) {
       this.update(fresh);
-      for (const move of missed) {
+      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)) });
       }
-    } else {
-      this.update(fresh);
     }
   }
 
@@ -238,12 +335,16 @@ export class TurnGame<View = GamePayload, Move extends GamePayload = GamePayload
     this.host.closed(this);
   }
 
-  /** Take a fresh answer from the hub; fire `turn` and `ended` when they changed. */
+  /** 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.chatMode !== next.chatMode || previous.link !== next.link;
+      || previous.summary.handOverAt !== next.summary.handOverAt || previous.chatMode !== next.chatMode || previous.link !== next.link;
     if (isChanged) {
       this.emit('turn', next.summary);
     }
@@ -259,8 +360,15 @@ export class TurnGame<View = GamePayload, Move extends GamePayload = GamePayload
     }
   }
 
+  /** Whether it is another player's move now (the page is waiting on someone). */
+  private isWaitingOnOthers(): boolean {
+    const { summary } = this.state;
+    return 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');
@@ -271,6 +379,10 @@ export class TurnGame<View = GamePayload, Move extends GamePayload = GamePayload
       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');
@@ -279,7 +391,11 @@ export class TurnGame<View = GamePayload, Move extends GamePayload = GamePayload
       // 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))) : [] });
     }
@@ -327,10 +443,16 @@ export class TurnGame<View = GamePayload, Move extends GamePayload = GamePayload
     window.addEventListener(TURN_RESYNC_EVENT, onResync);
     document.addEventListener('visibilitychange', onVisible);
     const poll = setInterval(() => {
-      if (!this.host.isLive() && document.visibilityState === 'visible') {
+      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 else's move.
+      if (this.host.isLive() ? this.isWaitingOnOthers() && quietMs >= TURN_QUIET_MS : quietMs >= TURN_POLL_MS) {
+        this.heardAt = Date.now();
         void this.catchUp();
       }
-    }, TURN_POLL_MS);
+    }, TURN_CHECK_MS);
     this.stopListening.push(
       () => { window.removeEventListener(TURN_EVENT, onTurn); },
       () => { window.removeEventListener(TURN_CHAT_EVENT, onChat); },
@@ -354,9 +476,9 @@ function sameSeating(a: TurnSummary, b: TurnSummary): boolean {
   return eachSeat(a, b, (seat, other) => seat.status === other.status && seat.userId === other.userId);
 }
 
-/** The same seating, and the same looks (a player's new avatar is a change: `turn` fires). */
+/** 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);
+  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. */

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;
+  }
+}

package/src/core/version/client-version.gen.ts

@@ -1,3 +1,3 @@
 // Generated by tools/hub-client/generate.ts. Do not edit; run `npm run gen:hub-client`.
 /** This client's package version, sent as `x-hub-client` on REST calls and `client` in `hello`. */
-export const HUB_CLIENT_VERSION = '2.0.0-next.7';
+export const HUB_CLIENT_VERSION = '2.0.0-next.9';