feat(hint): idle-gated wallet-free vs_ai hint on a monotonic clock (B4)
CI / changes (pull_request) Successful in 3s
CI / unit (pull_request) Has been skipped
CI / integration (pull_request) Has been skipped
CI / ui (pull_request) Successful in 1m11s
CI / conformance (pull_request) Successful in 11s
CI / gate (pull_request) Successful in 0s
CI / deploy (pull_request) Successful in 1m42s

A vs_ai hint is now unlimited and wallet-free, but idle-gated as an anti-frustration
aid: it unlocks only after the player has been stuck ~30 min on a turn (timed from the
robot's last move; the human's first move, before the robot has played, is exempt).
While gated the hint button carries a small lock badge and a tap shows the remaining
minutes ('Available in N min.'); the lock lifts live at the mark.

The gate is enforced CLIENT-SIDE against a MONOTONIC clock (performance.now()), never a
wall-clock timestamp: a device clock the player controls (or an auto-sync) must not be
able to open or freeze it. The wait is therefore session-scoped -- a reload restarts it
(there is no tamper-proof way to carry idle time across a relaunch without a wall clock).
An online vs_ai game will gate the same way but from the server's clock (a follow-up).

- lib/hints.ts: HINT_GATE_MS + pure hintGateRemainingMs (monotonic) + hintLockMinutes;
  removed the wall-clock hintRemainingMs. Unit-tested red->green.
- Game.svelte: the monotonic gate (hintGateStart/monoNow, armed on the turn change), a
  vs_ai hint button (plain: no confirm, no count; lock badge + gated tap -> toast), a
  live 10s tick.
- localgame: removed the wall-clock hint gate and the now-dead robotLastMoveAtUnix field
  from source.ts/serialize.ts (the client is authoritative); hint() just serves the top
  move.
- i18n game.hintLockedIn.
- offline.spec.ts: assert the first move is un-gated and the lock arms after the robot moves.
- Docs FUNCTIONAL(+_ru) + ARCHITECTURE; bundle budget 114->115 (game-screen feature).
This commit is contained in:
Ilia Denisov
2026-07-06 22:03:27 +02:00
parent 08792dad3d
commit 42a6308261
14 changed files with 176 additions and 36 deletions
+30 -1
View File
@@ -1,5 +1,5 @@
import { describe, expect, it } from 'vitest';
import { hintsLeft } from './hints';
import { hintsLeft, hintGateRemainingMs, hintLockMinutes } from './hints';
// view carries only the two fields hintsLeft reads.
const view = (hintsRemaining: number, walletBalance: number) => ({ hintsRemaining, walletBalance });
@@ -30,3 +30,32 @@ describe('hintsLeft', () => {
expect(hintsLeft(view(1, 0), -5)).toBe(1);
});
});
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);
});
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('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);
});
});
describe('hintLockMinutes (the toast N, rounded up)', () => {
it('rounds up to whole minutes, so a still-closed gate never reads 0', () => {
expect(hintLockMinutes(1)).toBe(1);
expect(hintLockMinutes(60_000)).toBe(1);
expect(hintLockMinutes(61_000)).toBe(2);
expect(hintLockMinutes(29 * 60_000)).toBe(29);
});
it('is 0 when nothing remains', () => {
expect(hintLockMinutes(0)).toBe(0);
});
});