From 6216359c6f072dd4453a0c735fe6159fd09cabe7 Mon Sep 17 00:00:00 2001
From: Ilia Denisov <evilcart@gmail.com>
Date: Tue, 7 Jul 2026 11:28:17 +0200
Subject: [PATCH] feat(offline): hotseat creation roster + host-participate
 flow

NewGame offline 'with friends' now builds a local pass-and-play game:
- lib/roster.ts: keep-last-valid name + roster->seats (unit-tested).
- NewGame.svelte: master host-PIN gate (rows disabled until set),
  'are you playing too?' prompt seating the host at row 0, 2-4 player
  rows with inline name validation + optional per-seat PIN, add/remove
  (remove behind the master PIN), variant + multiple-words, Start.
- PinPad: verification via a verify(pin) callback (UI-held lock at
  creation, source-held in-game) instead of a lock prop.
- i18n: hotseat.* (en + ru); the offline mode selector is now shown offline.
---
 ui/src/components/PinPad.svelte |  25 +--
 ui/src/lib/i18n/en.ts           |  10 ++
 ui/src/lib/i18n/ru.ts           |  10 ++
 ui/src/lib/roster.test.ts       |  50 ++++++
 ui/src/lib/roster.ts            |  32 ++++
 ui/src/screens/NewGame.svelte   | 280 +++++++++++++++++++++++++++++++-
 6 files changed, 393 insertions(+), 14 deletions(-)
 create mode 100644 ui/src/lib/roster.test.ts
 create mode 100644 ui/src/lib/roster.ts

diff --git a/ui/src/components/PinPad.svelte b/ui/src/components/PinPad.svelte
index ff2f125..f903392 100644
--- a/ui/src/components/PinPad.svelte
+++ b/ui/src/components/PinPad.svelte
@@ -2,15 +2,17 @@
   // Apple-lock-screen-style 4-digit PIN pad for offline pass-and-play (hotseat) games.
   // Modes:
   //   set     — enter a PIN, then repeat it to confirm; emits { kind: 'set', lock }.
-  //   verify  — enter a PIN; auto-checks against `lock` on the 4th digit; emits
-  //             { kind: 'verified' } or shakes + clears on a wrong PIN.
-  //   change  — verify the current PIN (against `lock`), then offer "set a new PIN"
-  //             (the set flow) or, when allowRemove, "remove PIN" ({ kind: 'removed' }).
-  // The pad never shows an OK button: entering the 4th digit is the action. PIN storage
-  // is a social lock, not cryptography — see lib/pin.ts.
+  //   verify  — enter a PIN; runs `verify(pin)` on the 4th digit; emits { kind: 'verified' }
+  //             or shakes + clears on a wrong PIN.
+  //   change  — run `verify` on the current PIN, then offer "set a new PIN" (the set flow)
+  //             or, when allowRemove, "remove PIN" ({ kind: 'removed' }).
+  // Verification is delegated to the caller's `verify` callback: at creation time it checks a
+  // UI-held lock (lib/pin verifyPin); in-game it delegates to the local source (which holds the
+  // stored lock). The pad never shows an OK button: entering the 4th digit is the action. PIN
+  // storage is a social lock, not cryptography — see lib/pin.ts.
   import Modal from './Modal.svelte';
   import { t } from '../lib/i18n/index.svelte';
-  import { newLock, verifyPin, type PinLock } from '../lib/pin';
+  import { newLock, type PinLock } from '../lib/pin';
 
   /** PinResult is the outcome handed to onresult when the pad completes. */
   export type PinResult =
