feat(hint): persist the vs_ai idle-hint wait (wall-clock + read sanitiser)

Per the owner's call, the idle-hint gate now PERSISTS across leaving and reopening the
app, instead of the session-scoped monotonic clock: the unlock is a wall-clock instant
(hintUnlockAtMs) stamped from the robot's reply, stored on the local record, carried on
the game view + the opponent_moved move delta, and read through a sanitiser that caps it
at now + the window. So:
- the wait survives a relaunch (a stuck turn is not forgotten);
- a device clock set BACK cannot freeze the gate (the cap bounds the remaining to the
  window and self-heals on the next read);
- a clock set FORWARD just opens the hint early -- accepted as harmless for a solo game.

- lib/hints.ts hintGateRemainingMs now takes the unlock instant + clamps to the window.
- localgame: re-add hintUnlockAtMs to the record/meta; stamp it off the robot's reply;
  sanitise on read (a shared hintUnlock helper feeds stateView + the opponent_moved event).
- gamedelta + PushEvent: the move delta carries hintUnlockAtMs so the view stays fresh.
- Game.svelte: hintUnlockAt derives from the view; the tick + lock + toast unchanged.
- offline.spec.ts: also assert the lock survives a reload (the wait persisted).
- Docs FUNCTIONAL(+_ru)/ARCHITECTURE updated (persist + sanitiser, not monotonic-resets).

ui/src/game/Game.svelte

@@ -168,35 +168,19 @@
   // hint was spent in another game (see lib/hints).
   const hintCount = $derived(hintsLeft(view, app.profile?.hintBalance ?? 0));
   // A vs_ai game's hint is unlimited and wallet-free, but idle-gated (an anti-frustration aid: it
-  // unlocks only after the player has been stuck ~30 min on a turn). The wait is measured with a
-  // MONOTONIC clock (performance.now()), never a wall-clock timestamp — a device clock change (by the
-  // player or an auto-sync) must not open or freeze the gate. hintGateStart is that clock when the
-  // current turn's wait began (null = open: the human's first move, or the robot's turn); monoNow
-  // ticks so the 🔒 lifts live at the mark. A reload restarts the wait — the monotonic clock is
-  // session-scoped, and there is no tamper-proof way to carry idle time across a relaunch.
-  let hintGateStart = $state<number | null>(null);
-  let hintArmedFor = -1; // the moveCount the current wait was armed for (plain: not a reactive dep)
-  let monoNow = $state(performance.now());
-  const hintRemaining = $derived(view?.game.vsAi ? hintGateRemainingMs(hintGateStart, monoNow) : 0);
+  // unlocks only after the player has been stuck ~30 min on a turn). The unlock is a persisted
+  // wall-clock instant carried on the game view (`hintUnlockAtMs`, stamped by the source off the
+  // robot's reply and kept fresh by the move delta), so the wait survives leaving and reopening the
+  // app. It is sanitised on read (source + lib/hints cap it at now + the window) so a device clock
+  // set BACK cannot freeze the gate; a clock set forward just opens the hint early, harmless for a
+  // solo game. `now` ticks so the 🔒 lifts live at the mark. 0 = open (the human's first move).
+  let now = $state(Date.now());
+  const hintUnlockAt = $derived(view?.game.vsAi ? (view.hintUnlockAtMs ?? 0) : 0);
+  const hintRemaining = $derived(hintGateRemainingMs(hintUnlockAt, now));
   const hintGated = $derived(hintRemaining > 0);
-  // Arm the wait when it becomes the human's turn after the robot has moved; a human-first opening
-  // (no move yet, moveCount 0) is open at once. Re-arms only when the turn actually changes.
-  $effect(() => {
-    const mc = view?.game.moveCount ?? 0;
-    if (!view?.game.vsAi || !isMyTurn) {
-      hintGateStart = null;
-      hintArmedFor = -1;
-      return;
-    }
-    if (hintArmedFor !== mc) {
-      hintArmedFor = mc;
-      hintGateStart = mc === 0 ? null : performance.now();
-    }
-  });
-  // Tick the monotonic clock while a vs_ai game is open, so the gate re-evaluates and unlocks live.
   $effect(() => {
     if (!view?.game.vsAi) return;
-    const iv = setInterval(() => (monoNow = performance.now()), 10_000);
+    const iv = setInterval(() => (now = Date.now()), 10_000);
     return () => clearInterval(iv);
   });
   // RACK_SIZE mirrors the engine's rules.RackSize (7 for every current variant). The exchange
@@ -361,7 +345,7 @@
         // While composing, reload so a draft overlapping the new move is reconciled; otherwise apply
         // the move as a delta with no fetch.
         if (placement.pending.length > 0) void load();
