Reliable figure autocomplete under Wikipedia throttling

What changed, and why

The "Who in history will you reach?" autocomplete often showed nothing — even for an easy prefix like "Leonardo" — and the dropdown just never opened, with no error. It looked like "no matches" when the real cause was a transient Wikipedia outage (issue #58).

The dominant cause is Wikipedia rate-limiting. On board load three callers hit one egress IP: this autocomplete (per keystroke), the figure grounding (350ms debounce), and the era suggester (on mount). The autocomplete is the most frequent caller, so it starves first. Two things make that worse: a User-Agent with no contact draws harder throttling (Wikimedia's UA policy), and the client did a single retry then silently gave up.

The fix has two halves. On the server, one shared, policy-compliant User-Agent with a reachable contact, sent by all three callers. On the client, spaced backoff retries and — when the record truly can't be reached — a visible, retryable hint instead of an empty box. The rest of this guide walks both halves at the merged state, then the tests that pin them.

One shared, policy-compliant User-Agent

Wikimedia's User-Agent policy asks that a client identify itself and carry a reachable contact, so an operator can be reached about problematic traffic; an agent without one is throttled harder. The header used to be duplicated across two files with per-feature wording and no contact. It is now a single exported constant with a mailto: contact (the deployed site is auth-gated and the repo is private, so neither would reach a human).

The one header, exported so every caller sends the identical compliant string.

server/utils/figure-grounding.ts · 292 lines

server/utils/figure-grounding.ts292 lines · TypeScript

⋯ 52 lines hidden (lines 1–52)1/**
* Real-world grounding for historical figures — the backbone of the "timeline RPG"
* direction (see docs/ROADMAP.md). Resolves a free-form name to solid facts so the
* game can show who someone was, validate *when* you may contact them, and feed the
* role-play real dates.
*
* Pipeline (the wiki APIs are open + key-less):
*   1. Wikipedia REST summary — the reliable resolver. It follows redirects and
*      picks the notable article, giving a canonical title, a one-line description,
*      a blurb, a portrait, and the Wikidata item id. (Wikidata search alone is NOT
*      reliable: "Cleopatra" resolves to "female given name", "Genghis Khan" to an
*      Iron Maiden song.)
*   2. Wikidata, looked up by that item id (title as fallback) — structured birth
*      (P569) / death (P570), taking the best-ranked claim that actually carries a
*      date, with sub-year precision surfaced honestly as `circa`.
*   3. If the record still has no birth year, a small AI estimator bridges the gap
*      with circa dates (issue #31) — so a real, resolvable figure keeps their
*      "when" slider even when Wikidata can't date them.
*
* Anything unresolved returns `{ resolved: false }`, and callers fall back to the
* free-form behavior rather than blocking — we never punish reaching for someone.
*
* Cache honesty: only definitive answers — a real Wikidata reply (dated or not,
* with the estimator genuinely consulted), a genuine no-such-article miss, a
* disambiguation page — keep the full TTL. A transient failure anywhere on the
* path (a rate-limit 429, a timeout, an estimator outage) gets a short TTL, so
* one blip never poisons a figure for a day.
*/
29import { estimateLifespan } from './lifespan-estimator'
30 
31/** A year on the timeline. `signed` is AD-positive / BCE-negative for comparison. */
32export interface FigureYear {
  year: number
  bce: boolean
  signed: number
  display: string
  /** Approximate: sub-year Wikidata precision (decade/century/…) or an AI estimate. */
  circa?: boolean
39}
40 
41export interface GroundedFigure {
  name: string
  resolved: boolean
  description?: string
  extract?: string
  born?: FigureYear
  died?: FigureYear
  living?: boolean
  thumbnail?: string
  wikiUrl?: string
51}
52 
53/**
* The one header for every Wikipedia / Wikidata call the server makes — grounding,
* the name autocomplete, and the suggester's lookups all share it (issue #58).
* Wikimedia's User-Agent policy wants the client identified plus a reachable CONTACT
* so an operator can be reached about problematic traffic; an agent without one gets
* throttled harder, and rate-limit blips are the dominant real-world failure for the
* autocomplete. A mailto is that contact — the deployed site is auth-gated and the
* repo private, so neither would reach a human. Exported so every caller sends the
* identical compliant string instead of drifting per-feature copies.
*/
63export const WIKI_HEADERS = {
  accept: 'application/json',
  'User-Agent': 'Revisionist/1.0 (timeline RPG; mailto:matthew@mseeks.me)'
66}
⋯ 226 lines hidden (lines 67–292)67 
68const FULL_TTL_MS = 24 * 60 * 60 * 1000
69const TRANSIENT_TTL_MS = 10 * 60 * 1000
70const WIKIDATA_RETRY_DELAY_MS = 400
71const cache = new Map<string, { value: GroundedFigure; expires: number }>()
72 
73/** Builds a `FigureYear`; the display string owns the "c." honesty marker. */
74export function makeFigureYear(year: number, bce: boolean, circa = false): FigureYear {
  const base = bce ? `${year} BC` : `${year}`
  return {
      year,
      bce,
      signed: bce ? -year : year,
      display: circa ? `c. ${base}` : base,
      ...(circa ? { circa: true } : {})
  }
83}
84 
85/**
* Parses a Wikidata time literal (e.g. "+1856-07-10T..", "-0069-01-13T..") to a year.
* Precision 9 means year-level; anything below (8 decade, 7 century, 6 millennium)
* still carries a representative year in the literal, but only approximately —
* those parse as `circa` rather than being dropped or displayed as exact.
*/
91export function parseWikidataYear(time?: string, precision?: number): FigureYear | undefined {
  if (!time) return undefined
  const m = /^([+-])0*(\d+)-/.exec(time)
  if (!m) return undefined
  const year = parseInt(m[2], 10)
  if (!year) return undefined
  const bce = m[1] === '-'
  return makeFigureYear(year, bce, precision != null && precision < 9)
99}
100 
101/** The slice of the Wikipedia REST summary we actually read. */
102interface WikiSummary {
  type?: string
  title?: string
  description?: string
  extract?: string
  thumbnail?: { source?: string }
  content_urls?: { desktop?: { page?: string } }
  wikibase_item?: string
110}
111 
112/** The slice of a Wikidata date claim we actually read. */
113interface WikidataClaim {
  rank?: string
  mainsnak?: {
      snaktype?: string
      datavalue?: { value?: { time?: string; precision?: number } }
  }
119}
120 
121/** The slice of the Wikidata `wbgetentities` response we actually read. */
122interface WikidataEntities {
  entities?: Record<string, { claims?: Record<string, WikidataClaim[]> }>
124}
125 
126/**
* The best date a claim list actually carries. Wikidata routinely stacks several
* birth/death claims (scholarly guesses, deprecated values, "unknown value"
* placeholders) and the community-preferred one is often NOT first — Moses, Jesus
* and Confucius all keep theirs at index 2. So: only claims whose snak carries a
* real time (somevalue/novalue snaks don't), never deprecated, preferred rank first.
*/
133export function pickClaimYear(claims?: WikidataClaim[]): FigureYear | undefined {
  const usable = (claims ?? []).filter(c =>
      c.rank !== 'deprecated' &&
      c.mainsnak?.snaktype === 'value' &&
      c.mainsnak.datavalue?.value?.time
  )
  const best = usable.find(c => c.rank === 'preferred') ?? usable[0]
  const value = best?.mainsnak?.datavalue?.value
  return parseWikidataYear(value?.time, value?.precision)
142}
143 
144/**
* A fetch that tells a definitive miss from a transient one: 404 means the thing
* genuinely isn't there (cacheable at full TTL), anything else — 429, 5xx, timeout,
* network error — is weather to retry soon, not remember for a day.
*/
149interface FetchOutcome<T> {
  data: T | null
  transient: boolean
152}
153 
154async function fetchJson<T>(url: string): Promise<FetchOutcome<T>> {
  try {
      const res = await fetch(url, { headers: WIKI_HEADERS, signal: AbortSignal.timeout(6000) })
      if (!res.ok) return { data: null, transient: res.status !== 404 }
      return { data: (await res.json()) as T, transient: false }
  } catch {
      return { data: null, transient: true }
  }
162}
163 
164interface WikidataDates {
  born?: FigureYear
  died?: FigureYear
  /** True when we never got a real answer (so the result must not cache long). */
  transient: boolean
169}
170 
171/**
* Birth/death from Wikidata — by item id when the summary supplied one (immune to
* title-matching quirks), by sitelink title otherwise. Rate-limit blips are the
* dominant way dates go missing in practice (a 429 body carries no `entities`), so
* a no-entities response gets one spaced retry before being declared transient.
*/
177async function wikidataDates(qid: string | undefined, title: string): Promise<WikidataDates> {
  const subject = qid
      ? `ids=${encodeURIComponent(qid)}`
      : `sites=enwiki&titles=${encodeURIComponent(title)}&normalize=1`
  const url = `https://www.wikidata.org/w/api.php?action=wbgetentities&${subject}&props=claims&languages=en&format=json&origin=*`
  let outcome = await fetchJson<WikidataEntities>(url)
  if (!outcome.data?.entities) {
      await new Promise(resolve => setTimeout(resolve, WIKIDATA_RETRY_DELAY_MS))
      outcome = await fetchJson<WikidataEntities>(url)
  }
  const entities = outcome.data?.entities
  if (!entities) return { transient: true }
  const id = Object.keys(entities)[0]
  const claims = id ? entities[id]?.claims : undefined
  return { born: pickClaimYear(claims?.P569), died: pickClaimYear(claims?.P570), transient: false }
192}
193 
194/**
* Resolves a name to grounded facts (cached). Never throws; returns
* `{ resolved: false }` when the figure can't be confidently identified.
*/
198export async function groundFigure(rawName: string): Promise<GroundedFigure> {
  const name = (rawName || '').trim()
  if (!name) return { name: '', resolved: false }
201 
  const key = name.toLowerCase()
  const hit = cache.get(key)
  if (hit && hit.expires > Date.now()) return hit.value
205 
  const { value, ttlMs } = await resolve(name)
  cache.set(key, { value, expires: Date.now() + ttlMs })
  return value
209}
210 
211/**
* Keep a URL only if it's a plain http(s) link — drop `javascript:` / `data:` /
* relative values. These come from a remote Wikipedia response and end up bound to
* `:href` / `:src` in the figure dossier; Vue escapes the value but NOT the scheme,
* so a spoofed `javascript:` URL would execute on click. (Surfaced by the
* unsafe-render loop.) Exported for the figure-search route, which binds Wikipedia
* thumbnails the same way.
*/
219export function safeUrl(url?: string): string | undefined {
  if (!url) return undefined
  try {
      const { protocol } = new URL(url)
      return protocol === 'https:' || protocol === 'http:' ? url : undefined
  } catch {
      return undefined
  }
227}
228 
229interface Resolution {
  value: GroundedFigure
  ttlMs: number
232}
233 
234async function resolve(name: string): Promise<Resolution> {
  const summary = await fetchJson<WikiSummary>(
      `https://en.wikipedia.org/api/rest_v1/page/summary/${encodeURIComponent(name)}`
  )
238 
  // No article, or an ambiguous disambiguation page → can't pin a person.
  const article = summary.data
  if (!article || article.type === 'disambiguation' || !article.title) {
      return {
          value: { name, resolved: false },
          ttlMs: summary.transient ? TRANSIENT_TTL_MS : FULL_TTL_MS
      }
  }
247 
  const title: string = article.title
249 
  const dates = await wikidataDates(article.wikibase_item, title)
  let born = dates.born
  let died = dates.died
  let bridgeTransient = false
254 
  // The AI bridge (issue #31): the record knows WHO they are but not WHEN — either
  // Wikidata genuinely has no usable birth claim, or the lookup is down right now.
  // Estimated years arrive marked circa, so the dossier and prompts stay honest.
  // A recorded death is law: the estimate only fills what the record lacks, and an
  // estimate that contradicts the record (born after the documented death) is
  // dropped whole rather than shipped as an incoherent lifespan.
  if (!born) {
      const bridge = await estimateLifespan(title, article.description, article.extract, died?.display)
      bridgeTransient = bridge.transient
      if (bridge.estimate) {
          const estBorn = makeFigureYear(bridge.estimate.born.year, bridge.estimate.born.bce, true)
          if (!died || estBorn.signed <= died.signed) {
              born = estBorn
              died = died ?? (bridge.estimate.died
                  ? makeFigureYear(bridge.estimate.died.year, bridge.estimate.died.bce, true)
                  : undefined)
          }
      }
  }
274 
  return {
      value: {
          name: title,
          resolved: true,
          description: article.description || undefined,
          extract: article.extract || undefined,
          born,
          died,
          living: !!born && !died,
          thumbnail: safeUrl(article.thumbnail?.source),
          wikiUrl: safeUrl(article.content_urls?.desktop?.page)
      },
      // Anything short of a definitive answer keeps the short TTL: a transient
      // Wikidata miss (even when the estimator papered over it — the next lookup
      // should get a shot at the real dates) and an estimator outage alike.
      ttlMs: dates.transient || bridgeTransient ? TRANSIENT_TTL_MS : FULL_TTL_MS
  }
292}

The search module now imports that constant instead of defining its own, and passes it on the same fetch as before. Because the suggester's candidate lookups run through groundFigure (same module), all three Wikipedia/Wikidata callers are now identified to Wikimedia with the same compliant header — not just the search call.

Import the shared header (top); use it on the title-search fetch (bottom).

server/utils/figure-search.ts · 105 lines

server/utils/figure-search.ts105 lines · TypeScript

⋯ 10 lines hidden (lines 1–10)1/**
2 * Name autocomplete for the contact step — Wikipedia REST title search (the
3 * prefix-matching endpoint built for exactly this), key-less like the grounding
4 * pipeline. Deliberately unfiltered: the player may reach for anyone or anything
5 * Wikipedia knows; the description line is what lets them tell the pharaoh from
6 * the 1963 film. Never throws.
7 *
8 * Failure honesty (the lesson of issue #31, applied to search): a rate-limit 429
9 * or timeout is weather, not "no matches". A failed fetch gets one spaced retry,
10 * and if that fails too the outcome says `transient: true` instead of posing as
11 * an empty result — so the combobox can quietly try again rather than silently
12 * never opening. Only real answers are cached.
13 */
14import { safeUrl, WIKI_HEADERS } from './figure-grounding'
15 
16export interface FigureSearchResult {
⋯ 39 lines hidden (lines 17–55)17    name: string
18    description?: string
19    thumbnail?: string
20}
21 
22export interface FigureSearchOutcome {
23    results: FigureSearchResult[]
24    /** True when Wikipedia couldn't be reached (429, timeout, network): the empty
25     *  answer is weather, and the caller may retry soon. Never set on a real
26     *  "no matches" answer. */
27    transient: boolean
28}
29 
30/** Cache: queries repeat heavily while typing (and across players). Capped so a
31 *  crawl of unique queries can't grow it without bound (the grounding cache's
32 *  known gap — not repeated here). */
33const CACHE_TTL_MS = 60 * 60 * 1000
34const CACHE_MAX_ENTRIES = 500
35const cache = new Map<string, { value: FigureSearchResult[]; expires: number }>()
36 
37const RESULT_LIMIT = 5
38const SEARCH_RETRY_DELAY_MS = 250
39 
40/** The slice of the Wikipedia REST v1 title-search response we read. */
41interface WikiTitleSearch {
42    pages?: Array<{
43        title?: string
44        description?: string
45        thumbnail?: { url?: string } | null
46    }>
47}
48 
49/** Wikipedia thumbnails arrive protocol-relative ("//upload.wikimedia.org/…"). */
50function absoluteThumb(url?: string): string | undefined {
51    if (!url) return undefined
52    return safeUrl(url.startsWith('//') ? `https:${url}` : url)
53}
54 
55/** One attempt against the title-search endpoint; null means it didn't answer. */
56async function fetchSearch(query: string): Promise<FigureSearchResult[] | null> {
57    try {
58        const res = await fetch(
59            `https://en.wikipedia.org/w/rest.php/v1/search/title?q=${encodeURIComponent(query)}&limit=${RESULT_LIMIT}`,
60            { headers: WIKI_HEADERS, signal: AbortSignal.timeout(4000) }
61        )
⋯ 44 lines hidden (lines 62–105)62        if (!res.ok) return null
63        const data = (await res.json()) as WikiTitleSearch
64        return (data.pages ?? [])
65            .filter(p => typeof p.title === 'string' && p.title.length > 0)
66            .slice(0, RESULT_LIMIT)
67            .map(p => ({
68                name: p.title as string,
69                description: p.description || undefined,
70                thumbnail: absoluteThumb(p.thumbnail?.url)
71            }))
72    } catch {
73        return null
74    }
75}
76 
77export async function searchFigures(rawQuery: string): Promise<FigureSearchOutcome> {
78    const query = (rawQuery || '').trim()
79    if (query.length < 2) return { results: [], transient: false }
80 
81    const key = query.toLowerCase()
82    const hit = cache.get(key)
83    if (hit && hit.expires > Date.now()) return { results: hit.value, transient: false }
84 
85    let results = await fetchSearch(query)
86    if (results === null) {
87        // Rate-limit blips are the dominant real-world failure here (shared egress
88        // IP, plus the suggester's own wiki bursts) — one spaced retry rescues most.
89        await new Promise(resolve => setTimeout(resolve, SEARCH_RETRY_DELAY_MS))
90        results = await fetchSearch(query)
91    }
92    if (results === null) return { results: [], transient: true }
93 
94    // Cache REAL ANSWERS only — a timeout or a Wikipedia 5xx must not blank this
95    // query's autocomplete for every player for the next hour. (A legitimate
96    // "no such title" empty result IS an answer and caches normally.)
97    if (cache.size >= CACHE_MAX_ENTRIES) {
98        // Drop the oldest entry (Map preserves insertion order) — a tiny, boring
99        // eviction that keeps the cap honest without LRU machinery.
100        const oldest = cache.keys().next().value
101        if (oldest !== undefined) cache.delete(oldest)
102    }
103    cache.set(key, { value: results, expires: Date.now() + CACHE_TTL_MS })
104    return { results, transient: false }
105}

Backoff, not a single silent give-up

The combobox state grows three members: searchUnavailable (the give-up flag), listboxOpen (a computed that is true only when there are results to show), and SEARCH_RETRY_DELAYS_MS, the backoff schedule. Splitting "the listbox is open" from "the popup is showing something" matters: the unavailable hint is a popup but not a listbox, so ARIA must track the listbox alone (next section).

New combobox state: the give-up flag, the listbox-open computed, the backoff schedule.

components/FigurePicker.vue · 517 lines

components/FigurePicker.vue517 lines · Vue

⋯ 308 lines hidden (lines 1–308)1<template>
2  <div data-testid="figure-picker" class="space-y-3">
3    <div ref="searchBoxRef" class="relative" @focusout="onSearchFocusOut">
4      <label for="figure-input" class="rv-label block mb-1">Who in history will you reach?</label>
5      <input id="figure-input" ref="searchInputRef" v-model="figure" data-testid="figure-input" type="text"
6        class="rv-field rv-mono text-sm" placeholder="Anyone, any era — Cleopatra, Tesla, Genghis Khan…"
7        :disabled="disabled"
8        role="combobox" aria-autocomplete="list" :aria-expanded="listboxOpen ? 'true' : 'false'"
9        :aria-controls="listboxOpen ? 'figure-search-listbox' : undefined"
10        :aria-activedescendant="activeIndex >= 0 ? `figure-search-option-${activeIndex}` : undefined"
11        autocomplete="off" @keydown="onSearchKeydown" />
12      <span class="sr-only" role="status">{{ searchStatus }}</span>
13      <!-- Name autocomplete: Wikipedia title search, the description line telling
14           the pharaoh from the 1963 film. Picking one fills the input; grounding
15           fires exactly as if it had been typed. -->
16      <ul v-if="listboxOpen" id="figure-search-listbox" data-testid="figure-search-listbox" role="listbox"
17        aria-label="Matching names from the record"
18        class="search-pop absolute left-0 right-0 top-full mt-1 z-20 border rv-line rounded-sm rv-bg max-h-64 overflow-y-auto">
19        <li v-for="(r, i) in searchResults" :id="`figure-search-option-${i}`" :key="r.name" role="option"
20          :aria-selected="i === activeIndex ? 'true' : 'false'" data-testid="figure-search-option"
21          class="flex items-center gap-2 px-2.5 py-1.5 cursor-pointer text-sm"
22          :class="i === activeIndex ? 'rv-tint' : 'rv-hover'"
23          @mousedown.prevent @click="choose(r.name)" @mousemove="activeIndex = i">
24          <img v-if="r.thumbnail" :src="r.thumbnail" alt="" class="h-7 w-7 shrink-0 rounded object-cover" aria-hidden="true" />
25          <span v-else class="h-7 w-7 shrink-0 rounded rv-tint" aria-hidden="true" />
26          <span class="min-w-0">
27            <span class="rv-fg font-medium block truncate">{{ r.name }}</span>
28            <span v-if="r.description" class="rv-faint text-[11px] block truncate">{{ r.description }}</span>
29          </span>
30        </li>
31      </ul>
32      <!-- The search couldn't reach Wikipedia after its retries: a visible, retryable
33           hint so a rate-limit blip degrades honestly instead of an empty box that
34           reads as "no matches" (issue #58). The sr-only role=status span above is the
35           sole live region — this surface is NOT one, to avoid a double announcement. -->
36      <div v-else-if="searchOpen && searchUnavailable" data-testid="figure-search-unavailable"
37        class="search-pop absolute left-0 right-0 top-full mt-1 z-20 border rv-line rounded-sm rv-bg px-2.5 py-2 text-sm rv-muted flex items-center justify-between gap-2">
38        <span>Couldn't reach the record — a brief network hiccup.</span>
39        <button type="button" data-testid="figure-search-retry"
40          class="rv-accent text-[11px] font-medium hover:underline shrink-0"
41          @mousedown.prevent @click="retrySearch">Retry</button>
42      </div>
43    </div>
44 
45    <!-- Grounding: who they were, and when you reach them -->
46    <div v-if="groundingLoading" data-testid="grounding-loading" class="flex items-center gap-2 text-xs rv-faint">
47      <span class="rv-spinner" aria-hidden="true" />
48      Consulting the records…
49    </div>
50 
51    <div v-else-if="grounding?.resolved" data-testid="figure-dossier" class="rv-card p-3">
52      <div class="flex gap-3">
53        <img v-if="grounding.thumbnail" :src="grounding.thumbnail" :alt="grounding.name"
54          class="h-12 w-12 shrink-0 rounded object-cover" />
55        <div class="min-w-0 flex-1">
56          <div class="flex flex-wrap items-center gap-x-2 gap-y-0.5">
57            <span data-testid="dossier-name" class="rv-fg font-semibold text-sm">{{ grounding.name }}</span>
58            <span v-if="lifespan" data-testid="dossier-lifespan" class="rv-mono text-[11px] rv-faint">{{ lifespan }}</span>
59            <a v-if="grounding.wikiUrl" :href="grounding.wikiUrl" target="_blank" rel="noopener noreferrer"
60              class="rv-accent text-[11px]">Wikipedia ↗</a>
61          </div>
62          <p v-if="grounding.description" class="rv-muted text-xs mt-0.5">{{ grounding.description }}</p>
63 
64          <!-- When do you reach them? A promoted, lifetime-bounded playhead: the
65               chosen year + live age lead, big and in the accent, so the moment you're
66               writing into is the loudest thing in the dossier (not a buried micro-row). -->
67          <div v-if="hasLifespan" data-testid="when-control" class="mt-2.5 border-t rv-line pt-2.5">
68            <div class="flex items-baseline justify-between gap-2">
69              <span id="when-label" class="rv-label">Reach them in</span>
70              <span data-testid="when-display" class="rv-mono rv-accent text-lg font-bold leading-none">
71                {{ whenDisplay }}<span v-if="contactAge != null" data-testid="when-age" class="rv-faint text-xs font-normal"> · age {{ contactAge }}</span>
72              </span>
73            </div>
74            <input type="range" data-testid="when-slider" class="w-full mt-2" :style="{ accentColor: 'var(--rv-accent)' }"
75              :min="range.min" :max="range.max" :value="contactWhen ?? range.min" :disabled="disabled"
76              aria-labelledby="when-label" :aria-valuetext="whenValueText" @input="onWhenInput" />
77            <div class="flex items-center justify-between text-[10px] rv-faint rv-mono">
78              <span>{{ grounding.born?.display }} · born</span>
79              <span>{{ grounding.died?.display ? grounding.died.display + ' · died' : 'present' }}</span>
80            </div>
81 
82            <!-- Pin the moment (issue #32): an optional month/day refinement of the
83                 chosen year. Display + prompt flavor only — the year stays the value
84                 every mechanic computes with, so the wager, world-brief, and liveness
85                 gates are untouched by whatever is pinned here. -->
86            <div class="mt-1.5">
87              <button v-if="!momentOpen" type="button" data-testid="pin-moment"
88                class="rv-accent text-[11px] font-medium hover:underline disabled:opacity-50"
89                :disabled="disabled" @click="momentOpen = true">
90                <span aria-hidden="true">📍</span> {{ contactMoment ? 'adjust the moment' : 'pin the moment' }}
91              </button>
92              <div v-else data-testid="moment-picker">
93                <div class="flex flex-wrap gap-1" role="group" aria-label="Month of the contact">
94                  <button v-for="(m, i) in MONTH_NAMES" :key="m" type="button" data-testid="month-chip"
95                    class="rv-press border rv-line rounded-sm px-1.5 py-0.5 text-[10px]"
96                    :class="contactMoment?.month === i + 1 ? 'rv-tint rv-fg' : 'rv-muted rv-hover'"
97                    :aria-pressed="contactMoment?.month === i + 1 ? 'true' : 'false'"
98                    :disabled="disabled" @click="pickMonth(i + 1)">{{ m.slice(0, 3) }}</button>
99                </div>
100                <div class="flex items-center gap-1.5 mt-1">
101                  <template v-if="contactMoment">
102                    <label for="moment-day" class="rv-label">day</label>
103                    <input id="moment-day" data-testid="moment-day" type="number" inputmode="numeric"
104                      class="rv-field rv-mono text-xs w-16 px-1.5 py-0.5" min="1" :max="maxDay"
105                      :value="contactMoment.day ?? ''" :disabled="disabled" placeholder="—"
106                      @input="onDayInput" />
107                  </template>
108                  <button type="button" data-testid="unpin-moment"
109                    class="rv-faint text-[11px] hover:underline ml-auto" :disabled="disabled"
110                    @click="unpinMoment">{{ contactMoment ? 'unpin' : 'close' }}</button>
111                </div>
112              </div>
113            </div>
114          </div>
115 
116          <!-- Even the AI bridge couldn't date them: say so honestly instead of a
117               mysteriously absent control. The copy claims only the lookup outcome
118               (it may be a transient outage, not a dateless record). No manual year
119               here — the contact year prices the anachronism wager, so it stays
120               grounded or unset. -->
121          <p v-else data-testid="when-unknown" class="mt-2.5 border-t rv-line pt-2.5 text-[11px] italic rv-faint">
122            No dates could be found for them — your message will find them in their own time.
123          </p>
124 
125          <!-- The Archive: study who you're reaching, at the chosen moment -->
126          <div data-testid="archive" class="mt-2 border-t rv-line pt-2">
127            <button v-if="!studyShown" type="button" data-testid="study-button"
128              class="rv-accent text-[11px] font-medium hover:underline disabled:opacity-50"
129              :disabled="studyLoading || disabled" @click="studyThem">
130              <span aria-hidden="true">🔎</span> {{ studyLoading ? 'The Archivist consults the record…' : studyLabel }}
131            </button>
132 
133            <div v-else data-testid="figure-study" class="space-y-1 text-[11px] leading-snug rv-muted">
134              <p class="italic rv-fg">{{ figureStudy?.atThisMoment }}</p>
135              <p v-if="figureStudy?.grasp.length"><span class="rv-faint">grasps</span> {{ figureStudy?.grasp.join(' · ') }}</p>
136              <p v-if="figureStudy?.reaching.length"><span class="rv-faint">reaching</span> {{ figureStudy?.reaching.join(' · ') }}</p>
137              <p v-if="figureStudy?.cannotYetKnow" class="rv-warn"><span class="rv-faint">beyond them</span> {{ figureStudy?.cannotYetKnow }}</p>
138              <button v-if="yearMoved" type="button" data-testid="restudy-button"
139                class="rv-accent font-medium hover:underline disabled:opacity-50" :disabled="studyLoading || disabled" @click="studyThem">
140                <span aria-hidden="true">🔎</span> {{ studyLoading ? 'Consulting…' : restudyLabel }}
141              </button>
142            </div>
143 
144            <p v-if="studyNotice" data-testid="study-blocked" role="alert" aria-live="assertive"
145              class="mt-1 text-[11px] border-l-2 border-red-500/70 bg-red-500/5 pl-2 py-1 text-red-300">
146              <span class="font-semibold uppercase tracking-wide">⚠ blocked</span> {{ studyNotice }}
147            </p>
148          </div>
149        </div>
150      </div>
151    </div>
152 
153    <div v-else-if="grounding && !grounding.resolved" data-testid="figure-unresolved" class="text-xs italic rv-faint">
154      No record found for "{{ activeName }}" — you can still send a message into the unknown.
155    </div>
156 
157    <!-- Figures already contacted this run -->
158    <div v-if="contacted.length" class="flex flex-wrap items-center gap-1.5">
159      <span class="rv-label">contacts</span>
160      <button v-for="f in contacted" :key="f.name" type="button" data-testid="contact-chip"
161        class="rv-press text-xs px-2 py-0.5 border rv-line rounded-sm inline-flex items-center gap-1.5" :class="chipClass(f.name)" @click="select(f.name)">
162        <span class="rv-dot" :class="f.name === figure ? 'rv-dot--accent' : 'rv-dot--hollow'" aria-hidden="true" />{{ f.name }}
163      </button>
164    </div>
165 
166    <!-- Era-relevant figures for this objective (the on-ramp); you can still type anyone. -->
167    <div class="space-y-1.5">
168      <span class="rv-label block" aria-live="polite">{{ suggestionsLabel }}</span>
169      <p v-if="suggestionsNotice" data-testid="suggestions-blocked" role="alert" aria-live="assertive"
170        class="text-[11px] border-l-2 border-red-500/70 bg-red-500/5 pl-2 py-1 text-red-300">
171        <span class="font-semibold uppercase tracking-wide">⚠ blocked</span> {{ suggestionsNotice }}
172      </p>
173      <!-- While the era-aware agent works: quiet skeleton chips — never clickable
174           generic defaults masquerading as objective-relevant picks. The famous-
175           names fallback appears only AFTER the agent has genuinely come up empty,
176           labeled honestly as what it is. -->
177      <div v-if="suggestionsPending" data-testid="suggestion-skeletons" class="flex flex-col gap-1" aria-hidden="true">
178        <div v-for="i in 3" :key="i" class="border rv-line rounded-sm px-2.5 py-2">
179          <span class="skeleton-line w-32" />
180          <span class="skeleton-line w-48 mt-1.5" />
181        </div>
182      </div>
183      <div v-else class="flex flex-col gap-1">
184        <button v-for="s in displaySuggestions" :key="s.name" type="button" data-testid="suggestion-chip"
185          class="rv-press border rv-line rounded-sm px-2.5 py-1.5 text-left" :class="suggestionClass(s.name)" @click="select(s.name)">
186          <span class="text-sm rv-fg font-medium">{{ s.name }}</span>
187          <span v-if="s.lifespan" class="ml-1.5 rv-mono text-[10px] rv-faint">{{ s.lifespan }}</span>
188          <span v-if="s.reason" data-testid="suggestion-reason" class="block text-[11px] leading-snug rv-faint">{{ s.reason }}</span>
189        </button>
190      </div>
191    </div>
192  </div>
193</template>
194 
195<script setup lang="ts">
196/**
197 * FigurePicker — choose whom (free-form name, suggestion, or prior contact) and, once
198 * grounded, when to reach them (a lifetime-bounded slider with a live age). The
199 * Archive's "study them" brief discloses who they are at that moment. Re-skin only —
200 * every store binding (grounding, contactWhen, study, suggestions) is unchanged.
201 */
202import { computed, watch, onMounted, onUnmounted } from 'vue'
203import { useGameStore } from '~/stores/game'
204import { formatContactMoment, MONTH_NAMES, MONTH_MAX_DAY } from '~/utils/contact-moment'
205import type { FigureSuggestion } from '~/server/utils/figure-suggester'
206 
207const figure = defineModel<string>({ default: '' })
208defineProps<{ disabled?: boolean }>()
209 
210const gameStore = useGameStore()
211const contacted = computed(() => gameStore.figures)
212const figureSuggestions = computed(() => gameStore.figureSuggestions)
213const suggestionsLoading = computed(() => gameStore.suggestionsLoading)
214const suggestionsNotice = computed(() => gameStore.suggestionsNotice)
215const grounding = computed(() => gameStore.figureGrounding)
216const groundingLoading = computed(() => gameStore.groundingLoading)
217const contactWhen = computed(() => gameStore.contactWhen)
218const contactAge = computed(() => gameStore.contactAge)
219const activeName = computed(() => figure.value.trim())
220 
221const hasLifespan = computed(() => !!(grounding.value?.resolved && grounding.value.born))
222const lifespan = computed(() => {
223    const g = grounding.value
224    if (!g?.born) return ''
225    if (g.died) return `${g.born.display} – ${g.died.display}`
226    return g.living ? `${g.born.display} – present` : g.born.display
227})
228const range = computed(() => ({
229    min: grounding.value?.born?.signed ?? 0,
230    max: grounding.value?.died?.signed ?? new Date().getFullYear()
231}))
232const contactMoment = computed(() => gameStore.contactMoment)
233const whenDisplay = computed(() => (contactWhen.value != null ? formatContactMoment(contactWhen.value, contactMoment.value) : ''))
234// What AT announces for the slider: the human year + live age (e.g. "44 BC · age 25"),
235// not the raw signed integer the value attribute carries.
236const whenValueText = computed(() =>
237    contactWhen.value == null ? '' : whenDisplay.value + (contactAge.value != null ? ` · age ${contactAge.value}` : '')
238)
239 
240function onWhenInput(e: Event) {
241    gameStore.setContactWhen(Number((e.target as HTMLInputElement).value))
242}
243 
244// --- Pin the moment (issue #32): month chips + optional day, year-canonical ---
245const momentOpen = ref(false)
246const maxDay = computed(() => (contactMoment.value ? MONTH_MAX_DAY[contactMoment.value.month - 1] : 31))
247function pickMonth(month: number) {
248    const current = gameStore.contactMoment
249    if (current?.month === month) return
250    // Switching months keeps the day where it stays valid, clamps where it doesn't.
251    const day = current?.day ? Math.min(current.day, MONTH_MAX_DAY[month - 1]) : undefined
252    gameStore.setContactMoment(day ? { month, day } : { month })
253}
254function onDayInput(e: Event) {
255    const current = gameStore.contactMoment
256    if (!current) return
257    const raw = Number((e.target as HTMLInputElement).value)
258    if (!Number.isInteger(raw) || raw < 1) {
259        gameStore.setContactMoment({ month: current.month })
260        return
261    }
262    gameStore.setContactMoment({ month: current.month, day: Math.min(raw, MONTH_MAX_DAY[current.month - 1]) })
263}
264function unpinMoment() {
265    gameStore.setContactMoment(null)
266    momentOpen.value = false
267}
268 
269// The Archive: study the grounded figure in-game, at the chosen moment.
270const figureStudy = computed(() => gameStore.figureStudy)
271const studyLoading = computed(() => gameStore.studyLoading)
272const studyNotice = computed(() => gameStore.studyNotice)
273const studyShown = computed(() => !!figureStudy.value && gameStore.studyFor === grounding.value?.name)
274const yearMoved = computed(() => studyShown.value && gameStore.studyWhen !== contactWhen.value)
275const studyLabel = computed(() => (contactWhen.value != null ? `Study them in ${whenDisplay.value}` : 'Study them'))
276const restudyLabel = computed(() => (contactWhen.value != null ? `Re-study in ${whenDisplay.value}` : 'Re-study'))
277function studyThem() { gameStore.studyActiveFigure() }
278 
279const LOCAL_DEFAULT: FigureSuggestion[] = [
280    { name: 'Cleopatra', reason: '' },
281    { name: 'Nikola Tesla', reason: '' },
282    { name: 'Genghis Khan', reason: '' },
283    { name: 'Marie Curie', reason: '' },
284    { name: 'Leonardo da Vinci', reason: '' }
285]
286const displaySuggestions = computed(() => (figureSuggestions.value.length ? figureSuggestions.value : LOCAL_DEFAULT))
287// Pending = in flight, OR simply not yet asked for this objective — the latter
288// covers the first painted frame (loadSuggestions fires onMounted, after render),
289// which would otherwise flash the clickable famous-names fallback for one frame.
290// The store records suggestionsFor even on failure, so a genuine miss still
291// settles into the honest fallback rather than skeletons forever.
292const suggestionsPending = computed(() =>
293    !figureSuggestions.value.length && (
294        suggestionsLoading.value ||
295        (!!gameStore.currentObjective && gameStore.suggestionsFor !== gameStore.currentObjective.title)
296    )
297)
298const suggestionsLabel = computed(() =>
299    suggestionsPending.value
300        ? 'finding figures who matter here…'
301        : figureSuggestions.value.length
302            ? 'figures who might matter here'
303            : 'some famous names to start with'
304)
305 
306function select(name: string) {
307    choose(name)
308}
309 
310// --- Name autocomplete (a combobox over Wikipedia title search) ---
311interface SearchResult { name: string; description?: string; thumbnail?: string }
312const searchBoxRef = ref<HTMLElement | null>(null)
313const searchInputRef = ref<HTMLInputElement | null>(null)
314const searchResults = ref<SearchResult[]>([])
315const searchOpen = ref(false)
316// Sustained weather (rate-limit blips) finally gave up with nothing to show: a
317// visible, retryable hint takes the popup so an outage degrades honestly instead
318// of an empty box that reads as "no matches" (issue #58).
319const searchUnavailable = ref(false)
320const activeIndex = ref(-1)
321// The listbox is the result popup; the unavailable hint is a separate, non-listbox
322// surface. aria-expanded / aria-controls track only this.
323const listboxOpen = computed(() => searchOpen.value && searchResults.value.length > 0)
324let searchDebounce: ReturnType<typeof setTimeout> | null = null
325let searchSeq = 0
326// Backoff for transient (rate-limit) misses: spaced retries before giving up, so a
327// throttled prefix like "Leonardo" gets time to clear rather than vanishing.
328const SEARCH_RETRY_DELAYS_MS = [800, 1600]
329// The name most recently CHOSEN (dropdown option, suggestion chip, contact chip):
⋯ 188 lines hidden (lines 330–517)330// the model change it causes must not reopen the dropdown over the fresh dossier.
331let lastChosen = ''
332 
333/** Closing also INVALIDATES any response still in flight: bumping the seq is what
334 *  keeps a slow fetch from reopening a stale dropdown over a chosen figure's
335 *  dossier, an emptied input, or a disabled one mid-send. It also cancels a pending
336 *  backoff retry — otherwise a timer armed before the dismissal would later fire and
337 *  pop the dropdown (or the unavailable hint) back up unprompted. */
338function closeSearch() {
339    if (searchDebounce) clearTimeout(searchDebounce)
340    searchDebounce = null
341    searchSeq++
342    searchResults.value = []
343    searchOpen.value = false
344    searchUnavailable.value = false
345    activeIndex.value = -1
346}
347 
348/** Deliberate selection from any surface: fill the input and stand down. */
349function choose(name: string) {
350    lastChosen = name
351    figure.value = name
352    closeSearch()
353}
354 
355/** Fire the actual lookup for the CURRENT seq; results land only if still current. */
356async function runSearch(q: string, seq: number, attempt = 0) {
357    try {
358        const res = await $fetch('/api/figure-search', { params: { q } }) as { results?: SearchResult[]; transient?: boolean }
359        if (seq !== searchSeq) return // closed, or a newer keystroke took over
360        const results = res?.results ?? []
361        // Weather, not absence: an empty answer the server marks transient must not
362        // read as "no matches" — keep whatever is showing and retry with backoff.
363        // (A new keystroke clears the timer; the seq guard drops a stale landing.)
364        if (!results.length && res?.transient) {
365            const delay = SEARCH_RETRY_DELAYS_MS[attempt]
366            if (delay != null) {
367                searchDebounce = setTimeout(() => { void runSearch(q, seq, attempt + 1) }, delay)
368            } else if (!searchResults.value.length) {
369                // Out of retries with nothing to fall back on: say so plainly and
370                // offer a retry, rather than an empty box that looks like "no matches".
371                searchUnavailable.value = true
372                searchOpen.value = true
373                activeIndex.value = -1
374            }
375            return
376        }
377        searchUnavailable.value = false
378        searchResults.value = results
379        searchOpen.value = results.length > 0
380        activeIndex.value = -1
381    } catch {
382        if (seq === searchSeq) closeSearch()
383    }
384}
385 
386/** Manual retry from the "unavailable" hint — refire the search for the current text.
387 *  Returns focus to the input first: clearing the hint unmounts the Retry button, and
388 *  a keyboard user activating it would otherwise have focus fall to <body>. */
389function retrySearch() {
390    const q = (figure.value || '').trim()
391    if (q.length < 2) return
392    searchInputRef.value?.focus()
393    searchUnavailable.value = false
394    void runSearch(q, ++searchSeq)
395}
396 
397watch(figure, (name) => {
398    if (searchDebounce) clearTimeout(searchDebounce)
399    const q = (name || '').trim()
400    if (q.length < 2 || q === lastChosen) {
401        closeSearch()
402        // One-shot suppression: it exists to swallow the single model echo a
403        // choice causes. A later deliberate retype of the same name searches again.
404        if (q === lastChosen) lastChosen = ''
405        return
406    }
407    lastChosen = ''
408    searchUnavailable.value = false // a fresh keystroke retires any prior outage hint
409    const seq = ++searchSeq
410    searchDebounce = setTimeout(() => { void runSearch(q, seq) }, 250)
411})
412 
413function onSearchKeydown(e: KeyboardEvent) {
414    if (e.isComposing) return // IME candidate navigation owns these keys
415    // Escape always dismisses: it must clear a populated listbox OR the unavailable
416    // hint, and — even when nothing is on screen yet — cancel a pending backoff retry
417    // and invalidate any in-flight fetch (closeSearch clears the timer and bumps the
418    // seq). Handled before the guard below, which only covers a populated listbox.
419    if (e.key === 'Escape') {
420        closeSearch()
421        return
422    }
423    if (!searchOpen.value || !searchResults.value.length) {
424        // APG editable-combobox: Down Arrow on a closed combobox reopens the popup
425        // (the only recovery after Escape that doesn't require editing the text).
426        if (e.key === 'ArrowDown') {
427            const q = (figure.value || '').trim()
428            if (q.length >= 2) {
429                e.preventDefault()
430                void runSearch(q, ++searchSeq)
431            }
432        }
433        return
434    }
435    if (e.key === 'ArrowDown') {
436        e.preventDefault()
437        activeIndex.value = (activeIndex.value + 1) % searchResults.value.length
438    } else if (e.key === 'ArrowUp') {
439        e.preventDefault()
440        activeIndex.value = activeIndex.value <= 0 ? searchResults.value.length - 1 : activeIndex.value - 1
441    } else if (e.key === 'Enter') {
442        if (activeIndex.value >= 0) {
443            e.preventDefault()
444            choose(searchResults.value[activeIndex.value].name)
445        }
446    }
447    // Escape is handled up top (it must also dismiss the unavailable hint, where
448    // searchResults is empty and this block is skipped).
449}
450 
451/** Close when focus genuinely leaves the combobox (not when it moves within it). */
452function onSearchFocusOut(e: FocusEvent) {
453    const next = e.relatedTarget as Node | null
454    if (next && searchBoxRef.value?.contains(next)) return
455    closeSearch()
456}
457 
458/** Spoken result count — aria-expanded alone is not reliably announced while typing. */
459const searchStatus = computed(() =>
460    searchUnavailable.value
461        ? 'The record is unreachable right now — press the down arrow or Retry to search again.'
462        : listboxOpen.value
463            ? `${searchResults.value.length} ${searchResults.value.length === 1 ? 'match' : 'matches'} — up and down arrows to review, Enter to choose`
464            : ''
465)
466 
467function chipClass(name: string) {
468    return name === figure.value ? 'rv-tint rv-fg' : 'rv-muted rv-hover'
469}
470function suggestionClass(name: string) {
471    return name === figure.value ? 'rv-tint' : 'rv-hover'
472}
473 
474// Ground the chosen figure, debounced so typing doesn't spam the lookup. The
475// PREVIOUS dossier is cleared synchronously the instant the name changes: a send
476// fired during the debounce/fetch window must go out clean (free-form), never
477// wearing the old figure's facts, year, or liveness gate.
478let debounce: ReturnType<typeof setTimeout> | null = null
479watch(figure, (name) => {
480    if (debounce) clearTimeout(debounce)
481    gameStore.clearGrounding()
482    const trimmed = (name || '').trim()
483    if (!trimmed) return
484    debounce = setTimeout(() => gameStore.groundActiveFigure(trimmed), 350)
485})
486onUnmounted(() => {
487    if (debounce) clearTimeout(debounce)
488    if (searchDebounce) clearTimeout(searchDebounce)
489})
490 
491// Load era-relevant suggestions for the current objective when the board appears.
492onMounted(() => gameStore.loadSuggestions())
493</script>
494 
495<style scoped>
496/* Quiet placeholder bars while the suggester works — letterpress tint, a gentle
497   pulse, stilled under reduced motion. Never a clickable fake. */
498.skeleton-line {
499    display: block;
500    height: 10px;
501    border-radius: 2px;
502    background: var(--rv-tint);
503    animation: skeleton-pulse 1.6s var(--rv-ease) infinite;
504}
505@keyframes skeleton-pulse {
506    0%, 100% { opacity: .55; }
507    50% { opacity: 1; }
508}
509@media (prefers-reduced-motion: reduce) {
510    .skeleton-line { animation: none; }
511}
512 
513/* The autocomplete pop floats over the dossier on warm paper, not chrome. */
514.search-pop {
515    box-shadow: 0 6px 18px color-mix(in srgb, var(--rv-fg) 10%, transparent);
516}
517</style>

runSearch is where the behavior changes. A transient empty answer (rate-limit weather, flagged by the server) no longer retries once and stops. It walks the backoff schedule — 800ms, then 1600ms — re-firing for the same sequence number. Only when the schedule is exhausted and nothing is already on screen does it set searchUnavailable and force the popup open. A successful or genuinely-empty answer clears the flag and renders as before.

Backoff via SEARCH_RETRY_DELAYS_MS[attempt]; give up visibly only with nothing to show.

components/FigurePicker.vue · 517 lines

components/FigurePicker.vue517 lines · Vue

⋯ 355 lines hidden (lines 1–355)1<template>
2  <div data-testid="figure-picker" class="space-y-3">
3    <div ref="searchBoxRef" class="relative" @focusout="onSearchFocusOut">
4      <label for="figure-input" class="rv-label block mb-1">Who in history will you reach?</label>
5      <input id="figure-input" ref="searchInputRef" v-model="figure" data-testid="figure-input" type="text"
6        class="rv-field rv-mono text-sm" placeholder="Anyone, any era — Cleopatra, Tesla, Genghis Khan…"
7        :disabled="disabled"
8        role="combobox" aria-autocomplete="list" :aria-expanded="listboxOpen ? 'true' : 'false'"
9        :aria-controls="listboxOpen ? 'figure-search-listbox' : undefined"
10        :aria-activedescendant="activeIndex >= 0 ? `figure-search-option-${activeIndex}` : undefined"
11        autocomplete="off" @keydown="onSearchKeydown" />
12      <span class="sr-only" role="status">{{ searchStatus }}</span>
13      <!-- Name autocomplete: Wikipedia title search, the description line telling
14           the pharaoh from the 1963 film. Picking one fills the input; grounding
15           fires exactly as if it had been typed. -->
16      <ul v-if="listboxOpen" id="figure-search-listbox" data-testid="figure-search-listbox" role="listbox"
17        aria-label="Matching names from the record"
18        class="search-pop absolute left-0 right-0 top-full mt-1 z-20 border rv-line rounded-sm rv-bg max-h-64 overflow-y-auto">
19        <li v-for="(r, i) in searchResults" :id="`figure-search-option-${i}`" :key="r.name" role="option"
20          :aria-selected="i === activeIndex ? 'true' : 'false'" data-testid="figure-search-option"
21          class="flex items-center gap-2 px-2.5 py-1.5 cursor-pointer text-sm"
22          :class="i === activeIndex ? 'rv-tint' : 'rv-hover'"
23          @mousedown.prevent @click="choose(r.name)" @mousemove="activeIndex = i">
24          <img v-if="r.thumbnail" :src="r.thumbnail" alt="" class="h-7 w-7 shrink-0 rounded object-cover" aria-hidden="true" />
25          <span v-else class="h-7 w-7 shrink-0 rounded rv-tint" aria-hidden="true" />
26          <span class="min-w-0">
27            <span class="rv-fg font-medium block truncate">{{ r.name }}</span>
28            <span v-if="r.description" class="rv-faint text-[11px] block truncate">{{ r.description }}</span>
29          </span>
30        </li>
31      </ul>
32      <!-- The search couldn't reach Wikipedia after its retries: a visible, retryable
33           hint so a rate-limit blip degrades honestly instead of an empty box that
34           reads as "no matches" (issue #58). The sr-only role=status span above is the
35           sole live region — this surface is NOT one, to avoid a double announcement. -->
36      <div v-else-if="searchOpen && searchUnavailable" data-testid="figure-search-unavailable"
37        class="search-pop absolute left-0 right-0 top-full mt-1 z-20 border rv-line rounded-sm rv-bg px-2.5 py-2 text-sm rv-muted flex items-center justify-between gap-2">
38        <span>Couldn't reach the record — a brief network hiccup.</span>
39        <button type="button" data-testid="figure-search-retry"
40          class="rv-accent text-[11px] font-medium hover:underline shrink-0"
41          @mousedown.prevent @click="retrySearch">Retry</button>
42      </div>
43    </div>
44 
45    <!-- Grounding: who they were, and when you reach them -->
46    <div v-if="groundingLoading" data-testid="grounding-loading" class="flex items-center gap-2 text-xs rv-faint">
47      <span class="rv-spinner" aria-hidden="true" />
48      Consulting the records…
49    </div>
50 
51    <div v-else-if="grounding?.resolved" data-testid="figure-dossier" class="rv-card p-3">
52      <div class="flex gap-3">
53        <img v-if="grounding.thumbnail" :src="grounding.thumbnail" :alt="grounding.name"
54          class="h-12 w-12 shrink-0 rounded object-cover" />
55        <div class="min-w-0 flex-1">
56          <div class="flex flex-wrap items-center gap-x-2 gap-y-0.5">
57            <span data-testid="dossier-name" class="rv-fg font-semibold text-sm">{{ grounding.name }}</span>
58            <span v-if="lifespan" data-testid="dossier-lifespan" class="rv-mono text-[11px] rv-faint">{{ lifespan }}</span>
59            <a v-if="grounding.wikiUrl" :href="grounding.wikiUrl" target="_blank" rel="noopener noreferrer"
60              class="rv-accent text-[11px]">Wikipedia ↗</a>
61          </div>
62          <p v-if="grounding.description" class="rv-muted text-xs mt-0.5">{{ grounding.description }}</p>
63 
64          <!-- When do you reach them? A promoted, lifetime-bounded playhead: the
65               chosen year + live age lead, big and in the accent, so the moment you're
66               writing into is the loudest thing in the dossier (not a buried micro-row). -->
67          <div v-if="hasLifespan" data-testid="when-control" class="mt-2.5 border-t rv-line pt-2.5">
68            <div class="flex items-baseline justify-between gap-2">
69              <span id="when-label" class="rv-label">Reach them in</span>
70              <span data-testid="when-display" class="rv-mono rv-accent text-lg font-bold leading-none">
71                {{ whenDisplay }}<span v-if="contactAge != null" data-testid="when-age" class="rv-faint text-xs font-normal"> · age {{ contactAge }}</span>
72              </span>
73            </div>
74            <input type="range" data-testid="when-slider" class="w-full mt-2" :style="{ accentColor: 'var(--rv-accent)' }"
75              :min="range.min" :max="range.max" :value="contactWhen ?? range.min" :disabled="disabled"
76              aria-labelledby="when-label" :aria-valuetext="whenValueText" @input="onWhenInput" />
77            <div class="flex items-center justify-between text-[10px] rv-faint rv-mono">
78              <span>{{ grounding.born?.display }} · born</span>
79              <span>{{ grounding.died?.display ? grounding.died.display + ' · died' : 'present' }}</span>
80            </div>
81 
82            <!-- Pin the moment (issue #32): an optional month/day refinement of the
83                 chosen year. Display + prompt flavor only — the year stays the value
84                 every mechanic computes with, so the wager, world-brief, and liveness
85                 gates are untouched by whatever is pinned here. -->
86            <div class="mt-1.5">
87              <button v-if="!momentOpen" type="button" data-testid="pin-moment"
88                class="rv-accent text-[11px] font-medium hover:underline disabled:opacity-50"
89                :disabled="disabled" @click="momentOpen = true">
90                <span aria-hidden="true">📍</span> {{ contactMoment ? 'adjust the moment' : 'pin the moment' }}
91              </button>
92              <div v-else data-testid="moment-picker">
93                <div class="flex flex-wrap gap-1" role="group" aria-label="Month of the contact">
94                  <button v-for="(m, i) in MONTH_NAMES" :key="m" type="button" data-testid="month-chip"
95                    class="rv-press border rv-line rounded-sm px-1.5 py-0.5 text-[10px]"
96                    :class="contactMoment?.month === i + 1 ? 'rv-tint rv-fg' : 'rv-muted rv-hover'"
97                    :aria-pressed="contactMoment?.month === i + 1 ? 'true' : 'false'"
98                    :disabled="disabled" @click="pickMonth(i + 1)">{{ m.slice(0, 3) }}</button>
99                </div>
100                <div class="flex items-center gap-1.5 mt-1">
101                  <template v-if="contactMoment">
102                    <label for="moment-day" class="rv-label">day</label>
103                    <input id="moment-day" data-testid="moment-day" type="number" inputmode="numeric"
104                      class="rv-field rv-mono text-xs w-16 px-1.5 py-0.5" min="1" :max="maxDay"
105                      :value="contactMoment.day ?? ''" :disabled="disabled" placeholder="—"
106                      @input="onDayInput" />
107                  </template>
108                  <button type="button" data-testid="unpin-moment"
109                    class="rv-faint text-[11px] hover:underline ml-auto" :disabled="disabled"
110                    @click="unpinMoment">{{ contactMoment ? 'unpin' : 'close' }}</button>
111                </div>
112              </div>
113            </div>
114          </div>
115 
116          <!-- Even the AI bridge couldn't date them: say so honestly instead of a
117               mysteriously absent control. The copy claims only the lookup outcome
118               (it may be a transient outage, not a dateless record). No manual year
119               here — the contact year prices the anachronism wager, so it stays
120               grounded or unset. -->
121          <p v-else data-testid="when-unknown" class="mt-2.5 border-t rv-line pt-2.5 text-[11px] italic rv-faint">
122            No dates could be found for them — your message will find them in their own time.
123          </p>
124 
125          <!-- The Archive: study who you're reaching, at the chosen moment -->
126          <div data-testid="archive" class="mt-2 border-t rv-line pt-2">
127            <button v-if="!studyShown" type="button" data-testid="study-button"
128              class="rv-accent text-[11px] font-medium hover:underline disabled:opacity-50"
129              :disabled="studyLoading || disabled" @click="studyThem">
130              <span aria-hidden="true">🔎</span> {{ studyLoading ? 'The Archivist consults the record…' : studyLabel }}
131            </button>
132 
133            <div v-else data-testid="figure-study" class="space-y-1 text-[11px] leading-snug rv-muted">
134              <p class="italic rv-fg">{{ figureStudy?.atThisMoment }}</p>
135              <p v-if="figureStudy?.grasp.length"><span class="rv-faint">grasps</span> {{ figureStudy?.grasp.join(' · ') }}</p>
136              <p v-if="figureStudy?.reaching.length"><span class="rv-faint">reaching</span> {{ figureStudy?.reaching.join(' · ') }}</p>
137              <p v-if="figureStudy?.cannotYetKnow" class="rv-warn"><span class="rv-faint">beyond them</span> {{ figureStudy?.cannotYetKnow }}</p>
138              <button v-if="yearMoved" type="button" data-testid="restudy-button"
139                class="rv-accent font-medium hover:underline disabled:opacity-50" :disabled="studyLoading || disabled" @click="studyThem">
140                <span aria-hidden="true">🔎</span> {{ studyLoading ? 'Consulting…' : restudyLabel }}
141              </button>
142            </div>
143 
144            <p v-if="studyNotice" data-testid="study-blocked" role="alert" aria-live="assertive"
145              class="mt-1 text-[11px] border-l-2 border-red-500/70 bg-red-500/5 pl-2 py-1 text-red-300">
146              <span class="font-semibold uppercase tracking-wide">⚠ blocked</span> {{ studyNotice }}
147            </p>
148          </div>
149        </div>
150      </div>
151    </div>
152 
153    <div v-else-if="grounding && !grounding.resolved" data-testid="figure-unresolved" class="text-xs italic rv-faint">
154      No record found for "{{ activeName }}" — you can still send a message into the unknown.
155    </div>
156 
157    <!-- Figures already contacted this run -->
158    <div v-if="contacted.length" class="flex flex-wrap items-center gap-1.5">
159      <span class="rv-label">contacts</span>
160      <button v-for="f in contacted" :key="f.name" type="button" data-testid="contact-chip"
161        class="rv-press text-xs px-2 py-0.5 border rv-line rounded-sm inline-flex items-center gap-1.5" :class="chipClass(f.name)" @click="select(f.name)">
162        <span class="rv-dot" :class="f.name === figure ? 'rv-dot--accent' : 'rv-dot--hollow'" aria-hidden="true" />{{ f.name }}
163      </button>
164    </div>
165 
166    <!-- Era-relevant figures for this objective (the on-ramp); you can still type anyone. -->
167    <div class="space-y-1.5">
168      <span class="rv-label block" aria-live="polite">{{ suggestionsLabel }}</span>
169      <p v-if="suggestionsNotice" data-testid="suggestions-blocked" role="alert" aria-live="assertive"
170        class="text-[11px] border-l-2 border-red-500/70 bg-red-500/5 pl-2 py-1 text-red-300">
171        <span class="font-semibold uppercase tracking-wide">⚠ blocked</span> {{ suggestionsNotice }}
172      </p>
173      <!-- While the era-aware agent works: quiet skeleton chips — never clickable
174           generic defaults masquerading as objective-relevant picks. The famous-
175           names fallback appears only AFTER the agent has genuinely come up empty,
176           labeled honestly as what it is. -->
177      <div v-if="suggestionsPending" data-testid="suggestion-skeletons" class="flex flex-col gap-1" aria-hidden="true">
178        <div v-for="i in 3" :key="i" class="border rv-line rounded-sm px-2.5 py-2">
179          <span class="skeleton-line w-32" />
180          <span class="skeleton-line w-48 mt-1.5" />
181        </div>
182      </div>
183      <div v-else class="flex flex-col gap-1">
184        <button v-for="s in displaySuggestions" :key="s.name" type="button" data-testid="suggestion-chip"
185          class="rv-press border rv-line rounded-sm px-2.5 py-1.5 text-left" :class="suggestionClass(s.name)" @click="select(s.name)">
186          <span class="text-sm rv-fg font-medium">{{ s.name }}</span>
187          <span v-if="s.lifespan" class="ml-1.5 rv-mono text-[10px] rv-faint">{{ s.lifespan }}</span>
188          <span v-if="s.reason" data-testid="suggestion-reason" class="block text-[11px] leading-snug rv-faint">{{ s.reason }}</span>
189        </button>
190      </div>
191    </div>
192  </div>
193</template>
194 
195<script setup lang="ts">
196/**
197 * FigurePicker — choose whom (free-form name, suggestion, or prior contact) and, once
198 * grounded, when to reach them (a lifetime-bounded slider with a live age). The
199 * Archive's "study them" brief discloses who they are at that moment. Re-skin only —
200 * every store binding (grounding, contactWhen, study, suggestions) is unchanged.
201 */
202import { computed, watch, onMounted, onUnmounted } from 'vue'
203import { useGameStore } from '~/stores/game'
204import { formatContactMoment, MONTH_NAMES, MONTH_MAX_DAY } from '~/utils/contact-moment'
205import type { FigureSuggestion } from '~/server/utils/figure-suggester'
206 
207const figure = defineModel<string>({ default: '' })
208defineProps<{ disabled?: boolean }>()
209 
210const gameStore = useGameStore()
211const contacted = computed(() => gameStore.figures)
212const figureSuggestions = computed(() => gameStore.figureSuggestions)
213const suggestionsLoading = computed(() => gameStore.suggestionsLoading)
214const suggestionsNotice = computed(() => gameStore.suggestionsNotice)
215const grounding = computed(() => gameStore.figureGrounding)
216const groundingLoading = computed(() => gameStore.groundingLoading)
217const contactWhen = computed(() => gameStore.contactWhen)
218const contactAge = computed(() => gameStore.contactAge)
219const activeName = computed(() => figure.value.trim())
220 
221const hasLifespan = computed(() => !!(grounding.value?.resolved && grounding.value.born))
222const lifespan = computed(() => {
223    const g = grounding.value
224    if (!g?.born) return ''
225    if (g.died) return `${g.born.display} – ${g.died.display}`
226    return g.living ? `${g.born.display} – present` : g.born.display
227})
228const range = computed(() => ({
229    min: grounding.value?.born?.signed ?? 0,
230    max: grounding.value?.died?.signed ?? new Date().getFullYear()
231}))
232const contactMoment = computed(() => gameStore.contactMoment)
233const whenDisplay = computed(() => (contactWhen.value != null ? formatContactMoment(contactWhen.value, contactMoment.value) : ''))
234// What AT announces for the slider: the human year + live age (e.g. "44 BC · age 25"),
235// not the raw signed integer the value attribute carries.
236const whenValueText = computed(() =>
237    contactWhen.value == null ? '' : whenDisplay.value + (contactAge.value != null ? ` · age ${contactAge.value}` : '')
238)
239 
240function onWhenInput(e: Event) {
241    gameStore.setContactWhen(Number((e.target as HTMLInputElement).value))
242}
243 
244// --- Pin the moment (issue #32): month chips + optional day, year-canonical ---
245const momentOpen = ref(false)
246const maxDay = computed(() => (contactMoment.value ? MONTH_MAX_DAY[contactMoment.value.month - 1] : 31))
247function pickMonth(month: number) {
248    const current = gameStore.contactMoment
249    if (current?.month === month) return
250    // Switching months keeps the day where it stays valid, clamps where it doesn't.
251    const day = current?.day ? Math.min(current.day, MONTH_MAX_DAY[month - 1]) : undefined
252    gameStore.setContactMoment(day ? { month, day } : { month })
253}
254function onDayInput(e: Event) {
255    const current = gameStore.contactMoment
256    if (!current) return
257    const raw = Number((e.target as HTMLInputElement).value)
258    if (!Number.isInteger(raw) || raw < 1) {
259        gameStore.setContactMoment({ month: current.month })
260        return
261    }
262    gameStore.setContactMoment({ month: current.month, day: Math.min(raw, MONTH_MAX_DAY[current.month - 1]) })
263}
264function unpinMoment() {
265    gameStore.setContactMoment(null)
266    momentOpen.value = false
267}
268 
269// The Archive: study the grounded figure in-game, at the chosen moment.
270const figureStudy = computed(() => gameStore.figureStudy)
271const studyLoading = computed(() => gameStore.studyLoading)
272const studyNotice = computed(() => gameStore.studyNotice)
273const studyShown = computed(() => !!figureStudy.value && gameStore.studyFor === grounding.value?.name)
274const yearMoved = computed(() => studyShown.value && gameStore.studyWhen !== contactWhen.value)
275const studyLabel = computed(() => (contactWhen.value != null ? `Study them in ${whenDisplay.value}` : 'Study them'))
276const restudyLabel = computed(() => (contactWhen.value != null ? `Re-study in ${whenDisplay.value}` : 'Re-study'))
277function studyThem() { gameStore.studyActiveFigure() }
278 
279const LOCAL_DEFAULT: FigureSuggestion[] = [
280    { name: 'Cleopatra', reason: '' },
281    { name: 'Nikola Tesla', reason: '' },
282    { name: 'Genghis Khan', reason: '' },
283    { name: 'Marie Curie', reason: '' },
284    { name: 'Leonardo da Vinci', reason: '' }
285]
286const displaySuggestions = computed(() => (figureSuggestions.value.length ? figureSuggestions.value : LOCAL_DEFAULT))
287// Pending = in flight, OR simply not yet asked for this objective — the latter
288// covers the first painted frame (loadSuggestions fires onMounted, after render),
289// which would otherwise flash the clickable famous-names fallback for one frame.
290// The store records suggestionsFor even on failure, so a genuine miss still
291// settles into the honest fallback rather than skeletons forever.
292const suggestionsPending = computed(() =>
293    !figureSuggestions.value.length && (
294        suggestionsLoading.value ||
295        (!!gameStore.currentObjective && gameStore.suggestionsFor !== gameStore.currentObjective.title)
296    )
297)
298const suggestionsLabel = computed(() =>
299    suggestionsPending.value
300        ? 'finding figures who matter here…'
301        : figureSuggestions.value.length
302            ? 'figures who might matter here'
303            : 'some famous names to start with'
304)
305 
306function select(name: string) {
307    choose(name)
308}
309 
310// --- Name autocomplete (a combobox over Wikipedia title search) ---
311interface SearchResult { name: string; description?: string; thumbnail?: string }
312const searchBoxRef = ref<HTMLElement | null>(null)
313const searchInputRef = ref<HTMLInputElement | null>(null)
314const searchResults = ref<SearchResult[]>([])
315const searchOpen = ref(false)
316// Sustained weather (rate-limit blips) finally gave up with nothing to show: a
317// visible, retryable hint takes the popup so an outage degrades honestly instead
318// of an empty box that reads as "no matches" (issue #58).
319const searchUnavailable = ref(false)
320const activeIndex = ref(-1)
321// The listbox is the result popup; the unavailable hint is a separate, non-listbox
322// surface. aria-expanded / aria-controls track only this.
323const listboxOpen = computed(() => searchOpen.value && searchResults.value.length > 0)
324let searchDebounce: ReturnType<typeof setTimeout> | null = null
325let searchSeq = 0
326// Backoff for transient (rate-limit) misses: spaced retries before giving up, so a
327// throttled prefix like "Leonardo" gets time to clear rather than vanishing.
328const SEARCH_RETRY_DELAYS_MS = [800, 1600]
329// The name most recently CHOSEN (dropdown option, suggestion chip, contact chip):
330// the model change it causes must not reopen the dropdown over the fresh dossier.
331let lastChosen = ''
332 
333/** Closing also INVALIDATES any response still in flight: bumping the seq is what
334 *  keeps a slow fetch from reopening a stale dropdown over a chosen figure's
335 *  dossier, an emptied input, or a disabled one mid-send. It also cancels a pending
336 *  backoff retry — otherwise a timer armed before the dismissal would later fire and
337 *  pop the dropdown (or the unavailable hint) back up unprompted. */
338function closeSearch() {
339    if (searchDebounce) clearTimeout(searchDebounce)
340    searchDebounce = null
341    searchSeq++
342    searchResults.value = []
343    searchOpen.value = false
344    searchUnavailable.value = false
345    activeIndex.value = -1
346}
347 
348/** Deliberate selection from any surface: fill the input and stand down. */
349function choose(name: string) {
350    lastChosen = name
351    figure.value = name
352    closeSearch()
353}
354 
355/** Fire the actual lookup for the CURRENT seq; results land only if still current. */
356async function runSearch(q: string, seq: number, attempt = 0) {
357    try {
358        const res = await $fetch('/api/figure-search', { params: { q } }) as { results?: SearchResult[]; transient?: boolean }
359        if (seq !== searchSeq) return // closed, or a newer keystroke took over
360        const results = res?.results ?? []
361        // Weather, not absence: an empty answer the server marks transient must not
362        // read as "no matches" — keep whatever is showing and retry with backoff.
363        // (A new keystroke clears the timer; the seq guard drops a stale landing.)
364        if (!results.length && res?.transient) {
365            const delay = SEARCH_RETRY_DELAYS_MS[attempt]
366            if (delay != null) {
367                searchDebounce = setTimeout(() => { void runSearch(q, seq, attempt + 1) }, delay)
368            } else if (!searchResults.value.length) {
369                // Out of retries with nothing to fall back on: say so plainly and
370                // offer a retry, rather than an empty box that looks like "no matches".
371                searchUnavailable.value = true
372                searchOpen.value = true
373                activeIndex.value = -1
374            }
375            return
376        }
377        searchUnavailable.value = false
378        searchResults.value = results
379        searchOpen.value = results.length > 0
380        activeIndex.value = -1
381    } catch {
382        if (seq === searchSeq) closeSearch()
383    }
384}
385 
⋯ 132 lines hidden (lines 386–517)386/** Manual retry from the "unavailable" hint — refire the search for the current text.
387 *  Returns focus to the input first: clearing the hint unmounts the Retry button, and
388 *  a keyboard user activating it would otherwise have focus fall to <body>. */
389function retrySearch() {
390    const q = (figure.value || '').trim()
391    if (q.length < 2) return
392    searchInputRef.value?.focus()
393    searchUnavailable.value = false
394    void runSearch(q, ++searchSeq)
395}
396 
397watch(figure, (name) => {
398    if (searchDebounce) clearTimeout(searchDebounce)
399    const q = (name || '').trim()
400    if (q.length < 2 || q === lastChosen) {
401        closeSearch()
402        // One-shot suppression: it exists to swallow the single model echo a
403        // choice causes. A later deliberate retype of the same name searches again.
404        if (q === lastChosen) lastChosen = ''
405        return
406    }
407    lastChosen = ''
408    searchUnavailable.value = false // a fresh keystroke retires any prior outage hint
409    const seq = ++searchSeq
410    searchDebounce = setTimeout(() => { void runSearch(q, seq) }, 250)
411})
412 
413function onSearchKeydown(e: KeyboardEvent) {
414    if (e.isComposing) return // IME candidate navigation owns these keys
415    // Escape always dismisses: it must clear a populated listbox OR the unavailable
416    // hint, and — even when nothing is on screen yet — cancel a pending backoff retry
417    // and invalidate any in-flight fetch (closeSearch clears the timer and bumps the
418    // seq). Handled before the guard below, which only covers a populated listbox.
419    if (e.key === 'Escape') {
420        closeSearch()
421        return
422    }
423    if (!searchOpen.value || !searchResults.value.length) {
424        // APG editable-combobox: Down Arrow on a closed combobox reopens the popup
425        // (the only recovery after Escape that doesn't require editing the text).
426        if (e.key === 'ArrowDown') {
427            const q = (figure.value || '').trim()
428            if (q.length >= 2) {
429                e.preventDefault()
430                void runSearch(q, ++searchSeq)
431            }
432        }
433        return
434    }
435    if (e.key === 'ArrowDown') {
436        e.preventDefault()
437        activeIndex.value = (activeIndex.value + 1) % searchResults.value.length
438    } else if (e.key === 'ArrowUp') {
439        e.preventDefault()
440        activeIndex.value = activeIndex.value <= 0 ? searchResults.value.length - 1 : activeIndex.value - 1
441    } else if (e.key === 'Enter') {
442        if (activeIndex.value >= 0) {
443            e.preventDefault()
444            choose(searchResults.value[activeIndex.value].name)
445        }
446    }
447    // Escape is handled up top (it must also dismiss the unavailable hint, where
448    // searchResults is empty and this block is skipped).
449}
450 
451/** Close when focus genuinely leaves the combobox (not when it moves within it). */
452function onSearchFocusOut(e: FocusEvent) {
453    const next = e.relatedTarget as Node | null
454    if (next && searchBoxRef.value?.contains(next)) return
455    closeSearch()
456}
457 
458/** Spoken result count — aria-expanded alone is not reliably announced while typing. */
459const searchStatus = computed(() =>
460    searchUnavailable.value
461        ? 'The record is unreachable right now — press the down arrow or Retry to search again.'
462        : listboxOpen.value
463            ? `${searchResults.value.length} ${searchResults.value.length === 1 ? 'match' : 'matches'} — up and down arrows to review, Enter to choose`
464            : ''
465)
466 
467function chipClass(name: string) {
468    return name === figure.value ? 'rv-tint rv-fg' : 'rv-muted rv-hover'
469}
470function suggestionClass(name: string) {
471    return name === figure.value ? 'rv-tint' : 'rv-hover'
472}
473 
474// Ground the chosen figure, debounced so typing doesn't spam the lookup. The
475// PREVIOUS dossier is cleared synchronously the instant the name changes: a send
476// fired during the debounce/fetch window must go out clean (free-form), never
477// wearing the old figure's facts, year, or liveness gate.
478let debounce: ReturnType<typeof setTimeout> | null = null
479watch(figure, (name) => {
480    if (debounce) clearTimeout(debounce)
481    gameStore.clearGrounding()
482    const trimmed = (name || '').trim()
483    if (!trimmed) return
484    debounce = setTimeout(() => gameStore.groundActiveFigure(trimmed), 350)
485})
486onUnmounted(() => {
487    if (debounce) clearTimeout(debounce)
488    if (searchDebounce) clearTimeout(searchDebounce)
489})
490 
491// Load era-relevant suggestions for the current objective when the board appears.
492onMounted(() => gameStore.loadSuggestions())
493</script>
494 
495<style scoped>
496/* Quiet placeholder bars while the suggester works — letterpress tint, a gentle
497   pulse, stilled under reduced motion. Never a clickable fake. */
498.skeleton-line {
499    display: block;
500    height: 10px;
501    border-radius: 2px;
502    background: var(--rv-tint);
503    animation: skeleton-pulse 1.6s var(--rv-ease) infinite;
504}
505@keyframes skeleton-pulse {
506    0%, 100% { opacity: .55; }
507    50% { opacity: 1; }
508}
509@media (prefers-reduced-motion: reduce) {
510    .skeleton-line { animation: none; }
511}
512 
513/* The autocomplete pop floats over the dossier on warm paper, not chrome. */
514.search-pop {
515    box-shadow: 0 6px 18px color-mix(in srgb, var(--rv-fg) 10%, transparent);
516}
517</style>

The visible, retryable hint

When the give-up branch fires, the popup shows a plain status surface with a Retry button instead of an empty listbox. The v-else-if ties it to searchOpen && searchUnavailable, and it sits as a sibling of the listbox (v-if="listboxOpen"), so exactly one of the two ever renders.

The unavailable hint: a sibling of the listbox, with a Retry button.

components/FigurePicker.vue · 517 lines

components/FigurePicker.vue517 lines · Vue

⋯ 30 lines hidden (lines 1–30)1<template>
2  <div data-testid="figure-picker" class="space-y-3">
3    <div ref="searchBoxRef" class="relative" @focusout="onSearchFocusOut">
4      <label for="figure-input" class="rv-label block mb-1">Who in history will you reach?</label>
5      <input id="figure-input" ref="searchInputRef" v-model="figure" data-testid="figure-input" type="text"
6        class="rv-field rv-mono text-sm" placeholder="Anyone, any era — Cleopatra, Tesla, Genghis Khan…"
7        :disabled="disabled"
8        role="combobox" aria-autocomplete="list" :aria-expanded="listboxOpen ? 'true' : 'false'"
9        :aria-controls="listboxOpen ? 'figure-search-listbox' : undefined"
10        :aria-activedescendant="activeIndex >= 0 ? `figure-search-option-${activeIndex}` : undefined"
11        autocomplete="off" @keydown="onSearchKeydown" />
12      <span class="sr-only" role="status">{{ searchStatus }}</span>
13      <!-- Name autocomplete: Wikipedia title search, the description line telling
14           the pharaoh from the 1963 film. Picking one fills the input; grounding
15           fires exactly as if it had been typed. -->
16      <ul v-if="listboxOpen" id="figure-search-listbox" data-testid="figure-search-listbox" role="listbox"
17        aria-label="Matching names from the record"
18        class="search-pop absolute left-0 right-0 top-full mt-1 z-20 border rv-line rounded-sm rv-bg max-h-64 overflow-y-auto">
19        <li v-for="(r, i) in searchResults" :id="`figure-search-option-${i}`" :key="r.name" role="option"
20          :aria-selected="i === activeIndex ? 'true' : 'false'" data-testid="figure-search-option"
21          class="flex items-center gap-2 px-2.5 py-1.5 cursor-pointer text-sm"
22          :class="i === activeIndex ? 'rv-tint' : 'rv-hover'"
23          @mousedown.prevent @click="choose(r.name)" @mousemove="activeIndex = i">
24          <img v-if="r.thumbnail" :src="r.thumbnail" alt="" class="h-7 w-7 shrink-0 rounded object-cover" aria-hidden="true" />
25          <span v-else class="h-7 w-7 shrink-0 rounded rv-tint" aria-hidden="true" />
26          <span class="min-w-0">
27            <span class="rv-fg font-medium block truncate">{{ r.name }}</span>
28            <span v-if="r.description" class="rv-faint text-[11px] block truncate">{{ r.description }}</span>
29          </span>
30        </li>
31      </ul>
32      <!-- The search couldn't reach Wikipedia after its retries: a visible, retryable
33           hint so a rate-limit blip degrades honestly instead of an empty box that
34           reads as "no matches" (issue #58). The sr-only role=status span above is the
35           sole live region — this surface is NOT one, to avoid a double announcement. -->
36      <div v-else-if="searchOpen && searchUnavailable" data-testid="figure-search-unavailable"
37        class="search-pop absolute left-0 right-0 top-full mt-1 z-20 border rv-line rounded-sm rv-bg px-2.5 py-2 text-sm rv-muted flex items-center justify-between gap-2">
38        <span>Couldn't reach the record — a brief network hiccup.</span>
39        <button type="button" data-testid="figure-search-retry"
40          class="rv-accent text-[11px] font-medium hover:underline shrink-0"
41          @mousedown.prevent @click="retrySearch">Retry</button>
42      </div>
⋯ 475 lines hidden (lines 43–517)43    </div>
44 
45    <!-- Grounding: who they were, and when you reach them -->
46    <div v-if="groundingLoading" data-testid="grounding-loading" class="flex items-center gap-2 text-xs rv-faint">
47      <span class="rv-spinner" aria-hidden="true" />
48      Consulting the records…
49    </div>
50 
51    <div v-else-if="grounding?.resolved" data-testid="figure-dossier" class="rv-card p-3">
52      <div class="flex gap-3">
53        <img v-if="grounding.thumbnail" :src="grounding.thumbnail" :alt="grounding.name"
54          class="h-12 w-12 shrink-0 rounded object-cover" />
55        <div class="min-w-0 flex-1">
56          <div class="flex flex-wrap items-center gap-x-2 gap-y-0.5">
57            <span data-testid="dossier-name" class="rv-fg font-semibold text-sm">{{ grounding.name }}</span>
58            <span v-if="lifespan" data-testid="dossier-lifespan" class="rv-mono text-[11px] rv-faint">{{ lifespan }}</span>
59            <a v-if="grounding.wikiUrl" :href="grounding.wikiUrl" target="_blank" rel="noopener noreferrer"
60              class="rv-accent text-[11px]">Wikipedia ↗</a>
61          </div>
62          <p v-if="grounding.description" class="rv-muted text-xs mt-0.5">{{ grounding.description }}</p>
63 
64          <!-- When do you reach them? A promoted, lifetime-bounded playhead: the
65               chosen year + live age lead, big and in the accent, so the moment you're
66               writing into is the loudest thing in the dossier (not a buried micro-row). -->
67          <div v-if="hasLifespan" data-testid="when-control" class="mt-2.5 border-t rv-line pt-2.5">
68            <div class="flex items-baseline justify-between gap-2">
69              <span id="when-label" class="rv-label">Reach them in</span>
70              <span data-testid="when-display" class="rv-mono rv-accent text-lg font-bold leading-none">
71                {{ whenDisplay }}<span v-if="contactAge != null" data-testid="when-age" class="rv-faint text-xs font-normal"> · age {{ contactAge }}</span>
72              </span>
73            </div>
74            <input type="range" data-testid="when-slider" class="w-full mt-2" :style="{ accentColor: 'var(--rv-accent)' }"
75              :min="range.min" :max="range.max" :value="contactWhen ?? range.min" :disabled="disabled"
76              aria-labelledby="when-label" :aria-valuetext="whenValueText" @input="onWhenInput" />
77            <div class="flex items-center justify-between text-[10px] rv-faint rv-mono">
78              <span>{{ grounding.born?.display }} · born</span>
79              <span>{{ grounding.died?.display ? grounding.died.display + ' · died' : 'present' }}</span>
80            </div>
81 
82            <!-- Pin the moment (issue #32): an optional month/day refinement of the
83                 chosen year. Display + prompt flavor only — the year stays the value
84                 every mechanic computes with, so the wager, world-brief, and liveness
85                 gates are untouched by whatever is pinned here. -->
86            <div class="mt-1.5">
87              <button v-if="!momentOpen" type="button" data-testid="pin-moment"
88                class="rv-accent text-[11px] font-medium hover:underline disabled:opacity-50"
89                :disabled="disabled" @click="momentOpen = true">
90                <span aria-hidden="true">📍</span> {{ contactMoment ? 'adjust the moment' : 'pin the moment' }}
91              </button>
92              <div v-else data-testid="moment-picker">
93                <div class="flex flex-wrap gap-1" role="group" aria-label="Month of the contact">
94                  <button v-for="(m, i) in MONTH_NAMES" :key="m" type="button" data-testid="month-chip"
95                    class="rv-press border rv-line rounded-sm px-1.5 py-0.5 text-[10px]"
96                    :class="contactMoment?.month === i + 1 ? 'rv-tint rv-fg' : 'rv-muted rv-hover'"
97                    :aria-pressed="contactMoment?.month === i + 1 ? 'true' : 'false'"
98                    :disabled="disabled" @click="pickMonth(i + 1)">{{ m.slice(0, 3) }}</button>
99                </div>
100                <div class="flex items-center gap-1.5 mt-1">
101                  <template v-if="contactMoment">
102                    <label for="moment-day" class="rv-label">day</label>
103                    <input id="moment-day" data-testid="moment-day" type="number" inputmode="numeric"
104                      class="rv-field rv-mono text-xs w-16 px-1.5 py-0.5" min="1" :max="maxDay"
105                      :value="contactMoment.day ?? ''" :disabled="disabled" placeholder="—"
106                      @input="onDayInput" />
107                  </template>
108                  <button type="button" data-testid="unpin-moment"
109                    class="rv-faint text-[11px] hover:underline ml-auto" :disabled="disabled"
110                    @click="unpinMoment">{{ contactMoment ? 'unpin' : 'close' }}</button>
111                </div>
112              </div>
113            </div>
114          </div>
115 
116          <!-- Even the AI bridge couldn't date them: say so honestly instead of a
117               mysteriously absent control. The copy claims only the lookup outcome
118               (it may be a transient outage, not a dateless record). No manual year
119               here — the contact year prices the anachronism wager, so it stays
120               grounded or unset. -->
121          <p v-else data-testid="when-unknown" class="mt-2.5 border-t rv-line pt-2.5 text-[11px] italic rv-faint">
122            No dates could be found for them — your message will find them in their own time.
123          </p>
124 
125          <!-- The Archive: study who you're reaching, at the chosen moment -->
126          <div data-testid="archive" class="mt-2 border-t rv-line pt-2">
127            <button v-if="!studyShown" type="button" data-testid="study-button"
128              class="rv-accent text-[11px] font-medium hover:underline disabled:opacity-50"
129              :disabled="studyLoading || disabled" @click="studyThem">
130              <span aria-hidden="true">🔎</span> {{ studyLoading ? 'The Archivist consults the record…' : studyLabel }}
131            </button>
132 
133            <div v-else data-testid="figure-study" class="space-y-1 text-[11px] leading-snug rv-muted">
134              <p class="italic rv-fg">{{ figureStudy?.atThisMoment }}</p>
135              <p v-if="figureStudy?.grasp.length"><span class="rv-faint">grasps</span> {{ figureStudy?.grasp.join(' · ') }}</p>
136              <p v-if="figureStudy?.reaching.length"><span class="rv-faint">reaching</span> {{ figureStudy?.reaching.join(' · ') }}</p>
137              <p v-if="figureStudy?.cannotYetKnow" class="rv-warn"><span class="rv-faint">beyond them</span> {{ figureStudy?.cannotYetKnow }}</p>
138              <button v-if="yearMoved" type="button" data-testid="restudy-button"
139                class="rv-accent font-medium hover:underline disabled:opacity-50" :disabled="studyLoading || disabled" @click="studyThem">
140                <span aria-hidden="true">🔎</span> {{ studyLoading ? 'Consulting…' : restudyLabel }}
141              </button>
142            </div>
143 
144            <p v-if="studyNotice" data-testid="study-blocked" role="alert" aria-live="assertive"
145              class="mt-1 text-[11px] border-l-2 border-red-500/70 bg-red-500/5 pl-2 py-1 text-red-300">
146              <span class="font-semibold uppercase tracking-wide">⚠ blocked</span> {{ studyNotice }}
147            </p>
148          </div>
149        </div>
150      </div>
151    </div>
152 
153    <div v-else-if="grounding && !grounding.resolved" data-testid="figure-unresolved" class="text-xs italic rv-faint">
154      No record found for "{{ activeName }}" — you can still send a message into the unknown.
155    </div>
156 
157    <!-- Figures already contacted this run -->
158    <div v-if="contacted.length" class="flex flex-wrap items-center gap-1.5">
159      <span class="rv-label">contacts</span>
160      <button v-for="f in contacted" :key="f.name" type="button" data-testid="contact-chip"
161        class="rv-press text-xs px-2 py-0.5 border rv-line rounded-sm inline-flex items-center gap-1.5" :class="chipClass(f.name)" @click="select(f.name)">
162        <span class="rv-dot" :class="f.name === figure ? 'rv-dot--accent' : 'rv-dot--hollow'" aria-hidden="true" />{{ f.name }}
163      </button>
164    </div>
165 
166    <!-- Era-relevant figures for this objective (the on-ramp); you can still type anyone. -->
167    <div class="space-y-1.5">
168      <span class="rv-label block" aria-live="polite">{{ suggestionsLabel }}</span>
169      <p v-if="suggestionsNotice" data-testid="suggestions-blocked" role="alert" aria-live="assertive"
170        class="text-[11px] border-l-2 border-red-500/70 bg-red-500/5 pl-2 py-1 text-red-300">
171        <span class="font-semibold uppercase tracking-wide">⚠ blocked</span> {{ suggestionsNotice }}
172      </p>
173      <!-- While the era-aware agent works: quiet skeleton chips — never clickable
174           generic defaults masquerading as objective-relevant picks. The famous-
175           names fallback appears only AFTER the agent has genuinely come up empty,
176           labeled honestly as what it is. -->
177      <div v-if="suggestionsPending" data-testid="suggestion-skeletons" class="flex flex-col gap-1" aria-hidden="true">
178        <div v-for="i in 3" :key="i" class="border rv-line rounded-sm px-2.5 py-2">
179          <span class="skeleton-line w-32" />
180          <span class="skeleton-line w-48 mt-1.5" />
181        </div>
182      </div>
183      <div v-else class="flex flex-col gap-1">
184        <button v-for="s in displaySuggestions" :key="s.name" type="button" data-testid="suggestion-chip"
185          class="rv-press border rv-line rounded-sm px-2.5 py-1.5 text-left" :class="suggestionClass(s.name)" @click="select(s.name)">
186          <span class="text-sm rv-fg font-medium">{{ s.name }}</span>
187          <span v-if="s.lifespan" class="ml-1.5 rv-mono text-[10px] rv-faint">{{ s.lifespan }}</span>
188          <span v-if="s.reason" data-testid="suggestion-reason" class="block text-[11px] leading-snug rv-faint">{{ s.reason }}</span>
189        </button>
190      </div>
191    </div>
192  </div>
193</template>
194 
195<script setup lang="ts">
196/**
197 * FigurePicker — choose whom (free-form name, suggestion, or prior contact) and, once
198 * grounded, when to reach them (a lifetime-bounded slider with a live age). The
199 * Archive's "study them" brief discloses who they are at that moment. Re-skin only —
200 * every store binding (grounding, contactWhen, study, suggestions) is unchanged.
201 */
202import { computed, watch, onMounted, onUnmounted } from 'vue'
203import { useGameStore } from '~/stores/game'
204import { formatContactMoment, MONTH_NAMES, MONTH_MAX_DAY } from '~/utils/contact-moment'
205import type { FigureSuggestion } from '~/server/utils/figure-suggester'
206 
207const figure = defineModel<string>({ default: '' })
208defineProps<{ disabled?: boolean }>()
209 
210const gameStore = useGameStore()
211const contacted = computed(() => gameStore.figures)
212const figureSuggestions = computed(() => gameStore.figureSuggestions)
213const suggestionsLoading = computed(() => gameStore.suggestionsLoading)
214const suggestionsNotice = computed(() => gameStore.suggestionsNotice)
215const grounding = computed(() => gameStore.figureGrounding)
216const groundingLoading = computed(() => gameStore.groundingLoading)
217const contactWhen = computed(() => gameStore.contactWhen)
218const contactAge = computed(() => gameStore.contactAge)
219const activeName = computed(() => figure.value.trim())
220 
221const hasLifespan = computed(() => !!(grounding.value?.resolved && grounding.value.born))
222const lifespan = computed(() => {
223    const g = grounding.value
224    if (!g?.born) return ''
225    if (g.died) return `${g.born.display} – ${g.died.display}`
226    return g.living ? `${g.born.display} – present` : g.born.display
227})
228const range = computed(() => ({
229    min: grounding.value?.born?.signed ?? 0,
230    max: grounding.value?.died?.signed ?? new Date().getFullYear()
231}))
232const contactMoment = computed(() => gameStore.contactMoment)
233const whenDisplay = computed(() => (contactWhen.value != null ? formatContactMoment(contactWhen.value, contactMoment.value) : ''))
234// What AT announces for the slider: the human year + live age (e.g. "44 BC · age 25"),
235// not the raw signed integer the value attribute carries.
236const whenValueText = computed(() =>
237    contactWhen.value == null ? '' : whenDisplay.value + (contactAge.value != null ? ` · age ${contactAge.value}` : '')
238)
239 
240function onWhenInput(e: Event) {
241    gameStore.setContactWhen(Number((e.target as HTMLInputElement).value))
242}
243 
244// --- Pin the moment (issue #32): month chips + optional day, year-canonical ---
245const momentOpen = ref(false)
246const maxDay = computed(() => (contactMoment.value ? MONTH_MAX_DAY[contactMoment.value.month - 1] : 31))
247function pickMonth(month: number) {
248    const current = gameStore.contactMoment
249    if (current?.month === month) return
250    // Switching months keeps the day where it stays valid, clamps where it doesn't.
251    const day = current?.day ? Math.min(current.day, MONTH_MAX_DAY[month - 1]) : undefined
252    gameStore.setContactMoment(day ? { month, day } : { month })
253}
254function onDayInput(e: Event) {
255    const current = gameStore.contactMoment
256    if (!current) return
257    const raw = Number((e.target as HTMLInputElement).value)
258    if (!Number.isInteger(raw) || raw < 1) {
259        gameStore.setContactMoment({ month: current.month })
260        return
261    }
262    gameStore.setContactMoment({ month: current.month, day: Math.min(raw, MONTH_MAX_DAY[current.month - 1]) })
263}
264function unpinMoment() {
265    gameStore.setContactMoment(null)
266    momentOpen.value = false
267}
268 
269// The Archive: study the grounded figure in-game, at the chosen moment.
270const figureStudy = computed(() => gameStore.figureStudy)
271const studyLoading = computed(() => gameStore.studyLoading)
272const studyNotice = computed(() => gameStore.studyNotice)
273const studyShown = computed(() => !!figureStudy.value && gameStore.studyFor === grounding.value?.name)
274const yearMoved = computed(() => studyShown.value && gameStore.studyWhen !== contactWhen.value)
275const studyLabel = computed(() => (contactWhen.value != null ? `Study them in ${whenDisplay.value}` : 'Study them'))
276const restudyLabel = computed(() => (contactWhen.value != null ? `Re-study in ${whenDisplay.value}` : 'Re-study'))
277function studyThem() { gameStore.studyActiveFigure() }
278 
279const LOCAL_DEFAULT: FigureSuggestion[] = [
280    { name: 'Cleopatra', reason: '' },
281    { name: 'Nikola Tesla', reason: '' },
282    { name: 'Genghis Khan', reason: '' },
283    { name: 'Marie Curie', reason: '' },
284    { name: 'Leonardo da Vinci', reason: '' }
285]
286const displaySuggestions = computed(() => (figureSuggestions.value.length ? figureSuggestions.value : LOCAL_DEFAULT))
287// Pending = in flight, OR simply not yet asked for this objective — the latter
288// covers the first painted frame (loadSuggestions fires onMounted, after render),
289// which would otherwise flash the clickable famous-names fallback for one frame.
290// The store records suggestionsFor even on failure, so a genuine miss still
291// settles into the honest fallback rather than skeletons forever.
292const suggestionsPending = computed(() =>
293    !figureSuggestions.value.length && (
294        suggestionsLoading.value ||
295        (!!gameStore.currentObjective && gameStore.suggestionsFor !== gameStore.currentObjective.title)
296    )
297)
298const suggestionsLabel = computed(() =>
299    suggestionsPending.value
300        ? 'finding figures who matter here…'
301        : figureSuggestions.value.length
302            ? 'figures who might matter here'
303            : 'some famous names to start with'
304)
305 
306function select(name: string) {
307    choose(name)
308}
309 
310// --- Name autocomplete (a combobox over Wikipedia title search) ---
311interface SearchResult { name: string; description?: string; thumbnail?: string }
312const searchBoxRef = ref<HTMLElement | null>(null)
313const searchInputRef = ref<HTMLInputElement | null>(null)
314const searchResults = ref<SearchResult[]>([])
315const searchOpen = ref(false)
316// Sustained weather (rate-limit blips) finally gave up with nothing to show: a
317// visible, retryable hint takes the popup so an outage degrades honestly instead
318// of an empty box that reads as "no matches" (issue #58).
319const searchUnavailable = ref(false)
320const activeIndex = ref(-1)
321// The listbox is the result popup; the unavailable hint is a separate, non-listbox
322// surface. aria-expanded / aria-controls track only this.
323const listboxOpen = computed(() => searchOpen.value && searchResults.value.length > 0)
324let searchDebounce: ReturnType<typeof setTimeout> | null = null
325let searchSeq = 0
326// Backoff for transient (rate-limit) misses: spaced retries before giving up, so a
327// throttled prefix like "Leonardo" gets time to clear rather than vanishing.
328const SEARCH_RETRY_DELAYS_MS = [800, 1600]
329// The name most recently CHOSEN (dropdown option, suggestion chip, contact chip):
330// the model change it causes must not reopen the dropdown over the fresh dossier.
331let lastChosen = ''
332 
333/** Closing also INVALIDATES any response still in flight: bumping the seq is what
334 *  keeps a slow fetch from reopening a stale dropdown over a chosen figure's
335 *  dossier, an emptied input, or a disabled one mid-send. It also cancels a pending
336 *  backoff retry — otherwise a timer armed before the dismissal would later fire and
337 *  pop the dropdown (or the unavailable hint) back up unprompted. */
338function closeSearch() {
339    if (searchDebounce) clearTimeout(searchDebounce)
340    searchDebounce = null
341    searchSeq++
342    searchResults.value = []
343    searchOpen.value = false
344    searchUnavailable.value = false
345    activeIndex.value = -1
346}
347 
348/** Deliberate selection from any surface: fill the input and stand down. */
349function choose(name: string) {
350    lastChosen = name
351    figure.value = name
352    closeSearch()
353}
354 
355/** Fire the actual lookup for the CURRENT seq; results land only if still current. */
356async function runSearch(q: string, seq: number, attempt = 0) {
357    try {
358        const res = await $fetch('/api/figure-search', { params: { q } }) as { results?: SearchResult[]; transient?: boolean }
359        if (seq !== searchSeq) return // closed, or a newer keystroke took over
360        const results = res?.results ?? []
361        // Weather, not absence: an empty answer the server marks transient must not
362        // read as "no matches" — keep whatever is showing and retry with backoff.
363        // (A new keystroke clears the timer; the seq guard drops a stale landing.)
364        if (!results.length && res?.transient) {
365            const delay = SEARCH_RETRY_DELAYS_MS[attempt]
366            if (delay != null) {
367                searchDebounce = setTimeout(() => { void runSearch(q, seq, attempt + 1) }, delay)
368            } else if (!searchResults.value.length) {
369                // Out of retries with nothing to fall back on: say so plainly and
370                // offer a retry, rather than an empty box that looks like "no matches".
371                searchUnavailable.value = true
372                searchOpen.value = true
373                activeIndex.value = -1
374            }
375            return
376        }
377        searchUnavailable.value = false
378        searchResults.value = results
379        searchOpen.value = results.length > 0
380        activeIndex.value = -1
381    } catch {
382        if (seq === searchSeq) closeSearch()
383    }
384}
385 
386/** Manual retry from the "unavailable" hint — refire the search for the current text.
387 *  Returns focus to the input first: clearing the hint unmounts the Retry button, and
388 *  a keyboard user activating it would otherwise have focus fall to <body>. */
389function retrySearch() {
390    const q = (figure.value || '').trim()
391    if (q.length < 2) return
392    searchInputRef.value?.focus()
393    searchUnavailable.value = false
394    void runSearch(q, ++searchSeq)
395}
396 
397watch(figure, (name) => {
398    if (searchDebounce) clearTimeout(searchDebounce)
399    const q = (name || '').trim()
400    if (q.length < 2 || q === lastChosen) {
401        closeSearch()
402        // One-shot suppression: it exists to swallow the single model echo a
403        // choice causes. A later deliberate retype of the same name searches again.
404        if (q === lastChosen) lastChosen = ''
405        return
406    }
407    lastChosen = ''
408    searchUnavailable.value = false // a fresh keystroke retires any prior outage hint
409    const seq = ++searchSeq
410    searchDebounce = setTimeout(() => { void runSearch(q, seq) }, 250)
411})
412 
413function onSearchKeydown(e: KeyboardEvent) {
414    if (e.isComposing) return // IME candidate navigation owns these keys
415    // Escape always dismisses: it must clear a populated listbox OR the unavailable
416    // hint, and — even when nothing is on screen yet — cancel a pending backoff retry
417    // and invalidate any in-flight fetch (closeSearch clears the timer and bumps the
418    // seq). Handled before the guard below, which only covers a populated listbox.
419    if (e.key === 'Escape') {
420        closeSearch()
421        return
422    }
423    if (!searchOpen.value || !searchResults.value.length) {
424        // APG editable-combobox: Down Arrow on a closed combobox reopens the popup
425        // (the only recovery after Escape that doesn't require editing the text).
426        if (e.key === 'ArrowDown') {
427            const q = (figure.value || '').trim()
428            if (q.length >= 2) {
429                e.preventDefault()
430                void runSearch(q, ++searchSeq)
431            }
432        }
433        return
434    }
435    if (e.key === 'ArrowDown') {
436        e.preventDefault()
437        activeIndex.value = (activeIndex.value + 1) % searchResults.value.length
438    } else if (e.key === 'ArrowUp') {
439        e.preventDefault()
440        activeIndex.value = activeIndex.value <= 0 ? searchResults.value.length - 1 : activeIndex.value - 1
441    } else if (e.key === 'Enter') {
442        if (activeIndex.value >= 0) {
443            e.preventDefault()
444            choose(searchResults.value[activeIndex.value].name)
445        }
446    }
447    // Escape is handled up top (it must also dismiss the unavailable hint, where
448    // searchResults is empty and this block is skipped).
449}
450 
451/** Close when focus genuinely leaves the combobox (not when it moves within it). */
452function onSearchFocusOut(e: FocusEvent) {
453    const next = e.relatedTarget as Node | null
454    if (next && searchBoxRef.value?.contains(next)) return
455    closeSearch()
456}
457 
458/** Spoken result count — aria-expanded alone is not reliably announced while typing. */
459const searchStatus = computed(() =>
460    searchUnavailable.value
461        ? 'The record is unreachable right now — press the down arrow or Retry to search again.'
462        : listboxOpen.value
463            ? `${searchResults.value.length} ${searchResults.value.length === 1 ? 'match' : 'matches'} — up and down arrows to review, Enter to choose`
464            : ''
465)
466 
467function chipClass(name: string) {
468    return name === figure.value ? 'rv-tint rv-fg' : 'rv-muted rv-hover'
469}
470function suggestionClass(name: string) {
471    return name === figure.value ? 'rv-tint' : 'rv-hover'
472}
473 
474// Ground the chosen figure, debounced so typing doesn't spam the lookup. The
475// PREVIOUS dossier is cleared synchronously the instant the name changes: a send
476// fired during the debounce/fetch window must go out clean (free-form), never
477// wearing the old figure's facts, year, or liveness gate.
478let debounce: ReturnType<typeof setTimeout> | null = null
479watch(figure, (name) => {
480    if (debounce) clearTimeout(debounce)
481    gameStore.clearGrounding()
482    const trimmed = (name || '').trim()
483    if (!trimmed) return
484    debounce = setTimeout(() => gameStore.groundActiveFigure(trimmed), 350)
485})
486onUnmounted(() => {
487    if (debounce) clearTimeout(debounce)
488    if (searchDebounce) clearTimeout(searchDebounce)
489})
490 
491// Load era-relevant suggestions for the current objective when the board appears.
492onMounted(() => gameStore.loadSuggestions())
493</script>
494 
495<style scoped>
496/* Quiet placeholder bars while the suggester works — letterpress tint, a gentle
497   pulse, stilled under reduced motion. Never a clickable fake. */
498.skeleton-line {
499    display: block;
500    height: 10px;
501    border-radius: 2px;
502    background: var(--rv-tint);
503    animation: skeleton-pulse 1.6s var(--rv-ease) infinite;
504}
505@keyframes skeleton-pulse {
506    0%, 100% { opacity: .55; }
507    50% { opacity: 1; }
508}
509@media (prefers-reduced-motion: reduce) {
510    .skeleton-line { animation: none; }
511}
512 
513/* The autocomplete pop floats over the dossier on warm paper, not chrome. */
514.search-pop {
515    box-shadow: 0 6px 18px color-mix(in srgb, var(--rv-fg) 10%, transparent);
516}
517</style>

Screen-reader users get the same honesty through the existing sr-only status region (line 12). Its computed gains an outage branch that announces the failure and how to recover — deliberately not the misleading "0 matches" the old code would have read out when searchOpen was true with zero results.

The status computed: outage message first, then the match count, else silent.

components/FigurePicker.vue · 517 lines

components/FigurePicker.vue517 lines · Vue

⋯ 457 lines hidden (lines 1–457)1<template>
2  <div data-testid="figure-picker" class="space-y-3">
3    <div ref="searchBoxRef" class="relative" @focusout="onSearchFocusOut">
4      <label for="figure-input" class="rv-label block mb-1">Who in history will you reach?</label>
5      <input id="figure-input" ref="searchInputRef" v-model="figure" data-testid="figure-input" type="text"
6        class="rv-field rv-mono text-sm" placeholder="Anyone, any era — Cleopatra, Tesla, Genghis Khan…"
7        :disabled="disabled"
8        role="combobox" aria-autocomplete="list" :aria-expanded="listboxOpen ? 'true' : 'false'"
9        :aria-controls="listboxOpen ? 'figure-search-listbox' : undefined"
10        :aria-activedescendant="activeIndex >= 0 ? `figure-search-option-${activeIndex}` : undefined"
11        autocomplete="off" @keydown="onSearchKeydown" />
12      <span class="sr-only" role="status">{{ searchStatus }}</span>
13      <!-- Name autocomplete: Wikipedia title search, the description line telling
14           the pharaoh from the 1963 film. Picking one fills the input; grounding
15           fires exactly as if it had been typed. -->
16      <ul v-if="listboxOpen" id="figure-search-listbox" data-testid="figure-search-listbox" role="listbox"
17        aria-label="Matching names from the record"
18        class="search-pop absolute left-0 right-0 top-full mt-1 z-20 border rv-line rounded-sm rv-bg max-h-64 overflow-y-auto">
19        <li v-for="(r, i) in searchResults" :id="`figure-search-option-${i}`" :key="r.name" role="option"
20          :aria-selected="i === activeIndex ? 'true' : 'false'" data-testid="figure-search-option"
21          class="flex items-center gap-2 px-2.5 py-1.5 cursor-pointer text-sm"
22          :class="i === activeIndex ? 'rv-tint' : 'rv-hover'"
23          @mousedown.prevent @click="choose(r.name)" @mousemove="activeIndex = i">
24          <img v-if="r.thumbnail" :src="r.thumbnail" alt="" class="h-7 w-7 shrink-0 rounded object-cover" aria-hidden="true" />
25          <span v-else class="h-7 w-7 shrink-0 rounded rv-tint" aria-hidden="true" />
26          <span class="min-w-0">
27            <span class="rv-fg font-medium block truncate">{{ r.name }}</span>
28            <span v-if="r.description" class="rv-faint text-[11px] block truncate">{{ r.description }}</span>
29          </span>
30        </li>
31      </ul>
32      <!-- The search couldn't reach Wikipedia after its retries: a visible, retryable
33           hint so a rate-limit blip degrades honestly instead of an empty box that
34           reads as "no matches" (issue #58). The sr-only role=status span above is the
35           sole live region — this surface is NOT one, to avoid a double announcement. -->
36      <div v-else-if="searchOpen && searchUnavailable" data-testid="figure-search-unavailable"
37        class="search-pop absolute left-0 right-0 top-full mt-1 z-20 border rv-line rounded-sm rv-bg px-2.5 py-2 text-sm rv-muted flex items-center justify-between gap-2">
38        <span>Couldn't reach the record — a brief network hiccup.</span>
39        <button type="button" data-testid="figure-search-retry"
40          class="rv-accent text-[11px] font-medium hover:underline shrink-0"
41          @mousedown.prevent @click="retrySearch">Retry</button>
42      </div>
43    </div>
44 
45    <!-- Grounding: who they were, and when you reach them -->
46    <div v-if="groundingLoading" data-testid="grounding-loading" class="flex items-center gap-2 text-xs rv-faint">
47      <span class="rv-spinner" aria-hidden="true" />
48      Consulting the records…
49    </div>
50 
51    <div v-else-if="grounding?.resolved" data-testid="figure-dossier" class="rv-card p-3">
52      <div class="flex gap-3">
53        <img v-if="grounding.thumbnail" :src="grounding.thumbnail" :alt="grounding.name"
54          class="h-12 w-12 shrink-0 rounded object-cover" />
55        <div class="min-w-0 flex-1">
56          <div class="flex flex-wrap items-center gap-x-2 gap-y-0.5">
57            <span data-testid="dossier-name" class="rv-fg font-semibold text-sm">{{ grounding.name }}</span>
58            <span v-if="lifespan" data-testid="dossier-lifespan" class="rv-mono text-[11px] rv-faint">{{ lifespan }}</span>
59            <a v-if="grounding.wikiUrl" :href="grounding.wikiUrl" target="_blank" rel="noopener noreferrer"
60              class="rv-accent text-[11px]">Wikipedia ↗</a>
61          </div>
62          <p v-if="grounding.description" class="rv-muted text-xs mt-0.5">{{ grounding.description }}</p>
63 
64          <!-- When do you reach them? A promoted, lifetime-bounded playhead: the
65               chosen year + live age lead, big and in the accent, so the moment you're
66               writing into is the loudest thing in the dossier (not a buried micro-row). -->
67          <div v-if="hasLifespan" data-testid="when-control" class="mt-2.5 border-t rv-line pt-2.5">
68            <div class="flex items-baseline justify-between gap-2">
69              <span id="when-label" class="rv-label">Reach them in</span>
70              <span data-testid="when-display" class="rv-mono rv-accent text-lg font-bold leading-none">
71                {{ whenDisplay }}<span v-if="contactAge != null" data-testid="when-age" class="rv-faint text-xs font-normal"> · age {{ contactAge }}</span>
72              </span>
73            </div>
74            <input type="range" data-testid="when-slider" class="w-full mt-2" :style="{ accentColor: 'var(--rv-accent)' }"
75              :min="range.min" :max="range.max" :value="contactWhen ?? range.min" :disabled="disabled"
76              aria-labelledby="when-label" :aria-valuetext="whenValueText" @input="onWhenInput" />
77            <div class="flex items-center justify-between text-[10px] rv-faint rv-mono">
78              <span>{{ grounding.born?.display }} · born</span>
79              <span>{{ grounding.died?.display ? grounding.died.display + ' · died' : 'present' }}</span>
80            </div>
81 
82            <!-- Pin the moment (issue #32): an optional month/day refinement of the
83                 chosen year. Display + prompt flavor only — the year stays the value
84                 every mechanic computes with, so the wager, world-brief, and liveness
85                 gates are untouched by whatever is pinned here. -->
86            <div class="mt-1.5">
87              <button v-if="!momentOpen" type="button" data-testid="pin-moment"
88                class="rv-accent text-[11px] font-medium hover:underline disabled:opacity-50"
89                :disabled="disabled" @click="momentOpen = true">
90                <span aria-hidden="true">📍</span> {{ contactMoment ? 'adjust the moment' : 'pin the moment' }}
91              </button>
92              <div v-else data-testid="moment-picker">
93                <div class="flex flex-wrap gap-1" role="group" aria-label="Month of the contact">
94                  <button v-for="(m, i) in MONTH_NAMES" :key="m" type="button" data-testid="month-chip"
95                    class="rv-press border rv-line rounded-sm px-1.5 py-0.5 text-[10px]"
96                    :class="contactMoment?.month === i + 1 ? 'rv-tint rv-fg' : 'rv-muted rv-hover'"
97                    :aria-pressed="contactMoment?.month === i + 1 ? 'true' : 'false'"
98                    :disabled="disabled" @click="pickMonth(i + 1)">{{ m.slice(0, 3) }}</button>
99                </div>
100                <div class="flex items-center gap-1.5 mt-1">
101                  <template v-if="contactMoment">
102                    <label for="moment-day" class="rv-label">day</label>
103                    <input id="moment-day" data-testid="moment-day" type="number" inputmode="numeric"
104                      class="rv-field rv-mono text-xs w-16 px-1.5 py-0.5" min="1" :max="maxDay"
105                      :value="contactMoment.day ?? ''" :disabled="disabled" placeholder="—"
106                      @input="onDayInput" />
107                  </template>
108                  <button type="button" data-testid="unpin-moment"
109                    class="rv-faint text-[11px] hover:underline ml-auto" :disabled="disabled"
110                    @click="unpinMoment">{{ contactMoment ? 'unpin' : 'close' }}</button>
111                </div>
112              </div>
113            </div>
114          </div>
115 
116          <!-- Even the AI bridge couldn't date them: say so honestly instead of a
117               mysteriously absent control. The copy claims only the lookup outcome
118               (it may be a transient outage, not a dateless record). No manual year
119               here — the contact year prices the anachronism wager, so it stays
120               grounded or unset. -->
121          <p v-else data-testid="when-unknown" class="mt-2.5 border-t rv-line pt-2.5 text-[11px] italic rv-faint">
122            No dates could be found for them — your message will find them in their own time.
123          </p>
124 
125          <!-- The Archive: study who you're reaching, at the chosen moment -->
126          <div data-testid="archive" class="mt-2 border-t rv-line pt-2">
127            <button v-if="!studyShown" type="button" data-testid="study-button"
128              class="rv-accent text-[11px] font-medium hover:underline disabled:opacity-50"
129              :disabled="studyLoading || disabled" @click="studyThem">
130              <span aria-hidden="true">🔎</span> {{ studyLoading ? 'The Archivist consults the record…' : studyLabel }}
131            </button>
132 
133            <div v-else data-testid="figure-study" class="space-y-1 text-[11px] leading-snug rv-muted">
134              <p class="italic rv-fg">{{ figureStudy?.atThisMoment }}</p>
135              <p v-if="figureStudy?.grasp.length"><span class="rv-faint">grasps</span> {{ figureStudy?.grasp.join(' · ') }}</p>
136              <p v-if="figureStudy?.reaching.length"><span class="rv-faint">reaching</span> {{ figureStudy?.reaching.join(' · ') }}</p>
137              <p v-if="figureStudy?.cannotYetKnow" class="rv-warn"><span class="rv-faint">beyond them</span> {{ figureStudy?.cannotYetKnow }}</p>
138              <button v-if="yearMoved" type="button" data-testid="restudy-button"
139                class="rv-accent font-medium hover:underline disabled:opacity-50" :disabled="studyLoading || disabled" @click="studyThem">
140                <span aria-hidden="true">🔎</span> {{ studyLoading ? 'Consulting…' : restudyLabel }}
141              </button>
142            </div>
143 
144            <p v-if="studyNotice" data-testid="study-blocked" role="alert" aria-live="assertive"
145              class="mt-1 text-[11px] border-l-2 border-red-500/70 bg-red-500/5 pl-2 py-1 text-red-300">
146              <span class="font-semibold uppercase tracking-wide">⚠ blocked</span> {{ studyNotice }}
147            </p>
148          </div>
149        </div>
150      </div>
151    </div>
152 
153    <div v-else-if="grounding && !grounding.resolved" data-testid="figure-unresolved" class="text-xs italic rv-faint">
154      No record found for "{{ activeName }}" — you can still send a message into the unknown.
155    </div>
156 
157    <!-- Figures already contacted this run -->
158    <div v-if="contacted.length" class="flex flex-wrap items-center gap-1.5">
159      <span class="rv-label">contacts</span>
160      <button v-for="f in contacted" :key="f.name" type="button" data-testid="contact-chip"
161        class="rv-press text-xs px-2 py-0.5 border rv-line rounded-sm inline-flex items-center gap-1.5" :class="chipClass(f.name)" @click="select(f.name)">
162        <span class="rv-dot" :class="f.name === figure ? 'rv-dot--accent' : 'rv-dot--hollow'" aria-hidden="true" />{{ f.name }}
163      </button>
164    </div>
165 
166    <!-- Era-relevant figures for this objective (the on-ramp); you can still type anyone. -->
167    <div class="space-y-1.5">
168      <span class="rv-label block" aria-live="polite">{{ suggestionsLabel }}</span>
169      <p v-if="suggestionsNotice" data-testid="suggestions-blocked" role="alert" aria-live="assertive"
170        class="text-[11px] border-l-2 border-red-500/70 bg-red-500/5 pl-2 py-1 text-red-300">
171        <span class="font-semibold uppercase tracking-wide">⚠ blocked</span> {{ suggestionsNotice }}
172      </p>
173      <!-- While the era-aware agent works: quiet skeleton chips — never clickable
174           generic defaults masquerading as objective-relevant picks. The famous-
175           names fallback appears only AFTER the agent has genuinely come up empty,
176           labeled honestly as what it is. -->
177      <div v-if="suggestionsPending" data-testid="suggestion-skeletons" class="flex flex-col gap-1" aria-hidden="true">
178        <div v-for="i in 3" :key="i" class="border rv-line rounded-sm px-2.5 py-2">
179          <span class="skeleton-line w-32" />
180          <span class="skeleton-line w-48 mt-1.5" />
181        </div>
182      </div>
183      <div v-else class="flex flex-col gap-1">
184        <button v-for="s in displaySuggestions" :key="s.name" type="button" data-testid="suggestion-chip"
185          class="rv-press border rv-line rounded-sm px-2.5 py-1.5 text-left" :class="suggestionClass(s.name)" @click="select(s.name)">
186          <span class="text-sm rv-fg font-medium">{{ s.name }}</span>
187          <span v-if="s.lifespan" class="ml-1.5 rv-mono text-[10px] rv-faint">{{ s.lifespan }}</span>
188          <span v-if="s.reason" data-testid="suggestion-reason" class="block text-[11px] leading-snug rv-faint">{{ s.reason }}</span>
189        </button>
190      </div>
191    </div>
192  </div>
193</template>
194 
195<script setup lang="ts">
196/**
197 * FigurePicker — choose whom (free-form name, suggestion, or prior contact) and, once
198 * grounded, when to reach them (a lifetime-bounded slider with a live age). The
199 * Archive's "study them" brief discloses who they are at that moment. Re-skin only —
200 * every store binding (grounding, contactWhen, study, suggestions) is unchanged.
201 */
202import { computed, watch, onMounted, onUnmounted } from 'vue'
203import { useGameStore } from '~/stores/game'
204import { formatContactMoment, MONTH_NAMES, MONTH_MAX_DAY } from '~/utils/contact-moment'
205import type { FigureSuggestion } from '~/server/utils/figure-suggester'
206 
207const figure = defineModel<string>({ default: '' })
208defineProps<{ disabled?: boolean }>()
209 
210const gameStore = useGameStore()
211const contacted = computed(() => gameStore.figures)
212const figureSuggestions = computed(() => gameStore.figureSuggestions)
213const suggestionsLoading = computed(() => gameStore.suggestionsLoading)
214const suggestionsNotice = computed(() => gameStore.suggestionsNotice)
215const grounding = computed(() => gameStore.figureGrounding)
216const groundingLoading = computed(() => gameStore.groundingLoading)
217const contactWhen = computed(() => gameStore.contactWhen)
218const contactAge = computed(() => gameStore.contactAge)
219const activeName = computed(() => figure.value.trim())
220 
221const hasLifespan = computed(() => !!(grounding.value?.resolved && grounding.value.born))
222const lifespan = computed(() => {
223    const g = grounding.value
224    if (!g?.born) return ''
225    if (g.died) return `${g.born.display} – ${g.died.display}`
226    return g.living ? `${g.born.display} – present` : g.born.display
227})
228const range = computed(() => ({
229    min: grounding.value?.born?.signed ?? 0,
230    max: grounding.value?.died?.signed ?? new Date().getFullYear()
231}))
232const contactMoment = computed(() => gameStore.contactMoment)
233const whenDisplay = computed(() => (contactWhen.value != null ? formatContactMoment(contactWhen.value, contactMoment.value) : ''))
234// What AT announces for the slider: the human year + live age (e.g. "44 BC · age 25"),
235// not the raw signed integer the value attribute carries.
236const whenValueText = computed(() =>
237    contactWhen.value == null ? '' : whenDisplay.value + (contactAge.value != null ? ` · age ${contactAge.value}` : '')
238)
239 
240function onWhenInput(e: Event) {
241    gameStore.setContactWhen(Number((e.target as HTMLInputElement).value))
242}
243 
244// --- Pin the moment (issue #32): month chips + optional day, year-canonical ---
245const momentOpen = ref(false)
246const maxDay = computed(() => (contactMoment.value ? MONTH_MAX_DAY[contactMoment.value.month - 1] : 31))
247function pickMonth(month: number) {
248    const current = gameStore.contactMoment
249    if (current?.month === month) return
250    // Switching months keeps the day where it stays valid, clamps where it doesn't.
251    const day = current?.day ? Math.min(current.day, MONTH_MAX_DAY[month - 1]) : undefined
252    gameStore.setContactMoment(day ? { month, day } : { month })
253}
254function onDayInput(e: Event) {
255    const current = gameStore.contactMoment
256    if (!current) return
257    const raw = Number((e.target as HTMLInputElement).value)
258    if (!Number.isInteger(raw) || raw < 1) {
259        gameStore.setContactMoment({ month: current.month })
260        return
261    }
262    gameStore.setContactMoment({ month: current.month, day: Math.min(raw, MONTH_MAX_DAY[current.month - 1]) })
263}
264function unpinMoment() {
265    gameStore.setContactMoment(null)
266    momentOpen.value = false
267}
268 
269// The Archive: study the grounded figure in-game, at the chosen moment.
270const figureStudy = computed(() => gameStore.figureStudy)
271const studyLoading = computed(() => gameStore.studyLoading)
272const studyNotice = computed(() => gameStore.studyNotice)
273const studyShown = computed(() => !!figureStudy.value && gameStore.studyFor === grounding.value?.name)
274const yearMoved = computed(() => studyShown.value && gameStore.studyWhen !== contactWhen.value)
275const studyLabel = computed(() => (contactWhen.value != null ? `Study them in ${whenDisplay.value}` : 'Study them'))
276const restudyLabel = computed(() => (contactWhen.value != null ? `Re-study in ${whenDisplay.value}` : 'Re-study'))
277function studyThem() { gameStore.studyActiveFigure() }
278 
279const LOCAL_DEFAULT: FigureSuggestion[] = [
280    { name: 'Cleopatra', reason: '' },
281    { name: 'Nikola Tesla', reason: '' },
282    { name: 'Genghis Khan', reason: '' },
283    { name: 'Marie Curie', reason: '' },
284    { name: 'Leonardo da Vinci', reason: '' }
285]
286const displaySuggestions = computed(() => (figureSuggestions.value.length ? figureSuggestions.value : LOCAL_DEFAULT))
287// Pending = in flight, OR simply not yet asked for this objective — the latter
288// covers the first painted frame (loadSuggestions fires onMounted, after render),
289// which would otherwise flash the clickable famous-names fallback for one frame.
290// The store records suggestionsFor even on failure, so a genuine miss still
291// settles into the honest fallback rather than skeletons forever.
292const suggestionsPending = computed(() =>
293    !figureSuggestions.value.length && (
294        suggestionsLoading.value ||
295        (!!gameStore.currentObjective && gameStore.suggestionsFor !== gameStore.currentObjective.title)
296    )
297)
298const suggestionsLabel = computed(() =>
299    suggestionsPending.value
300        ? 'finding figures who matter here…'
301        : figureSuggestions.value.length
302            ? 'figures who might matter here'
303            : 'some famous names to start with'
304)
305 
306function select(name: string) {
307    choose(name)
308}
309 
310// --- Name autocomplete (a combobox over Wikipedia title search) ---
311interface SearchResult { name: string; description?: string; thumbnail?: string }
312const searchBoxRef = ref<HTMLElement | null>(null)
313const searchInputRef = ref<HTMLInputElement | null>(null)
314const searchResults = ref<SearchResult[]>([])
315const searchOpen = ref(false)
316// Sustained weather (rate-limit blips) finally gave up with nothing to show: a
317// visible, retryable hint takes the popup so an outage degrades honestly instead
318// of an empty box that reads as "no matches" (issue #58).
319const searchUnavailable = ref(false)
320const activeIndex = ref(-1)
321// The listbox is the result popup; the unavailable hint is a separate, non-listbox
322// surface. aria-expanded / aria-controls track only this.
323const listboxOpen = computed(() => searchOpen.value && searchResults.value.length > 0)
324let searchDebounce: ReturnType<typeof setTimeout> | null = null
325let searchSeq = 0
326// Backoff for transient (rate-limit) misses: spaced retries before giving up, so a
327// throttled prefix like "Leonardo" gets time to clear rather than vanishing.
328const SEARCH_RETRY_DELAYS_MS = [800, 1600]
329// The name most recently CHOSEN (dropdown option, suggestion chip, contact chip):
330// the model change it causes must not reopen the dropdown over the fresh dossier.
331let lastChosen = ''
332 
333/** Closing also INVALIDATES any response still in flight: bumping the seq is what
334 *  keeps a slow fetch from reopening a stale dropdown over a chosen figure's
335 *  dossier, an emptied input, or a disabled one mid-send. It also cancels a pending
336 *  backoff retry — otherwise a timer armed before the dismissal would later fire and
337 *  pop the dropdown (or the unavailable hint) back up unprompted. */
338function closeSearch() {
339    if (searchDebounce) clearTimeout(searchDebounce)
340    searchDebounce = null
341    searchSeq++
342    searchResults.value = []
343    searchOpen.value = false
344    searchUnavailable.value = false
345    activeIndex.value = -1
346}
347 
348/** Deliberate selection from any surface: fill the input and stand down. */
349function choose(name: string) {
350    lastChosen = name
351    figure.value = name
352    closeSearch()
353}
354 
355/** Fire the actual lookup for the CURRENT seq; results land only if still current. */
356async function runSearch(q: string, seq: number, attempt = 0) {
357    try {
358        const res = await $fetch('/api/figure-search', { params: { q } }) as { results?: SearchResult[]; transient?: boolean }
359        if (seq !== searchSeq) return // closed, or a newer keystroke took over
360        const results = res?.results ?? []
361        // Weather, not absence: an empty answer the server marks transient must not
362        // read as "no matches" — keep whatever is showing and retry with backoff.
363        // (A new keystroke clears the timer; the seq guard drops a stale landing.)
364        if (!results.length && res?.transient) {
365            const delay = SEARCH_RETRY_DELAYS_MS[attempt]
366            if (delay != null) {
367                searchDebounce = setTimeout(() => { void runSearch(q, seq, attempt + 1) }, delay)
368            } else if (!searchResults.value.length) {
369                // Out of retries with nothing to fall back on: say so plainly and
370                // offer a retry, rather than an empty box that looks like "no matches".
371                searchUnavailable.value = true
372                searchOpen.value = true
373                activeIndex.value = -1
374            }
375            return
376        }
377        searchUnavailable.value = false
378        searchResults.value = results
379        searchOpen.value = results.length > 0
380        activeIndex.value = -1
381    } catch {
382        if (seq === searchSeq) closeSearch()
383    }
384}
385 
386/** Manual retry from the "unavailable" hint — refire the search for the current text.
387 *  Returns focus to the input first: clearing the hint unmounts the Retry button, and
388 *  a keyboard user activating it would otherwise have focus fall to <body>. */
389function retrySearch() {
390    const q = (figure.value || '').trim()
391    if (q.length < 2) return
392    searchInputRef.value?.focus()
393    searchUnavailable.value = false
394    void runSearch(q, ++searchSeq)
395}
396 
397watch(figure, (name) => {
398    if (searchDebounce) clearTimeout(searchDebounce)
399    const q = (name || '').trim()
400    if (q.length < 2 || q === lastChosen) {
401        closeSearch()
402        // One-shot suppression: it exists to swallow the single model echo a
403        // choice causes. A later deliberate retype of the same name searches again.
404        if (q === lastChosen) lastChosen = ''
405        return
406    }
407    lastChosen = ''
408    searchUnavailable.value = false // a fresh keystroke retires any prior outage hint
409    const seq = ++searchSeq
410    searchDebounce = setTimeout(() => { void runSearch(q, seq) }, 250)
411})
412 
413function onSearchKeydown(e: KeyboardEvent) {
414    if (e.isComposing) return // IME candidate navigation owns these keys
415    // Escape always dismisses: it must clear a populated listbox OR the unavailable
416    // hint, and — even when nothing is on screen yet — cancel a pending backoff retry
417    // and invalidate any in-flight fetch (closeSearch clears the timer and bumps the
418    // seq). Handled before the guard below, which only covers a populated listbox.
419    if (e.key === 'Escape') {
420        closeSearch()
421        return
422    }
423    if (!searchOpen.value || !searchResults.value.length) {
424        // APG editable-combobox: Down Arrow on a closed combobox reopens the popup
425        // (the only recovery after Escape that doesn't require editing the text).
426        if (e.key === 'ArrowDown') {
427            const q = (figure.value || '').trim()
428            if (q.length >= 2) {
429                e.preventDefault()
430                void runSearch(q, ++searchSeq)
431            }
432        }
433        return
434    }
435    if (e.key === 'ArrowDown') {
436        e.preventDefault()
437        activeIndex.value = (activeIndex.value + 1) % searchResults.value.length
438    } else if (e.key === 'ArrowUp') {
439        e.preventDefault()
440        activeIndex.value = activeIndex.value <= 0 ? searchResults.value.length - 1 : activeIndex.value - 1
441    } else if (e.key === 'Enter') {
442        if (activeIndex.value >= 0) {
443            e.preventDefault()
444            choose(searchResults.value[activeIndex.value].name)
445        }
446    }
447    // Escape is handled up top (it must also dismiss the unavailable hint, where
448    // searchResults is empty and this block is skipped).
449}
450 
451/** Close when focus genuinely leaves the combobox (not when it moves within it). */
452function onSearchFocusOut(e: FocusEvent) {
453    const next = e.relatedTarget as Node | null
454    if (next && searchBoxRef.value?.contains(next)) return
455    closeSearch()
456}
457 
458/** Spoken result count — aria-expanded alone is not reliably announced while typing. */
459const searchStatus = computed(() =>
460    searchUnavailable.value
461        ? 'The record is unreachable right now — press the down arrow or Retry to search again.'
462        : listboxOpen.value
463            ? `${searchResults.value.length} ${searchResults.value.length === 1 ? 'match' : 'matches'} — up and down arrows to review, Enter to choose`
464            : ''
465)
⋯ 52 lines hidden (lines 466–517)466 
467function chipClass(name: string) {
468    return name === figure.value ? 'rv-tint rv-fg' : 'rv-muted rv-hover'
469}
470function suggestionClass(name: string) {
471    return name === figure.value ? 'rv-tint' : 'rv-hover'
472}
473 
474// Ground the chosen figure, debounced so typing doesn't spam the lookup. The
475// PREVIOUS dossier is cleared synchronously the instant the name changes: a send
476// fired during the debounce/fetch window must go out clean (free-form), never
477// wearing the old figure's facts, year, or liveness gate.
478let debounce: ReturnType<typeof setTimeout> | null = null
479watch(figure, (name) => {
480    if (debounce) clearTimeout(debounce)
481    gameStore.clearGrounding()
482    const trimmed = (name || '').trim()
483    if (!trimmed) return
484    debounce = setTimeout(() => gameStore.groundActiveFigure(trimmed), 350)
485})
486onUnmounted(() => {
487    if (debounce) clearTimeout(debounce)
488    if (searchDebounce) clearTimeout(searchDebounce)
489})
490 
491// Load era-relevant suggestions for the current objective when the board appears.
492onMounted(() => gameStore.loadSuggestions())
493</script>
494 
495<style scoped>
496/* Quiet placeholder bars while the suggester works — letterpress tint, a gentle
497   pulse, stilled under reduced motion. Never a clickable fake. */
498.skeleton-line {
499    display: block;
500    height: 10px;
501    border-radius: 2px;
502    background: var(--rv-tint);
503    animation: skeleton-pulse 1.6s var(--rv-ease) infinite;
504}
505@keyframes skeleton-pulse {
506    0%, 100% { opacity: .55; }
507    50% { opacity: 1; }
508}
509@media (prefers-reduced-motion: reduce) {
510    .skeleton-line { animation: none; }
511}
512 
513/* The autocomplete pop floats over the dossier on warm paper, not chrome. */
514.search-pop {
515    box-shadow: 0 6px 18px color-mix(in srgb, var(--rv-fg) 10%, transparent);
516}
517</style>

Dismissal and focus correctness

Three small correctness points, all surfaced by an adversarial review of the diff. First, closeSearch now cancels any pending backoff timer. A retry armed before a dismissal would otherwise fire later and pop the dropdown — or the unavailable hint — back up over a field the player had walked away from.

closeSearch clears the timer (and bumps the seq) so no armed retry resurfaces.

components/FigurePicker.vue · 517 lines

components/FigurePicker.vue517 lines · Vue

⋯ 330 lines hidden (lines 1–330)1<template>
2  <div data-testid="figure-picker" class="space-y-3">
3    <div ref="searchBoxRef" class="relative" @focusout="onSearchFocusOut">
4      <label for="figure-input" class="rv-label block mb-1">Who in history will you reach?</label>
5      <input id="figure-input" ref="searchInputRef" v-model="figure" data-testid="figure-input" type="text"
6        class="rv-field rv-mono text-sm" placeholder="Anyone, any era — Cleopatra, Tesla, Genghis Khan…"
7        :disabled="disabled"
8        role="combobox" aria-autocomplete="list" :aria-expanded="listboxOpen ? 'true' : 'false'"
9        :aria-controls="listboxOpen ? 'figure-search-listbox' : undefined"
10        :aria-activedescendant="activeIndex >= 0 ? `figure-search-option-${activeIndex}` : undefined"
11        autocomplete="off" @keydown="onSearchKeydown" />
12      <span class="sr-only" role="status">{{ searchStatus }}</span>
13      <!-- Name autocomplete: Wikipedia title search, the description line telling
14           the pharaoh from the 1963 film. Picking one fills the input; grounding
15           fires exactly as if it had been typed. -->
16      <ul v-if="listboxOpen" id="figure-search-listbox" data-testid="figure-search-listbox" role="listbox"
17        aria-label="Matching names from the record"
18        class="search-pop absolute left-0 right-0 top-full mt-1 z-20 border rv-line rounded-sm rv-bg max-h-64 overflow-y-auto">
19        <li v-for="(r, i) in searchResults" :id="`figure-search-option-${i}`" :key="r.name" role="option"
20          :aria-selected="i === activeIndex ? 'true' : 'false'" data-testid="figure-search-option"
21          class="flex items-center gap-2 px-2.5 py-1.5 cursor-pointer text-sm"
22          :class="i === activeIndex ? 'rv-tint' : 'rv-hover'"
23          @mousedown.prevent @click="choose(r.name)" @mousemove="activeIndex = i">
24          <img v-if="r.thumbnail" :src="r.thumbnail" alt="" class="h-7 w-7 shrink-0 rounded object-cover" aria-hidden="true" />
25          <span v-else class="h-7 w-7 shrink-0 rounded rv-tint" aria-hidden="true" />
26          <span class="min-w-0">
27            <span class="rv-fg font-medium block truncate">{{ r.name }}</span>
28            <span v-if="r.description" class="rv-faint text-[11px] block truncate">{{ r.description }}</span>
29          </span>
30        </li>
31      </ul>
32      <!-- The search couldn't reach Wikipedia after its retries: a visible, retryable
33           hint so a rate-limit blip degrades honestly instead of an empty box that
34           reads as "no matches" (issue #58). The sr-only role=status span above is the
35           sole live region — this surface is NOT one, to avoid a double announcement. -->
36      <div v-else-if="searchOpen && searchUnavailable" data-testid="figure-search-unavailable"
37        class="search-pop absolute left-0 right-0 top-full mt-1 z-20 border rv-line rounded-sm rv-bg px-2.5 py-2 text-sm rv-muted flex items-center justify-between gap-2">
38        <span>Couldn't reach the record — a brief network hiccup.</span>
39        <button type="button" data-testid="figure-search-retry"
40          class="rv-accent text-[11px] font-medium hover:underline shrink-0"
41          @mousedown.prevent @click="retrySearch">Retry</button>
42      </div>
43    </div>
44 
45    <!-- Grounding: who they were, and when you reach them -->
46    <div v-if="groundingLoading" data-testid="grounding-loading" class="flex items-center gap-2 text-xs rv-faint">
47      <span class="rv-spinner" aria-hidden="true" />
48      Consulting the records…
49    </div>
50 
51    <div v-else-if="grounding?.resolved" data-testid="figure-dossier" class="rv-card p-3">
52      <div class="flex gap-3">
53        <img v-if="grounding.thumbnail" :src="grounding.thumbnail" :alt="grounding.name"
54          class="h-12 w-12 shrink-0 rounded object-cover" />
55        <div class="min-w-0 flex-1">
56          <div class="flex flex-wrap items-center gap-x-2 gap-y-0.5">
57            <span data-testid="dossier-name" class="rv-fg font-semibold text-sm">{{ grounding.name }}</span>
58            <span v-if="lifespan" data-testid="dossier-lifespan" class="rv-mono text-[11px] rv-faint">{{ lifespan }}</span>
59            <a v-if="grounding.wikiUrl" :href="grounding.wikiUrl" target="_blank" rel="noopener noreferrer"
60              class="rv-accent text-[11px]">Wikipedia ↗</a>
61          </div>
62          <p v-if="grounding.description" class="rv-muted text-xs mt-0.5">{{ grounding.description }}</p>
63 
64          <!-- When do you reach them? A promoted, lifetime-bounded playhead: the
65               chosen year + live age lead, big and in the accent, so the moment you're
66               writing into is the loudest thing in the dossier (not a buried micro-row). -->
67          <div v-if="hasLifespan" data-testid="when-control" class="mt-2.5 border-t rv-line pt-2.5">
68            <div class="flex items-baseline justify-between gap-2">
69              <span id="when-label" class="rv-label">Reach them in</span>
70              <span data-testid="when-display" class="rv-mono rv-accent text-lg font-bold leading-none">
71                {{ whenDisplay }}<span v-if="contactAge != null" data-testid="when-age" class="rv-faint text-xs font-normal"> · age {{ contactAge }}</span>
72              </span>
73            </div>
74            <input type="range" data-testid="when-slider" class="w-full mt-2" :style="{ accentColor: 'var(--rv-accent)' }"
75              :min="range.min" :max="range.max" :value="contactWhen ?? range.min" :disabled="disabled"
76              aria-labelledby="when-label" :aria-valuetext="whenValueText" @input="onWhenInput" />
77            <div class="flex items-center justify-between text-[10px] rv-faint rv-mono">
78              <span>{{ grounding.born?.display }} · born</span>
79              <span>{{ grounding.died?.display ? grounding.died.display + ' · died' : 'present' }}</span>
80            </div>
81 
82            <!-- Pin the moment (issue #32): an optional month/day refinement of the
83                 chosen year. Display + prompt flavor only — the year stays the value
84                 every mechanic computes with, so the wager, world-brief, and liveness
85                 gates are untouched by whatever is pinned here. -->
86            <div class="mt-1.5">
87              <button v-if="!momentOpen" type="button" data-testid="pin-moment"
88                class="rv-accent text-[11px] font-medium hover:underline disabled:opacity-50"
89                :disabled="disabled" @click="momentOpen = true">
90                <span aria-hidden="true">📍</span> {{ contactMoment ? 'adjust the moment' : 'pin the moment' }}
91              </button>
92              <div v-else data-testid="moment-picker">
93                <div class="flex flex-wrap gap-1" role="group" aria-label="Month of the contact">
94                  <button v-for="(m, i) in MONTH_NAMES" :key="m" type="button" data-testid="month-chip"
95                    class="rv-press border rv-line rounded-sm px-1.5 py-0.5 text-[10px]"
96                    :class="contactMoment?.month === i + 1 ? 'rv-tint rv-fg' : 'rv-muted rv-hover'"
97                    :aria-pressed="contactMoment?.month === i + 1 ? 'true' : 'false'"
98                    :disabled="disabled" @click="pickMonth(i + 1)">{{ m.slice(0, 3) }}</button>
99                </div>
100                <div class="flex items-center gap-1.5 mt-1">
101                  <template v-if="contactMoment">
102                    <label for="moment-day" class="rv-label">day</label>
103                    <input id="moment-day" data-testid="moment-day" type="number" inputmode="numeric"
104                      class="rv-field rv-mono text-xs w-16 px-1.5 py-0.5" min="1" :max="maxDay"
105                      :value="contactMoment.day ?? ''" :disabled="disabled" placeholder="—"
106                      @input="onDayInput" />
107                  </template>
108                  <button type="button" data-testid="unpin-moment"
109                    class="rv-faint text-[11px] hover:underline ml-auto" :disabled="disabled"
110                    @click="unpinMoment">{{ contactMoment ? 'unpin' : 'close' }}</button>
111                </div>
112              </div>
113            </div>
114          </div>
115 
116          <!-- Even the AI bridge couldn't date them: say so honestly instead of a
117               mysteriously absent control. The copy claims only the lookup outcome
118               (it may be a transient outage, not a dateless record). No manual year
119               here — the contact year prices the anachronism wager, so it stays
120               grounded or unset. -->
121          <p v-else data-testid="when-unknown" class="mt-2.5 border-t rv-line pt-2.5 text-[11px] italic rv-faint">
122            No dates could be found for them — your message will find them in their own time.
123          </p>
124 
125          <!-- The Archive: study who you're reaching, at the chosen moment -->
126          <div data-testid="archive" class="mt-2 border-t rv-line pt-2">
127            <button v-if="!studyShown" type="button" data-testid="study-button"
128              class="rv-accent text-[11px] font-medium hover:underline disabled:opacity-50"
129              :disabled="studyLoading || disabled" @click="studyThem">
130              <span aria-hidden="true">🔎</span> {{ studyLoading ? 'The Archivist consults the record…' : studyLabel }}
131            </button>
132 
133            <div v-else data-testid="figure-study" class="space-y-1 text-[11px] leading-snug rv-muted">
134              <p class="italic rv-fg">{{ figureStudy?.atThisMoment }}</p>
135              <p v-if="figureStudy?.grasp.length"><span class="rv-faint">grasps</span> {{ figureStudy?.grasp.join(' · ') }}</p>
136              <p v-if="figureStudy?.reaching.length"><span class="rv-faint">reaching</span> {{ figureStudy?.reaching.join(' · ') }}</p>
137              <p v-if="figureStudy?.cannotYetKnow" class="rv-warn"><span class="rv-faint">beyond them</span> {{ figureStudy?.cannotYetKnow }}</p>
138              <button v-if="yearMoved" type="button" data-testid="restudy-button"
139                class="rv-accent font-medium hover:underline disabled:opacity-50" :disabled="studyLoading || disabled" @click="studyThem">
140                <span aria-hidden="true">🔎</span> {{ studyLoading ? 'Consulting…' : restudyLabel }}
141              </button>
142            </div>
143 
144            <p v-if="studyNotice" data-testid="study-blocked" role="alert" aria-live="assertive"
145              class="mt-1 text-[11px] border-l-2 border-red-500/70 bg-red-500/5 pl-2 py-1 text-red-300">
146              <span class="font-semibold uppercase tracking-wide">⚠ blocked</span> {{ studyNotice }}
147            </p>
148          </div>
149        </div>
150      </div>
151    </div>
152 
153    <div v-else-if="grounding && !grounding.resolved" data-testid="figure-unresolved" class="text-xs italic rv-faint">
154      No record found for "{{ activeName }}" — you can still send a message into the unknown.
155    </div>
156 
157    <!-- Figures already contacted this run -->
158    <div v-if="contacted.length" class="flex flex-wrap items-center gap-1.5">
159      <span class="rv-label">contacts</span>
160      <button v-for="f in contacted" :key="f.name" type="button" data-testid="contact-chip"
161        class="rv-press text-xs px-2 py-0.5 border rv-line rounded-sm inline-flex items-center gap-1.5" :class="chipClass(f.name)" @click="select(f.name)">
162        <span class="rv-dot" :class="f.name === figure ? 'rv-dot--accent' : 'rv-dot--hollow'" aria-hidden="true" />{{ f.name }}
163      </button>
164    </div>
165 
166    <!-- Era-relevant figures for this objective (the on-ramp); you can still type anyone. -->
167    <div class="space-y-1.5">
168      <span class="rv-label block" aria-live="polite">{{ suggestionsLabel }}</span>
169      <p v-if="suggestionsNotice" data-testid="suggestions-blocked" role="alert" aria-live="assertive"
170        class="text-[11px] border-l-2 border-red-500/70 bg-red-500/5 pl-2 py-1 text-red-300">
171        <span class="font-semibold uppercase tracking-wide">⚠ blocked</span> {{ suggestionsNotice }}
172      </p>
173      <!-- While the era-aware agent works: quiet skeleton chips — never clickable
174           generic defaults masquerading as objective-relevant picks. The famous-
175           names fallback appears only AFTER the agent has genuinely come up empty,
176           labeled honestly as what it is. -->
177      <div v-if="suggestionsPending" data-testid="suggestion-skeletons" class="flex flex-col gap-1" aria-hidden="true">
178        <div v-for="i in 3" :key="i" class="border rv-line rounded-sm px-2.5 py-2">
179          <span class="skeleton-line w-32" />
180          <span class="skeleton-line w-48 mt-1.5" />
181        </div>
182      </div>
183      <div v-else class="flex flex-col gap-1">
184        <button v-for="s in displaySuggestions" :key="s.name" type="button" data-testid="suggestion-chip"
185          class="rv-press border rv-line rounded-sm px-2.5 py-1.5 text-left" :class="suggestionClass(s.name)" @click="select(s.name)">
186          <span class="text-sm rv-fg font-medium">{{ s.name }}</span>
187          <span v-if="s.lifespan" class="ml-1.5 rv-mono text-[10px] rv-faint">{{ s.lifespan }}</span>
188          <span v-if="s.reason" data-testid="suggestion-reason" class="block text-[11px] leading-snug rv-faint">{{ s.reason }}</span>
189        </button>
190      </div>
191    </div>
192  </div>
193</template>
194 
195<script setup lang="ts">
196/**
197 * FigurePicker — choose whom (free-form name, suggestion, or prior contact) and, once
198 * grounded, when to reach them (a lifetime-bounded slider with a live age). The
199 * Archive's "study them" brief discloses who they are at that moment. Re-skin only —
200 * every store binding (grounding, contactWhen, study, suggestions) is unchanged.
201 */
202import { computed, watch, onMounted, onUnmounted } from 'vue'
203import { useGameStore } from '~/stores/game'
204import { formatContactMoment, MONTH_NAMES, MONTH_MAX_DAY } from '~/utils/contact-moment'
205import type { FigureSuggestion } from '~/server/utils/figure-suggester'
206 
207const figure = defineModel<string>({ default: '' })
208defineProps<{ disabled?: boolean }>()
209 
210const gameStore = useGameStore()
211const contacted = computed(() => gameStore.figures)
212const figureSuggestions = computed(() => gameStore.figureSuggestions)
213const suggestionsLoading = computed(() => gameStore.suggestionsLoading)
214const suggestionsNotice = computed(() => gameStore.suggestionsNotice)
215const grounding = computed(() => gameStore.figureGrounding)
216const groundingLoading = computed(() => gameStore.groundingLoading)
217const contactWhen = computed(() => gameStore.contactWhen)
218const contactAge = computed(() => gameStore.contactAge)
219const activeName = computed(() => figure.value.trim())
220 
221const hasLifespan = computed(() => !!(grounding.value?.resolved && grounding.value.born))
222const lifespan = computed(() => {
223    const g = grounding.value
224    if (!g?.born) return ''
225    if (g.died) return `${g.born.display} – ${g.died.display}`
226    return g.living ? `${g.born.display} – present` : g.born.display
227})
228const range = computed(() => ({
229    min: grounding.value?.born?.signed ?? 0,
230    max: grounding.value?.died?.signed ?? new Date().getFullYear()
231}))
232const contactMoment = computed(() => gameStore.contactMoment)
233const whenDisplay = computed(() => (contactWhen.value != null ? formatContactMoment(contactWhen.value, contactMoment.value) : ''))
234// What AT announces for the slider: the human year + live age (e.g. "44 BC · age 25"),
235// not the raw signed integer the value attribute carries.
236const whenValueText = computed(() =>
237    contactWhen.value == null ? '' : whenDisplay.value + (contactAge.value != null ? ` · age ${contactAge.value}` : '')
238)
239 
240function onWhenInput(e: Event) {
241    gameStore.setContactWhen(Number((e.target as HTMLInputElement).value))
242}
243 
244// --- Pin the moment (issue #32): month chips + optional day, year-canonical ---
245const momentOpen = ref(false)
246const maxDay = computed(() => (contactMoment.value ? MONTH_MAX_DAY[contactMoment.value.month - 1] : 31))
247function pickMonth(month: number) {
248    const current = gameStore.contactMoment
249    if (current?.month === month) return
250    // Switching months keeps the day where it stays valid, clamps where it doesn't.
251    const day = current?.day ? Math.min(current.day, MONTH_MAX_DAY[month - 1]) : undefined
252    gameStore.setContactMoment(day ? { month, day } : { month })
253}
254function onDayInput(e: Event) {
255    const current = gameStore.contactMoment
256    if (!current) return
257    const raw = Number((e.target as HTMLInputElement).value)
258    if (!Number.isInteger(raw) || raw < 1) {
259        gameStore.setContactMoment({ month: current.month })
260        return
261    }
262    gameStore.setContactMoment({ month: current.month, day: Math.min(raw, MONTH_MAX_DAY[current.month - 1]) })
263}
264function unpinMoment() {
265    gameStore.setContactMoment(null)
266    momentOpen.value = false
267}
268 
269// The Archive: study the grounded figure in-game, at the chosen moment.
270const figureStudy = computed(() => gameStore.figureStudy)
271const studyLoading = computed(() => gameStore.studyLoading)
272const studyNotice = computed(() => gameStore.studyNotice)
273const studyShown = computed(() => !!figureStudy.value && gameStore.studyFor === grounding.value?.name)
274const yearMoved = computed(() => studyShown.value && gameStore.studyWhen !== contactWhen.value)
275const studyLabel = computed(() => (contactWhen.value != null ? `Study them in ${whenDisplay.value}` : 'Study them'))
276const restudyLabel = computed(() => (contactWhen.value != null ? `Re-study in ${whenDisplay.value}` : 'Re-study'))
277function studyThem() { gameStore.studyActiveFigure() }
278 
279const LOCAL_DEFAULT: FigureSuggestion[] = [
280    { name: 'Cleopatra', reason: '' },
281    { name: 'Nikola Tesla', reason: '' },
282    { name: 'Genghis Khan', reason: '' },
283    { name: 'Marie Curie', reason: '' },
284    { name: 'Leonardo da Vinci', reason: '' }
285]
286const displaySuggestions = computed(() => (figureSuggestions.value.length ? figureSuggestions.value : LOCAL_DEFAULT))
287// Pending = in flight, OR simply not yet asked for this objective — the latter
288// covers the first painted frame (loadSuggestions fires onMounted, after render),
289// which would otherwise flash the clickable famous-names fallback for one frame.
290// The store records suggestionsFor even on failure, so a genuine miss still
291// settles into the honest fallback rather than skeletons forever.
292const suggestionsPending = computed(() =>
293    !figureSuggestions.value.length && (
294        suggestionsLoading.value ||
295        (!!gameStore.currentObjective && gameStore.suggestionsFor !== gameStore.currentObjective.title)
296    )
297)
298const suggestionsLabel = computed(() =>
299    suggestionsPending.value
300        ? 'finding figures who matter here…'
301        : figureSuggestions.value.length
302            ? 'figures who might matter here'
303            : 'some famous names to start with'
304)
305 
306function select(name: string) {
307    choose(name)
308}
309 
310// --- Name autocomplete (a combobox over Wikipedia title search) ---
311interface SearchResult { name: string; description?: string; thumbnail?: string }
312const searchBoxRef = ref<HTMLElement | null>(null)
313const searchInputRef = ref<HTMLInputElement | null>(null)
314const searchResults = ref<SearchResult[]>([])
315const searchOpen = ref(false)
316// Sustained weather (rate-limit blips) finally gave up with nothing to show: a
317// visible, retryable hint takes the popup so an outage degrades honestly instead
318// of an empty box that reads as "no matches" (issue #58).
319const searchUnavailable = ref(false)
320const activeIndex = ref(-1)
321// The listbox is the result popup; the unavailable hint is a separate, non-listbox
322// surface. aria-expanded / aria-controls track only this.
323const listboxOpen = computed(() => searchOpen.value && searchResults.value.length > 0)
324let searchDebounce: ReturnType<typeof setTimeout> | null = null
325let searchSeq = 0
326// Backoff for transient (rate-limit) misses: spaced retries before giving up, so a
327// throttled prefix like "Leonardo" gets time to clear rather than vanishing.
328const SEARCH_RETRY_DELAYS_MS = [800, 1600]
329// The name most recently CHOSEN (dropdown option, suggestion chip, contact chip):
330// the model change it causes must not reopen the dropdown over the fresh dossier.
331let lastChosen = ''
332 
333/** Closing also INVALIDATES any response still in flight: bumping the seq is what
334 *  keeps a slow fetch from reopening a stale dropdown over a chosen figure's
335 *  dossier, an emptied input, or a disabled one mid-send. It also cancels a pending
336 *  backoff retry — otherwise a timer armed before the dismissal would later fire and
337 *  pop the dropdown (or the unavailable hint) back up unprompted. */
338function closeSearch() {
339    if (searchDebounce) clearTimeout(searchDebounce)
340    searchDebounce = null
341    searchSeq++
342    searchResults.value = []
343    searchOpen.value = false
344    searchUnavailable.value = false
345    activeIndex.value = -1
346}
347 
348/** Deliberate selection from any surface: fill the input and stand down. */
349function choose(name: string) {
⋯ 168 lines hidden (lines 350–517)350    lastChosen = name
351    figure.value = name
352    closeSearch()
353}
354 
355/** Fire the actual lookup for the CURRENT seq; results land only if still current. */
356async function runSearch(q: string, seq: number, attempt = 0) {
357    try {
358        const res = await $fetch('/api/figure-search', { params: { q } }) as { results?: SearchResult[]; transient?: boolean }
359        if (seq !== searchSeq) return // closed, or a newer keystroke took over
360        const results = res?.results ?? []
361        // Weather, not absence: an empty answer the server marks transient must not
362        // read as "no matches" — keep whatever is showing and retry with backoff.
363        // (A new keystroke clears the timer; the seq guard drops a stale landing.)
364        if (!results.length && res?.transient) {
365            const delay = SEARCH_RETRY_DELAYS_MS[attempt]
366            if (delay != null) {
367                searchDebounce = setTimeout(() => { void runSearch(q, seq, attempt + 1) }, delay)
368            } else if (!searchResults.value.length) {
369                // Out of retries with nothing to fall back on: say so plainly and
370                // offer a retry, rather than an empty box that looks like "no matches".
371                searchUnavailable.value = true
372                searchOpen.value = true
373                activeIndex.value = -1
374            }
375            return
376        }
377        searchUnavailable.value = false
378        searchResults.value = results
379        searchOpen.value = results.length > 0
380        activeIndex.value = -1
381    } catch {
382        if (seq === searchSeq) closeSearch()
383    }
384}
385 
386/** Manual retry from the "unavailable" hint — refire the search for the current text.
387 *  Returns focus to the input first: clearing the hint unmounts the Retry button, and
388 *  a keyboard user activating it would otherwise have focus fall to <body>. */
389function retrySearch() {
390    const q = (figure.value || '').trim()
391    if (q.length < 2) return
392    searchInputRef.value?.focus()
393    searchUnavailable.value = false
394    void runSearch(q, ++searchSeq)
395}
396 
397watch(figure, (name) => {
398    if (searchDebounce) clearTimeout(searchDebounce)
399    const q = (name || '').trim()
400    if (q.length < 2 || q === lastChosen) {
401        closeSearch()
402        // One-shot suppression: it exists to swallow the single model echo a
403        // choice causes. A later deliberate retype of the same name searches again.
404        if (q === lastChosen) lastChosen = ''
405        return
406    }
407    lastChosen = ''
408    searchUnavailable.value = false // a fresh keystroke retires any prior outage hint
409    const seq = ++searchSeq
410    searchDebounce = setTimeout(() => { void runSearch(q, seq) }, 250)
411})
412 
413function onSearchKeydown(e: KeyboardEvent) {
414    if (e.isComposing) return // IME candidate navigation owns these keys
415    // Escape always dismisses: it must clear a populated listbox OR the unavailable
416    // hint, and — even when nothing is on screen yet — cancel a pending backoff retry
417    // and invalidate any in-flight fetch (closeSearch clears the timer and bumps the
418    // seq). Handled before the guard below, which only covers a populated listbox.
419    if (e.key === 'Escape') {
420        closeSearch()
421        return
422    }
423    if (!searchOpen.value || !searchResults.value.length) {
424        // APG editable-combobox: Down Arrow on a closed combobox reopens the popup
425        // (the only recovery after Escape that doesn't require editing the text).
426        if (e.key === 'ArrowDown') {
427            const q = (figure.value || '').trim()
428            if (q.length >= 2) {
429                e.preventDefault()
430                void runSearch(q, ++searchSeq)
431            }
432        }
433        return
434    }
435    if (e.key === 'ArrowDown') {
436        e.preventDefault()
437        activeIndex.value = (activeIndex.value + 1) % searchResults.value.length
438    } else if (e.key === 'ArrowUp') {
439        e.preventDefault()
440        activeIndex.value = activeIndex.value <= 0 ? searchResults.value.length - 1 : activeIndex.value - 1
441    } else if (e.key === 'Enter') {
442        if (activeIndex.value >= 0) {
443            e.preventDefault()
444            choose(searchResults.value[activeIndex.value].name)
445        }
446    }
447    // Escape is handled up top (it must also dismiss the unavailable hint, where
448    // searchResults is empty and this block is skipped).
449}
450 
451/** Close when focus genuinely leaves the combobox (not when it moves within it). */
452function onSearchFocusOut(e: FocusEvent) {
453    const next = e.relatedTarget as Node | null
454    if (next && searchBoxRef.value?.contains(next)) return
455    closeSearch()
456}
457 
458/** Spoken result count — aria-expanded alone is not reliably announced while typing. */
459const searchStatus = computed(() =>
460    searchUnavailable.value
461        ? 'The record is unreachable right now — press the down arrow or Retry to search again.'
462        : listboxOpen.value
463            ? `${searchResults.value.length} ${searchResults.value.length === 1 ? 'match' : 'matches'} — up and down arrows to review, Enter to choose`
464            : ''
465)
466 
467function chipClass(name: string) {
468    return name === figure.value ? 'rv-tint rv-fg' : 'rv-muted rv-hover'
469}
470function suggestionClass(name: string) {
471    return name === figure.value ? 'rv-tint' : 'rv-hover'
472}
473 
474// Ground the chosen figure, debounced so typing doesn't spam the lookup. The
475// PREVIOUS dossier is cleared synchronously the instant the name changes: a send
476// fired during the debounce/fetch window must go out clean (free-form), never
477// wearing the old figure's facts, year, or liveness gate.
478let debounce: ReturnType<typeof setTimeout> | null = null
479watch(figure, (name) => {
480    if (debounce) clearTimeout(debounce)
481    gameStore.clearGrounding()
482    const trimmed = (name || '').trim()
483    if (!trimmed) return
484    debounce = setTimeout(() => gameStore.groundActiveFigure(trimmed), 350)
485})
486onUnmounted(() => {
487    if (debounce) clearTimeout(debounce)
488    if (searchDebounce) clearTimeout(searchDebounce)
489})
490 
491// Load era-relevant suggestions for the current objective when the board appears.
492onMounted(() => gameStore.loadSuggestions())
493</script>
494 
495<style scoped>
496/* Quiet placeholder bars while the suggester works — letterpress tint, a gentle
497   pulse, stilled under reduced motion. Never a clickable fake. */
498.skeleton-line {
499    display: block;
500    height: 10px;
501    border-radius: 2px;
502    background: var(--rv-tint);
503    animation: skeleton-pulse 1.6s var(--rv-ease) infinite;
504}
505@keyframes skeleton-pulse {
506    0%, 100% { opacity: .55; }
507    50% { opacity: 1; }
508}
509@media (prefers-reduced-motion: reduce) {
510    .skeleton-line { animation: none; }
511}
512 
513/* The autocomplete pop floats over the dossier on warm paper, not chrome. */
514.search-pop {
515    box-shadow: 0 6px 18px color-mix(in srgb, var(--rv-fg) 10%, transparent);
516}
517</style>

Second, Escape is handled before the populated-listbox guard, so it dismisses any open surface — a listbox or the unavailable hint — and, even when nothing is on screen yet, cancels a pending retry through closeSearch. Without this, Escape during a backoff wait left the timer alive.

Escape dismisses everything and cancels pending retries, ahead of the listbox-only guard.

components/FigurePicker.vue · 517 lines

components/FigurePicker.vue517 lines · Vue

⋯ 412 lines hidden (lines 1–412)1<template>
2  <div data-testid="figure-picker" class="space-y-3">
3    <div ref="searchBoxRef" class="relative" @focusout="onSearchFocusOut">
4      <label for="figure-input" class="rv-label block mb-1">Who in history will you reach?</label>
5      <input id="figure-input" ref="searchInputRef" v-model="figure" data-testid="figure-input" type="text"
6        class="rv-field rv-mono text-sm" placeholder="Anyone, any era — Cleopatra, Tesla, Genghis Khan…"
7        :disabled="disabled"
8        role="combobox" aria-autocomplete="list" :aria-expanded="listboxOpen ? 'true' : 'false'"
9        :aria-controls="listboxOpen ? 'figure-search-listbox' : undefined"
10        :aria-activedescendant="activeIndex >= 0 ? `figure-search-option-${activeIndex}` : undefined"
11        autocomplete="off" @keydown="onSearchKeydown" />
12      <span class="sr-only" role="status">{{ searchStatus }}</span>
13      <!-- Name autocomplete: Wikipedia title search, the description line telling
14           the pharaoh from the 1963 film. Picking one fills the input; grounding
15           fires exactly as if it had been typed. -->
16      <ul v-if="listboxOpen" id="figure-search-listbox" data-testid="figure-search-listbox" role="listbox"
17        aria-label="Matching names from the record"
18        class="search-pop absolute left-0 right-0 top-full mt-1 z-20 border rv-line rounded-sm rv-bg max-h-64 overflow-y-auto">
19        <li v-for="(r, i) in searchResults" :id="`figure-search-option-${i}`" :key="r.name" role="option"
20          :aria-selected="i === activeIndex ? 'true' : 'false'" data-testid="figure-search-option"
21          class="flex items-center gap-2 px-2.5 py-1.5 cursor-pointer text-sm"
22          :class="i === activeIndex ? 'rv-tint' : 'rv-hover'"
23          @mousedown.prevent @click="choose(r.name)" @mousemove="activeIndex = i">
24          <img v-if="r.thumbnail" :src="r.thumbnail" alt="" class="h-7 w-7 shrink-0 rounded object-cover" aria-hidden="true" />
25          <span v-else class="h-7 w-7 shrink-0 rounded rv-tint" aria-hidden="true" />
26          <span class="min-w-0">
27            <span class="rv-fg font-medium block truncate">{{ r.name }}</span>
28            <span v-if="r.description" class="rv-faint text-[11px] block truncate">{{ r.description }}</span>
29          </span>
30        </li>
31      </ul>
32      <!-- The search couldn't reach Wikipedia after its retries: a visible, retryable
33           hint so a rate-limit blip degrades honestly instead of an empty box that
34           reads as "no matches" (issue #58). The sr-only role=status span above is the
35           sole live region — this surface is NOT one, to avoid a double announcement. -->
36      <div v-else-if="searchOpen && searchUnavailable" data-testid="figure-search-unavailable"
37        class="search-pop absolute left-0 right-0 top-full mt-1 z-20 border rv-line rounded-sm rv-bg px-2.5 py-2 text-sm rv-muted flex items-center justify-between gap-2">
38        <span>Couldn't reach the record — a brief network hiccup.</span>
39        <button type="button" data-testid="figure-search-retry"
40          class="rv-accent text-[11px] font-medium hover:underline shrink-0"
41          @mousedown.prevent @click="retrySearch">Retry</button>
42      </div>
43    </div>
44 
45    <!-- Grounding: who they were, and when you reach them -->
46    <div v-if="groundingLoading" data-testid="grounding-loading" class="flex items-center gap-2 text-xs rv-faint">
47      <span class="rv-spinner" aria-hidden="true" />
48      Consulting the records…
49    </div>
50 
51    <div v-else-if="grounding?.resolved" data-testid="figure-dossier" class="rv-card p-3">
52      <div class="flex gap-3">
53        <img v-if="grounding.thumbnail" :src="grounding.thumbnail" :alt="grounding.name"
54          class="h-12 w-12 shrink-0 rounded object-cover" />
55        <div class="min-w-0 flex-1">
56          <div class="flex flex-wrap items-center gap-x-2 gap-y-0.5">
57            <span data-testid="dossier-name" class="rv-fg font-semibold text-sm">{{ grounding.name }}</span>
58            <span v-if="lifespan" data-testid="dossier-lifespan" class="rv-mono text-[11px] rv-faint">{{ lifespan }}</span>
59            <a v-if="grounding.wikiUrl" :href="grounding.wikiUrl" target="_blank" rel="noopener noreferrer"
60              class="rv-accent text-[11px]">Wikipedia ↗</a>
61          </div>
62          <p v-if="grounding.description" class="rv-muted text-xs mt-0.5">{{ grounding.description }}</p>
63 
64          <!-- When do you reach them? A promoted, lifetime-bounded playhead: the
65               chosen year + live age lead, big and in the accent, so the moment you're
66               writing into is the loudest thing in the dossier (not a buried micro-row). -->
67          <div v-if="hasLifespan" data-testid="when-control" class="mt-2.5 border-t rv-line pt-2.5">
68            <div class="flex items-baseline justify-between gap-2">
69              <span id="when-label" class="rv-label">Reach them in</span>
70              <span data-testid="when-display" class="rv-mono rv-accent text-lg font-bold leading-none">
71                {{ whenDisplay }}<span v-if="contactAge != null" data-testid="when-age" class="rv-faint text-xs font-normal"> · age {{ contactAge }}</span>
72              </span>
73            </div>
74            <input type="range" data-testid="when-slider" class="w-full mt-2" :style="{ accentColor: 'var(--rv-accent)' }"
75              :min="range.min" :max="range.max" :value="contactWhen ?? range.min" :disabled="disabled"
76              aria-labelledby="when-label" :aria-valuetext="whenValueText" @input="onWhenInput" />
77            <div class="flex items-center justify-between text-[10px] rv-faint rv-mono">
78              <span>{{ grounding.born?.display }} · born</span>
79              <span>{{ grounding.died?.display ? grounding.died.display + ' · died' : 'present' }}</span>
80            </div>
81 
82            <!-- Pin the moment (issue #32): an optional month/day refinement of the
83                 chosen year. Display + prompt flavor only — the year stays the value
84                 every mechanic computes with, so the wager, world-brief, and liveness
85                 gates are untouched by whatever is pinned here. -->
86            <div class="mt-1.5">
87              <button v-if="!momentOpen" type="button" data-testid="pin-moment"
88                class="rv-accent text-[11px] font-medium hover:underline disabled:opacity-50"
89                :disabled="disabled" @click="momentOpen = true">
90                <span aria-hidden="true">📍</span> {{ contactMoment ? 'adjust the moment' : 'pin the moment' }}
91              </button>
92              <div v-else data-testid="moment-picker">
93                <div class="flex flex-wrap gap-1" role="group" aria-label="Month of the contact">
94                  <button v-for="(m, i) in MONTH_NAMES" :key="m" type="button" data-testid="month-chip"
95                    class="rv-press border rv-line rounded-sm px-1.5 py-0.5 text-[10px]"
96                    :class="contactMoment?.month === i + 1 ? 'rv-tint rv-fg' : 'rv-muted rv-hover'"
97                    :aria-pressed="contactMoment?.month === i + 1 ? 'true' : 'false'"
98                    :disabled="disabled" @click="pickMonth(i + 1)">{{ m.slice(0, 3) }}</button>
99                </div>
100                <div class="flex items-center gap-1.5 mt-1">
101                  <template v-if="contactMoment">
102                    <label for="moment-day" class="rv-label">day</label>
103                    <input id="moment-day" data-testid="moment-day" type="number" inputmode="numeric"
104                      class="rv-field rv-mono text-xs w-16 px-1.5 py-0.5" min="1" :max="maxDay"
105                      :value="contactMoment.day ?? ''" :disabled="disabled" placeholder="—"
106                      @input="onDayInput" />
107                  </template>
108                  <button type="button" data-testid="unpin-moment"
109                    class="rv-faint text-[11px] hover:underline ml-auto" :disabled="disabled"
110                    @click="unpinMoment">{{ contactMoment ? 'unpin' : 'close' }}</button>
111                </div>
112              </div>
113            </div>
114          </div>
115 
116          <!-- Even the AI bridge couldn't date them: say so honestly instead of a
117               mysteriously absent control. The copy claims only the lookup outcome
118               (it may be a transient outage, not a dateless record). No manual year
119               here — the contact year prices the anachronism wager, so it stays
120               grounded or unset. -->
121          <p v-else data-testid="when-unknown" class="mt-2.5 border-t rv-line pt-2.5 text-[11px] italic rv-faint">
122            No dates could be found for them — your message will find them in their own time.
123          </p>
124 
125          <!-- The Archive: study who you're reaching, at the chosen moment -->
126          <div data-testid="archive" class="mt-2 border-t rv-line pt-2">
127            <button v-if="!studyShown" type="button" data-testid="study-button"
128              class="rv-accent text-[11px] font-medium hover:underline disabled:opacity-50"
129              :disabled="studyLoading || disabled" @click="studyThem">
130              <span aria-hidden="true">🔎</span> {{ studyLoading ? 'The Archivist consults the record…' : studyLabel }}
131            </button>
132 
133            <div v-else data-testid="figure-study" class="space-y-1 text-[11px] leading-snug rv-muted">
134              <p class="italic rv-fg">{{ figureStudy?.atThisMoment }}</p>
135              <p v-if="figureStudy?.grasp.length"><span class="rv-faint">grasps</span> {{ figureStudy?.grasp.join(' · ') }}</p>
136              <p v-if="figureStudy?.reaching.length"><span class="rv-faint">reaching</span> {{ figureStudy?.reaching.join(' · ') }}</p>
137              <p v-if="figureStudy?.cannotYetKnow" class="rv-warn"><span class="rv-faint">beyond them</span> {{ figureStudy?.cannotYetKnow }}</p>
138              <button v-if="yearMoved" type="button" data-testid="restudy-button"
139                class="rv-accent font-medium hover:underline disabled:opacity-50" :disabled="studyLoading || disabled" @click="studyThem">
140                <span aria-hidden="true">🔎</span> {{ studyLoading ? 'Consulting…' : restudyLabel }}
141              </button>
142            </div>
143 
144            <p v-if="studyNotice" data-testid="study-blocked" role="alert" aria-live="assertive"
145              class="mt-1 text-[11px] border-l-2 border-red-500/70 bg-red-500/5 pl-2 py-1 text-red-300">
146              <span class="font-semibold uppercase tracking-wide">⚠ blocked</span> {{ studyNotice }}
147            </p>
148          </div>
149        </div>
150      </div>
151    </div>
152 
153    <div v-else-if="grounding && !grounding.resolved" data-testid="figure-unresolved" class="text-xs italic rv-faint">
154      No record found for "{{ activeName }}" — you can still send a message into the unknown.
155    </div>
156 
157    <!-- Figures already contacted this run -->
158    <div v-if="contacted.length" class="flex flex-wrap items-center gap-1.5">
159      <span class="rv-label">contacts</span>
160      <button v-for="f in contacted" :key="f.name" type="button" data-testid="contact-chip"
161        class="rv-press text-xs px-2 py-0.5 border rv-line rounded-sm inline-flex items-center gap-1.5" :class="chipClass(f.name)" @click="select(f.name)">
162        <span class="rv-dot" :class="f.name === figure ? 'rv-dot--accent' : 'rv-dot--hollow'" aria-hidden="true" />{{ f.name }}
163      </button>
164    </div>
165 
166    <!-- Era-relevant figures for this objective (the on-ramp); you can still type anyone. -->
167    <div class="space-y-1.5">
168      <span class="rv-label block" aria-live="polite">{{ suggestionsLabel }}</span>
169      <p v-if="suggestionsNotice" data-testid="suggestions-blocked" role="alert" aria-live="assertive"
170        class="text-[11px] border-l-2 border-red-500/70 bg-red-500/5 pl-2 py-1 text-red-300">
171        <span class="font-semibold uppercase tracking-wide">⚠ blocked</span> {{ suggestionsNotice }}
172      </p>
173      <!-- While the era-aware agent works: quiet skeleton chips — never clickable
174           generic defaults masquerading as objective-relevant picks. The famous-
175           names fallback appears only AFTER the agent has genuinely come up empty,
176           labeled honestly as what it is. -->
177      <div v-if="suggestionsPending" data-testid="suggestion-skeletons" class="flex flex-col gap-1" aria-hidden="true">
178        <div v-for="i in 3" :key="i" class="border rv-line rounded-sm px-2.5 py-2">
179          <span class="skeleton-line w-32" />
180          <span class="skeleton-line w-48 mt-1.5" />
181        </div>
182      </div>
183      <div v-else class="flex flex-col gap-1">
184        <button v-for="s in displaySuggestions" :key="s.name" type="button" data-testid="suggestion-chip"
185          class="rv-press border rv-line rounded-sm px-2.5 py-1.5 text-left" :class="suggestionClass(s.name)" @click="select(s.name)">
186          <span class="text-sm rv-fg font-medium">{{ s.name }}</span>
187          <span v-if="s.lifespan" class="ml-1.5 rv-mono text-[10px] rv-faint">{{ s.lifespan }}</span>
188          <span v-if="s.reason" data-testid="suggestion-reason" class="block text-[11px] leading-snug rv-faint">{{ s.reason }}</span>
189        </button>
190      </div>
191    </div>
192  </div>
193</template>
194 
195<script setup lang="ts">
196/**
197 * FigurePicker — choose whom (free-form name, suggestion, or prior contact) and, once
198 * grounded, when to reach them (a lifetime-bounded slider with a live age). The
199 * Archive's "study them" brief discloses who they are at that moment. Re-skin only —
200 * every store binding (grounding, contactWhen, study, suggestions) is unchanged.
201 */
202import { computed, watch, onMounted, onUnmounted } from 'vue'
203import { useGameStore } from '~/stores/game'
204import { formatContactMoment, MONTH_NAMES, MONTH_MAX_DAY } from '~/utils/contact-moment'
205import type { FigureSuggestion } from '~/server/utils/figure-suggester'
206 
207const figure = defineModel<string>({ default: '' })
208defineProps<{ disabled?: boolean }>()
209 
210const gameStore = useGameStore()
211const contacted = computed(() => gameStore.figures)
212const figureSuggestions = computed(() => gameStore.figureSuggestions)
213const suggestionsLoading = computed(() => gameStore.suggestionsLoading)
214const suggestionsNotice = computed(() => gameStore.suggestionsNotice)
215const grounding = computed(() => gameStore.figureGrounding)
216const groundingLoading = computed(() => gameStore.groundingLoading)
217const contactWhen = computed(() => gameStore.contactWhen)
218const contactAge = computed(() => gameStore.contactAge)
219const activeName = computed(() => figure.value.trim())
220 
221const hasLifespan = computed(() => !!(grounding.value?.resolved && grounding.value.born))
222const lifespan = computed(() => {
223    const g = grounding.value
224    if (!g?.born) return ''
225    if (g.died) return `${g.born.display} – ${g.died.display}`
226    return g.living ? `${g.born.display} – present` : g.born.display
227})
228const range = computed(() => ({
229    min: grounding.value?.born?.signed ?? 0,
230    max: grounding.value?.died?.signed ?? new Date().getFullYear()
231}))
232const contactMoment = computed(() => gameStore.contactMoment)
233const whenDisplay = computed(() => (contactWhen.value != null ? formatContactMoment(contactWhen.value, contactMoment.value) : ''))
234// What AT announces for the slider: the human year + live age (e.g. "44 BC · age 25"),
235// not the raw signed integer the value attribute carries.
236const whenValueText = computed(() =>
237    contactWhen.value == null ? '' : whenDisplay.value + (contactAge.value != null ? ` · age ${contactAge.value}` : '')
238)
239 
240function onWhenInput(e: Event) {
241    gameStore.setContactWhen(Number((e.target as HTMLInputElement).value))
242}
243 
244// --- Pin the moment (issue #32): month chips + optional day, year-canonical ---
245const momentOpen = ref(false)
246const maxDay = computed(() => (contactMoment.value ? MONTH_MAX_DAY[contactMoment.value.month - 1] : 31))
247function pickMonth(month: number) {
248    const current = gameStore.contactMoment
249    if (current?.month === month) return
250    // Switching months keeps the day where it stays valid, clamps where it doesn't.
251    const day = current?.day ? Math.min(current.day, MONTH_MAX_DAY[month - 1]) : undefined
252    gameStore.setContactMoment(day ? { month, day } : { month })
253}
254function onDayInput(e: Event) {
255    const current = gameStore.contactMoment
256    if (!current) return
257    const raw = Number((e.target as HTMLInputElement).value)
258    if (!Number.isInteger(raw) || raw < 1) {
259        gameStore.setContactMoment({ month: current.month })
260        return
261    }
262    gameStore.setContactMoment({ month: current.month, day: Math.min(raw, MONTH_MAX_DAY[current.month - 1]) })
263}
264function unpinMoment() {
265    gameStore.setContactMoment(null)
266    momentOpen.value = false
267}
268 
269// The Archive: study the grounded figure in-game, at the chosen moment.
270const figureStudy = computed(() => gameStore.figureStudy)
271const studyLoading = computed(() => gameStore.studyLoading)
272const studyNotice = computed(() => gameStore.studyNotice)
273const studyShown = computed(() => !!figureStudy.value && gameStore.studyFor === grounding.value?.name)
274const yearMoved = computed(() => studyShown.value && gameStore.studyWhen !== contactWhen.value)
275const studyLabel = computed(() => (contactWhen.value != null ? `Study them in ${whenDisplay.value}` : 'Study them'))
276const restudyLabel = computed(() => (contactWhen.value != null ? `Re-study in ${whenDisplay.value}` : 'Re-study'))
277function studyThem() { gameStore.studyActiveFigure() }
278 
279const LOCAL_DEFAULT: FigureSuggestion[] = [
280    { name: 'Cleopatra', reason: '' },
281    { name: 'Nikola Tesla', reason: '' },
282    { name: 'Genghis Khan', reason: '' },
283    { name: 'Marie Curie', reason: '' },
284    { name: 'Leonardo da Vinci', reason: '' }
285]
286const displaySuggestions = computed(() => (figureSuggestions.value.length ? figureSuggestions.value : LOCAL_DEFAULT))
287// Pending = in flight, OR simply not yet asked for this objective — the latter
288// covers the first painted frame (loadSuggestions fires onMounted, after render),
289// which would otherwise flash the clickable famous-names fallback for one frame.
290// The store records suggestionsFor even on failure, so a genuine miss still
291// settles into the honest fallback rather than skeletons forever.
292const suggestionsPending = computed(() =>
293    !figureSuggestions.value.length && (
294        suggestionsLoading.value ||
295        (!!gameStore.currentObjective && gameStore.suggestionsFor !== gameStore.currentObjective.title)
296    )
297)
298const suggestionsLabel = computed(() =>
299    suggestionsPending.value
300        ? 'finding figures who matter here…'
301        : figureSuggestions.value.length
302            ? 'figures who might matter here'
303            : 'some famous names to start with'
304)
305 
306function select(name: string) {
307    choose(name)
308}
309 
310// --- Name autocomplete (a combobox over Wikipedia title search) ---
311interface SearchResult { name: string; description?: string; thumbnail?: string }
312const searchBoxRef = ref<HTMLElement | null>(null)
313const searchInputRef = ref<HTMLInputElement | null>(null)
314const searchResults = ref<SearchResult[]>([])
315const searchOpen = ref(false)
316// Sustained weather (rate-limit blips) finally gave up with nothing to show: a
317// visible, retryable hint takes the popup so an outage degrades honestly instead
318// of an empty box that reads as "no matches" (issue #58).
319const searchUnavailable = ref(false)
320const activeIndex = ref(-1)
321// The listbox is the result popup; the unavailable hint is a separate, non-listbox
322// surface. aria-expanded / aria-controls track only this.
323const listboxOpen = computed(() => searchOpen.value && searchResults.value.length > 0)
324let searchDebounce: ReturnType<typeof setTimeout> | null = null
325let searchSeq = 0
326// Backoff for transient (rate-limit) misses: spaced retries before giving up, so a
327// throttled prefix like "Leonardo" gets time to clear rather than vanishing.
328const SEARCH_RETRY_DELAYS_MS = [800, 1600]
329// The name most recently CHOSEN (dropdown option, suggestion chip, contact chip):
330// the model change it causes must not reopen the dropdown over the fresh dossier.
331let lastChosen = ''
332 
333/** Closing also INVALIDATES any response still in flight: bumping the seq is what
334 *  keeps a slow fetch from reopening a stale dropdown over a chosen figure's
335 *  dossier, an emptied input, or a disabled one mid-send. It also cancels a pending
336 *  backoff retry — otherwise a timer armed before the dismissal would later fire and
337 *  pop the dropdown (or the unavailable hint) back up unprompted. */
338function closeSearch() {
339    if (searchDebounce) clearTimeout(searchDebounce)
340    searchDebounce = null
341    searchSeq++
342    searchResults.value = []
343    searchOpen.value = false
344    searchUnavailable.value = false
345    activeIndex.value = -1
346}
347 
348/** Deliberate selection from any surface: fill the input and stand down. */
349function choose(name: string) {
350    lastChosen = name
351    figure.value = name
352    closeSearch()
353}
354 
355/** Fire the actual lookup for the CURRENT seq; results land only if still current. */
356async function runSearch(q: string, seq: number, attempt = 0) {
357    try {
358        const res = await $fetch('/api/figure-search', { params: { q } }) as { results?: SearchResult[]; transient?: boolean }
359        if (seq !== searchSeq) return // closed, or a newer keystroke took over
360        const results = res?.results ?? []
361        // Weather, not absence: an empty answer the server marks transient must not
362        // read as "no matches" — keep whatever is showing and retry with backoff.
363        // (A new keystroke clears the timer; the seq guard drops a stale landing.)
364        if (!results.length && res?.transient) {
365            const delay = SEARCH_RETRY_DELAYS_MS[attempt]
366            if (delay != null) {
367                searchDebounce = setTimeout(() => { void runSearch(q, seq, attempt + 1) }, delay)
368            } else if (!searchResults.value.length) {
369                // Out of retries with nothing to fall back on: say so plainly and
370                // offer a retry, rather than an empty box that looks like "no matches".
371                searchUnavailable.value = true
372                searchOpen.value = true
373                activeIndex.value = -1
374            }
375            return
376        }
377        searchUnavailable.value = false
378        searchResults.value = results
379        searchOpen.value = results.length > 0
380        activeIndex.value = -1
381    } catch {
382        if (seq === searchSeq) closeSearch()
383    }
384}
385 
386/** Manual retry from the "unavailable" hint — refire the search for the current text.
387 *  Returns focus to the input first: clearing the hint unmounts the Retry button, and
388 *  a keyboard user activating it would otherwise have focus fall to <body>. */
389function retrySearch() {
390    const q = (figure.value || '').trim()
391    if (q.length < 2) return
392    searchInputRef.value?.focus()
393    searchUnavailable.value = false
394    void runSearch(q, ++searchSeq)
395}
396 
397watch(figure, (name) => {
398    if (searchDebounce) clearTimeout(searchDebounce)
399    const q = (name || '').trim()
400    if (q.length < 2 || q === lastChosen) {
401        closeSearch()
402        // One-shot suppression: it exists to swallow the single model echo a
403        // choice causes. A later deliberate retype of the same name searches again.
404        if (q === lastChosen) lastChosen = ''
405        return
406    }
407    lastChosen = ''
408    searchUnavailable.value = false // a fresh keystroke retires any prior outage hint
409    const seq = ++searchSeq
410    searchDebounce = setTimeout(() => { void runSearch(q, seq) }, 250)
411})
412 
413function onSearchKeydown(e: KeyboardEvent) {
414    if (e.isComposing) return // IME candidate navigation owns these keys
415    // Escape always dismisses: it must clear a populated listbox OR the unavailable
416    // hint, and — even when nothing is on screen yet — cancel a pending backoff retry
417    // and invalidate any in-flight fetch (closeSearch clears the timer and bumps the
418    // seq). Handled before the guard below, which only covers a populated listbox.
419    if (e.key === 'Escape') {
420        closeSearch()
421        return
422    }
423    if (!searchOpen.value || !searchResults.value.length) {
424        // APG editable-combobox: Down Arrow on a closed combobox reopens the popup
425        // (the only recovery after Escape that doesn't require editing the text).
426        if (e.key === 'ArrowDown') {
⋯ 91 lines hidden (lines 427–517)427            const q = (figure.value || '').trim()
428            if (q.length >= 2) {
429                e.preventDefault()
430                void runSearch(q, ++searchSeq)
431            }
432        }
433        return
434    }
435    if (e.key === 'ArrowDown') {
436        e.preventDefault()
437        activeIndex.value = (activeIndex.value + 1) % searchResults.value.length
438    } else if (e.key === 'ArrowUp') {
439        e.preventDefault()
440        activeIndex.value = activeIndex.value <= 0 ? searchResults.value.length - 1 : activeIndex.value - 1
441    } else if (e.key === 'Enter') {
442        if (activeIndex.value >= 0) {
443            e.preventDefault()
444            choose(searchResults.value[activeIndex.value].name)
445        }
446    }
447    // Escape is handled up top (it must also dismiss the unavailable hint, where
448    // searchResults is empty and this block is skipped).
449}
450 
451/** Close when focus genuinely leaves the combobox (not when it moves within it). */
452function onSearchFocusOut(e: FocusEvent) {
453    const next = e.relatedTarget as Node | null
454    if (next && searchBoxRef.value?.contains(next)) return
455    closeSearch()
456}
457 
458/** Spoken result count — aria-expanded alone is not reliably announced while typing. */
459const searchStatus = computed(() =>
460    searchUnavailable.value
461        ? 'The record is unreachable right now — press the down arrow or Retry to search again.'
462        : listboxOpen.value
463            ? `${searchResults.value.length} ${searchResults.value.length === 1 ? 'match' : 'matches'} — up and down arrows to review, Enter to choose`
464            : ''
465)
466 
467function chipClass(name: string) {
468    return name === figure.value ? 'rv-tint rv-fg' : 'rv-muted rv-hover'
469}
470function suggestionClass(name: string) {
471    return name === figure.value ? 'rv-tint' : 'rv-hover'
472}
473 
474// Ground the chosen figure, debounced so typing doesn't spam the lookup. The
475// PREVIOUS dossier is cleared synchronously the instant the name changes: a send
476// fired during the debounce/fetch window must go out clean (free-form), never
477// wearing the old figure's facts, year, or liveness gate.
478let debounce: ReturnType<typeof setTimeout> | null = null
479watch(figure, (name) => {
480    if (debounce) clearTimeout(debounce)
481    gameStore.clearGrounding()
482    const trimmed = (name || '').trim()
483    if (!trimmed) return
484    debounce = setTimeout(() => gameStore.groundActiveFigure(trimmed), 350)
485})
486onUnmounted(() => {
487    if (debounce) clearTimeout(debounce)
488    if (searchDebounce) clearTimeout(searchDebounce)
489})
490 
491// Load era-relevant suggestions for the current objective when the board appears.
492onMounted(() => gameStore.loadSuggestions())
493</script>
494 
495<style scoped>
496/* Quiet placeholder bars while the suggester works — letterpress tint, a gentle
497   pulse, stilled under reduced motion. Never a clickable fake. */
498.skeleton-line {
499    display: block;
500    height: 10px;
501    border-radius: 2px;
502    background: var(--rv-tint);
503    animation: skeleton-pulse 1.6s var(--rv-ease) infinite;
504}
505@keyframes skeleton-pulse {
506    0%, 100% { opacity: .55; }
507    50% { opacity: 1; }
508}
509@media (prefers-reduced-motion: reduce) {
510    .skeleton-line { animation: none; }
511}
512 
513/* The autocomplete pop floats over the dossier on warm paper, not chrome. */
514.search-pop {
515    box-shadow: 0 6px 18px color-mix(in srgb, var(--rv-fg) 10%, transparent);
516}
517</style>

Third, retrySearch returns focus to the input before clearing the flag. Clearing searchUnavailable unmounts the div that holds the Retry button, so a keyboard user who just activated it would otherwise have focus fall to <body> and lose their place in the combobox.

Focus the input first, then tear down the hint the button lives in.

components/FigurePicker.vue · 517 lines

components/FigurePicker.vue517 lines · Vue

⋯ 385 lines hidden (lines 1–385)1<template>
2  <div data-testid="figure-picker" class="space-y-3">
3    <div ref="searchBoxRef" class="relative" @focusout="onSearchFocusOut">
4      <label for="figure-input" class="rv-label block mb-1">Who in history will you reach?</label>
5      <input id="figure-input" ref="searchInputRef" v-model="figure" data-testid="figure-input" type="text"
6        class="rv-field rv-mono text-sm" placeholder="Anyone, any era — Cleopatra, Tesla, Genghis Khan…"
7        :disabled="disabled"
8        role="combobox" aria-autocomplete="list" :aria-expanded="listboxOpen ? 'true' : 'false'"
9        :aria-controls="listboxOpen ? 'figure-search-listbox' : undefined"
10        :aria-activedescendant="activeIndex >= 0 ? `figure-search-option-${activeIndex}` : undefined"
11        autocomplete="off" @keydown="onSearchKeydown" />
12      <span class="sr-only" role="status">{{ searchStatus }}</span>
13      <!-- Name autocomplete: Wikipedia title search, the description line telling
14           the pharaoh from the 1963 film. Picking one fills the input; grounding
15           fires exactly as if it had been typed. -->
16      <ul v-if="listboxOpen" id="figure-search-listbox" data-testid="figure-search-listbox" role="listbox"
17        aria-label="Matching names from the record"
18        class="search-pop absolute left-0 right-0 top-full mt-1 z-20 border rv-line rounded-sm rv-bg max-h-64 overflow-y-auto">
19        <li v-for="(r, i) in searchResults" :id="`figure-search-option-${i}`" :key="r.name" role="option"
20          :aria-selected="i === activeIndex ? 'true' : 'false'" data-testid="figure-search-option"
21          class="flex items-center gap-2 px-2.5 py-1.5 cursor-pointer text-sm"
22          :class="i === activeIndex ? 'rv-tint' : 'rv-hover'"
23          @mousedown.prevent @click="choose(r.name)" @mousemove="activeIndex = i">
24          <img v-if="r.thumbnail" :src="r.thumbnail" alt="" class="h-7 w-7 shrink-0 rounded object-cover" aria-hidden="true" />
25          <span v-else class="h-7 w-7 shrink-0 rounded rv-tint" aria-hidden="true" />
26          <span class="min-w-0">
27            <span class="rv-fg font-medium block truncate">{{ r.name }}</span>
28            <span v-if="r.description" class="rv-faint text-[11px] block truncate">{{ r.description }}</span>
29          </span>
30        </li>
31      </ul>
32      <!-- The search couldn't reach Wikipedia after its retries: a visible, retryable
33           hint so a rate-limit blip degrades honestly instead of an empty box that
34           reads as "no matches" (issue #58). The sr-only role=status span above is the
35           sole live region — this surface is NOT one, to avoid a double announcement. -->
36      <div v-else-if="searchOpen && searchUnavailable" data-testid="figure-search-unavailable"
37        class="search-pop absolute left-0 right-0 top-full mt-1 z-20 border rv-line rounded-sm rv-bg px-2.5 py-2 text-sm rv-muted flex items-center justify-between gap-2">
38        <span>Couldn't reach the record — a brief network hiccup.</span>
39        <button type="button" data-testid="figure-search-retry"
40          class="rv-accent text-[11px] font-medium hover:underline shrink-0"
41          @mousedown.prevent @click="retrySearch">Retry</button>
42      </div>
43    </div>
44 
45    <!-- Grounding: who they were, and when you reach them -->
46    <div v-if="groundingLoading" data-testid="grounding-loading" class="flex items-center gap-2 text-xs rv-faint">
47      <span class="rv-spinner" aria-hidden="true" />
48      Consulting the records…
49    </div>
50 
51    <div v-else-if="grounding?.resolved" data-testid="figure-dossier" class="rv-card p-3">
52      <div class="flex gap-3">
53        <img v-if="grounding.thumbnail" :src="grounding.thumbnail" :alt="grounding.name"
54          class="h-12 w-12 shrink-0 rounded object-cover" />
55        <div class="min-w-0 flex-1">
56          <div class="flex flex-wrap items-center gap-x-2 gap-y-0.5">
57            <span data-testid="dossier-name" class="rv-fg font-semibold text-sm">{{ grounding.name }}</span>
58            <span v-if="lifespan" data-testid="dossier-lifespan" class="rv-mono text-[11px] rv-faint">{{ lifespan }}</span>
59            <a v-if="grounding.wikiUrl" :href="grounding.wikiUrl" target="_blank" rel="noopener noreferrer"
60              class="rv-accent text-[11px]">Wikipedia ↗</a>
61          </div>
62          <p v-if="grounding.description" class="rv-muted text-xs mt-0.5">{{ grounding.description }}</p>
63 
64          <!-- When do you reach them? A promoted, lifetime-bounded playhead: the
65               chosen year + live age lead, big and in the accent, so the moment you're
66               writing into is the loudest thing in the dossier (not a buried micro-row). -->
67          <div v-if="hasLifespan" data-testid="when-control" class="mt-2.5 border-t rv-line pt-2.5">
68            <div class="flex items-baseline justify-between gap-2">
69              <span id="when-label" class="rv-label">Reach them in</span>
70              <span data-testid="when-display" class="rv-mono rv-accent text-lg font-bold leading-none">
71                {{ whenDisplay }}<span v-if="contactAge != null" data-testid="when-age" class="rv-faint text-xs font-normal"> · age {{ contactAge }}</span>
72              </span>
73            </div>
74            <input type="range" data-testid="when-slider" class="w-full mt-2" :style="{ accentColor: 'var(--rv-accent)' }"
75              :min="range.min" :max="range.max" :value="contactWhen ?? range.min" :disabled="disabled"
76              aria-labelledby="when-label" :aria-valuetext="whenValueText" @input="onWhenInput" />
77            <div class="flex items-center justify-between text-[10px] rv-faint rv-mono">
78              <span>{{ grounding.born?.display }} · born</span>
79              <span>{{ grounding.died?.display ? grounding.died.display + ' · died' : 'present' }}</span>
80            </div>
81 
82            <!-- Pin the moment (issue #32): an optional month/day refinement of the
83                 chosen year. Display + prompt flavor only — the year stays the value
84                 every mechanic computes with, so the wager, world-brief, and liveness
85                 gates are untouched by whatever is pinned here. -->
86            <div class="mt-1.5">
87              <button v-if="!momentOpen" type="button" data-testid="pin-moment"
88                class="rv-accent text-[11px] font-medium hover:underline disabled:opacity-50"
89                :disabled="disabled" @click="momentOpen = true">
90                <span aria-hidden="true">📍</span> {{ contactMoment ? 'adjust the moment' : 'pin the moment' }}
91              </button>
92              <div v-else data-testid="moment-picker">
93                <div class="flex flex-wrap gap-1" role="group" aria-label="Month of the contact">
94                  <button v-for="(m, i) in MONTH_NAMES" :key="m" type="button" data-testid="month-chip"
95                    class="rv-press border rv-line rounded-sm px-1.5 py-0.5 text-[10px]"
96                    :class="contactMoment?.month === i + 1 ? 'rv-tint rv-fg' : 'rv-muted rv-hover'"
97                    :aria-pressed="contactMoment?.month === i + 1 ? 'true' : 'false'"
98                    :disabled="disabled" @click="pickMonth(i + 1)">{{ m.slice(0, 3) }}</button>
99                </div>
100                <div class="flex items-center gap-1.5 mt-1">
101                  <template v-if="contactMoment">
102                    <label for="moment-day" class="rv-label">day</label>
103                    <input id="moment-day" data-testid="moment-day" type="number" inputmode="numeric"
104                      class="rv-field rv-mono text-xs w-16 px-1.5 py-0.5" min="1" :max="maxDay"
105                      :value="contactMoment.day ?? ''" :disabled="disabled" placeholder="—"
106                      @input="onDayInput" />
107                  </template>
108                  <button type="button" data-testid="unpin-moment"
109                    class="rv-faint text-[11px] hover:underline ml-auto" :disabled="disabled"
110                    @click="unpinMoment">{{ contactMoment ? 'unpin' : 'close' }}</button>
111                </div>
112              </div>
113            </div>
114          </div>
115 
116          <!-- Even the AI bridge couldn't date them: say so honestly instead of a
117               mysteriously absent control. The copy claims only the lookup outcome
118               (it may be a transient outage, not a dateless record). No manual year
119               here — the contact year prices the anachronism wager, so it stays
120               grounded or unset. -->
121          <p v-else data-testid="when-unknown" class="mt-2.5 border-t rv-line pt-2.5 text-[11px] italic rv-faint">
122            No dates could be found for them — your message will find them in their own time.
123          </p>
124 
125          <!-- The Archive: study who you're reaching, at the chosen moment -->
126          <div data-testid="archive" class="mt-2 border-t rv-line pt-2">
127            <button v-if="!studyShown" type="button" data-testid="study-button"
128              class="rv-accent text-[11px] font-medium hover:underline disabled:opacity-50"
129              :disabled="studyLoading || disabled" @click="studyThem">
130              <span aria-hidden="true">🔎</span> {{ studyLoading ? 'The Archivist consults the record…' : studyLabel }}
131            </button>
132 
133            <div v-else data-testid="figure-study" class="space-y-1 text-[11px] leading-snug rv-muted">
134              <p class="italic rv-fg">{{ figureStudy?.atThisMoment }}</p>
135              <p v-if="figureStudy?.grasp.length"><span class="rv-faint">grasps</span> {{ figureStudy?.grasp.join(' · ') }}</p>
136              <p v-if="figureStudy?.reaching.length"><span class="rv-faint">reaching</span> {{ figureStudy?.reaching.join(' · ') }}</p>
137              <p v-if="figureStudy?.cannotYetKnow" class="rv-warn"><span class="rv-faint">beyond them</span> {{ figureStudy?.cannotYetKnow }}</p>
138              <button v-if="yearMoved" type="button" data-testid="restudy-button"
139                class="rv-accent font-medium hover:underline disabled:opacity-50" :disabled="studyLoading || disabled" @click="studyThem">
140                <span aria-hidden="true">🔎</span> {{ studyLoading ? 'Consulting…' : restudyLabel }}
141              </button>
142            </div>
143 
144            <p v-if="studyNotice" data-testid="study-blocked" role="alert" aria-live="assertive"
145              class="mt-1 text-[11px] border-l-2 border-red-500/70 bg-red-500/5 pl-2 py-1 text-red-300">
146              <span class="font-semibold uppercase tracking-wide">⚠ blocked</span> {{ studyNotice }}
147            </p>
148          </div>
149        </div>
150      </div>
151    </div>
152 
153    <div v-else-if="grounding && !grounding.resolved" data-testid="figure-unresolved" class="text-xs italic rv-faint">
154      No record found for "{{ activeName }}" — you can still send a message into the unknown.
155    </div>
156 
157    <!-- Figures already contacted this run -->
158    <div v-if="contacted.length" class="flex flex-wrap items-center gap-1.5">
159      <span class="rv-label">contacts</span>
160      <button v-for="f in contacted" :key="f.name" type="button" data-testid="contact-chip"
161        class="rv-press text-xs px-2 py-0.5 border rv-line rounded-sm inline-flex items-center gap-1.5" :class="chipClass(f.name)" @click="select(f.name)">
162        <span class="rv-dot" :class="f.name === figure ? 'rv-dot--accent' : 'rv-dot--hollow'" aria-hidden="true" />{{ f.name }}
163      </button>
164    </div>
165 
166    <!-- Era-relevant figures for this objective (the on-ramp); you can still type anyone. -->
167    <div class="space-y-1.5">
168      <span class="rv-label block" aria-live="polite">{{ suggestionsLabel }}</span>
169      <p v-if="suggestionsNotice" data-testid="suggestions-blocked" role="alert" aria-live="assertive"
170        class="text-[11px] border-l-2 border-red-500/70 bg-red-500/5 pl-2 py-1 text-red-300">
171        <span class="font-semibold uppercase tracking-wide">⚠ blocked</span> {{ suggestionsNotice }}
172      </p>
173      <!-- While the era-aware agent works: quiet skeleton chips — never clickable
174           generic defaults masquerading as objective-relevant picks. The famous-
175           names fallback appears only AFTER the agent has genuinely come up empty,
176           labeled honestly as what it is. -->
177      <div v-if="suggestionsPending" data-testid="suggestion-skeletons" class="flex flex-col gap-1" aria-hidden="true">
178        <div v-for="i in 3" :key="i" class="border rv-line rounded-sm px-2.5 py-2">
179          <span class="skeleton-line w-32" />
180          <span class="skeleton-line w-48 mt-1.5" />
181        </div>
182      </div>
183      <div v-else class="flex flex-col gap-1">
184        <button v-for="s in displaySuggestions" :key="s.name" type="button" data-testid="suggestion-chip"
185          class="rv-press border rv-line rounded-sm px-2.5 py-1.5 text-left" :class="suggestionClass(s.name)" @click="select(s.name)">
186          <span class="text-sm rv-fg font-medium">{{ s.name }}</span>
187          <span v-if="s.lifespan" class="ml-1.5 rv-mono text-[10px] rv-faint">{{ s.lifespan }}</span>
188          <span v-if="s.reason" data-testid="suggestion-reason" class="block text-[11px] leading-snug rv-faint">{{ s.reason }}</span>
189        </button>
190      </div>
191    </div>
192  </div>
193</template>
194 
195<script setup lang="ts">
196/**
197 * FigurePicker — choose whom (free-form name, suggestion, or prior contact) and, once
198 * grounded, when to reach them (a lifetime-bounded slider with a live age). The
199 * Archive's "study them" brief discloses who they are at that moment. Re-skin only —
200 * every store binding (grounding, contactWhen, study, suggestions) is unchanged.
201 */
202import { computed, watch, onMounted, onUnmounted } from 'vue'
203import { useGameStore } from '~/stores/game'
204import { formatContactMoment, MONTH_NAMES, MONTH_MAX_DAY } from '~/utils/contact-moment'
205import type { FigureSuggestion } from '~/server/utils/figure-suggester'
206 
207const figure = defineModel<string>({ default: '' })
208defineProps<{ disabled?: boolean }>()
209 
210const gameStore = useGameStore()
211const contacted = computed(() => gameStore.figures)
212const figureSuggestions = computed(() => gameStore.figureSuggestions)
213const suggestionsLoading = computed(() => gameStore.suggestionsLoading)
214const suggestionsNotice = computed(() => gameStore.suggestionsNotice)
215const grounding = computed(() => gameStore.figureGrounding)
216const groundingLoading = computed(() => gameStore.groundingLoading)
217const contactWhen = computed(() => gameStore.contactWhen)
218const contactAge = computed(() => gameStore.contactAge)
219const activeName = computed(() => figure.value.trim())
220 
221const hasLifespan = computed(() => !!(grounding.value?.resolved && grounding.value.born))
222const lifespan = computed(() => {
223    const g = grounding.value
224    if (!g?.born) return ''
225    if (g.died) return `${g.born.display} – ${g.died.display}`
226    return g.living ? `${g.born.display} – present` : g.born.display
227})
228const range = computed(() => ({
229    min: grounding.value?.born?.signed ?? 0,
230    max: grounding.value?.died?.signed ?? new Date().getFullYear()
231}))
232const contactMoment = computed(() => gameStore.contactMoment)
233const whenDisplay = computed(() => (contactWhen.value != null ? formatContactMoment(contactWhen.value, contactMoment.value) : ''))
234// What AT announces for the slider: the human year + live age (e.g. "44 BC · age 25"),
235// not the raw signed integer the value attribute carries.
236const whenValueText = computed(() =>
237    contactWhen.value == null ? '' : whenDisplay.value + (contactAge.value != null ? ` · age ${contactAge.value}` : '')
238)
239 
240function onWhenInput(e: Event) {
241    gameStore.setContactWhen(Number((e.target as HTMLInputElement).value))
242}
243 
244// --- Pin the moment (issue #32): month chips + optional day, year-canonical ---
245const momentOpen = ref(false)
246const maxDay = computed(() => (contactMoment.value ? MONTH_MAX_DAY[contactMoment.value.month - 1] : 31))
247function pickMonth(month: number) {
248    const current = gameStore.contactMoment
249    if (current?.month === month) return
250    // Switching months keeps the day where it stays valid, clamps where it doesn't.
251    const day = current?.day ? Math.min(current.day, MONTH_MAX_DAY[month - 1]) : undefined
252    gameStore.setContactMoment(day ? { month, day } : { month })
253}
254function onDayInput(e: Event) {
255    const current = gameStore.contactMoment
256    if (!current) return
257    const raw = Number((e.target as HTMLInputElement).value)
258    if (!Number.isInteger(raw) || raw < 1) {
259        gameStore.setContactMoment({ month: current.month })
260        return
261    }
262    gameStore.setContactMoment({ month: current.month, day: Math.min(raw, MONTH_MAX_DAY[current.month - 1]) })
263}
264function unpinMoment() {
265    gameStore.setContactMoment(null)
266    momentOpen.value = false
267}
268 
269// The Archive: study the grounded figure in-game, at the chosen moment.
270const figureStudy = computed(() => gameStore.figureStudy)
271const studyLoading = computed(() => gameStore.studyLoading)
272const studyNotice = computed(() => gameStore.studyNotice)
273const studyShown = computed(() => !!figureStudy.value && gameStore.studyFor === grounding.value?.name)
274const yearMoved = computed(() => studyShown.value && gameStore.studyWhen !== contactWhen.value)
275const studyLabel = computed(() => (contactWhen.value != null ? `Study them in ${whenDisplay.value}` : 'Study them'))
276const restudyLabel = computed(() => (contactWhen.value != null ? `Re-study in ${whenDisplay.value}` : 'Re-study'))
277function studyThem() { gameStore.studyActiveFigure() }
278 
279const LOCAL_DEFAULT: FigureSuggestion[] = [
280    { name: 'Cleopatra', reason: '' },
281    { name: 'Nikola Tesla', reason: '' },
282    { name: 'Genghis Khan', reason: '' },
283    { name: 'Marie Curie', reason: '' },
284    { name: 'Leonardo da Vinci', reason: '' }
285]
286const displaySuggestions = computed(() => (figureSuggestions.value.length ? figureSuggestions.value : LOCAL_DEFAULT))
287// Pending = in flight, OR simply not yet asked for this objective — the latter
288// covers the first painted frame (loadSuggestions fires onMounted, after render),
289// which would otherwise flash the clickable famous-names fallback for one frame.
290// The store records suggestionsFor even on failure, so a genuine miss still
291// settles into the honest fallback rather than skeletons forever.
292const suggestionsPending = computed(() =>
293    !figureSuggestions.value.length && (
294        suggestionsLoading.value ||
295        (!!gameStore.currentObjective && gameStore.suggestionsFor !== gameStore.currentObjective.title)
296    )
297)
298const suggestionsLabel = computed(() =>
299    suggestionsPending.value
300        ? 'finding figures who matter here…'
301        : figureSuggestions.value.length
302            ? 'figures who might matter here'
303            : 'some famous names to start with'
304)
305 
306function select(name: string) {
307    choose(name)
308}
309 
310// --- Name autocomplete (a combobox over Wikipedia title search) ---
311interface SearchResult { name: string; description?: string; thumbnail?: string }
312const searchBoxRef = ref<HTMLElement | null>(null)
313const searchInputRef = ref<HTMLInputElement | null>(null)
314const searchResults = ref<SearchResult[]>([])
315const searchOpen = ref(false)
316// Sustained weather (rate-limit blips) finally gave up with nothing to show: a
317// visible, retryable hint takes the popup so an outage degrades honestly instead
318// of an empty box that reads as "no matches" (issue #58).
319const searchUnavailable = ref(false)
320const activeIndex = ref(-1)
321// The listbox is the result popup; the unavailable hint is a separate, non-listbox
322// surface. aria-expanded / aria-controls track only this.
323const listboxOpen = computed(() => searchOpen.value && searchResults.value.length > 0)
324let searchDebounce: ReturnType<typeof setTimeout> | null = null
325let searchSeq = 0
326// Backoff for transient (rate-limit) misses: spaced retries before giving up, so a
327// throttled prefix like "Leonardo" gets time to clear rather than vanishing.
328const SEARCH_RETRY_DELAYS_MS = [800, 1600]
329// The name most recently CHOSEN (dropdown option, suggestion chip, contact chip):
330// the model change it causes must not reopen the dropdown over the fresh dossier.
331let lastChosen = ''
332 
333/** Closing also INVALIDATES any response still in flight: bumping the seq is what
334 *  keeps a slow fetch from reopening a stale dropdown over a chosen figure's
335 *  dossier, an emptied input, or a disabled one mid-send. It also cancels a pending
336 *  backoff retry — otherwise a timer armed before the dismissal would later fire and
337 *  pop the dropdown (or the unavailable hint) back up unprompted. */
338function closeSearch() {
339    if (searchDebounce) clearTimeout(searchDebounce)
340    searchDebounce = null
341    searchSeq++
342    searchResults.value = []
343    searchOpen.value = false
344    searchUnavailable.value = false
345    activeIndex.value = -1
346}
347 
348/** Deliberate selection from any surface: fill the input and stand down. */
349function choose(name: string) {
350    lastChosen = name
351    figure.value = name
352    closeSearch()
353}
354 
355/** Fire the actual lookup for the CURRENT seq; results land only if still current. */
356async function runSearch(q: string, seq: number, attempt = 0) {
357    try {
358        const res = await $fetch('/api/figure-search', { params: { q } }) as { results?: SearchResult[]; transient?: boolean }
359        if (seq !== searchSeq) return // closed, or a newer keystroke took over
360        const results = res?.results ?? []
361        // Weather, not absence: an empty answer the server marks transient must not
362        // read as "no matches" — keep whatever is showing and retry with backoff.
363        // (A new keystroke clears the timer; the seq guard drops a stale landing.)
364        if (!results.length && res?.transient) {
365            const delay = SEARCH_RETRY_DELAYS_MS[attempt]
366            if (delay != null) {
367                searchDebounce = setTimeout(() => { void runSearch(q, seq, attempt + 1) }, delay)
368            } else if (!searchResults.value.length) {
369                // Out of retries with nothing to fall back on: say so plainly and
370                // offer a retry, rather than an empty box that looks like "no matches".
371                searchUnavailable.value = true
372                searchOpen.value = true
373                activeIndex.value = -1
374            }
375            return
376        }
377        searchUnavailable.value = false
378        searchResults.value = results
379        searchOpen.value = results.length > 0
380        activeIndex.value = -1
381    } catch {
382        if (seq === searchSeq) closeSearch()
383    }
384}
385 
386/** Manual retry from the "unavailable" hint — refire the search for the current text.
387 *  Returns focus to the input first: clearing the hint unmounts the Retry button, and
388 *  a keyboard user activating it would otherwise have focus fall to <body>. */
389function retrySearch() {
390    const q = (figure.value || '').trim()
391    if (q.length < 2) return
392    searchInputRef.value?.focus()
393    searchUnavailable.value = false
394    void runSearch(q, ++searchSeq)
395}
⋯ 122 lines hidden (lines 396–517)396 
397watch(figure, (name) => {
398    if (searchDebounce) clearTimeout(searchDebounce)
399    const q = (name || '').trim()
400    if (q.length < 2 || q === lastChosen) {
401        closeSearch()
402        // One-shot suppression: it exists to swallow the single model echo a
403        // choice causes. A later deliberate retype of the same name searches again.
404        if (q === lastChosen) lastChosen = ''
405        return
406    }
407    lastChosen = ''
408    searchUnavailable.value = false // a fresh keystroke retires any prior outage hint
409    const seq = ++searchSeq
410    searchDebounce = setTimeout(() => { void runSearch(q, seq) }, 250)
411})
412 
413function onSearchKeydown(e: KeyboardEvent) {
414    if (e.isComposing) return // IME candidate navigation owns these keys
415    // Escape always dismisses: it must clear a populated listbox OR the unavailable
416    // hint, and — even when nothing is on screen yet — cancel a pending backoff retry
417    // and invalidate any in-flight fetch (closeSearch clears the timer and bumps the
418    // seq). Handled before the guard below, which only covers a populated listbox.
419    if (e.key === 'Escape') {
420        closeSearch()
421        return
422    }
423    if (!searchOpen.value || !searchResults.value.length) {
424        // APG editable-combobox: Down Arrow on a closed combobox reopens the popup
425        // (the only recovery after Escape that doesn't require editing the text).
426        if (e.key === 'ArrowDown') {
427            const q = (figure.value || '').trim()
428            if (q.length >= 2) {
429                e.preventDefault()
430                void runSearch(q, ++searchSeq)
431            }
432        }
433        return
434    }
435    if (e.key === 'ArrowDown') {
436        e.preventDefault()
437        activeIndex.value = (activeIndex.value + 1) % searchResults.value.length
438    } else if (e.key === 'ArrowUp') {
439        e.preventDefault()
440        activeIndex.value = activeIndex.value <= 0 ? searchResults.value.length - 1 : activeIndex.value - 1
441    } else if (e.key === 'Enter') {
442        if (activeIndex.value >= 0) {
443            e.preventDefault()
444            choose(searchResults.value[activeIndex.value].name)
445        }
446    }
447    // Escape is handled up top (it must also dismiss the unavailable hint, where
448    // searchResults is empty and this block is skipped).
449}
450 
451/** Close when focus genuinely leaves the combobox (not when it moves within it). */
452function onSearchFocusOut(e: FocusEvent) {
453    const next = e.relatedTarget as Node | null
454    if (next && searchBoxRef.value?.contains(next)) return
455    closeSearch()
456}
457 
458/** Spoken result count — aria-expanded alone is not reliably announced while typing. */
459const searchStatus = computed(() =>
460    searchUnavailable.value
461        ? 'The record is unreachable right now — press the down arrow or Retry to search again.'
462        : listboxOpen.value
463            ? `${searchResults.value.length} ${searchResults.value.length === 1 ? 'match' : 'matches'} — up and down arrows to review, Enter to choose`
464            : ''
465)
466 
467function chipClass(name: string) {
468    return name === figure.value ? 'rv-tint rv-fg' : 'rv-muted rv-hover'
469}
470function suggestionClass(name: string) {
471    return name === figure.value ? 'rv-tint' : 'rv-hover'
472}
473 
474// Ground the chosen figure, debounced so typing doesn't spam the lookup. The
475// PREVIOUS dossier is cleared synchronously the instant the name changes: a send
476// fired during the debounce/fetch window must go out clean (free-form), never
477// wearing the old figure's facts, year, or liveness gate.
478let debounce: ReturnType<typeof setTimeout> | null = null
479watch(figure, (name) => {
480    if (debounce) clearTimeout(debounce)
481    gameStore.clearGrounding()
482    const trimmed = (name || '').trim()
483    if (!trimmed) return
484    debounce = setTimeout(() => gameStore.groundActiveFigure(trimmed), 350)
485})
486onUnmounted(() => {
487    if (debounce) clearTimeout(debounce)
488    if (searchDebounce) clearTimeout(searchDebounce)
489})
490 
491// Load era-relevant suggestions for the current objective when the board appears.
492onMounted(() => gameStore.loadSuggestions())
493</script>
494 
495<style scoped>
496/* Quiet placeholder bars while the suggester works — letterpress tint, a gentle
497   pulse, stilled under reduced motion. Never a clickable fake. */
498.skeleton-line {
499    display: block;
500    height: 10px;
501    border-radius: 2px;
502    background: var(--rv-tint);
503    animation: skeleton-pulse 1.6s var(--rv-ease) infinite;
504}
505@keyframes skeleton-pulse {
506    0%, 100% { opacity: .55; }
507    50% { opacity: 1; }
508}
509@media (prefers-reduced-motion: reduce) {
510    .skeleton-line { animation: none; }
511}
512 
513/* The autocomplete pop floats over the dossier on warm paper, not chrome. */
514.search-pop {
515    box-shadow: 0 6px 18px color-mix(in srgb, var(--rv-fg) 10%, transparent);
516}
517</style>

Tests that pin the behavior

The server test asserts the header is compliant: it carries the app name and a reachable contact (a mailto: or URL). It is a discriminating test — drop the contact and it fails.

The User-Agent carries the app name plus a reachable contact.

tests/unit/server/utils/figure-search.spec.ts · 125 lines

tests/unit/server/utils/figure-search.spec.ts125 lines · TypeScript

⋯ 68 lines hidden (lines 1–68)1import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
2import { searchFigures } from '../../../../server/utils/figure-search'
3 
4/** Wikipedia REST v1 title-search response, shaped like the real thing. */
5function wikiResponse(pages: unknown[]) {
  return {
      ok: true,
      json: async () => ({ pages })
  } as Response
10}
11 
12describe('figure search (name autocomplete)', () => {
  let fetchMock: ReturnType<typeof vi.fn>
14 
  beforeEach(() => {
      fetchMock = vi.fn()
      vi.stubGlobal('fetch', fetchMock)
  })
19 
  afterEach(() => {
      vi.useRealTimers()
      vi.unstubAllGlobals()
  })
24 
  it('maps titles, descriptions, and protocol-relative thumbnails', async () => {
      fetchMock.mockResolvedValue(wikiResponse([
          {
              title: 'Cleopatra',
              description: 'Pharaoh of Egypt from 51 to 30 BC',
              thumbnail: { url: '//upload.wikimedia.org/kleo.jpg' }
          },
          { title: 'Cleopatra (1963 film)', description: '1963 film', thumbnail: null }
      ]))
34 
      const outcome = await searchFigures('cleopat')
36 
      expect(outcome.transient).toBe(false)
      expect(outcome.results).toEqual([
          {
              name: 'Cleopatra',
              description: 'Pharaoh of Egypt from 51 to 30 BC',
              thumbnail: 'https://upload.wikimedia.org/kleo.jpg'
          },
          { name: 'Cleopatra (1963 film)', description: '1963 film', thumbnail: undefined }
      ])
  })
47 
  it('drops unsafe thumbnail schemes (the unsafe-render rule)', async () => {
      fetchMock.mockResolvedValue(wikiResponse([
          { title: 'Spoofed', description: 'x', thumbnail: { url: 'javascript:alert(1)' } }
      ]))
      const { results } = await searchFigures('spoofed person')
      expect(results[0].thumbnail).toBeUndefined()
  })
55 
  it('returns [] without fetching for queries under two characters', async () => {
      expect(await searchFigures('a')).toEqual({ results: [], transient: false })
      expect(await searchFigures('  ')).toEqual({ results: [], transient: false })
      expect(fetchMock).not.toHaveBeenCalled()
  })
61 
  it('caches a query — the second call never refetches', async () => {
      fetchMock.mockResolvedValue(wikiResponse([{ title: 'Nikola Tesla', description: 'Inventor' }]))
      await searchFigures('tesla cache probe')
      await searchFigures('Tesla Cache Probe') // case-insensitive key
      expect(fetchMock).toHaveBeenCalledTimes(1)
  })
68 
  it('sends a Wikimedia-policy-compliant User-Agent (identifies the app + a contact URL)', async () => {
      // A non-compliant agent (no contact) gets throttled harder — the dominant
      // cause of the autocomplete silently failing (issue #58).
      fetchMock.mockResolvedValue(wikiResponse([{ title: 'Leonardo da Vinci', description: 'Polymath' }]))
      await searchFigures('leonardo ua probe')
74 
      const init = fetchMock.mock.calls[0][1] as RequestInit
      const ua = String((init.headers as Record<string, string>)['User-Agent'])
      expect(ua).toContain('Revisionist')
      expect(ua).toMatch(/mailto:\S+@\S+|https?:\/\/\S+/) // a reachable contact, per the UA policy
  })
80 
  it('retries a rate-limited search once and recovers the matches', async () => {
⋯ 44 lines hidden (lines 82–125)82        vi.useFakeTimers()
      fetchMock
          .mockResolvedValueOnce({ ok: false, status: 429 } as Response)
          .mockResolvedValueOnce(wikiResponse([{ title: 'Alfred Nobel', description: 'Inventor of dynamite' }]))
86 
      const pending = searchFigures('alfred retry probe')
      await vi.advanceTimersByTimeAsync(250)
      const outcome = await pending
90 
      expect(outcome.transient).toBe(false)
      expect(outcome.results[0].name).toBe('Alfred Nobel')
      expect(fetchMock).toHaveBeenCalledTimes(2)
  })
95 
  it('a failure that survives the retry is flagged transient — weather, not "no matches"', async () => {
      vi.useFakeTimers()
      fetchMock.mockRejectedValue(new Error('offline'))
99 
      const pending = searchFigures('failing query one')
      await vi.advanceTimersByTimeAsync(250)
      expect(await pending).toEqual({ results: [], transient: true })
  })
104 
  it('a real empty answer is NOT transient (and caches like any answer)', async () => {
      fetchMock.mockResolvedValue(wikiResponse([]))
      expect(await searchFigures('xqzv nobody')).toEqual({ results: [], transient: false })
      await searchFigures('xqzv nobody')
      expect(fetchMock).toHaveBeenCalledTimes(1)
  })
111 
  it('never caches a failure — the next call for the same query refetches', async () => {
      vi.useFakeTimers()
      fetchMock.mockRejectedValueOnce(new Error('wikipedia blip')).mockRejectedValueOnce(new Error('still down'))
      const pending = searchFigures('transient blip probe')
      await vi.advanceTimersByTimeAsync(250)
      expect((await pending).transient).toBe(true)
118 
      fetchMock.mockResolvedValueOnce(wikiResponse([{ title: 'Recovered', description: 'after the blip' }]))
      const second = await searchFigures('transient blip probe')
121 
      expect(fetchMock).toHaveBeenCalledTimes(3)
      expect(second.results).toEqual([{ name: 'Recovered', description: 'after the blip', thumbnail: undefined }])
  })
125})

The component tests cover the new client paths end to end: the visible retryable hint after backoff exhausts (and that Retry recovers), a fresh keystroke retiring the hint, Escape cancelling a pending retry so nothing pops up later, Escape dismissing the visible hint, and keyboard Retry keeping focus in the combobox. Each maps to one of the fixes above and would fail if that fix were reverted.

The issue-#58 block: backoff give-up, retry recovery, Escape, and focus retention.

tests/unit/components/FigurePicker.spec.ts · 556 lines

tests/unit/components/FigurePicker.spec.ts556 lines · TypeScript

⋯ 202 lines hidden (lines 1–202)1import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
2import { mount } from '@vue/test-utils'
3import { setActivePinia, createPinia } from 'pinia'
4import FigurePicker from '../../../components/FigurePicker.vue'
5import { useGameStore } from '../../../stores/game'
6 
7const CLEO = {
  name: 'Cleopatra',
  resolved: true,
  description: 'Pharaoh of Egypt from 51 to 30 BC',
  born: { year: 69, bce: true, signed: -69, display: '69 BC' },
  died: { year: 30, bce: true, signed: -30, display: '30 BC' },
  living: false,
  thumbnail: 'https://example.org/cleo.jpg',
  wikiUrl: 'https://en.wikipedia.org/wiki/Cleopatra'
16}
17 
18describe('FigurePicker', () => {
  let gameStore: ReturnType<typeof useGameStore>
  let fetchMock: ReturnType<typeof vi.fn>
21 
  beforeEach(() => {
      setActivePinia(createPinia())
      gameStore = useGameStore()
      // The grounding + autocomplete watches call $fetch; stub it with a handle
      // the combobox tests can program.
      fetchMock = vi.fn()
      vi.stubGlobal('$fetch', fetchMock)
  })
30 
  afterEach(() => {
      vi.unstubAllGlobals()
      vi.restoreAllMocks()
  })
35 
  it('offers cross-era suggestions to start from', () => {
      const wrapper = mount(FigurePicker)
      expect(wrapper.find('[data-testid="figure-picker"]').exists()).toBe(true)
      expect(wrapper.findAll('[data-testid="suggestion-chip"]').length).toBeGreaterThan(0)
  })
41 
  it('shows quiet skeletons while suggestions load — never clickable generic defaults', async () => {
      gameStore.suggestionsLoading = true
      gameStore.figureSuggestions = []
      const wrapper = mount(FigurePicker)
46 
      expect(wrapper.find('[data-testid="suggestion-skeletons"]').exists()).toBe(true)
      expect(wrapper.findAll('[data-testid="suggestion-chip"]')).toHaveLength(0)
      expect(wrapper.text()).toContain('finding figures who matter here')
  })
51 
  it('labels the famous-names fallback honestly once the agent has come up empty', () => {
      gameStore.suggestionsLoading = false
      gameStore.figureSuggestions = []
      const wrapper = mount(FigurePicker)
56 
      expect(wrapper.find('[data-testid="suggestion-skeletons"]').exists()).toBe(false)
      expect(wrapper.findAll('[data-testid="suggestion-chip"]').length).toBeGreaterThan(0)
      expect(wrapper.text()).toContain('some famous names to start with')
      expect(wrapper.text()).not.toContain('finding figures who matter here')
  })
62 
  describe('name autocomplete (combobox)', () => {
      const RESULTS = {
          results: [
              { name: 'Cleopatra', description: 'Pharaoh of Egypt from 51 to 30 BC', thumbnail: 'https://upload.wikimedia.org/kleo.jpg' },
              { name: 'Cleopatra (1963 film)', description: '1963 film' }
          ]
      }
70 
      function mountPicker(modelValue = '') {
          return mount(FigurePicker, { props: { modelValue } })
      }
74 
      async function typeAndSettle(wrapper: ReturnType<typeof mountPicker>, text: string) {
          await wrapper.setProps({ modelValue: text })
          await vi.advanceTimersByTimeAsync(260) // past the 250ms search debounce
          await wrapper.vm.$nextTick()
      }
80 
      beforeEach(() => {
          vi.useFakeTimers()
      })
84 
      afterEach(() => {
          vi.useRealTimers()
      })
88 
      it('offers matches from the record as you type, with descriptions', async () => {
          fetchMock.mockResolvedValue(RESULTS)
          const wrapper = mountPicker()
92 
          await typeAndSettle(wrapper, 'cleopat')
94 
          const options = wrapper.findAll('[data-testid="figure-search-option"]')
          expect(options).toHaveLength(2)
          expect(options[0].text()).toContain('Cleopatra')
          expect(options[0].text()).toContain('Pharaoh of Egypt')
          expect(wrapper.find('#figure-input').attributes('aria-expanded')).toBe('true')
          wrapper.unmount()
      })
102 
      it('arrow keys + Enter choose an option and fill the input', async () => {
          fetchMock.mockResolvedValue(RESULTS)
          const wrapper = mountPicker()
          await typeAndSettle(wrapper, 'cleopat')
107 
          const input = wrapper.find('#figure-input')
          await input.trigger('keydown', { key: 'ArrowDown' })
          await input.trigger('keydown', { key: 'Enter' })
111 
          const emitted = wrapper.emitted('update:modelValue')
          expect(emitted?.at(-1)).toEqual(['Cleopatra'])
          expect(wrapper.find('[data-testid="figure-search-listbox"]').exists()).toBe(false)
          wrapper.unmount()
      })
117 
      it('Escape closes the dropdown without touching the input', async () => {
          fetchMock.mockResolvedValue(RESULTS)
          const wrapper = mountPicker()
          await typeAndSettle(wrapper, 'cleopat')
          expect(wrapper.find('[data-testid="figure-search-listbox"]').exists()).toBe(true)
123 
          await wrapper.find('#figure-input').trigger('keydown', { key: 'Escape' })
125 
          expect(wrapper.find('[data-testid="figure-search-listbox"]').exists()).toBe(false)
          wrapper.unmount()
      })
129 
      it('a response still in flight cannot reopen the dropdown after a choice (close invalidates)', async () => {
          let release!: (v: unknown) => void
          fetchMock.mockReturnValue(new Promise((res) => { release = res }))
          const wrapper = mountPicker()
134 
          await wrapper.setProps({ modelValue: 'cleopat' })
          await vi.advanceTimersByTimeAsync(260) // debounce fires — fetch now in flight
137 
          // The player picks a suggestion chip while the search is still out.
          await wrapper.find('[data-testid="suggestion-chip"]').trigger('click')
140 
          release(RESULTS) // the stale response limps home
          await vi.advanceTimersByTimeAsync(1)
          await wrapper.vm.$nextTick()
144 
          expect(wrapper.find('[data-testid="figure-search-listbox"]').exists()).toBe(false)
          wrapper.unmount()
      })
148 
      it('retyping a previously chosen name searches again (suppression is one-shot)', async () => {
          fetchMock.mockResolvedValue(RESULTS)
          const wrapper = mountPicker()
          await typeAndSettle(wrapper, 'cleopat')
          await wrapper.find('#figure-input').trigger('keydown', { key: 'ArrowDown' })
          await wrapper.find('#figure-input').trigger('keydown', { key: 'Enter' })
          await typeAndSettle(wrapper, 'Cleopatra') // the v-model echo — suppressed once
156 
          await typeAndSettle(wrapper, '') // player clears the field…
          await typeAndSettle(wrapper, 'Cleopatra') // …and deliberately retypes the name
159 
          expect(wrapper.find('[data-testid="figure-search-listbox"]').exists()).toBe(true)
          wrapper.unmount()
      })
163 
      it('a transient miss quietly retries once — weather never reads as "no matches"', async () => {
          // Route by URL: the grounding watcher shares $fetch and must not eat
          // the queued search answers.
          let searchCalls = 0
          fetchMock.mockImplementation((url: unknown) => {
              if (!String(url).includes('figure-search')) return Promise.resolve({ name: '', resolved: false })
              searchCalls++
              return Promise.resolve(searchCalls === 1 ? { results: [], transient: true } : RESULTS)
          })
          const wrapper = mountPicker()
174 
          await typeAndSettle(wrapper, 'alfred nob')
          // First answer was rate-limit weather: nothing shows yet, no "no matches" state.
          expect(wrapper.find('[data-testid="figure-search-listbox"]').exists()).toBe(false)
178 
          // The quiet retry (800ms) lands the real matches without another keystroke.
          await vi.advanceTimersByTimeAsync(810)
          await wrapper.vm.$nextTick()
          expect(wrapper.findAll('[data-testid="figure-search-option"]')).toHaveLength(2)
          wrapper.unmount()
      })
185 
      it('a transient miss never blanks results already on screen', async () => {
          fetchMock.mockResolvedValueOnce(RESULTS)
          const wrapper = mountPicker()
          await typeAndSettle(wrapper, 'cleopat')
          expect(wrapper.findAll('[data-testid="figure-search-option"]')).toHaveLength(2)
191 
          // The next keystroke's search hits weather twice (initial + quiet retry).
          fetchMock.mockResolvedValue({ results: [], transient: true })
          await typeAndSettle(wrapper, 'cleopatr')
          await vi.advanceTimersByTimeAsync(810)
          await wrapper.vm.$nextTick()
197 
          // The prior list stays up rather than vanishing mid-type.
          expect(wrapper.findAll('[data-testid="figure-search-option"]')).toHaveLength(2)
          wrapper.unmount()
      })
202 
      it('after retries fail with nothing to show, offers a visible, retryable hint (issue #58)', async () => {
          // Sustained weather and no prior list to fall back on: the box must say so
          // (and let the player retry), not sit silently empty like a real "no matches".
          fetchMock.mockImplementation((url: unknown) =>
              String(url).includes('figure-search')
                  ? Promise.resolve({ results: [], transient: true })
                  : Promise.resolve({ name: '', resolved: false })
          )
          const wrapper = mountPicker()
212 
          await typeAndSettle(wrapper, 'leonardo')   // attempt 0 → transient
          await vi.advanceTimersByTimeAsync(810)     // backoff retry 1 (800ms) → transient
          await vi.advanceTimersByTimeAsync(1610)    // backoff retry 2 (1600ms) → give up
          await wrapper.vm.$nextTick()
217 
          expect(wrapper.find('[data-testid="figure-search-unavailable"]').exists()).toBe(true)
          expect(wrapper.find('[data-testid="figure-search-listbox"]').exists()).toBe(false)
          expect(wrapper.find('#figure-input').attributes('aria-expanded')).toBe('false')
          // The screen-reader status announces the outage (not a misleading "0 matches").
          expect(wrapper.find('.sr-only').text()).toContain('unreachable')
223 
          // Retry recovers the moment the weather clears.
          fetchMock.mockImplementation((url: unknown) =>
              String(url).includes('figure-search')
                  ? Promise.resolve(RESULTS)
                  : Promise.resolve({ name: '', resolved: false })
          )
          await wrapper.find('[data-testid="figure-search-retry"]').trigger('click')
          await vi.advanceTimersByTimeAsync(1)
          await wrapper.vm.$nextTick()
233 
          expect(wrapper.find('[data-testid="figure-search-unavailable"]').exists()).toBe(false)
          expect(wrapper.findAll('[data-testid="figure-search-option"]')).toHaveLength(2)
          expect(wrapper.find('.sr-only').text()).not.toContain('unreachable')
          wrapper.unmount()
      })
239 
      it('Escape during a backoff wait cancels the pending retry — nothing pops up later (issue #58)', async () => {
          // The player types, hits weather, then gives up and presses Escape before
          // any retry lands. The armed backoff timer must be cancelled, not fire later
          // and resurrect the dropdown over a field they walked away from.
          fetchMock.mockImplementation((url: unknown) =>
              String(url).includes('figure-search')
                  ? Promise.resolve({ results: [], transient: true })
                  : Promise.resolve({ name: '', resolved: false })
          )
          const wrapper = mountPicker()
          await typeAndSettle(wrapper, 'leonardo')  // attempt 0 → transient → retry armed at 800ms
          await wrapper.find('#figure-input').trigger('keydown', { key: 'Escape' })
252 
          await vi.advanceTimersByTimeAsync(2500)   // well past both backoff delays
          await wrapper.vm.$nextTick()
255 
          expect(wrapper.find('[data-testid="figure-search-unavailable"]').exists()).toBe(false)
          expect(wrapper.find('[data-testid="figure-search-listbox"]').exists()).toBe(false)
          expect(wrapper.find('#figure-input').attributes('aria-expanded')).toBe('false')
          wrapper.unmount()
      })
261 
      it('Escape dismisses the visible unavailable hint (issue #58)', async () => {
          fetchMock.mockImplementation((url: unknown) =>
              String(url).includes('figure-search')
                  ? Promise.resolve({ results: [], transient: true })
                  : Promise.resolve({ name: '', resolved: false })
          )
          const wrapper = mountPicker()
          await typeAndSettle(wrapper, 'leonardo')
          await vi.advanceTimersByTimeAsync(810)
          await vi.advanceTimersByTimeAsync(1610)
          await wrapper.vm.$nextTick()
          expect(wrapper.find('[data-testid="figure-search-unavailable"]').exists()).toBe(true)
274 
          await wrapper.find('#figure-input').trigger('keydown', { key: 'Escape' })
276 
          expect(wrapper.find('[data-testid="figure-search-unavailable"]').exists()).toBe(false)
          expect(wrapper.find('.sr-only').text()).not.toContain('unreachable')
          wrapper.unmount()
      })
281 
      it('keyboard Retry keeps focus in the combobox, not lost to the body (issue #58)', async () => {
          fetchMock.mockImplementation((url: unknown) =>
              String(url).includes('figure-search')
                  ? Promise.resolve({ results: [], transient: true })
                  : Promise.resolve({ name: '', resolved: false })
          )
          const wrapper = mount(FigurePicker, { props: { modelValue: '' }, attachTo: document.body })
          await wrapper.setProps({ modelValue: 'leonardo' })
          await vi.advanceTimersByTimeAsync(260)
          await vi.advanceTimersByTimeAsync(810)
          await vi.advanceTimersByTimeAsync(1610)
          await wrapper.vm.$nextTick()
          expect(wrapper.find('[data-testid="figure-search-unavailable"]').exists()).toBe(true)
295 
          fetchMock.mockImplementation((url: unknown) =>
              String(url).includes('figure-search')
                  ? Promise.resolve(RESULTS)
                  : Promise.resolve({ name: '', resolved: false })
          )
⋯ 256 lines hidden (lines 301–556)301            await wrapper.find('[data-testid="figure-search-retry"]').trigger('click')
          // Clearing the hint unmounts the Retry button; focus must land back on the
          // input, not fall to <body>.
          expect(document.activeElement).toBe(wrapper.find('#figure-input').element)
305 
          await vi.advanceTimersByTimeAsync(1)
          await wrapper.vm.$nextTick()
          expect(wrapper.findAll('[data-testid="figure-search-option"]')).toHaveLength(2)
          wrapper.unmount()
      })
311 
      it('a fresh keystroke retires the unavailable hint', async () => {
          fetchMock.mockImplementation((url: unknown) =>
              String(url).includes('figure-search')
                  ? Promise.resolve({ results: [], transient: true })
                  : Promise.resolve({ name: '', resolved: false })
          )
          const wrapper = mountPicker()
          await typeAndSettle(wrapper, 'leonardo')
          await vi.advanceTimersByTimeAsync(810)
          await vi.advanceTimersByTimeAsync(1610)
          await wrapper.vm.$nextTick()
          expect(wrapper.find('[data-testid="figure-search-unavailable"]').exists()).toBe(true)
324 
          // Typing more clears the outage hint while the new search is in flight.
          await wrapper.setProps({ modelValue: 'leonardx' })
          await wrapper.vm.$nextTick()
          expect(wrapper.find('[data-testid="figure-search-unavailable"]').exists()).toBe(false)
          wrapper.unmount()
      })
331 
      it('ArrowDown on a closed combobox reopens the search (APG recovery after Escape)', async () => {
          fetchMock.mockResolvedValue(RESULTS)
          const wrapper = mountPicker()
          await typeAndSettle(wrapper, 'cleopat')
          await wrapper.find('#figure-input').trigger('keydown', { key: 'Escape' })
          expect(wrapper.find('[data-testid="figure-search-listbox"]').exists()).toBe(false)
338 
          await wrapper.find('#figure-input').trigger('keydown', { key: 'ArrowDown' })
          await vi.advanceTimersByTimeAsync(1)
          await wrapper.vm.$nextTick()
342 
          expect(wrapper.find('[data-testid="figure-search-listbox"]').exists()).toBe(true)
          wrapper.unmount()
      })
346 
      it('a chosen name does not reopen the dropdown over its own dossier', async () => {
          fetchMock.mockResolvedValue(RESULTS)
          const wrapper = mountPicker()
          await typeAndSettle(wrapper, 'cleopat')
351 
          const input = wrapper.find('#figure-input')
          await input.trigger('keydown', { key: 'ArrowDown' })
          await input.trigger('keydown', { key: 'Enter' })
355 
          // The parent echoes the chosen value back through the model, as v-model does.
          await typeAndSettle(wrapper, 'Cleopatra')
358 
          expect(wrapper.find('[data-testid="figure-search-listbox"]').exists()).toBe(false)
          wrapper.unmount()
      })
  })
363 
  it('clears the previous dossier the instant the name changes (no stale facts on a fast send)', async () => {
      gameStore.figureGrounding = CLEO as never
      gameStore.contactWhen = -40
      const wrapper = mount(FigurePicker, { props: { modelValue: 'Cleopatra' } })
      expect(wrapper.find('[data-testid="figure-dossier"]').exists()).toBe(true)
369 
      await wrapper.setProps({ modelValue: 'Marie Curie' })
371 
      // A send fired during the grounding debounce must go out clean — never
      // wearing Cleopatra's facts, year, or liveness gate on Curie's name.
      expect(gameStore.figureGrounding).toBeNull()
      expect(gameStore.contactWhen).toBeNull()
      expect(wrapper.find('[data-testid="figure-dossier"]').exists()).toBe(false)
      wrapper.unmount() // clears the pending debounce before $fetch is unstubbed
  })
379 
  it('shows a grounded dossier with lifespan and a lifetime-bounded when slider', () => {
      gameStore.figureGrounding = CLEO as never
      gameStore.contactWhen = -49
      const wrapper = mount(FigurePicker)
384 
      expect(wrapper.find('[data-testid="figure-dossier"]').exists()).toBe(true)
      expect(wrapper.find('[data-testid="dossier-name"]').text()).toBe('Cleopatra')
      expect(wrapper.find('[data-testid="dossier-lifespan"]').text()).toContain('69 BC – 30 BC')
      expect(wrapper.find('[data-testid="when-display"]').text()).toContain('49 BC')
389 
      const slider = wrapper.find('[data-testid="when-slider"]')
      expect(slider.exists()).toBe(true)
      expect(slider.attributes('min')).toBe('-69')
      expect(slider.attributes('max')).toBe('-30')
  })
395 
  it('updates the chosen year when the slider moves', async () => {
      gameStore.figureGrounding = CLEO as never
      gameStore.contactWhen = -49
      const wrapper = mount(FigurePicker)
400 
      await wrapper.find('[data-testid="when-slider"]').setValue('-40')
      expect(gameStore.contactWhen).toBe(-40)
  })
404 
  it('shows the figure age at the chosen year, and updates it live with the slider', async () => {
      gameStore.figureGrounding = CLEO as never
      gameStore.contactWhen = -49
      const wrapper = mount(FigurePicker)
409 
      // 49 BC: Cleopatra (born 69 BC) is 20.
      expect(wrapper.find('[data-testid="when-age"]').text()).toContain('age 20')
412 
      await wrapper.find('[data-testid="when-slider"]').setValue('-40')
      expect(wrapper.find('[data-testid="when-age"]').text()).toContain('age 29')
  })
416 
  it('omits the age when there is no birth year to anchor it', () => {
      gameStore.figureGrounding = { name: 'Nobody', resolved: false } as never
      const wrapper = mount(FigurePicker)
      expect(wrapper.find('[data-testid="when-age"]').exists()).toBe(false)
  })
422 
  it('pins a moment: month chips refine the display, day clamps, unpin restores (issue #32)', async () => {
      gameStore.figureGrounding = CLEO as never
      gameStore.contactWhen = -48
      const wrapper = mount(FigurePicker)
427 
      expect(wrapper.find('[data-testid="when-display"]').text()).toContain('48 BC')
      await wrapper.find('[data-testid="pin-moment"]').trigger('click')
430 
      const chips = wrapper.findAll('[data-testid="month-chip"]')
      expect(chips).toHaveLength(12)
      await chips[2].trigger('click') // March
      expect(gameStore.contactMoment).toEqual({ month: 3 })
      expect(wrapper.find('[data-testid="when-display"]').text()).toContain('March 48 BC')
436 
      // Day input clamps to the month's cap (no calendar math, just the table).
      await wrapper.find('[data-testid="moment-day"]').setValue('45')
      expect(gameStore.contactMoment).toEqual({ month: 3, day: 31 })
      await wrapper.find('[data-testid="moment-day"]').setValue('15')
      expect(wrapper.find('[data-testid="when-display"]').text()).toContain('March 15, 48 BC')
442 
      // The slider keeps the pin; unpin restores the plain year.
      await wrapper.find('[data-testid="when-slider"]').setValue('-44')
      expect(wrapper.find('[data-testid="when-display"]').text()).toContain('March 15, 44 BC')
      await wrapper.find('[data-testid="unpin-moment"]').trigger('click')
      expect(gameStore.contactMoment).toBeNull()
      expect(wrapper.find('[data-testid="when-display"]').text()).toContain('44 BC')
      expect(wrapper.find('[data-testid="when-display"]').text()).not.toContain('March')
  })
451 
  it('says so honestly when a resolved figure has no dates — note, no slider, no lifespan', () => {
      gameStore.figureGrounding = {
          name: 'Mysterious Sage',
          resolved: true,
          description: 'Semi-legendary teacher'
      } as never
      const wrapper = mount(FigurePicker)
459 
      expect(wrapper.find('[data-testid="figure-dossier"]').exists()).toBe(true)
      expect(wrapper.find('[data-testid="when-control"]').exists()).toBe(false)
      expect(wrapper.find('[data-testid="when-slider"]').exists()).toBe(false)
      expect(wrapper.find('[data-testid="dossier-lifespan"]').exists()).toBe(false)
      expect(wrapper.find('[data-testid="when-unknown"]').text()).toContain('No dates could be found')
  })
466 
  it('passes circa displays through verbatim — one "c." marker, never on the chosen year', () => {
      gameStore.figureGrounding = {
          name: 'Homer',
          resolved: true,
          description: 'Ancient Greek poet',
          born: { year: 800, bce: true, signed: -800, display: 'c. 800 BC', circa: true },
          died: { year: 720, bce: true, signed: -720, display: 'c. 720 BC', circa: true },
          living: false
      } as never
      gameStore.contactWhen = -760
      const wrapper = mount(FigurePicker)
478 
      // Exact equality: a component-side re-format (a second "c." prefix, a
      // dropped marker) must fail here, not ship.
      expect(wrapper.find('[data-testid="dossier-lifespan"]').text()).toBe('c. 800 BC – c. 720 BC')
      const slider = wrapper.find('[data-testid="when-slider"]')
      expect(slider.attributes('min')).toBe('-800')
      expect(slider.attributes('max')).toBe('-720')
      // The chosen year itself stays exact — the player picked it.
      expect(wrapper.find('[data-testid="when-display"]').text()).not.toContain('c.')
      expect(wrapper.find('[data-testid="when-display"]').text()).toContain('760 BC')
  })
489 
  it('offers a "Study them" action for a grounded figure', () => {
      gameStore.figureGrounding = CLEO as never
      const wrapper = mount(FigurePicker)
      expect(wrapper.find('[data-testid="study-button"]').exists()).toBe(true)
      expect(wrapper.find('[data-testid="figure-study"]').exists()).toBe(false)
  })
496 
  it('renders the Archivist brief once the figure has been studied', () => {
      gameStore.figureGrounding = CLEO as never
      gameStore.figureStudy = {
          atThisMoment: 'Queen at the height of her power.',
          grasp: ['statecraft'],
          reaching: ['securing Egypt against Rome'],
          cannotYetKnow: 'the fall of the Republic'
      }
      gameStore.studyFor = 'Cleopatra'
      gameStore.studyWhen = -49
      gameStore.contactWhen = -49
      const wrapper = mount(FigurePicker)
509 
      expect(wrapper.find('[data-testid="figure-study"]').exists()).toBe(true)
      expect(wrapper.text()).toContain('Queen at the height of her power')
      expect(wrapper.text()).toContain('securing Egypt against Rome')
      expect(wrapper.text()).toContain('the fall of the Republic')
      // The brief replaces the prompt to study; same year, so no re-study prompt.
      expect(wrapper.find('[data-testid="study-button"]').exists()).toBe(false)
      expect(wrapper.find('[data-testid="restudy-button"]').exists()).toBe(false)
  })
518 
  it('offers a re-study once the contact year has moved since the brief', () => {
      gameStore.figureGrounding = CLEO as never
      gameStore.figureStudy = {
          atThisMoment: 'Queen at the height of her power.',
          grasp: ['statecraft'], reaching: ['securing Egypt'], cannotYetKnow: 'the fall of the Republic'
      }
      gameStore.studyFor = 'Cleopatra'
      gameStore.studyWhen = -49 // studied at 49 BC
      gameStore.contactWhen = -40 // but the slider has since moved to 40 BC
      const wrapper = mount(FigurePicker)
529 
      const restudy = wrapper.find('[data-testid="restudy-button"]')
      expect(restudy.exists()).toBe(true)
      expect(restudy.text()).toContain('40 BC')
  })
534 
  it('falls back gracefully for an unresolved figure', () => {
      gameStore.figureGrounding = { name: 'Nobody', resolved: false } as never
      const wrapper = mount(FigurePicker)
      expect(wrapper.find('[data-testid="figure-unresolved"]').exists()).toBe(true)
      expect(wrapper.find('[data-testid="figure-dossier"]').exists()).toBe(false)
  })
541 
  it('shows era-relevant suggestions with reasons once loaded', () => {
      // Pre-seed as already-loaded so onMounted's loadSuggestions is a cache no-op.
      gameStore.currentObjective = { title: 'Prevent the Great War', description: '', era: '', icon: '🕊️' } as never
      gameStore.suggestionsFor = 'Prevent the Great War'
      gameStore.figureSuggestions = [
          { name: 'Wilhelm II', reason: 'German Emperor who could restrain Vienna.', lifespan: '1859 – 1941' }
      ]
549 
      const wrapper = mount(FigurePicker)
      const chips = wrapper.findAll('[data-testid="suggestion-chip"]')
      expect(chips).toHaveLength(1)
      expect(chips[0].text()).toContain('Wilhelm II')
      expect(wrapper.find('[data-testid="suggestion-reason"]').text()).toContain('restrain Vienna')
  })
556})