@@ -21,14 +23,15 @@
   let {
     mode,
     title = '',
-    lock,
+    verify,
     allowRemove = false,
     onclose,
     onresult,
   }: {
     mode: 'set' | 'verify' | 'change';
     title?: string;
-    lock?: PinLock;
+    /** Verifies an entered PIN (required for 'verify' and 'change'). */
+    verify?: (pin: string) => Promise<boolean>;
     allowRemove?: boolean;
     onclose?: () => void;
     onresult: (r: PinResult) => void;
@@ -70,13 +73,13 @@
     busy = true;
     try {
       if (phase === 'old') {
-        if (lock && (await verifyPin(buffer, lock))) {
+        if (verify && (await verify(buffer))) {
           buffer = '';
           error = false;
           phase = 'menu';
         } else fail();
       } else if (phase === 'enter' && mode === 'verify') {
-        if (lock && (await verifyPin(buffer, lock))) onresult({ kind: 'verified' });
+        if (verify && (await verify(buffer))) onresult({ kind: 'verified' });
         else fail();
       } else if (phase === 'enter') {
         first = buffer;
diff --git a/ui/src/lib/i18n/en.ts b/ui/src/lib/i18n/en.ts
index 7e4b2e5..f3bd967 100644
--- a/ui/src/lib/i18n/en.ts
+++ b/ui/src/lib/i18n/en.ts
@@ -398,6 +398,16 @@ export const en = {
   'pin.wrong': 'Wrong PIN',
   'pin.setNew': 'Set a new PIN',
   'pin.remove': 'Remove PIN',
+
+  'hotseat.hostPin': 'Host password',
+  'hotseat.setPin': 'Password',
+  'hotseat.changePin': 'Change',
+  'hotseat.playerName': 'Player name',
+  'hotseat.addPlayer': 'Add player',
+  'hotseat.removePlayer': 'Remove player',
+  'hotseat.hostPlaysTitle': 'Are you playing too?',
+  'hotseat.hostPlaysYes': 'Yes, I play',
+  'hotseat.hostPlaysNo': 'No',
 } as const;
 
 export type MessageKey = keyof typeof en;
diff --git a/ui/src/lib/i18n/ru.ts b/ui/src/lib/i18n/ru.ts
index e752d41..ea0310c 100644
--- a/ui/src/lib/i18n/ru.ts
+++ b/ui/src/lib/i18n/ru.ts
@@ -398,4 +398,14 @@ export const ru: Record<MessageKey, string> = {
   'pin.wrong': 'Неверный PIN',
   'pin.setNew': 'Задать новый PIN',
   'pin.remove': 'Удалить пароль',
+
+  'hotseat.hostPin': 'Пароль ведущего',
+  'hotseat.setPin': 'Пароль',
+  'hotseat.changePin': 'Изменить',
+  'hotseat.playerName': 'Имя игрока',
+  'hotseat.addPlayer': 'Добавить игрока',
+  'hotseat.removePlayer': 'Удалить игрока',
+  'hotseat.hostPlaysTitle': 'Принимаете участие в игре?',
+  'hotseat.hostPlaysYes': 'Да, играю',
+  'hotseat.hostPlaysNo': 'Нет',
 };
diff --git a/ui/src/lib/roster.test.ts b/ui/src/lib/roster.test.ts
new file mode 100644
index 0000000..8b7007d
--- /dev/null
+++ b/ui/src/lib/roster.test.ts
@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest';
+import { buildSeats, commitName, rosterReady, type RosterRow } from './roster';
+
+describe('commitName (keep-last-valid)', () => {
+  it('commits a valid, trimmed name', () => {
+    expect(commitName('Ann', '')).toBe('Ann');
+    expect(commitName('  Ann  ', '')).toBe('Ann');
+  });
+
+  it('keeps the previous valid name when the input goes invalid', () => {
+    expect(commitName('', 'Ann')).toBe('Ann');
+    expect(commitName('   ', 'Ann')).toBe('Ann');
+    expect(commitName('a'.repeat(33), 'Ann')).toBe('Ann'); // over the 32-rune cap
+    expect(commitName('_bad', 'Ann')).toBe('Ann'); // leading separator
+  });
+
+  it('replaces the committed name with a newer valid one', () => {
+    expect(commitName('Bob', 'Ann')).toBe('Bob');
+  });
+});
+
+describe('rosterReady', () => {
+  const row = (committed: string): RosterRow => ({ name: committed, committed });
+
+  it('needs 2-4 rows, each with a committed name', () => {
+    expect(rosterReady([row('A'), row('B')])).toBe(true);
+    expect(rosterReady([row('A'), row('B'), row('C'), row('D')])).toBe(true);
+  });
+
+  it('rejects fewer than 2, more than 4, or an empty row', () => {
+    expect(rosterReady([row('A')])).toBe(false);
+    expect(rosterReady([row('A'), row('B'), row('C'), row('D'), row('E')])).toBe(false);
+    expect(rosterReady([row('A'), row('')])).toBe(false);
+  });
+});
+
+describe('buildSeats', () => {
+  it('maps committed rows to account-less human seats, carrying the PIN', () => {
+    const lock = { hash: 'h', salt: 's' };
+    const seats = buildSeats([
+      { name: 'Ann', committed: 'Ann', pin: lock },
+      { name: 'x', committed: 'Bob' },
+    ]);
+    expect(seats).toEqual([
+      { kind: 'human', name: 'Ann', pin: lock },
+      { kind: 'human', name: 'Bob', pin: undefined },
+    ]);
+    expect(seats.every((s) => !('accountId' in s) || s.accountId === undefined)).toBe(true);
+  });
+});
diff --git a/ui/src/lib/roster.ts b/ui/src/lib/roster.ts
new file mode 100644
index 0000000..31768bd
--- /dev/null
+++ b/ui/src/lib/roster.ts
@@ -0,0 +1,32 @@
+// Pure helpers for the offline hotseat (pass-and-play) creation roster: keeping a last-valid name as
+// a row is edited, and turning the finished roster into engine seats. Kept out of the component so it
+// is unit-testable; the form itself is exercised by the e2e layer.
+
+import { validDisplayName } from './profileValidation';
+import type { PinLock } from './pin';
+import type { Seat } from './localgame/serialize';
+
+/** RosterRow is one editable player row: the live input, the last valid name kept when the input
+ *  goes invalid, and the optional per-seat PIN lock. */
+export interface RosterRow {
+  name: string;
+  committed: string;
+  pin?: PinLock;
+}
+
+/** commitName returns the new last-valid name: the trimmed input when it is a valid display name,
+ *  otherwise prevCommitted unchanged — so editing a set name into an invalid one keeps the old one. */
+export function commitName(input: string, prevCommitted: string): string {
+  return validDisplayName(input) ? input.trim() : prevCommitted;
+}
+
+/** rosterReady reports whether the roster can start a game: 2-4 rows, each with a committed name. */
+export function rosterReady(rows: RosterRow[]): boolean {
+  return rows.length >= 2 && rows.length <= 4 && rows.every((r) => r.committed !== '');
+}
+
+/** buildSeats turns committed roster rows into engine seats — all human, account-less (local
+ *  players sharing a device), carrying each row's optional PIN. */
+export function buildSeats(rows: RosterRow[]): Seat[] {
+  return rows.map((r): Seat => ({ kind: 'human', name: r.committed, pin: r.pin }));
+}
diff --git a/ui/src/screens/NewGame.svelte b/ui/src/screens/NewGame.svelte
index 751b244..7b5d502 100644
--- a/ui/src/screens/NewGame.svelte
+++ b/ui/src/screens/NewGame.svelte
@@ -1,6 +1,8 @@
 <script lang="ts">
   import { onMount } from 'svelte';
   import Screen from '../components/Screen.svelte';
+  import Modal from '../components/Modal.svelte';
+  import PinPad, { type PinResult } from '../components/PinPad.svelte';
   import { gateway } from '../lib/gateway';
   import { app, handleError, showToast } from '../lib/app.svelte';
   import { connection } from '../lib/connection.svelte';
@@ -9,6 +11,9 @@
   import { newLocalGameId, randomSeed } from '../lib/localgame/id';
   import { navigate } from '../lib/router.svelte';
   import { t, type MessageKey } from '../lib/i18n/index.svelte';
+  import { validDisplayName } from '../lib/profileValidation';
+  import { verifyPin, type PinLock } from '../lib/pin';
+  import { commitName, rosterReady, buildSeats, type RosterRow } from '../lib/roster';
   import type { AccountRef, Variant } from '../lib/model';
   import {
     availableVariants,
@@ -144,13 +149,112 @@
     }
   }
 
+  // --- offline hotseat (pass-and-play) ---
+  // A device-local 2-4 human game. The host (referee) sets a mandatory master PIN first — it gates
+  // the roster and, in-game, the host overrides; each player row optionally locks its seat with a PIN.
+  let hostPin = $state<PinLock | undefined>(undefined);
+  let rows = $state<RosterRow[]>([
+    { name: '', committed: '' },
+    { name: '', committed: '' },
+  ]);
+  let askHostPlays = $state(false); // the "do you take a seat?" prompt shown once the host PIN is set
+
+  // The PIN-pad overlay target: what a completed PIN applies to.
+  type PadTarget =
+    | { kind: 'host-set' }
+    | { kind: 'host-change' }
+    | { kind: 'seat-set'; index: number }
+    | { kind: 'seat-change'; index: number }
+    | { kind: 'row-delete'; index: number };
+  let pad = $state<PadTarget | null>(null);
+
+  const padMode = (p: PadTarget): 'set' | 'verify' | 'change' =>
+    p.kind === 'host-set' || p.kind === 'seat-set' ? 'set' : p.kind === 'row-delete' ? 'verify' : 'change';
+  function padVerify(p: PadTarget): ((pin: string) => Promise<boolean>) | undefined {
+    if (p.kind === 'host-change' || p.kind === 'row-delete') return (pin) => verifyPin(pin, hostPin!);
+    if (p.kind === 'seat-change') return (pin) => verifyPin(pin, rows[p.index].pin!);
+    return undefined; // set flows need no verifier
+  }
+  const padTitle = (p: PadTarget): string =>
+    p.kind === 'host-set' || p.kind === 'host-change' || p.kind === 'row-delete'
+      ? t('hotseat.hostPin')
+      : t('hotseat.setPin');
+
+  function onPad(r: PinResult): void {
+    const target = pad;
+    pad = null;
+    if (!target) return;
+    switch (target.kind) {
+      case 'host-set':
+        if (r.kind === 'set') {
+          hostPin = r.lock;
+          askHostPlays = true;
+        }
+        break;
+      case 'host-change':
+        if (r.kind === 'set') hostPin = r.lock; // the host PIN is mandatory — no remove option
+        break;
+      case 'seat-set':
+        if (r.kind === 'set') rows[target.index].pin = r.lock;
+        break;
+      case 'seat-change':
+        if (r.kind === 'set') rows[target.index].pin = r.lock;
+        else if (r.kind === 'removed') rows[target.index].pin = undefined;
+        break;
+      case 'row-delete':
+        if (r.kind === 'verified') rows = rows.filter((_, j) => j !== target.index);
+        break;
+    }
+  }
+
+  function setHostPlays(yes: boolean): void {
+    askHostPlays = false;
+    if (!yes) return;
+    // Seat the host at row 0, its name reused from the profile (a normal seat — its optional seat PIN
+    // is separate from the master PIN).
+    const committed = commitName(app.profile?.displayName ?? '', '');
+    rows[0] = { name: committed, committed };
+  }
+
+  function openSeatPin(i: number): void {
+    pad = rows[i].pin ? { kind: 'seat-change', index: i } : { kind: 'seat-set', index: i };
+  }
+
+  async function startHotseat(): Promise<void> {
+    if (starting || !hostPin || !inviteVariant || !rosterReady(rows)) return;
+    starting = true;
+    try {
+      const version = app.profile?.dictVersions?.[inviteVariant];
+      if (!version) {
+        handleError(new Error('dict_unavailable'));
+        return;
+      }
+      const id = newLocalGameId();
+      await localSource.create({
+        id,
+        variant: inviteVariant,
+        dictVersion: version,
+        seed: randomSeed(),
+        multipleWords: multipleWordsForRequest(inviteVariant, multipleWords),
+        seats: buildSeats(rows),
+        hotseat: true,
+        hostPin,
+      });
+      navigate(`/game/${id}`);
+    } catch (e) {
+      handleError(e);
+    } finally {
+      starting = false;
+    }
+  }
 </script>
 
 <Screen title={t('new.title')} back="/">
   <div class="page">
-      <!-- Offline mode offers only a local vs_ai game: the friends flow needs the network, so the
-           auto/friends selector is hidden and the auto (vs_ai) flow shows on its own. -->
-      {#if !guest && !offlineMode.active}
+      <!-- The auto/friends selector. Online it is hidden for guests (no friends to invite). Offline
+           it is always shown: "quick" is the local vs_ai flow, "with friends" is the local
+           pass-and-play (hotseat) flow. -->
+      {#if !guest || offlineMode.active}
         <div class="seg modes">
           <button class="opt" class:active={mode === 'auto'} onclick={() => (mode = 'auto')}>{t('new.auto')}</button>
           <button class="opt" class:active={mode === 'friends'} onclick={() => (mode = 'friends')}>{t('new.withFriends')}</button>
@@ -198,6 +302,68 @@
           disabled={!selectedAuto || (!connection.online && !offlineMode.active) || starting}
           onclick={() => selectedAuto && find(selectedAuto)}
         >{t('new.start')}</button>
+      {:else if offlineMode.active}
+        <!-- Offline pass-and-play (hotseat): a device-local 2-4 human game. The host sets a master
+             PIN first (it gates the roster); each seat may add its own PIN. -->
+        <div class="fg">
+          <div class="hostpin">
+            <span class="ftitle">{t('hotseat.hostPin')}</span>
+            <button class="plink" onclick={() => (pad = hostPin ? { kind: 'host-change' } : { kind: 'host-set' })}>
+              {hostPin ? t('hotseat.changePin') : t('hotseat.setPin')}
+            </button>
+          </div>
+          <label class="field">
+            <span>{t('new.gameType')}</span>
+            <select bind:value={inviteVariant} class:placeholder={!inviteVariant} disabled={variants.length === 1}>
+              <option value="" disabled>—</option>
+              {#each variants as v (v.id)}<option value={v.id}>{t(v.label)}</option>{/each}
+            </select>
+          </label>
+          {#if inviteVariant && supportsMultipleWordsToggle(inviteVariant)}
+            <label class="toggle">
+              <span>{t('new.multipleWordsPerTurn')}</span>
+              <input type="checkbox" bind:checked={multipleWords} />
+            </label>
+          {/if}
+          <div class="roster">
+            {#each rows as row, i (i)}
+              <div class="prow">
+                <input
+                  class="pname"
+                  class:invalid={row.name.trim() !== '' && !validDisplayName(row.name)}
+                  bind:value={row.name}
+                  disabled={!hostPin}
+                  placeholder={t('hotseat.playerName')}
+                  maxlength="40"
+                  oninput={() => (row.committed = commitName(row.name, row.committed))}
+                  onblur={() => (row.name = row.committed)}
+                />
+                <button class="plink" disabled={!hostPin || row.committed === ''} onclick={() => openSeatPin(i)}>
+                  {row.pin ? t('hotseat.changePin') : t('hotseat.setPin')}
+                </button>
+                {#if rows.length > 2}
+                  <button
+                    class="pkebab"
+                    disabled={!hostPin}
+                    aria-label={t('hotseat.removePlayer')}
+                    onclick={() => (pad = { kind: 'row-delete', index: i })}
+                  >⋮</button>
+                {/if}
+              </div>
+            {/each}
+          </div>
+          {#if rows.length < 4}
+            <button class="addrow" disabled={!hostPin} onclick={() => (rows = [...rows, { name: '', committed: '' }])}>
+              + {t('hotseat.addPlayer')}
+            </button>
+          {/if}
+          <div class="grow"></div>
+          <button
+            class="invite"
+            disabled={!hostPin || !inviteVariant || !rosterReady(rows) || starting}
+            onclick={startHotseat}
+          >{t('new.start')}</button>
+        </div>
       {:else if friends.length === 0}
         <p class="subtitle">{t('new.noFriends')}</p>
       {:else}
@@ -245,6 +411,25 @@
           <button class="invite" disabled={selected.length === 0 || !inviteVariant || !connection.online} onclick={sendInvite}>{t('new.invite')}</button>
         </div>
       {/if}
+
+      {#if pad}
+        <PinPad
+          mode={padMode(pad)}
+          title={padTitle(pad)}
+          verify={padVerify(pad)}
+          allowRemove={pad.kind === 'seat-change'}
+          onclose={() => (pad = null)}
+          onresult={onPad}
+        />
+      {/if}
+      {#if askHostPlays}
+        <Modal title={t('hotseat.hostPlaysTitle')} onclose={() => (askHostPlays = false)}>
+          <div class="hostplays">
+            <button class="ghost" onclick={() => setHostPlays(false)}>{t('hotseat.hostPlaysNo')}</button>
+            <button class="primary" onclick={() => setHostPlays(true)}>{t('hotseat.hostPlaysYes')}</button>
+          </div>
+        </Modal>
+      {/if}
   </div>
 </Screen>
 
@@ -450,4 +635,93 @@
     font-size: 0.85rem;
     line-height: 1.4;
   }
+  /* --- offline hotseat roster --- */
+  .hostpin {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 8px;
+    padding: 11px;
+    border: 1px solid var(--border);
+    background: var(--surface);
+    border-radius: var(--radius-sm);
+  }
+  .roster {
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+  }
+  .prow {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+  }
+  .pname {
+    flex: 1;
+    min-width: 0;
+    padding: 10px 11px;
+    border: 1px solid var(--border);
+    background: var(--surface);
+    color: var(--text);
+    border-radius: var(--radius-sm);
+  }
+  .pname:disabled {
+    opacity: 0.5;
+  }
+  .pname.invalid {
+    border-color: var(--danger);
+  }
+  .plink {
+    flex: 0 0 auto;
+    padding: 8px 10px;
+    border: none;
+    background: none;
+    color: var(--accent);
+    font-weight: 600;
+    white-space: nowrap;
+  }
+  .plink:disabled {
+    color: var(--text-muted);
+    opacity: 0.6;
+  }
+  .pkebab {
+    flex: 0 0 auto;
+    padding: 6px 8px;
+    border: none;
+    background: none;
+    color: var(--text-muted);
+    font-size: 1.1rem;
+    line-height: 1;
+  }
+  .addrow {
+    align-self: flex-start;
+    padding: 8px 12px;
+    border: 1px dashed var(--border);
+    background: none;
+    color: var(--accent);
+    border-radius: var(--radius-sm);
+    font-weight: 600;
+  }
+  .addrow:disabled {
+    opacity: 0.5;
+    color: var(--text-muted);
+  }
+  .hostplays {
+    display: flex;
+    gap: 10px;
+    justify-content: flex-end;
+  }
+  .hostplays button {
+    padding: 10px 16px;
+    border-radius: var(--radius-sm);
+    border: 1px solid var(--border);
+    background: var(--surface);
+    color: var(--text);
+    font-weight: 600;
+  }
+  .hostplays .primary {
+    background: var(--accent);
+    color: var(--accent-text);
+    border-color: var(--accent);
+  }
 </style>