-        else applyDelta(applyMoveDelta(cacheSnapshot(), { move: e.move, game: e.game, bagLen: e.bagLen }));
+        else applyDelta(applyMoveDelta(cacheSnapshot(), { move: e.move, game: e.game, bagLen: e.bagLen, hintUnlockAtMs: e.hintUnlockAtMs }));
       } else if (e.kind === 'your_turn' && e.gameId === id) {
         // The opponent_moved delta carries the new state; your_turn only confirms the turn. Refetch
         // only if we missed the move (our cached count trails the event's).
@@ -887,10 +871,9 @@
   }
   async function doHint() {
     // vs_ai: the idle gate replaces the wallet. While it is still closed, a tap only explains when the
-    // hint unlocks (no wallet is ever spent) — matching the 🔒 badge. Measured fresh off the monotonic
-    // clock at tap time.
+    // hint unlocks (no wallet is ever spent) — matching the 🔒 badge. Measured fresh at tap time.
     if (view?.game.vsAi) {
-      const remaining = hintGateRemainingMs(hintGateStart, performance.now());
+      const remaining = hintGateRemainingMs(hintUnlockAt, Date.now());
       if (remaining > 0) {
         showToast(t('game.hintLockedIn', { n: hintLockMinutes(remaining) }), 'info');
         return;

ui/src/lib/gamedelta.ts

@@ -11,6 +11,9 @@ export interface MoveDelta {
   move?: MoveRecord;
   game?: GameView;
   bagLen: number;
+  /** For a vs_ai game, the refreshed idle-hint unlock instant (the robot's reply re-arms the gate),
+   *  so the cached view stays current without a refetch; absent leaves the prior value. */
+  hintUnlockAtMs?: number;
 }
 
 /**
@@ -50,7 +53,12 @@ export function applyMoveDelta(cached: CachedGame | undefined, d: MoveDelta): De
   if (next > have + 1) return { refetch: true }; // a gap — an intermediate move was missed
   // The actor's own move changed their rack (a draw), which opponent_moved does not carry.
   if (d.move.player === cached.view.seat) return { refetch: true };
-  const view: StateView = { ...cached.view, game: d.game, bagLen: d.bagLen };
+  const view: StateView = {
+    ...cached.view,
+    game: d.game,
+    bagLen: d.bagLen,
+    hintUnlockAtMs: d.hintUnlockAtMs ?? cached.view.hintUnlockAtMs,
+  };
   return { cache: { view, moves: [...cached.moves, d.move] }, refetch: false };
 }
 
@@ -79,7 +87,7 @@ export function applyGameOver(cached: CachedGame | undefined, game: GameView | u
  */
 export function advanceCached(cached: CachedGame | undefined, e: PushEvent): CachedGame | undefined {
   if (e.kind === 'opponent_moved') {
-    return applyMoveDelta(cached, { move: e.move, game: e.game, bagLen: e.bagLen }).cache;
+    return applyMoveDelta(cached, { move: e.move, game: e.game, bagLen: e.bagLen, hintUnlockAtMs: e.hintUnlockAtMs }).cache;
   }
   if (e.kind === 'game_over') return applyGameOver(cached, e.game).cache;
   if (e.kind === 'opponent_joined' && e.state) return applyOpponentJoined(cached, e.state);

ui/src/lib/hints.test.ts

@@ -31,19 +31,25 @@ describe('hintsLeft', () => {
   });
 });
 
-describe('hintGateRemainingMs (the vs_ai idle-hint gate, monotonic)', () => {
-  it('is 0 when the gate is open — a null start (the human first move, or a non-gated game)', () => {
-    expect(hintGateRemainingMs(null, 5000, 1000)).toBe(0);
+describe('hintGateRemainingMs (the vs_ai idle-hint gate)', () => {
+  it('is 0 when the gate is open — no unlock time (the human first move, or a non-gated game)', () => {
+    expect(hintGateRemainingMs(undefined, 5000, 1000)).toBe(0);
+    expect(hintGateRemainingMs(0, 5000, 1000)).toBe(0);
   });
 
-  it('is 0 once the idle window has fully elapsed', () => {
-    expect(hintGateRemainingMs(0, 1000, 1000)).toBe(0);
-    expect(hintGateRemainingMs(0, 1500, 1000)).toBe(0);
+  it('is 0 once the unlock instant has passed (the gate is open)', () => {
+    expect(hintGateRemainingMs(1000, 1000, 1000)).toBe(0);
+    expect(hintGateRemainingMs(1000, 1500, 1000)).toBe(0);
   });
 
-  it('counts down the monotonic time remaining while still gated (only the delta matters)', () => {
-    expect(hintGateRemainingMs(0, 400, 1000)).toBe(600);
-    expect(hintGateRemainingMs(1000, 1400, 1000)).toBe(600);
+  it('is the wall-clock time remaining while still gated', () => {
+    expect(hintGateRemainingMs(1000, 400, 1000)).toBe(600);
+  });
+
+  it('clamps to the window, so a clock set back cannot freeze the gate above the window', () => {
+    // now shoved far into the past (device clock moved back): the raw remaining would exceed the
+    // window, but the cap keeps it at the window so the wait stays bounded and self-heals.
+    expect(hintGateRemainingMs(1000, -100_000, 1000)).toBe(1000);
   });
 });
 

ui/src/lib/hints.ts

@@ -30,19 +30,23 @@ export const HINT_GATE_MS = 30 * 60 * 1000;
 
 /**
  * hintGateRemainingMs returns how long (in milliseconds) until a vs_ai game's idle hint unlocks — 0
- * once it is available. It is measured from a MONOTONIC clock (performance.now()), never a wall-clock
- * timestamp, so a device clock change — by the user or an auto-sync — can neither open nor freeze the
- * gate. gateStartMono is the performance.now() captured when the current turn's wait began; null
- * means the gate is open (the human's first move, or not a gated game). The vs_ai hint is unlimited
- * and wallet-free; this idle gate is an anti-frustration aid that unlocks only after a stuck turn.
+ * once it is available. hintUnlockAtMs is the wall-clock instant the hint opens (the robot's last
+ * move plus the idle window), persisted so the wait survives leaving and reopening the app; 0 or
+ * undefined means the gate is open (the human's first move, or a non-gated game).
+ *
+ * The result is CLAMPED to the window. A wall-clock timestamp is the only way to carry idle time
+ * across an app relaunch, but a device clock the player changes (or an auto-sync) could push the
+ * unlock far into the future and freeze the gate; capping the remaining at the window means the wait
+ * is never longer than intended and self-heals (the caller re-reads a sanitised value on load). A
+ * clock moved forward simply opens the hint early — harmless for this solo anti-frustration aid.
  */
 export function hintGateRemainingMs(
-  gateStartMono: number | null,
-  monoNow: number,
+  hintUnlockAtMs: number | undefined,
+  nowMs: number,
   gateMs: number = HINT_GATE_MS,
 ): number {
-  if (gateStartMono === null) return 0;
-  return Math.max(0, gateMs - (monoNow - gateStartMono));
+  if (!hintUnlockAtMs) return 0;
+  return Math.min(gateMs, Math.max(0, hintUnlockAtMs - nowMs));
 }
 
 /** hintLockMinutes rounds a remaining-milliseconds gap up to whole minutes for the "available in N

ui/src/lib/localgame/serialize.test.ts

@@ -46,7 +46,7 @@ function makeGame(seed: bigint): LocalGame {
   return new LocalGame({ variant: 'scrabble_en', version: 'sample', seed, players: 2, dawg, multipleWords: true });
 }
 
-const meta = { id: 'g1', seats, createdAtUnix: 1, updatedAtUnix: 2 };
+const meta = { id: 'g1', seats, createdAtUnix: 1, updatedAtUnix: 2, hintUnlockAtMs: 0 };
 
 describe('local game serialize + replay', () => {
   it('reconstructs a mid-game position by replay', () => {

ui/src/lib/localgame/serialize.ts

@@ -38,6 +38,11 @@ export interface LocalGameRecord {
   status: 'active' | 'finished';
   createdAtUnix: number;
   updatedAtUnix: number;
+  /** Wall-clock ms at which the vs_ai idle hint unlocks (the robot's last move + the window), or 0
+   *  while open (no robot move yet). Persisted so the wait survives leaving and reopening the app;
+   *  read through a sanitiser (cap at now + window) so a device clock set back cannot freeze it —
+   *  see lib/hints. */
+  hintUnlockAtMs: number;
 }
 
 /** The record fields the caller owns (the engine supplies the rest). */
@@ -46,6 +51,7 @@ export interface RecordMeta {
   seats: Seat[];
   createdAtUnix: number;
   updatedAtUnix: number;
+  hintUnlockAtMs: number;
 }
 
 /**
@@ -67,6 +73,7 @@ export function serializeGame(game: LocalGame, meta: RecordMeta): LocalGameRecor
     status: game.isOver ? 'finished' : 'active',
     createdAtUnix: meta.createdAtUnix,
     updatedAtUnix: meta.updatedAtUnix,
+    hintUnlockAtMs: meta.hintUnlockAtMs,
   };
 }
 

ui/src/lib/localgame/source.ts

@@ -13,6 +13,7 @@ import { serializeGame, replayGame, type LocalGameRecord, type Seat as LocalSeat
 import { getLocalGame, saveLocalGame, listLocalGames, deleteLocalGame } from './store';
 import { RULESETS } from './ruleset';
 import { getDawg } from '../dict';
+import { HINT_GATE_MS } from '../hints';
 import { LOCAL_ID_PREFIX, isLocalGameId } from './id';
 import { decide } from '../robot/strategy';
 import { GatewayError, type PlacedTile } from '../client';
@@ -120,6 +121,7 @@ export class LocalSource implements GameLoopSource {
       seats: opts.seats.map((s) => ({ kind: s.kind, name: s.name, accountId: s.accountId })),
       createdAtUnix: now,
       updatedAtUnix: now,
+      hintUnlockAtMs: 0, // no robot move yet: a human-first opening's hint is open at once
     });
     const entry: Live = { game, record };
     this.live.set(opts.id, entry);
@@ -277,15 +279,20 @@ export class LocalSource implements GameLoopSource {
       else if (dec.kind === 'exchange' && g.bagLength >= RULESETS[entry.record.variant].rackSize) out.push(g.exchange(dec.exchange));
       else out.push(g.pass());
     }
+    // Arm the idle hint gate from the robot's reply: a wall-clock unlock time, persisted so the wait
+    // survives a relaunch. Read back through a sanitiser (lib/hints / stateView) so a clock set back
+    // cannot freeze it.
+    if (out.length > 0) entry.record.hintUnlockAtMs = Date.now() + HINT_GATE_MS;
     return out;
   }
 
   private emitRobot(entry: Live, moves: LocalMove[]): void {
     const set = this.listeners.get(entry.record.id);
     if (!set) return;
+    const hintUnlockAtMs = this.hintUnlock(entry);
     for (const m of moves) {
       const game = this.gameView(entry);
-      const ev: PushEvent = { kind: 'opponent_moved', gameId: entry.record.id, move: this.moveRecord(entry.record.variant, m), game, bagLen: entry.game.bagLength };
+      const ev: PushEvent = { kind: 'opponent_moved', gameId: entry.record.id, move: this.moveRecord(entry.record.variant, m), game, bagLen: entry.game.bagLength, hintUnlockAtMs };
       for (const cb of set) cb(ev);
     }
     if (entry.game.isOver) {
@@ -301,6 +308,7 @@ export class LocalSource implements GameLoopSource {
       seats: entry.record.seats,
       createdAtUnix: entry.record.createdAtUnix,
       updatedAtUnix: nowUnix(),
+      hintUnlockAtMs: entry.record.hintUnlockAtMs,
     });
     await saveLocalGame(entry.record);
   }
@@ -333,10 +341,25 @@ export class LocalSource implements GameLoopSource {
 
   // --- shape builders --------------------------------------------------------
 
+  // The vs_ai idle-hint unlock instant, sanitised on read: capped at now + the window so a device
+  // clock set back cannot push it far ahead and freeze the gate (the client counts down from here).
+  // 0 while open (a human-first opening, no robot move yet).
+  private hintUnlock(entry: Live): number {
+    return entry.record.hintUnlockAtMs ? Math.min(entry.record.hintUnlockAtMs, Date.now() + HINT_GATE_MS) : 0;
+  }
+
   private stateView(entry: Live): StateView {
     const seat = this.humanSeat(entry);
     const rack = entry.game.handOf(seat).map((t) => indexToLetter(entry.record.variant, t));
-    return { game: this.gameView(entry), seat, rack, bagLen: entry.game.bagLength, hintsRemaining: 1, walletBalance: 0 };
+    return {
+      game: this.gameView(entry),
+      seat,
+      rack,
+      bagLen: entry.game.bagLength,
+      hintsRemaining: 1,
+      walletBalance: 0,
+      hintUnlockAtMs: this.hintUnlock(entry),
+    };
   }
 
   private gameView(entry: Live): GameView {

ui/src/lib/model.ts

@@ -82,6 +82,10 @@ export interface StateView {
   bagLen: number;
   hintsRemaining: number;
   walletBalance: number;
+  /** For a vs_ai game, the wall-clock ms at which the idle hint unlocks — persisted so the wait
+   *  survives a relaunch, and sanitised on read so a device clock set back cannot freeze it — or
+   *  0/undefined while open (the human's first move, or a non-vs_ai game). See lib/hints. */
+  hintUnlockAtMs?: number;
 }
 
 export interface MoveResult {
@@ -421,7 +425,7 @@ export interface GameList {
  */
 export type PushEvent =
   | { kind: 'your_turn'; gameId: string; deadlineUnix: number; opponentName: string; moveCount: number }
-  | { kind: 'opponent_moved'; gameId: string; move?: MoveRecord; game?: GameView; bagLen: number }
+  | { kind: 'opponent_moved'; gameId: string; move?: MoveRecord; game?: GameView; bagLen: number; hintUnlockAtMs?: number }
   | { kind: 'game_over'; gameId: string; result: string; scoreLine: string; game?: GameView }
   | { kind: 'chat_message'; message: ChatMessage }
   | { kind: 'nudge'; gameId: string; fromUserId: string; senderName: string }