Suggestion blurbs that reflect the altered timeline (#131)

What changed, and why

A figure's suggestion blurb — the one-line "why this figure matters" under a name in the contact picker — kept describing that figure's original fate even after the player had overturned it on the timeline ledger. From playtesting: after a node where Majorian survives past 461, the panel still called him someone whose "early death after only four years meant the West lost its last chance." It quietly contradicted the timeline the player was building.

Two facts caused it. Blurbs were fetched once per objective and never refreshed. And the suggester was handed only {title, description, era} — it never saw the ledger, so a blurb had no way to know what had changed.

This PR does three things: it feeds the landed ledger to the suggester so each blurb re-narrates against the altered history; it re-runs the suggester after each change (non-blocking, the suggestion-side twin of the living Chronicle); and when a blurb changes, it plays a "history rewritten" flourish — the old wording struck through and bled away while the new writes in over it.

The suggester's brief re-narrates against the timeline

The suggester is a small tool-using agent; the only thing it acts on is the brief it's handed. The fix folds the landed changes into that brief as the history that now stands, with one instruction: where a change has overturned a figure's known fate, say what's now true of them — never re-assert the outcome the change reversed. The framing is conditional, so a turn with no changes yet produces a brief byte-identical to the tuned original.

The conditional altered-timeline section, appended only when there are changes.

server/utils/figure-suggester.ts · 337 lines

server/utils/figure-suggester.ts337 lines · TypeScript

⋯ 149 lines hidden (lines 1–149)1/**
* Figure suggester — a small tool-using agent (grounding slice 2, see docs/ROADMAP.md).
*
* Given the run's objective, it proposes real historical figures the player could
* message, each with a one-line reason. It's built as a mini-agent: the model may
* call `lookup_figure` (which reuses the Wikidata/Wikipedia grounding) to verify a
* candidate exists and learn their era/role, so suggestions stay accurate rather
* than hallucinated. If the model is unavailable or misbehaves, a curated fallback
* guarantees the player is never left without ideas.
*
* Runs on the lane the routing table picks (ai-routing.ts): the agent loop is
* implemented per provider — the tool-call wire shapes differ — but both share
* the same system prompt, tool contract, and final structured-list schema.
*/
15import type { ChatCompletionMessageParam, ChatCompletionTool } from 'openai/resources/chat/completions'
16import type AnthropicSdk from '@anthropic-ai/sdk'
17import { getOpenAIClient, getAnthropicClient } from './ai-gateway'
18import { routeFor } from './ai-routing'
19import { groundFigure, isDeceased, type GroundedFigure } from './figure-grounding'
20import { cleanArray, cleanString, MAX_ERA_CHARS, MAX_OBJECTIVE_TITLE_CHARS, MAX_TIMELINE_ENTRIES } from './validate'
21 
22export interface FigureSuggestion {
  name: string
  reason: string
  lifespan?: string
26}
27 
28/**
* What the model returns on the wire under the strict schema: `lifespan` is ALWAYS
* present (an empty string when unknown). We type the raw parse against this — not
* the public `FigureSuggestion` — so the schema's contract is honest at the boundary;
* the mapping below turns the empty-string sentinel into the optional public field.
* (Surfaced by the ai-contract-drift loop: schema-required vs type-optional.)
*/
35interface FigureSuggestionWire {
  name: string
  reason: string
  lifespan: string
39}
40 
41export interface SuggestionResult {
  suggestions: FigureSuggestion[]
  fallback: boolean
44}
45 
46interface ObjectiveInput {
  title?: string
  description?: string
  era?: string
  /**
   * The changes the player has ALREADY landed on the timeline — era-stamped
   * headlines of the running ledger (issue #131). Threaded into the brief so a
   * reason re-narrates against the altered history instead of asserting a fate the
   * player has since overturned. Empty on the first turn, so the prompt there stays
   * byte-identical to the un-altered ask.
   */
  worldBrief?: string[]
58}
59 
60/**
* Recent landed changes folded into the suggester's altered-timeline brief. A wider
* window than the per-figure character world-brief (bounded to one figure's own past,
* `slice(-5)` in send-message): the suggester re-narrates figures across ALL eras at
* once, so it reads a few more of the latest changes. NOT a parity with that window.
*/
66export const MAX_LEDGER_HEADLINES = 8
67 
68/**
* Coerce an untrusted client ledger into bounded, era-stamped headlines for the
* altered-timeline brief (issue #131). Cap-first (`cleanArray`) so a crafted oversized
* body can't amplify CPU/allocations; then drop headline-less entries, stamp the era,
* and keep only the most recent few. These are the game's own prior turn headlines fed
* back to a model — bounded like every other untrusted field, and (like send-message
* reusing its ledger) not re-moderated; the objective remains the hard-blocked input.
*/
76export function buildLedgerBrief(rawLedger: unknown): string[] {
  return cleanArray(rawLedger, MAX_TIMELINE_ENTRIES)
      .map((e) => {
          const entry = e as { era?: unknown; headline?: unknown }
          const headline = cleanString(entry?.headline, MAX_OBJECTIVE_TITLE_CHARS)
          if (!headline) return null
          const era = cleanString(entry?.era, MAX_ERA_CHARS)
          return era ? `[${era}] ${headline}` : headline
      })
      .filter((l): l is string => l !== null)
      .slice(-MAX_LEDGER_HEADLINES)
87}
88 
89/** Era-agnostic safety net so the player always has somewhere to start. Every name
*  here MUST be a historically deceased figure (the deceased-only floor, #72) — the
*  fallback bypasses the live grounding filter, so a test pins this invariant. */
92const GENERIC_FALLBACK: FigureSuggestion[] = [
  { name: 'Cleopatra', reason: 'A ruler whose alliances reshaped the ancient Mediterranean.' },
  { name: 'Leonardo da Vinci', reason: 'A mind a century ahead — art, war machines, and invention.' },
  { name: 'Genghis Khan', reason: 'Forged the largest contiguous empire in history.' },
  { name: 'Marie Curie', reason: 'A pioneer whose science bent the modern age.' },
  { name: 'Abraham Lincoln', reason: 'Held a fracturing nation together at its hinge point.' }
98]
99 
100function lifespanOf(g: GroundedFigure): string | undefined {
  if (!g.born) return undefined
  if (g.died) return `${g.born.display} – ${g.died.display}`
  return g.living ? `${g.born.display} – present` : g.born.display
104}
105 
106const SYSTEM = `You are a historian helping a player of a timeline game decide whom to contact. Given their grand objective, propose real historical figures whose decisions could plausibly bend events toward it — spanning the relevant era(s) and the dynamics actually at play. Favor figures with real leverage over the situation, and include a few the player might not think of.
107 
108Only suggest figures who have already died — never anyone still living. Call lookup_figure to confirm a person is real, learn their lifespan and role, and check they are deceased; use it to keep every suggestion accurate and era-appropriate. Don't suggest anyone you can't ground, and drop anyone the lookup shows is still living.`
109 
110const LOOKUP_TOOL = {
  name: 'lookup_figure',
  description: 'Verify a real historical figure exists and fetch their lifespan and role.',
  parameters: {
      type: 'object' as const,
      properties: { name: { type: 'string', description: 'The figure’s name to look up' } },
      required: ['name'],
      additionalProperties: false
  }
119}
120 
121const SUGGESTIONS_SCHEMA = {
  type: 'object',
  properties: {
      suggestions: {
          type: 'array',
          items: {
              type: 'object',
              properties: {
                  name: { type: 'string', description: 'The figure’s name' },
                  reason: { type: 'string', description: 'One sentence: why this figure matters for the objective' },
                  lifespan: { type: 'string', description: 'e.g. "69 BC – 30 BC"; empty string if unknown' }
              },
              required: ['name', 'reason', 'lifespan'],
              additionalProperties: false
          }
      }
  },
  required: ['suggestions'],
  additionalProperties: false
140}
141 
142/**
* The research brief handed to the suggester agent. When the player has already
* altered the timeline, the landed changes are folded in as the history that now
* stands, with an instruction to keep each reason consistent with it — the fix for
* blurbs that kept asserting a figure's original fate after the player had overturned
* it (issue #131). Exported for the unit test. With no changes the brief is
* byte-identical to the original objective-only ask.
*/
150export function userBrief(objective: ObjectiveInput): string {
  const altered = objective.worldBrief?.length
      ? `\n\nThe player has ALREADY begun rewriting history — these changes are now real, recorded events on the timeline, not predictions:\n${objective.worldBrief.map(l => `- ${l}`).join('\n')}\nTreat them as the history that now stands. Each reason must fit this altered timeline: where a change above has overturned a figure's known fate (a death undone, a defeat averted, a work never lost), say what is now true of them — never describe the original outcome the change has already reversed.`
      : ''
  return `Objective: "${objective.title ?? 'Alter the course of history'}".
155What winning looks like: ${objective.description ?? '—'}
156${objective.era ? `Anchoring era: ${objective.era}` : ''}${altered}
157 
158Propose 5 figures the player could message to influence this. Verify each with lookup_figure before finalizing.`
159}
160 
161const FINAL_NUDGE = 'Now give your final answer: the 5 figures, each with a one-sentence reason it matters for this objective.'
162 
163/** Runs one lookup_figure call and shapes the evidence the agent reads. */
164async function runLookup(name: string): Promise<object> {
  const g = name ? await groundFigure(name) : ({ name: '', resolved: false } as GroundedFigure)
  return g.resolved
      ? { resolved: true, name: g.name, role: g.description, lifespan: lifespanOf(g), deceased: isDeceased(g) }
⋯ 170 lines hidden (lines 168–337)168        : { resolved: false }
169}
170 
171function mapWire(raw: unknown): FigureSuggestion[] {
  const parsed = raw as { suggestions?: FigureSuggestionWire[] }
  return (parsed.suggestions ?? [])
      .filter(s => s && s.name && s.reason)
      .map(s => ({ name: s.name, reason: s.reason, lifespan: s.lifespan || undefined }))
      .slice(0, 6)
177}
178 
179/**
* Defense in depth for the deceased-only floor (#72): re-ground every proposed
* figure and keep only the confirmed-deceased ones, so a model that ignores the
* instruction can never surface a living person as a one-tap contact. Grounding is
* usually cached (the agent typically looked these up), so usually near-free — a
* final name that differs from a looked-up one costs a fresh bounded lookup, and a
* transient outage drops that pick (fail closed; the list can fall to the curated
* fallback). We also normalize each lifespan to the grounded record. Exported for
* the unit test.
*/
189export async function keepDeceased(suggestions: FigureSuggestion[]): Promise<FigureSuggestion[]> {
  const checked = await Promise.all(suggestions.map(async (s): Promise<FigureSuggestion | null> => {
      const g = await groundFigure(s.name)
      return isDeceased(g) ? { ...s, lifespan: lifespanOf(g) ?? s.lifespan } : null
  }))
  return checked.filter((s): s is FigureSuggestion => s !== null)
195}
196 
197/** Max tool-call rounds in the suggester's research loop — one budget shared by both
*  provider lanes (OpenAI + Anthropic) so a bump can't silently diverge them. */
199const MAX_AGENT_LOOKUP_ROUNDS = 3
200 
201async function runAgentOpenAI(objective: ObjectiveInput): Promise<FigureSuggestion[]> {
  const params = routeFor('suggester').route.openai
  const client = getOpenAIClient()
  const tools: ChatCompletionTool[] = [{
      type: 'function',
      function: {
          name: LOOKUP_TOOL.name,
          description: LOOKUP_TOOL.description,
          parameters: LOOKUP_TOOL.parameters
      }
  }]
  const messages: ChatCompletionMessageParam[] = [
      { role: 'system', content: SYSTEM },
      { role: 'user', content: userBrief(objective) }
  ]
216 
  // Phase 1: let the agent research candidates with the grounding tool.
  for (let round = 0; round < MAX_AGENT_LOOKUP_ROUNDS; round++) {
      const completion = await client.chat.completions.create({
          model: params.model,
          messages,
          tools,
          tool_choice: 'auto',
          // gpt-5.5 rejects `reasoning_effort` alongside function tools on Chat
          // Completions, so we omit it here (the no-tool phase 2 keeps it).
          max_completion_tokens: params.maxTokens
      })
      const msg = completion.choices?.[0]?.message
      if (!msg) break
      messages.push(msg)
      if (!msg.tool_calls?.length) break
232 
      for (const call of msg.tool_calls) {
          let name = ''
          try { name = JSON.parse(call.function.arguments || '{}').name } catch { /* bad args */ }
          const result = await runLookup(name)
          messages.push({ role: 'tool', tool_call_id: call.id, content: JSON.stringify(result) })
      }
  }
240 
  // Phase 2: force a clean structured list out of the research.
  const final = await client.chat.completions.create({
      model: params.model,
      messages: [...messages, { role: 'user', content: FINAL_NUDGE }],
      reasoning_effort: 'low',
      max_completion_tokens: 1500,
      response_format: {
          type: 'json_schema',
          json_schema: { name: 'figure_suggestions', strict: true, schema: SUGGESTIONS_SCHEMA }
      }
  })
252 
  const content = final.choices?.[0]?.message?.content
  if (!content) return []
  return mapWire(JSON.parse(content))
256}
257 
258async function runAgentAnthropic(objective: ObjectiveInput): Promise<FigureSuggestion[]> {
  const params = routeFor('suggester').route.anthropic
  const client = getAnthropicClient()
  const tools: AnthropicSdk.ToolUnion[] = [{
      name: LOOKUP_TOOL.name,
      description: LOOKUP_TOOL.description,
      input_schema: LOOKUP_TOOL.parameters,
      // Strict tools: the API guarantees the input matches the schema.
      strict: true
  }]
  const messages: AnthropicSdk.MessageParam[] = [
      { role: 'user', content: userBrief(objective) }
  ]
  const common = {
      model: params.model,
      max_tokens: params.maxTokens,
      system: SYSTEM,
      ...(params.temperature !== undefined ? { temperature: params.temperature } : {})
  }
277 
  // Phase 1: the research loop — run tools until the model stops asking.
  for (let round = 0; round < MAX_AGENT_LOOKUP_ROUNDS; round++) {
      const response = await client.messages.create({ ...common, messages, tools })
      messages.push({ role: 'assistant', content: response.content })
      const toolUses = response.content.filter(
          (b): b is AnthropicSdk.ToolUseBlock => b.type === 'tool_use'
      )
      if (response.stop_reason !== 'tool_use' || !toolUses.length) break
286 
      const results: AnthropicSdk.ToolResultBlockParam[] = []
      for (const use of toolUses) {
          const name = typeof (use.input as { name?: unknown })?.name === 'string'
              ? (use.input as { name: string }).name
              : ''
          results.push({
              type: 'tool_result',
              tool_use_id: use.id,
              content: JSON.stringify(await runLookup(name))
          })
      }
      messages.push({ role: 'user', content: results })
  }
300 
  // Phase 2: force a clean structured list out of the research.
  const final = await client.messages.create({
      ...common,
      max_tokens: 1500,
      messages: [...messages, { role: 'user', content: FINAL_NUDGE }],
      output_config: { format: { type: 'json_schema', schema: SUGGESTIONS_SCHEMA } }
  })
308 
  const text = final.content.find(
      (b): b is AnthropicSdk.TextBlock => b.type === 'text'
  )?.text
  if (!text) return []
  return mapWire(JSON.parse(text))
314}
315 
316/** Suggests era-relevant figures for an objective, with a curated fallback. */
317export async function suggestFigures(objective: ObjectiveInput): Promise<SuggestionResult> {
  try {
      const { lane } = routeFor('suggester')
      const suggestions = lane === 'anthropic'
          ? await runAgentAnthropic(objective)
          : await runAgentOpenAI(objective)
      // Deceased-only floor (#72): re-ground and drop anyone still living before
      // they reach the player. If that empties the list (a fully misbehaving
      // model), fall through to the curated, all-deceased fallback below.
      const deceased = await keepDeceased(suggestions)
      if (deceased.length) return { suggestions: deceased, fallback: false }
  } catch (error) {
      console.error('Figure suggester agent failed; using fallback:', error)
  }
  return { suggestions: GENERIC_FALLBACK, fallback: true }
332}
333 
334/** Exposed for the fallback path + tests. */
335export function fallbackSuggestions(): FigureSuggestion[] {
  return [...GENERIC_FALLBACK]
337}

The ledger crosses the boundary, bounded once

The ledger arrives from the client, so it's untrusted input reaching a model prompt. buildLedgerBrief is the one place it's coerced: cap the array first (so a crafted oversized body can't amplify CPU before the count cap), then drop headline-less entries, stamp the era, and keep the most recent few.

Cap-first, then coerce + bound each field — the established input discipline.

server/utils/figure-suggester.ts · 337 lines

server/utils/figure-suggester.ts337 lines · TypeScript

⋯ 65 lines hidden (lines 1–65)1/**
* Figure suggester — a small tool-using agent (grounding slice 2, see docs/ROADMAP.md).
*
* Given the run's objective, it proposes real historical figures the player could
* message, each with a one-line reason. It's built as a mini-agent: the model may
* call `lookup_figure` (which reuses the Wikidata/Wikipedia grounding) to verify a
* candidate exists and learn their era/role, so suggestions stay accurate rather
* than hallucinated. If the model is unavailable or misbehaves, a curated fallback
* guarantees the player is never left without ideas.
*
* Runs on the lane the routing table picks (ai-routing.ts): the agent loop is
* implemented per provider — the tool-call wire shapes differ — but both share
* the same system prompt, tool contract, and final structured-list schema.
*/
15import type { ChatCompletionMessageParam, ChatCompletionTool } from 'openai/resources/chat/completions'
16import type AnthropicSdk from '@anthropic-ai/sdk'
17import { getOpenAIClient, getAnthropicClient } from './ai-gateway'
18import { routeFor } from './ai-routing'
19import { groundFigure, isDeceased, type GroundedFigure } from './figure-grounding'
20import { cleanArray, cleanString, MAX_ERA_CHARS, MAX_OBJECTIVE_TITLE_CHARS, MAX_TIMELINE_ENTRIES } from './validate'
21 
22export interface FigureSuggestion {
  name: string
  reason: string
  lifespan?: string
26}
27 
28/**
* What the model returns on the wire under the strict schema: `lifespan` is ALWAYS
* present (an empty string when unknown). We type the raw parse against this — not
* the public `FigureSuggestion` — so the schema's contract is honest at the boundary;
* the mapping below turns the empty-string sentinel into the optional public field.
* (Surfaced by the ai-contract-drift loop: schema-required vs type-optional.)
*/
35interface FigureSuggestionWire {
  name: string
  reason: string
  lifespan: string
39}
40 
41export interface SuggestionResult {
  suggestions: FigureSuggestion[]
  fallback: boolean
44}
45 
46interface ObjectiveInput {
  title?: string
  description?: string
  era?: string
  /**
   * The changes the player has ALREADY landed on the timeline — era-stamped
   * headlines of the running ledger (issue #131). Threaded into the brief so a
   * reason re-narrates against the altered history instead of asserting a fate the
   * player has since overturned. Empty on the first turn, so the prompt there stays
   * byte-identical to the un-altered ask.
   */
  worldBrief?: string[]
58}
59 
60/**
* Recent landed changes folded into the suggester's altered-timeline brief. A wider
* window than the per-figure character world-brief (bounded to one figure's own past,
* `slice(-5)` in send-message): the suggester re-narrates figures across ALL eras at
* once, so it reads a few more of the latest changes. NOT a parity with that window.
*/
66export const MAX_LEDGER_HEADLINES = 8
67 
68/**
* Coerce an untrusted client ledger into bounded, era-stamped headlines for the
* altered-timeline brief (issue #131). Cap-first (`cleanArray`) so a crafted oversized
* body can't amplify CPU/allocations; then drop headline-less entries, stamp the era,
* and keep only the most recent few. These are the game's own prior turn headlines fed
* back to a model — bounded like every other untrusted field, and (like send-message
* reusing its ledger) not re-moderated; the objective remains the hard-blocked input.
*/
76export function buildLedgerBrief(rawLedger: unknown): string[] {
  return cleanArray(rawLedger, MAX_TIMELINE_ENTRIES)
      .map((e) => {
          const entry = e as { era?: unknown; headline?: unknown }
          const headline = cleanString(entry?.headline, MAX_OBJECTIVE_TITLE_CHARS)
          if (!headline) return null
          const era = cleanString(entry?.era, MAX_ERA_CHARS)
          return era ? `[${era}] ${headline}` : headline
      })
      .filter((l): l is string => l !== null)
      .slice(-MAX_LEDGER_HEADLINES)
87}
⋯ 250 lines hidden (lines 88–337)88 
89/** Era-agnostic safety net so the player always has somewhere to start. Every name
*  here MUST be a historically deceased figure (the deceased-only floor, #72) — the
*  fallback bypasses the live grounding filter, so a test pins this invariant. */
92const GENERIC_FALLBACK: FigureSuggestion[] = [
  { name: 'Cleopatra', reason: 'A ruler whose alliances reshaped the ancient Mediterranean.' },
  { name: 'Leonardo da Vinci', reason: 'A mind a century ahead — art, war machines, and invention.' },
  { name: 'Genghis Khan', reason: 'Forged the largest contiguous empire in history.' },
  { name: 'Marie Curie', reason: 'A pioneer whose science bent the modern age.' },
  { name: 'Abraham Lincoln', reason: 'Held a fracturing nation together at its hinge point.' }
98]
99 
100function lifespanOf(g: GroundedFigure): string | undefined {
  if (!g.born) return undefined
  if (g.died) return `${g.born.display} – ${g.died.display}`
  return g.living ? `${g.born.display} – present` : g.born.display
104}
105 
106const SYSTEM = `You are a historian helping a player of a timeline game decide whom to contact. Given their grand objective, propose real historical figures whose decisions could plausibly bend events toward it — spanning the relevant era(s) and the dynamics actually at play. Favor figures with real leverage over the situation, and include a few the player might not think of.
107 
108Only suggest figures who have already died — never anyone still living. Call lookup_figure to confirm a person is real, learn their lifespan and role, and check they are deceased; use it to keep every suggestion accurate and era-appropriate. Don't suggest anyone you can't ground, and drop anyone the lookup shows is still living.`
109 
110const LOOKUP_TOOL = {
  name: 'lookup_figure',
  description: 'Verify a real historical figure exists and fetch their lifespan and role.',
  parameters: {
      type: 'object' as const,
      properties: { name: { type: 'string', description: 'The figure’s name to look up' } },
      required: ['name'],
      additionalProperties: false
  }
119}
120 
121const SUGGESTIONS_SCHEMA = {
  type: 'object',
  properties: {
      suggestions: {
          type: 'array',
          items: {
              type: 'object',
              properties: {
                  name: { type: 'string', description: 'The figure’s name' },
                  reason: { type: 'string', description: 'One sentence: why this figure matters for the objective' },
                  lifespan: { type: 'string', description: 'e.g. "69 BC – 30 BC"; empty string if unknown' }
              },
              required: ['name', 'reason', 'lifespan'],
              additionalProperties: false
          }
      }
  },
  required: ['suggestions'],
  additionalProperties: false
140}
141 
142/**
* The research brief handed to the suggester agent. When the player has already
* altered the timeline, the landed changes are folded in as the history that now
* stands, with an instruction to keep each reason consistent with it — the fix for
* blurbs that kept asserting a figure's original fate after the player had overturned
* it (issue #131). Exported for the unit test. With no changes the brief is
* byte-identical to the original objective-only ask.
*/
150export function userBrief(objective: ObjectiveInput): string {
  const altered = objective.worldBrief?.length
      ? `\n\nThe player has ALREADY begun rewriting history — these changes are now real, recorded events on the timeline, not predictions:\n${objective.worldBrief.map(l => `- ${l}`).join('\n')}\nTreat them as the history that now stands. Each reason must fit this altered timeline: where a change above has overturned a figure's known fate (a death undone, a defeat averted, a work never lost), say what is now true of them — never describe the original outcome the change has already reversed.`
      : ''
  return `Objective: "${objective.title ?? 'Alter the course of history'}".
155What winning looks like: ${objective.description ?? '—'}
156${objective.era ? `Anchoring era: ${objective.era}` : ''}${altered}
157 
158Propose 5 figures the player could message to influence this. Verify each with lookup_figure before finalizing.`
159}
160 
161const FINAL_NUDGE = 'Now give your final answer: the 5 figures, each with a one-sentence reason it matters for this objective.'
162 
163/** Runs one lookup_figure call and shapes the evidence the agent reads. */
164async function runLookup(name: string): Promise<object> {
  const g = name ? await groundFigure(name) : ({ name: '', resolved: false } as GroundedFigure)
  return g.resolved
      ? { resolved: true, name: g.name, role: g.description, lifespan: lifespanOf(g), deceased: isDeceased(g) }
      : { resolved: false }
169}
170 
171function mapWire(raw: unknown): FigureSuggestion[] {
  const parsed = raw as { suggestions?: FigureSuggestionWire[] }
  return (parsed.suggestions ?? [])
      .filter(s => s && s.name && s.reason)
      .map(s => ({ name: s.name, reason: s.reason, lifespan: s.lifespan || undefined }))
      .slice(0, 6)
177}
178 
179/**
* Defense in depth for the deceased-only floor (#72): re-ground every proposed
* figure and keep only the confirmed-deceased ones, so a model that ignores the
* instruction can never surface a living person as a one-tap contact. Grounding is
* usually cached (the agent typically looked these up), so usually near-free — a
* final name that differs from a looked-up one costs a fresh bounded lookup, and a
* transient outage drops that pick (fail closed; the list can fall to the curated
* fallback). We also normalize each lifespan to the grounded record. Exported for
* the unit test.
*/
189export async function keepDeceased(suggestions: FigureSuggestion[]): Promise<FigureSuggestion[]> {
  const checked = await Promise.all(suggestions.map(async (s): Promise<FigureSuggestion | null> => {
      const g = await groundFigure(s.name)
      return isDeceased(g) ? { ...s, lifespan: lifespanOf(g) ?? s.lifespan } : null
  }))
  return checked.filter((s): s is FigureSuggestion => s !== null)
195}
196 
197/** Max tool-call rounds in the suggester's research loop — one budget shared by both
*  provider lanes (OpenAI + Anthropic) so a bump can't silently diverge them. */
199const MAX_AGENT_LOOKUP_ROUNDS = 3
200 
201async function runAgentOpenAI(objective: ObjectiveInput): Promise<FigureSuggestion[]> {
  const params = routeFor('suggester').route.openai
  const client = getOpenAIClient()
  const tools: ChatCompletionTool[] = [{
      type: 'function',
      function: {
          name: LOOKUP_TOOL.name,
          description: LOOKUP_TOOL.description,
          parameters: LOOKUP_TOOL.parameters
      }
  }]
  const messages: ChatCompletionMessageParam[] = [
      { role: 'system', content: SYSTEM },
      { role: 'user', content: userBrief(objective) }
  ]
216 
  // Phase 1: let the agent research candidates with the grounding tool.
  for (let round = 0; round < MAX_AGENT_LOOKUP_ROUNDS; round++) {
      const completion = await client.chat.completions.create({
          model: params.model,
          messages,
          tools,
          tool_choice: 'auto',
          // gpt-5.5 rejects `reasoning_effort` alongside function tools on Chat
          // Completions, so we omit it here (the no-tool phase 2 keeps it).
          max_completion_tokens: params.maxTokens
      })
      const msg = completion.choices?.[0]?.message
      if (!msg) break
      messages.push(msg)
      if (!msg.tool_calls?.length) break
232 
      for (const call of msg.tool_calls) {
          let name = ''
          try { name = JSON.parse(call.function.arguments || '{}').name } catch { /* bad args */ }
          const result = await runLookup(name)
          messages.push({ role: 'tool', tool_call_id: call.id, content: JSON.stringify(result) })
      }
  }
240 
  // Phase 2: force a clean structured list out of the research.
  const final = await client.chat.completions.create({
      model: params.model,
      messages: [...messages, { role: 'user', content: FINAL_NUDGE }],
      reasoning_effort: 'low',
      max_completion_tokens: 1500,
      response_format: {
          type: 'json_schema',
          json_schema: { name: 'figure_suggestions', strict: true, schema: SUGGESTIONS_SCHEMA }
      }
  })
252 
  const content = final.choices?.[0]?.message?.content
  if (!content) return []
  return mapWire(JSON.parse(content))
256}
257 
258async function runAgentAnthropic(objective: ObjectiveInput): Promise<FigureSuggestion[]> {
  const params = routeFor('suggester').route.anthropic
  const client = getAnthropicClient()
  const tools: AnthropicSdk.ToolUnion[] = [{
      name: LOOKUP_TOOL.name,
      description: LOOKUP_TOOL.description,
      input_schema: LOOKUP_TOOL.parameters,
      // Strict tools: the API guarantees the input matches the schema.
      strict: true
  }]
  const messages: AnthropicSdk.MessageParam[] = [
      { role: 'user', content: userBrief(objective) }
  ]
  const common = {
      model: params.model,
      max_tokens: params.maxTokens,
      system: SYSTEM,
      ...(params.temperature !== undefined ? { temperature: params.temperature } : {})
  }
277 
  // Phase 1: the research loop — run tools until the model stops asking.
  for (let round = 0; round < MAX_AGENT_LOOKUP_ROUNDS; round++) {
      const response = await client.messages.create({ ...common, messages, tools })
      messages.push({ role: 'assistant', content: response.content })
      const toolUses = response.content.filter(
          (b): b is AnthropicSdk.ToolUseBlock => b.type === 'tool_use'
      )
      if (response.stop_reason !== 'tool_use' || !toolUses.length) break
286 
      const results: AnthropicSdk.ToolResultBlockParam[] = []
      for (const use of toolUses) {
          const name = typeof (use.input as { name?: unknown })?.name === 'string'
              ? (use.input as { name: string }).name
              : ''
          results.push({
              type: 'tool_result',
              tool_use_id: use.id,
              content: JSON.stringify(await runLookup(name))
          })
      }
      messages.push({ role: 'user', content: results })
  }
300 
  // Phase 2: force a clean structured list out of the research.
  const final = await client.messages.create({
      ...common,
      max_tokens: 1500,
      messages: [...messages, { role: 'user', content: FINAL_NUDGE }],
      output_config: { format: { type: 'json_schema', schema: SUGGESTIONS_SCHEMA } }
  })
308 
  const text = final.content.find(
      (b): b is AnthropicSdk.TextBlock => b.type === 'text'
  )?.text
  if (!text) return []
  return mapWire(JSON.parse(text))
314}
315 
316/** Suggests era-relevant figures for an objective, with a curated fallback. */
317export async function suggestFigures(objective: ObjectiveInput): Promise<SuggestionResult> {
  try {
      const { lane } = routeFor('suggester')
      const suggestions = lane === 'anthropic'
          ? await runAgentAnthropic(objective)
          : await runAgentOpenAI(objective)
      // Deceased-only floor (#72): re-ground and drop anyone still living before
      // they reach the player. If that empties the list (a fully misbehaving
      // model), fall through to the curated, all-deceased fallback below.
      const deceased = await keepDeceased(suggestions)
      if (deceased.length) return { suggestions: deceased, fallback: false }
  } catch (error) {
      console.error('Figure suggester agent failed; using fallback:', error)
  }
  return { suggestions: GENERIC_FALLBACK, fallback: true }
332}
333 
334/** Exposed for the fallback path + tests. */
335export function fallbackSuggestions(): FigureSuggestion[] {
  return [...GENERIC_FALLBACK]
337}

The endpoint just calls the helper and threads the result through.

server/api/suggestions.post.ts · 35 lines

server/api/suggestions.post.ts35 lines · TypeScript

⋯ 17 lines hidden (lines 1–17)1import { suggestFigures, buildLedgerBrief } from '../utils/figure-suggester'
2import { cleanString, MAX_ERA_CHARS, MAX_OBJECTIVE_DESC_CHARS, MAX_OBJECTIVE_TITLE_CHARS } from '../utils/validate'
3 
4/**
* POST /api/suggestions — given the run's objective (and the changes landed so far),
* returns era-relevant historical figures (name + one-line reason) to seed the
* contact step. Runs the tool-using suggester agent server-side; always succeeds
* (curated fallback) so the player is never left without ideas. The landed ledger
* lets a blurb re-narrate against the altered timeline rather than asserting a fate
* the player has already overturned (issue #131).
*/
12export default defineEventHandler(async (event) => {
  const body = await readBody(event)
  const objective = body?.objective ?? {}
  // Untrusted body → the tool-using suggester agent's prompt: coerce + bound each
  // field. Empty → undefined so the suggester's own fallbacks still apply.
  const title = cleanString(objective.title, MAX_OBJECTIVE_TITLE_CHARS) || undefined
  const description = cleanString(objective.description, MAX_OBJECTIVE_DESC_CHARS) || undefined
  const era = cleanString(objective.era, MAX_ERA_CHARS) || undefined
20 
  // The landed ledger (issue #131): era-stamped headlines of the changes the player
  // has already made, so the suggester re-narrates each blurb against the altered
  // timeline. Untrusted body → buildLedgerBrief caps + coerces + bounds it.
  const worldBrief = buildLedgerBrief(body?.ledger)
25 
  // A custom objective is untrusted text reaching a model — deterministically
  // hard-block the unforgivable categories before the suggester acts on it.
  // (The full Sentinel re-reviews the objective in context on every turn.)
  const { hardBlockCheck } = await import('~/server/utils/moderation')
  const objectiveBlock = await hardBlockCheck([title, description, era].filter(Boolean).join(' — '), 'suggestions', 'input')
  if (objectiveBlock.blocked) return { success: true, suggestions: [], blocked: true, reason: objectiveBlock.block.reason }
32 
  const result = await suggestFigures({ title, description, era, worldBrief })
⋯ 2 lines hidden (lines 34–35)34    return { success: true, ...result }
35})

A non-blocking refresh, like the Chronicle

refreshSuggestions is the suggestion-side twin of refreshChronicle: it re-runs the suggester with the current ledger, fired after a landed change and never awaited, so the turn reveal waits on neither. A failed, blocked, or curated-fallback refresh keeps the prior list — a populated panel never blanks, and a model outage never regresses good era-specific picks to generic names.

Keep-prior on every degraded path; the finally settles the shared loading flag.

stores/game.ts · 1533 lines

stores/game.ts1533 lines · TypeScript

⋯ 772 lines hidden (lines 1–772)1import { defineStore } from 'pinia'
2import type { GameObjective, ObjectiveSteer } from '~/server/utils/objectives'
3import type { Pack } from '~/server/utils/packs'
4import type { GroundedFigure } from '~/server/utils/figure-grounding'
5import { formatContactMoment, type ContactMoment } from '~/utils/contact-moment'
6import type { FigureSuggestion } from '~/server/utils/figure-suggester'
7import type { ChronicleEntry } from '~/server/utils/openai'
8import type { FigureStudy, ArchiveLookup } from '~/server/utils/prompt-builder'
9import type { Anachronism } from '~/server/utils/anachronism'
10import { chainStatus, type ChainStatus } from '~/utils/causal-chain'
11import type { Craft } from '~/utils/craft'
12import type { Continuity } from '~/utils/continuity'
13import type { DiceOutcome } from '~/utils/dice'
14import { generateGameSummary, rateEfficiency, type GameSummary } from '~/utils/game-summary'
15import { TOTAL_MESSAGES, MAX_PROGRESS_SWING, MAX_PROGRESS } from '~/utils/game-config'
16import { RUN_SNAPSHOT_VERSION, type RunSnapshot } from '~/utils/run-snapshot'
17 
18export type Valence = 'positive' | 'negative' | 'neutral'
19 
20/**
* A historical figure the player has reached out to. Figures are freeform — the
* player can write to anyone, in any era. The AI infers each figure's era and a
* short descriptor on first contact, which we cache here for the UI.
*/
25export interface HistoricalFigure {
  name: string
  era: string
  descriptor: string
29}
30 
31/**
* Timeline Ledger entry — a single recorded change to history.
*
* The ledger is the heart of the game: every resolved turn appends one entry
* describing how the world bent, so the player literally watches the timeline
* rewrite itself as they play.
*/
38export interface TimelineEvent {
  id: string
  figureName: string
  era: string
  headline: string
  detail: string
  diceRoll: number
  diceOutcome: DiceOutcome
  progressChange: number
  /** The engine's swing BEFORE the anachronism amplifier — shown so the player
   *  can see exactly what their wager did ("+8 ⚡ far-ahead → +11%"). */
  baseProgressChange?: number
  valence: Valence
  /** How anachronistic the player's nudge was — it widened this swing. */
  anachronism?: Anachronism
  /** How far this landed from the nearest foothold — it decayed this swing. */
  causalChain?: ChainStatus
  /** The Judge's grade of the dispatch that caused this change. */
  craft?: Craft
  /** Signed year of the intervention, when the contact was grounded. */
  whenSigned?: number
  /** True when this was the run's staked last stand (doubled swing). */
  staked?: boolean
  timestamp: Date
62}
63 
64/**
* Message Interface — one line in the conversation with a figure.
* Dice / outcome / action / impact / progress are recorded on the AI (figure)
* turn, since that is the resolved result of the roll.
*/
69export interface Message {
  text: string
  sender: 'user' | 'ai' | 'system'
  timestamp: Date
  figureName?: string
  /** The effective (craft-tilted) roll — what the bands judged. */
  diceRoll?: number
  diceOutcome?: DiceOutcome
  /** The die as it actually landed, before the craft modifier. */
  naturalRoll?: number
  /** The Judge's tilt on the roll (±2..0), and the grade + reason behind it. */
  rollModifier?: number
  craft?: Craft
  craftReason?: string
  /** Whether the dispatch built on the run's thread (issue #62) — drives the
   *  momentum meter and the 'builds' badge in the reveal. */
  continuity?: Continuity
  characterAction?: string
  timelineImpact?: string
  progressChange?: number
  /** The pre-amplifier swing + the wager level, for the reveal's equation. */
  baseProgressChange?: number
  /** The PRE-turn momentum that amplified this swing — for the reveal's equation. */
  momentumAtSwing?: number
  anachronism?: Anachronism
  /** The causal-chain decay applied to this swing (for the reveal's equation). */
  causalChain?: ChainStatus
  /** True when this turn was the staked last stand. */
  staked?: boolean
98}
99 
100export type GameStatus = 'playing' | 'victory' | 'defeat'
101 
102/**
* Shape returned by `POST /api/send-message` (see `server/api/send-message.post.ts`).
* Discriminated by `success`: when `true`, all fields downstream of the dice roll are
* guaranteed; when `false`, only `userMessage` + `error` are guaranteed (and the
* Character-AI-failure path doesn't even surface a dice roll). The discriminant lets
* the consumer destructure without optional chaining or null gymnastics.
*/
109type SendMessageApiResponse =
  | {
      success: true
      message: string
      data: {
          userMessage: string
          figure: { name: string; era: string; descriptor: string }
          diceRoll: number
          diceOutcome: DiceOutcome
          // Judge-of-craft fields (optional so older mocks/fixtures stay valid;
          // the live server always sends them).
          naturalRoll?: number
          rollModifier?: number
          craft?: Craft
          craftReason?: string
          continuity?: Continuity
          momentum?: number
          staked?: boolean
          characterResponse: { message: string; action: string }
          timeline: {
              headline: string
              detail: string
              era: string
              progressChange: number
              baseProgressChange?: number
              momentumAtSwing?: number
              valence: Valence
              anachronism?: Anachronism
              causalChain?: ChainStatus
          }
          error: null
      }
  }
  | {
      success: false
      message: string
      data: {
          userMessage: string
          diceRoll?: number
          diceOutcome?: DiceOutcome
          characterResponse?: { message: string; action: string }
          error: string
          /** A content-moderation block (not an infra failure): the dispatch was
           *  refused by the detector, the Sentinel, or the model itself. */
          blocked?: boolean
          moderationReason?: string
      }
  }
157 
158const RATE_LIMIT_MS = 1000 // message cooldown window, in ms
159 
160// Turn-reveal pacing. A resolved turn releases its beats one at a time — a beat of
161// suspense, then the die lands and the figure's reply writes itself in, then the
162// timeline shift, then the ledger node — so the resolution reads as one conducted
163// moment instead of everything firing in the same tick. Each component already
164// animates when its own slice of state changes; sequencing the WRITES sequences the
165// animations, with no component coordination. Tuned so the swing lands with the
166// reply's own "ripple" line (~0.55s into its staged reveal).
167export const REVEAL = { suspense: 450, swing: 550, node: 250 } as const
168const wait = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms))
169/** Stagger the reveal only in a real browser with motion allowed. SSR and the test
*  env (no `matchMedia`) collapse to an instant, atomic apply — so the store's
*  contract (state present the moment sendMessage resolves) is unchanged for tests. */
172function canAnimateReveal(): boolean {
  return typeof window !== 'undefined'
      && typeof window.matchMedia === 'function'
      && !window.matchMedia('(prefers-reduced-motion: reduce)').matches
176}
177 
178function valenceOf(progressChange: number): Valence {
  if (progressChange > 0) return 'positive'
  if (progressChange < 0) return 'negative'
  return 'neutral'
182}
183 
184/** Formats a signed timeline year (AD positive, BCE negative) for display. */
185export function formatContactYear(signed: number): string {
  return signed < 0 ? `${-signed} BC` : `${signed}`
187}
188 
189/** The landed ledger as {era, headline} for the suggester's altered-timeline brief
*  (issue #131) — the server bounds + caps it. Drops changes without a headline. */
191function ledgerForSuggester(events: TimelineEvent[]): { era: string; headline: string }[] {
  return events.filter(e => e.headline).map(e => ({ era: e.era, headline: e.headline }))
193}
194 
195/** Human lifespan line for a grounded figure, e.g. "69 BC – 30 BC" or "1942 – present". */
196function lifespanText(g: GroundedFigure): string | undefined {
  if (!g.born) return undefined
  if (g.died) return `${g.born.display} – ${g.died.display}`
  return g.living ? `${g.born.display} – present` : g.born.display
200}
201 
202/** True when a $fetch error is a 402 (out of runs) — the paywall signal. ofetch
*  surfaces the status as statusCode and on the response, so check both. */
204function isPaymentRequired(error: unknown): boolean {
  const e = error as { statusCode?: number; status?: number; response?: { status?: number } }
  return e?.statusCode === 402 || e?.status === 402 || e?.response?.status === 402
207}
208 
209/** True when a $fetch error is a 503 / at-capacity — the spend cap paused new
*  runs (distinct from the per-device 402 paywall). */
211function isAtCapacity(error: unknown): boolean {
  const e = error as { statusCode?: number; status?: number; response?: { status?: number }; data?: { atCapacity?: boolean } }
  return e?.statusCode === 503 || e?.status === 503 || e?.response?.status === 503 || e?.data?.atCapacity === true
214}
215 
216export type ContactLiveness = 'ok' | 'before-birth' | 'after-death' | 'living' | 'unresolved' | 'unknown'
217 
218/**
* A replay seed (issue #89) — when a player starts a run from a shared run's captured
* objective. It carries the objective to seed (verbatim, no generation), the SOURCE run's
* public share token (rides along to /api/run-save to stamp the lineage pointer), and the
* source's display name at seed time (for the "remixed from" credit shown before/after the
* run; the public page re-derives the credit live, honoring the source's current opt-in).
*/
225export interface ReplaySeed {
  objective: GameObjective
  sourceToken: string
  sourceAttribution: string | null
229}
230 
231/**
* Game Store — core state for a session of freeform timeline editing.
*/
234export const useGameStore = defineStore('game', {
  state: () => ({
      remainingMessages: TOTAL_MESSAGES,
      messageHistory: [] as Message[],
      gameStatus: 'playing' as GameStatus,
      isLoading: false,
      error: null as string | null,
      lastMessageTime: null as number | null,
      isRateLimited: false,
      // Staleness plumbing, not run state. runEpoch increments on every reset so an
      // async result from a dead run can never write into a fresh one; the seq
      // counters order overlapping requests of the same kind so only the latest
      // lands (an earlier chronicle rewrite must not overwrite a later one).
      // Deliberately NOT restored by resetGame — they must survive it to work.
      runEpoch: 0,
      chronicleSeq: 0,
      suggestionsSeq: 0,
      groundingSeq: 0,
      // The current run's id — lazily minted on the run's first server call and
      // cleared by resetGame so each run gets a fresh one. Tags every AI call
      // (via the x-run-id header) so the gateway's cost telemetry groups per
      // run: the GTM cost instrument.
      runId: null as string | null,
      // The in-flight begin-run, so concurrent first-calls of a run share one
      // mint (one POST /api/run, one runs row) instead of racing two. Cleared
      // by resetGame. (Vue leaves a Promise unproxied, so awaiting it is safe.)
      runIdInflight: null as Promise<string> | null,
      // True once this run's snapshot is durably saved (POST /api/run-save returned
      // saved). Gates the end-screen Share affordance (issue #88) so it appears only for
      // a run that actually exists server-side to share — never for a degraded local id.
      // Reset per run.
      runSnapshotSaved: false,
      // outOfRuns gates the mission screen's paywall (set when a commit is
      // refused with 402). The run packs offered there are loaded into `packs`.
      outOfRuns: false,
      // atCapacity gates the "at capacity" notice (set when a commit is refused
      // with 503 because the global spend cap paused new runs).
      atCapacity: false,
      packs: [] as Pack[],
      // The device's run balance, for the header gauge + account popover. null
      // until first loaded (GET /api/balance); the run-commit response also
      // refreshes it so the gauge stays live without a second round-trip.
      runsRemaining: null as number | null,
      freeRuns: 1,
      deviceRef: '' as string,
      // Account state (from /api/balance): the signed-in email, and whether the
      // current user is anonymous (→ must sign in before buying). Drives the
      // account UI + the sign-in-to-buy gate. false/null in device-fallback mode.
      accountEmail: null as string | null,
      accountAnonymous: false,
      // The run-packs sales modal — opened on demand (header) or automatically
      // when a commit is refused for being out of runs.
      buyModalOpen: false,
      // A one-shot notice after returning from Stripe Checkout ('success' shows a
      // credited confirmation; 'cancel' a gentle "no charge" note). Cleared by the UI.
      purchaseNotice: null as 'success' | 'cancel' | null,
      currentObjective: null as GameObjective | null,
      // Set when this run is a REPLAY of a shared run's objective (issue #89): seeded
      // verbatim from the public projection, no generation. Survives chooseObjective so
      // it can stamp the lineage pointer at save time and credit the source on the end
      // screen; cleared by resetGame (a fresh "new timeline" carries no lineage).
      replayState: null as ReplaySeed | null,
      objectiveProgress: 0,
      // The run's high-water mark (0..MAX_PROGRESS): the highest objectiveProgress ever
      // reached this run. Tracked so the end screen can show "peaked at X%" when a run
      // loses ground from its peak — classically a staked final dispatch that crit-fails
      // to 0% — instead of the floored final % erasing the player's real effort (#129).
      peakProgress: 0,
      // The run-level momentum meter (0..MOMENTUM_MAX): a coherent arc compounds its
      // gains amplifier; a reset or catastrophe shatters it back to 0 (issue #62).
      momentum: 0,
      timelineEvents: [] as TimelineEvent[],
      figures: [] as HistoricalFigure[],
      activeFigureName: '' as string,
      // Grounding for the active contact: real facts + the chosen year to reach them.
      figureGrounding: null as GroundedFigure | null,
      groundingLoading: false,
      contactWhen: null as number | null,
      /** Optional sub-year refinement of contactWhen — display/prompt flavor
       *  only; every mechanic keeps doing arithmetic on the YEAR (issue #32). */
      contactMoment: null as ContactMoment | null,
      // Era-relevant figure suggestions for the current objective (the on-ramp).
      figureSuggestions: [] as FigureSuggestion[],
      suggestionsLoading: false,
      suggestionsFor: '' as string,
      // The living Chronicle (Layer 3): a prose telling of the altered timeline,
      // rewritten each turn. Non-blocking — see refreshChronicle.
      chronicle: null as ChronicleEntry | null,
      chronicleLoading: false,
      // The run's epilogue — the TERMINAL telling carrying the verdict — is being
      // written. Set when the final turn fires its refresh and cleared when that
      // telling lands or the refresh fails. Distinct from chronicleLoading (any
      // refresh): it lets the end screen show "the final account…" instead of
      // presenting the prior turn's stale, pre-ending telling as the epilogue.
      epiloguePending: false,
      // The Archive (prototype): an objective-blind brief on the active figure, so
      // the player can research who they're reaching without leaving the game. The
      // brief is moment-specific, so it's cached against the figure AND the year.
      figureStudy: null as FigureStudy | null,
      studyLoading: false,
      studyFor: '' as string,
      studyWhen: null as number | null,
      // Archive topic lookup (the "yellow" layer): concrete domain facts on demand.
      archiveResult: null as ArchiveLookup | null,
      lookupLoading: false,
      // A content-moderation block — distinct from `error` (an infra hiccup) so
      // the UI shows an honest, visibly different banner. One per surface that
      // takes untrusted input into a model: the dispatch/turn, the Archive lookup,
      // the Archivist study, and the figure-suggestions step.
      moderationNotice: null as string | null,
      archiveNotice: null as string | null,
      studyNotice: null as string | null,
      suggestionsNotice: null as string | null
  }),
348 
  getters: {
      /**
       * Can the player send right now? (messages left, still playing, not
       * mid-request, not rate-limited)
       */
      canSendMessage(): boolean {
          return this.remainingMessages > 0 &&
                 this.gameStatus === 'playing' &&
                 !this.isLoading &&
                 !this.isRateLimited
      },
360 
      /**
       * The conversation thread with a single figure (their turns + the
       * player's turns addressed to them). Each figure keeps a coherent,
       * independent thread.
       */
      conversationWith(): (name: string) => Message[] {
          return (name: string) => this.messageHistory.filter(
              m => m.figureName === name && m.sender !== 'system'
          )
      },
371 
      /** Total progress, net of setbacks, the player has clawed back. */
      gameSummary(): GameSummary {
          return generateGameSummary(this)
      },
376 
      /**
       * Whether the active figure can be reached at the chosen `when`.
       *
       * Require grounding (#73): an UNRESOLVED name can't be reached at all —
       * 'unresolved' (free-form contact is removed; the picker guides you to a real
       * match). Deceased-only floor (#72): a RESOLVED figure with no confirmed
       * death is living/undatable and never contactable — 'living', fail closed. A
       * resolved, deceased figure is gated to their lifetime (before-birth /
       * after-death). 'unknown' remains only for a resolved, deceased figure we
       * can't fully place (no birth year, or no contact year chosen yet), which
       * stays permissible.
       */
      contactLiveness(): ContactLiveness {
          const g = this.figureGrounding
          if (!g || !g.resolved) return 'unresolved'
          if (!g.died) return 'living'
          if (!g.born || this.contactWhen == null) return 'unknown'
          if (this.contactWhen < g.born.signed) return 'before-birth'
          if (this.contactWhen > g.died.signed) return 'after-death'
          return 'ok'
      },
398 
      /** Can the chosen contact + when actually be reached? */
      canContact(): boolean {
          return this.contactLiveness === 'ok' || this.contactLiveness === 'unknown'
      },
403 
      /**
       * The last stand is offered ONLY when the final dispatch can no longer win
       * inside the normal per-turn fuse — from any nearer position an unstaked
       * throw can still land it, and offering the (strictly win-probability-
       * increasing) doubling there would be a dominance trap, not a decision.
       */
      canStake(): boolean {
          return this.remainingMessages === 1 &&
                 this.gameStatus === 'playing' &&
                 (MAX_PROGRESS - this.objectiveProgress) > MAX_PROGRESS_SWING
      },
415 
      /**
       * The active figure's age at the chosen `when` — so the player never has to
       * do lifetime math in their head. Null when we lack a birth year or a chosen
       * year (a resolved figure we can't date, or before a year is chosen). Corrects for the missing year zero
       * when a life spans the BC→AD boundary (1 BC → AD 1 is one year, not two).
       */
      contactAge(): number | null {
          const g = this.figureGrounding
          if (!g?.resolved || !g.born || this.contactWhen == null) return null
          const bornSigned = g.born.signed
          const whenSigned = this.contactWhen
          if (whenSigned < bornSigned) return null // before birth — no meaningful age
          const crossedZero = bornSigned < 0 && whenSigned > 0 ? 1 : 0
          return whenSigned - bornSigned - crossedZero
      },
431 
      /**
       * The causal-chain read for the CURRENT contact — the pre-send ⏳ chip's
       * source, mirroring what the Timeline Engine will compute. Footholds are the
       * objective's anchor year plus every dated change already on the ledger; the
       * gap to the nearest one decays the swing. Null (no chip) for ungrounded
       * contacts or an anchorless objective with no dated changes yet.
       */
      causalChainRead(): ChainStatus | null {
          const footholds = [
              this.currentObjective?.anchorYear,
              ...this.timelineEvents.map(e => e.whenSigned)
          ]
          return chainStatus(this.contactWhen, footholds)
      }
  },
447 
  actions: {
      // ---------- message helpers ----------
      addUserMessage(text: string, figureName?: string) {
          if (this.gameStatus !== 'playing') return
          this.messageHistory.push({
              text,
              sender: 'user',
              timestamp: new Date(),
              figureName
          })
      },
459 
      addAIMessage(text: string, figureName?: string) {
          this.messageHistory.push({
              text,
              sender: 'ai',
              timestamp: new Date(),
              figureName
          })
      },
468 
      addAIMessageWithData(messageData: Partial<Message> & { text: string, sender: 'ai' }) {
          this.messageHistory.push({
              text: messageData.text,
              sender: messageData.sender,
              timestamp: messageData.timestamp || new Date(),
              figureName: messageData.figureName,
              diceRoll: messageData.diceRoll,
              diceOutcome: messageData.diceOutcome,
              naturalRoll: messageData.naturalRoll,
              rollModifier: messageData.rollModifier,
              craft: messageData.craft,
              craftReason: messageData.craftReason,
              continuity: messageData.continuity,
              characterAction: messageData.characterAction,
              timelineImpact: messageData.timelineImpact,
              progressChange: messageData.progressChange,
              baseProgressChange: messageData.baseProgressChange,
              momentumAtSwing: messageData.momentumAtSwing,
              anachronism: messageData.anachronism,
              causalChain: messageData.causalChain,
              staked: messageData.staked
          })
      },
492 
      // ---------- figures ----------
      registerFigure(figure: HistoricalFigure) {
          const existing = this.figures.find(f => f.name === figure.name)
          if (existing) {
              if (figure.era) existing.era = figure.era
              if (figure.descriptor) existing.descriptor = figure.descriptor
          } else {
              this.figures.push({ ...figure })
          }
      },
503 
      setActiveFigure(name: string) {
          this.activeFigureName = name
      },
507 
      /**
       * Synchronously clears the dossier the moment the contact NAME changes, so
       * a send racing the grounding debounce/fetch is gated as ungrounded (#73)
       * instead of wearing the PREVIOUS figure's facts, year, and liveness gate —
       * and so the wrong year can never be written into the ledger's whenSigned.
       */
      clearGrounding() {
          this.groundingSeq++ // invalidate any lookup still in flight
          this.figureGrounding = null
          this.contactWhen = null
          this.contactMoment = null
          this.groundingLoading = false
          this.figureStudy = null
          this.studyFor = ''
          this.studyWhen = null
          this.studyNotice = null
      },
525 
      /**
       * Resolves the active figure against the grounding service and defaults the
       * "when" to a point inside any known lifetime. Never throws: an unresolved
       * figure simply clears grounding; an ungrounded contact is then blocked (#73).
       */
      async groundActiveFigure(name: string): Promise<void> {
          const target = (name || '').trim()
          // A new contact makes any prior Archive study stale.
          this.figureStudy = null
          this.studyFor = ''
          this.studyWhen = null
          this.studyNotice = null
          if (!target) {
              this.groundingSeq++ // invalidate any lookup still in flight
              this.figureGrounding = null
              this.contactWhen = null
              this.contactMoment = null
              this.groundingLoading = false
              return
          }
          // Out-of-order guard: only the LATEST lookup may land. Without it, a slow
          // response for the previous name attaches the wrong dossier (and a wrong
          // figureContext on a fast send) to whatever the player typed next.
          const epoch = this.runEpoch
          const seq = ++this.groundingSeq
          this.groundingLoading = true
          try {
              const grounded = await $fetch('/api/figure', { params: { name: target }, headers: await this.aiHeaders() }) as GroundedFigure
              if (epoch !== this.runEpoch || seq !== this.groundingSeq) return
              this.figureGrounding = grounded
              this.contactMoment = null
              if (grounded?.resolved && grounded.born) {
                  const latest = grounded.died ? grounded.died.signed : new Date().getFullYear()
                  this.contactWhen = Math.round((grounded.born.signed + latest) / 2)
              } else {
                  this.contactWhen = null
              }
          } catch (error) {
              if (epoch !== this.runEpoch || seq !== this.groundingSeq) return
              console.error('Figure grounding failed:', error)
              this.figureGrounding = null
              this.contactWhen = null
              this.contactMoment = null
          } finally {
              if (epoch === this.runEpoch && seq === this.groundingSeq) this.groundingLoading = false
          }
      },
573 
      /** The current run's id, minted server-side via POST /api/run on first
       *  need. The run is a server fact (a persisted, charged row); the id then
       *  tags every AI call so cost telemetry groups per run, and the gameplay
       *  gate verifies it. Fails CLOSED: if begin-run can't return an id this
       *  REJECTS (no local fallback) — a run we can't back server-side must not
       *  start, or the paywall gate would reject it mid-run anyway. */
      async ensureRunId(): Promise<string> {
          if (this.runId) return this.runId
          // Collapse concurrent first-calls onto ONE begin-run (two overlapping
          // calls would otherwise mint two rows). The epoch guards a resetGame
          // mid-flight — a dead run's id must not become the fresh run's.
          if (!this.runIdInflight) {
              const epoch = this.runEpoch
              this.runIdInflight = (async () => {
                  const res = await $fetch('/api/run', { method: 'POST' }) as { runId?: string }
                  if (!res?.runId) throw new Error('begin-run returned no run id')
                  if (epoch === this.runEpoch) {
                      this.runId = res.runId
                      this.runIdInflight = null
                  }
                  return res.runId
              })().catch((err) => {
                  if (epoch === this.runEpoch) this.runIdInflight = null
                  throw err
              })
          }
          return this.runIdInflight
      },
602 
      /** Headers that tag a server call with the current run (the cost
       *  instrument), minting the run id first if needed. */
      async aiHeaders(base: Record<string, string> = {}): Promise<Record<string, string>> {
          return { ...base, 'x-run-id': await this.ensureRunId() }
      },
608 
      setContactWhen(year: number | null) {
          // Scrubbing the year keeps any pinned month/day — the pin refines
          // whichever year is chosen, it doesn't belong to one.
          this.contactWhen = year
      },
614 
      setContactMoment(moment: ContactMoment | null) {
          this.contactMoment = moment
      },
618 
      /**
       * Studies the active (grounded) figure via the Archivist — an objective-blind
       * brief on who they are AT THE CHOSEN MOMENT, so the player can research in the
       * game instead of a browser tab. The brief is moment-specific, so it's cached
       * against the figure AND the year: move the contact slider and the player can
       * re-study them at the new moment. Graceful on failure (leaves the prior brief).
       * Only resolved figures can be studied — an unresolved name has no record.
       */
      async studyActiveFigure(): Promise<void> {
          const g = this.figureGrounding
          if (!g?.resolved) {
              this.figureStudy = null
              return
          }
          // Cache hit only when both the figure AND the studied year still match.
          if (this.studyFor === g.name && this.studyWhen === this.contactWhen && this.figureStudy) return
635 
          // Capture the moment being studied NOW: the brief describes this figure at
          // this year. If the slider moves mid-flight, recording the live value would
          // mislabel the brief and silently suppress the Re-study button.
          const epoch = this.runEpoch
          const studiedName = g.name
          const studiedWhen = this.contactWhen
          this.studyLoading = true
          this.studyNotice = null
          try {
              const res = await $fetch('/api/research', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: {
                      figureName: studiedName,
                      when: studiedWhen != null ? formatContactYear(studiedWhen) : undefined,
                      description: g.description,
                      extract: g.extract
                  }
              }) as { success?: boolean; study?: FigureStudy; blocked?: boolean; error?: string }
              if (epoch !== this.runEpoch) return
              // If the contact changed mid-flight, the stale-study clear in
              // groundActiveFigure already ran — don't resurrect the old brief.
              if (res?.blocked && this.figureGrounding?.name === studiedName) {
                  this.studyNotice = res.error || 'That study was blocked by content moderation.'
              } else if (res?.success && res.study && this.figureGrounding?.name === studiedName) {
                  this.figureStudy = res.study
                  this.studyFor = studiedName
                  this.studyWhen = studiedWhen
              }
          } catch (error) {
              if (epoch !== this.runEpoch) return
              console.error('Failed to study the figure:', error)
          } finally {
              if (epoch === this.runEpoch) this.studyLoading = false
          }
      },
672 
      /**
       * Asks the Archive about a freeform topic (the "yellow" layer) — concrete
       * domain facts: what it is, what it takes, and when it first became known
       * (the player's anachronism read). Graceful on failure. Topic-scoped, so it
       * persists across figure changes within a run.
       */
      async askArchive(query: string): Promise<void> {
          const q = (query || '').trim()
          if (!q) return
          const epoch = this.runEpoch
          this.lookupLoading = true
          this.archiveNotice = null
          try {
              const res = await $fetch('/api/lookup', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: { query: q }
              }) as { success?: boolean; lookup?: ArchiveLookup; blocked?: boolean; error?: string }
              if (epoch !== this.runEpoch) return
              if (res?.blocked) {
                  // The Archive is the sharpest elicitation vector — a block here is
                  // honest and visible, not a silent empty result.
                  this.archiveNotice = res.error || 'That lookup was blocked by content moderation.'
              } else if (res?.success && res.lookup) {
                  this.archiveResult = res.lookup
              }
          } catch (error) {
              if (epoch !== this.runEpoch) return
              console.error('Archive lookup failed:', error)
          } finally {
              if (epoch === this.runEpoch) this.lookupLoading = false
          }
      },
706 
      /**
       * Loads era-relevant figure suggestions for the current objective (the
       * educational on-ramp). Cached per objective; on any failure it leaves the
       * list empty so the UI falls back to its generic starters.
       */
      async loadSuggestions(): Promise<void> {
          const objective = this.currentObjective
          if (!objective) {
              this.figureSuggestions = []
              this.suggestionsFor = ''
              return
          }
          if (this.suggestionsFor === objective.title && this.figureSuggestions.length) return
720 
          const epoch = this.runEpoch
          const seq = ++this.suggestionsSeq
          this.suggestionsLoading = true
          this.suggestionsNotice = null
          try {
              const res = await $fetch('/api/suggestions', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: {
                      objective: {
                          title: objective.title,
                          description: objective.description,
                          era: objective.era
                      },
                      // Usually empty here (the initial load fires at run start), but a
                      // mid-run remount carries the ledger so even the first paint is
                      // timeline-aware. refreshSuggestions re-sends it after each change.
                      ledger: ledgerForSuggester(this.timelineEvents)
                  }
              }) as { success?: boolean; suggestions?: FigureSuggestion[]; blocked?: boolean; reason?: string }
              if (epoch !== this.runEpoch || seq !== this.suggestionsSeq) return
              // A blocked objective must not masquerade as an empty result — surface it.
              if (res?.blocked) this.suggestionsNotice = res.reason || 'That objective was blocked by content moderation.'
              this.figureSuggestions = res?.suggestions ?? []
              this.suggestionsFor = objective.title
          } catch (error) {
              if (epoch !== this.runEpoch || seq !== this.suggestionsSeq) return
              console.error('Failed to load figure suggestions:', error)
              this.figureSuggestions = []
              // Record that this objective WAS asked, even though it failed — the
              // picker uses suggestionsFor to tell "not yet asked" (skeletons)
              // from "asked and came up empty" (the honest famous-names fallback).
              this.suggestionsFor = objective.title
          } finally {
              if (epoch === this.runEpoch && seq === this.suggestionsSeq) this.suggestionsLoading = false
          }
      },
758 
      /**
       * Re-narrate the figure-suggestion blurbs against the altered timeline (issue
       * #131). The suggester is re-run with the landed ledger so a blurb stops
       * asserting a fate the player has already overturned. Fired non-blocking after
       * a landed change, like refreshChronicle — the turn reveal waits on neither.
       * A failed, blocked, or curated-fallback refresh KEEPS the prior list: a
       * populated panel never blanks, and a model outage never regresses good
       * era-specific picks to the generic fallback.
       *
       * loadSuggestions and refreshSuggestions share `suggestionsSeq` so the newest
       * call of EITHER wins. Whichever holds the latest seq therefore owns settling
       * `suggestionsLoading` + `suggestionsFor` (in the finally), so a refresh fired
       * while the initial load is still in flight can never strand the skeletons.
       */
      async refreshSuggestions(): Promise<void> {
          const objective = this.currentObjective
          if (!objective) return
          const epoch = this.runEpoch
          const seq = ++this.suggestionsSeq
          try {
              const res = await $fetch('/api/suggestions', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: {
                      objective: {
                          title: objective.title,
                          description: objective.description,
                          era: objective.era
                      },
                      ledger: ledgerForSuggester(this.timelineEvents)
                  }
              }) as { success?: boolean; suggestions?: FigureSuggestion[]; fallback?: boolean; blocked?: boolean }
              if (epoch !== this.runEpoch || seq !== this.suggestionsSeq) return
              // Only a genuine, model-built list may overwrite the panel — a curated
              // fallback (model unavailable) or an empty/blocked result keeps the
              // better existing suggestions rather than regressing to generic names.
              if (res?.success && res.suggestions?.length && !res.fallback) {
                  this.figureSuggestions = res.suggestions
              }
              this.suggestionsFor = objective.title
          } catch (error) {
              if (epoch !== this.runEpoch || seq !== this.suggestionsSeq) return
              console.error('Failed to refresh figure suggestions:', error)
              // Keep the prior list — a failed refresh never blanks the panel.
          } finally {
              // This refresh bumped the shared seq; if it's still the latest, it owns
              // the resolution — clear a loading flag an invalidated in-flight load
              // can no longer clear itself (the stuck-skeletons race).
              if (epoch === this.runEpoch && seq === this.suggestionsSeq) this.suggestionsLoading = false
          }
      },
810 
⋯ 723 lines hidden (lines 811–1533)811        // ---------- timeline ledger ----------
      addTimelineEvent(
          evt: Omit<TimelineEvent, 'id' | 'timestamp' | 'valence'> & { valence?: Valence; timestamp?: Date }
      ) {
          this.timelineEvents.push({
              id: `evt-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
              figureName: evt.figureName,
              era: evt.era,
              headline: evt.headline,
              detail: evt.detail,
              diceRoll: evt.diceRoll,
              diceOutcome: evt.diceOutcome,
              progressChange: evt.progressChange,
              baseProgressChange: evt.baseProgressChange,
              valence: evt.valence ?? valenceOf(evt.progressChange),
              anachronism: evt.anachronism,
              causalChain: evt.causalChain,
              craft: evt.craft,
              whenSigned: evt.whenSigned,
              staked: evt.staked,
              timestamp: evt.timestamp ?? new Date()
          })
      },
834 
      // ---------- the living chronicle (Layer 3) ----------
      /**
       * Re-narrates the Chronicle from the freshly-bent timeline. Fired
       * non-blocking after a resolved turn (and at game end): the dice/progress
       * reveal never waits on prose. The WHOLE account is rewritten each turn —
       * a later change can re-frame how earlier events read.
       * Graceful: a failed refresh keeps the prior telling, so the panel never
       * blanks; an empty timeline clears it (nothing to chronicle yet).
       */
      async refreshChronicle(): Promise<void> {
          if (!this.timelineEvents.length) {
              this.chronicle = null
              return
          }
          // Sequencing: rewrites overlap (each turn fires one, never awaited), so
          // only the LATEST issued refresh may land — an earlier telling arriving
          // late must not regress the account (or worse, the epilogue). The epoch
          // guard keeps a dead run's telling out of a fresh run entirely.
          const epoch = this.runEpoch
          const seq = ++this.chronicleSeq
          this.chronicleLoading = true
          try {
              const res = await $fetch('/api/chronicle', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: {
                      objective: this.currentObjective,
                      status: this.gameStatus,
                      progress: this.objectiveProgress,
                      timeline: this.timelineEvents.map(e => ({
                          era: e.era,
                          figureName: e.figureName,
                          headline: e.headline,
                          detail: e.detail,
                          progressChange: e.progressChange
                      }))
                  }
              }) as { success?: boolean; chronicle?: ChronicleEntry }
              if (epoch !== this.runEpoch || seq !== this.chronicleSeq) return
              if (res?.success && res.chronicle) this.chronicle = res.chronicle
          } catch (error) {
              if (epoch !== this.runEpoch || seq !== this.chronicleSeq) return
              console.error('Failed to refresh the chronicle:', error)
              // Keep the prior chronicle — a failed refresh never blanks the panel.
          } finally {
              if (epoch === this.runEpoch && seq === this.chronicleSeq) this.chronicleLoading = false
          }
      },
883 
      // ---------- simple setters ----------
      setLoading(loading: boolean) { this.isLoading = loading },
      setError(error: string | null) { this.error = error },
      clearModerationNotice() { this.moderationNotice = null },
      clearArchiveNotice() { this.archiveNotice = null },
889 
      // ---------- rate limiting ----------
      checkRateLimit(): boolean {
          const now = Date.now()
          if (this.lastMessageTime && (now - this.lastMessageTime) < RATE_LIMIT_MS) return false
          return true
      },
896 
      setRateLimit() {
          this.isRateLimited = true
          const remainingTime = this.lastMessageTime
              ? Math.max(0, RATE_LIMIT_MS - (Date.now() - this.lastMessageTime))
              : 0
          setTimeout(() => { this.isRateLimited = false }, remainingTime || RATE_LIMIT_MS)
      },
904 
      // ---------- counter & status ----------
      decrementMessages() {
          if (this.remainingMessages > 0) this.remainingMessages--
      },
909 
      /**
       * Rolls back an unresolved turn: refunds the spent message and drops the
       * dangling user entry, so the counter and history can't drift out of sync.
       * Used for BOTH failure shapes — a thrown request and a graceful HTTP-200
       * `success:false` — an infra hiccup must never burn one of the five
       * dispatches (or, on the last one, convert into an instant unearned defeat).
       */
      refundUnresolvedTurn() {
          if (this.remainingMessages < TOTAL_MESSAGES) this.remainingMessages++
          for (let i = this.messageHistory.length - 1; i >= 0; i--) {
              if (this.messageHistory[i].sender === 'user') {
                  this.messageHistory.splice(i, 1)
                  break
              }
          }
      },
926 
      applyProgress(progressChange: number) {
          this.objectiveProgress = Math.max(0, Math.min(MAX_PROGRESS, this.objectiveProgress + progressChange))
          this.peakProgress = Math.max(this.peakProgress, this.objectiveProgress)
      },
931 
      /**
       * Resolves win/lose AFTER a turn's progress has been applied.
       *
       * Victory the instant the objective hits 100%; defeat only once the
       * final message is spent without reaching it. This fixes the old
       * premature-defeat bug, where status flipped on the last decrement
       * BEFORE that turn's progress had a chance to land.
       */
      resolveGameStatus() {
          if (this.objectiveProgress >= MAX_PROGRESS) {
              this.gameStatus = 'victory'
          } else if (this.remainingMessages <= 0) {
              this.gameStatus = 'defeat'
          }
      },
947 
      // ---------- the turn ----------
      /**
       * Sends a 160-char message to a chosen figure and folds the result back
       * into the world: the figure replies + acts, the dice decide the swing,
       * and the Timeline Engine records how history bent.
       *
       * Returns `true` only when the turn actually RESOLVED (a ledger entry
       * landed). A blocked or failed send returns `false` so the composer can
       * keep the player's crafted words instead of wiping them.
       *
       * `opts.stake` arms the last stand — honored only when `canStake` holds
       * (final message, win out of normal reach; the server doubles the resolved
       * swing, both ways, past the usual cap).
       */
      async sendMessage(text: string, figureName?: string, opts?: { stake?: boolean }): Promise<boolean> {
          const target = (figureName ?? this.activeFigureName ?? '').trim()
          const stake = opts?.stake === true && this.canStake
965 
          if (!this.canSendMessage) return false
          if (!target) {
              this.setError('Choose who in history to send your message to first.')
              return false
          }
          if (!this.checkRateLimit()) {
              this.setRateLimit()
              this.setError('The timeline needs a moment — wait before sending again.')
              return false
          }
          if (!this.canContact) {
              const who = this.figureGrounding?.name || target
              this.setError(
                  this.contactLiveness === 'unresolved'
                      ? (this.figureGrounding?.transient
                          ? `Couldn't reach the record to verify "${target}" — try again in a moment.`
                          : `No historical record found for "${target}" — reach for a real figure (pick a match as you type).`)
                      : this.contactLiveness === 'before-birth'
                          ? `${who} isn't born yet in that year — choose a later moment to reach them.`
                          : this.contactLiveness === 'living'
                              ? (this.figureGrounding?.born
                                  ? `${who} is still living — Everwhen only reaches figures from history.`
                                  : `${who} couldn't be dated — Everwhen can only reach figures it can place in history.`)
                              : `${who} has died by that year — choose an earlier moment to reach them.`
              )
              return false
          }
993 
          this.setError(null)
          this.moderationNotice = null
          this.setActiveFigure(target)
          this.addUserMessage(text, target)
          this.decrementMessages()
          this.setLoading(true)
          this.lastMessageTime = Date.now()
1001 
          // If the run is reset while this request is in flight, every write below
          // would land in a world that no longer exists — the epoch guard drops the
          // response (no fold-in, no refund: the new run's counter is not ours).
          const epoch = this.runEpoch
          const ledgerBefore = this.timelineEvents.length
          // Capture the contact year NOW: the slider can move while the request is
          // in flight, and the ledger must record the year this turn was SENT to.
          const sentWhen = this.contactWhen
          const sentMoment = this.contactMoment
          let resolved = false
          // Decide once whether to stagger the reveal (browser + motion allowed).
          const animate = canAnimateReveal()
1014 
          try {
              const response = await $fetch<SendMessageApiResponse>('/api/send-message', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: {
                      message: text,
                      figureName: target,
                      when: sentWhen != null ? formatContactMoment(sentWhen, sentMoment) : undefined,
                      whenSigned: sentWhen ?? undefined,
                      // The pinned moment travels as validated integers; the server
                      // re-derives the display string rather than trusting ours.
                      whenMonth: sentWhen != null ? sentMoment?.month : undefined,
                      whenDay: sentWhen != null ? sentMoment?.day : undefined,
                      stake,
                      // The pre-turn momentum the server amplifies the swing by, and
                      // returns advanced (the client stays the system of record).
                      momentum: this.momentum,
                      figureContext: this.figureGrounding?.resolved
                          ? {
                              description: this.figureGrounding.description,
                              lifespan: lifespanText(this.figureGrounding)
                          }
                          : undefined,
                      objective: this.currentObjective,
                      timeline: this.timelineEvents.map(e => ({
                          era: e.era,
                          figureName: e.figureName,
                          headline: e.headline,
                          detail: e.detail,
                          progressChange: e.progressChange,
                          whenSigned: e.whenSigned
                      })),
                      conversationHistory: this.conversationWith(target)
                  }
              })
1050 
              if (epoch !== this.runEpoch) return false
1052 
              if (response?.success && response.data?.characterResponse) {
                  const { figure, characterResponse, diceRoll, diceOutcome, timeline } = response.data
1055 
                  if (figure?.name) {
                      this.registerFigure({
                          name: figure.name,
                          era: figure.era || '',
                          descriptor: figure.descriptor || ''
                      })
                  }
1063 
                  // ---- conducted reveal ----
                  // A beat of suspense (the die keeps shaking) before the result
                  // lands, so the resolution has a moment of anticipation.
                  if (animate) {
                      await wait(REVEAL.suspense)
                      if (epoch !== this.runEpoch) return false
                  }
1071 
                  // Beat 1 — the die lands and the figure's reply writes itself in
                  // (its parts stage over ~0.55s via CSS). Flipping loading here
                  // (mid-sequence) is what lands the die now; the finally's flip
                  // becomes a no-op.
                  this.addAIMessageWithData({
                      text: characterResponse.message,
                      sender: 'ai',
                      figureName: target,
                      timestamp: new Date(),
                      diceRoll,
                      diceOutcome,
                      naturalRoll: response.data.naturalRoll ?? diceRoll,
                      rollModifier: response.data.rollModifier ?? 0,
                      craft: response.data.craft,
                      craftReason: response.data.craftReason,
                      continuity: response.data.continuity,
                      characterAction: characterResponse.action,
                      timelineImpact: timeline?.detail,
                      progressChange: timeline?.progressChange,
                      baseProgressChange: timeline?.baseProgressChange,
                      momentumAtSwing: timeline?.momentumAtSwing,
                      anachronism: timeline?.anachronism,
                      causalChain: timeline?.causalChain,
                      staked: response.data.staked
                  })
                  if (animate) this.setLoading(false)
1098 
                  if (timeline) {
                      // Beat 2 — the timeline shift (the % gauge flies its delta),
                      // timed to land with the reply's own "ripple" line.
                      if (animate) {
                          await wait(REVEAL.swing)
                          if (epoch !== this.runEpoch) return false
                      }
                      // Use !== undefined so a genuine neutral (0%) turn still
                      // registers instead of silently vanishing.
                      if (timeline.progressChange !== undefined) {
                          this.applyProgress(timeline.progressChange)
                      }
                      // The arc meter is server-authoritative for the result; advance
                      // it WITH the swing it amplified — and only past the epoch check
                      // above, so a stale turn never moves the meter (issue #62).
                      this.momentum = response.data.momentum ?? this.momentum
1115 
                      // Beat 3 — the change drops onto the Spine ledger.
                      if (animate) {
                          await wait(REVEAL.node)
                          if (epoch !== this.runEpoch) return false
                      }
                      this.addTimelineEvent({
                          figureName: target,
                          era: timeline.era || figure?.era || (this.currentObjective?.era ?? ''),
                          headline: timeline.headline,
                          detail: timeline.detail,
                          diceRoll,
                          diceOutcome,
                          progressChange: timeline.progressChange ?? 0,
                          baseProgressChange: timeline.baseProgressChange,
                          valence: timeline.valence,
                          anachronism: timeline.anachronism,
                          causalChain: timeline.causalChain,
                          craft: response.data.craft,
                          whenSigned: sentWhen ?? undefined,
                          staked: response.data.staked
                      })
                      resolved = true
                  }
              } else {
                  // A graceful failure (HTTP 200, success:false): an AI layer gave
                  // out mid-turn. No ripple landed, so the dispatch is refunded —
                  // exactly like the thrown path below.
                  // Narrow to the failure variant (its data carries `blocked`).
                  const failed = response && !response.success ? response.data : undefined
                  if (failed?.blocked) {
                      // A content-moderation block, not an infra hiccup — show an
                      // honest, distinct banner (not "try again"). The composer
                      // keeps the player's words (sendMessage returns false).
                      this.moderationNotice = failed.moderationReason || 'That dispatch was blocked by content moderation and cannot be sent.'
                  } else {
                      this.setError(failed?.error || 'History did not answer. Try again.')
                  }
                  this.refundUnresolvedTurn()
              }
          } catch (error) {
              if (epoch !== this.runEpoch) return false
              console.error('Error sending message:', error)
              this.setError('The timeline resisted your message. Please try again.')
              this.refundUnresolvedTurn()
          } finally {
              if (epoch === this.runEpoch) {
                  this.setLoading(false)
                  this.resolveGameStatus()
              }
          }
1166 
          // The living chronicle re-narrates the world from the new timeline — but
          // only when this turn actually added a change, and never awaited: the turn
          // reveal must not wait on prose. By here the status is resolved, so the
          // final turn's chronicle carries the victory/defeat framing (the epilogue).
          let refresh: Promise<void> | null = null
          if (resolved && this.timelineEvents.length > ledgerBefore) {
              refresh = this.refreshChronicle()
              void refresh
              // The on-ramp blurbs re-narrate against the altered timeline (issue
              // #131), non-blocking like the chronicle — neither holds the reveal.
              void this.refreshSuggestions()
          }
          // The run just ended: persist it (best-effort) so it survives reload, then
          // re-save once the epilogue's telling lands — the immediate save guards
          // against that refresh failing, the second captures the final Chronicle.
          if (this.gameStatus === 'victory' || this.gameStatus === 'defeat') {
              // This turn's refresh writes the EPILOGUE — the terminal telling that
              // carries the verdict. Mark it pending so the end screen shows "the
              // final account…" instead of the prior turn's stale telling. Cleared
              // when the telling lands OR the refresh fails (refreshChronicle keeps
              // the prior telling on failure) — so the panel reveals or falls back,
              // never hanging on the loading state.
              if (refresh) {
                  this.epiloguePending = true
                  void refresh.finally(() => { if (epoch === this.runEpoch) this.epiloguePending = false })
              }
              void this.saveRunSnapshot()
              if (refresh) void refresh.finally(() => { void this.saveRunSnapshot() })
          }
          return resolved
      },
1198 
      /**
       * Seed a replay (issue #89): start a fresh run on a shared run's captured
       * objective. Resets first (the share page may follow an abandoned run in the
       * same tab) so the run starts clean, THEN records the seed — so the mission
       * briefing opens focused on this objective, and the lineage + credit ride
       * through to the end. No generation: the objective is reused verbatim, and the
       * player still commits (and is charged) by pressing Begin.
       */
      preseedReplay(objective: GameObjective, sourceToken: string, sourceAttribution: string | null): void {
          this.resetGame()
          this.replayState = { objective, sourceToken, sourceAttribution }
      },
1211 
      /** Drop the replay seed — the player chose to start from scratch instead, so this
       *  run is an original (no "remixed from" lineage). */
      clearReplayState(): void {
          this.replayState = null
      },
1217 
      /**
       * Commits a chosen objective and starts the run from a clean slate of
       * progress. Used by the mission-select screen for both curated picks and
       * freshly composed ones.
       */
      async chooseObjective(objective: GameObjective): Promise<boolean> {
          // Commit = the run is charged here. Mint the run id server-side, then
          // spend one run from the device's balance. Fails CLOSED: out of runs →
          // raise the paywall; begin-run or commit failing → surface an error and
          // do NOT start. A run that isn't a charged, server-backed run would be
          // rejected by the gameplay gate anyway, so starting it only strands the
          // player mid-run. The spend cap (not free play) is the outage backstop.
          let runId: string
          try {
              runId = await this.ensureRunId()
          } catch (error) {
              console.error('Could not begin the run:', error)
              this.error = 'Could not start the run. Please try again.'
              return false
          }
          try {
              const res = await $fetch('/api/run-commit', {
                  method: 'POST',
                  headers: { 'Content-Type': 'application/json' },
                  body: { runId }
              }) as { runsRemaining?: number }
              this.outOfRuns = false
              // Keep the header gauge live: the commit returns the post-charge
              // balance (−1 marks a degraded, ungated run — leave the gauge as is).
              if (typeof res?.runsRemaining === 'number' && res.runsRemaining >= 0) {
                  this.runsRemaining = res.runsRemaining
              }
          } catch (error) {
              if (isPaymentRequired(error)) {
                  this.outOfRuns = true
                  this.openBuyModal()
                  return false
              }
              if (isAtCapacity(error)) {
                  this.atCapacity = true
                  return false
              }
              console.error('Could not charge the run:', error)
              this.error = 'Could not start the run. Please try again.'
              return false
          }
          this.currentObjective = objective
          this.objectiveProgress = 0
          this.peakProgress = 0
          this.momentum = 0
          this.error = null
          return true
      },
1271 
      /**
       * Asks the server to compose a fresh objective with the model, WITHOUT
       * committing it — the caller previews it, then commits via chooseObjective.
       * Generation lives server-side because it needs the OpenAI key (the client
       * has no access to it). An optional steer (era + theme, closed enums) biases
       * the composition; the server re-validates it against the enums, so a bad
       * value is harmless. `avoid` is the titles already composed this session, so
       * a reroll lands somewhere new (#95) — the stateless server only knows what
       * the client supplies. Returns null rather than throwing if composing fails,
       * so the UI can quietly fall back to the curated pool.
       */
      async fetchAIObjective(steer: ObjectiveSteer = {}, avoid: string[] = []): Promise<GameObjective | null> {
          try {
              const query: Record<string, string | string[]> = {}
              if (steer.era) query.era = steer.era
              if (steer.theme) query.theme = steer.theme
              if (avoid.length) query.avoid = avoid
              const res = await $fetch('/api/objective', { method: 'GET', query, headers: await this.aiHeaders() }) as {
                  success?: boolean
                  objective?: GameObjective
              }
              return res?.success && res.objective ? res.objective : null
          } catch (error) {
              console.error('Failed to compose a fresh objective:', error)
              return null
          }
      },
1299 
      /**
       * Loads the device's run balance for the header gauge + account popover.
       * Grants the free trial on a brand-new device (server-side). Graceful: on
       * failure it leaves the prior value (the gauge simply doesn't update).
       */
      async loadBalance(): Promise<void> {
          try {
              const res = await $fetch('/api/balance') as { runsRemaining?: number; freeRuns?: number; deviceRef?: string; email?: string | null; isAnonymous?: boolean }
              if (typeof res?.runsRemaining === 'number') this.runsRemaining = res.runsRemaining
              if (typeof res?.freeRuns === 'number') this.freeRuns = res.freeRuns
              if (typeof res?.deviceRef === 'string') this.deviceRef = res.deviceRef
              this.accountEmail = res?.email ?? null
              this.accountAnonymous = res?.isAnonymous === true
          } catch (error) {
              console.error('Failed to load balance:', error)
          }
      },
1317 
      /** Opens the run-packs sales modal, loading the catalog first. */
      async openBuyModal(): Promise<void> {
          this.buyModalOpen = true
          await this.loadPacks()
      },
1323 
      /** Closes the sales modal. */
      closeBuyModal(): void {
          this.buyModalOpen = false
      },
1328 
      /** Records the Stripe-return outcome and refreshes the balance on success
       *  (the webhook credits asynchronously; re-read so the gauge reflects it). */
      async notePurchaseReturn(outcome: 'success' | 'cancel'): Promise<void> {
          this.purchaseNotice = outcome
          this.buyModalOpen = false
          if (outcome === 'success') {
              this.outOfRuns = false
              await this.loadBalance()
          }
      },
1339 
      /** Dismisses the post-purchase notice. */
      clearPurchaseNotice(): void {
          this.purchaseNotice = null
      },
1344 
      /** Loads the run-pack catalog for the paywall. Caches only a NON-empty
       *  result: a transient empty/failed read must not poison the cache and
       *  strand the modal with zero packs for the rest of the session. */
      async loadPacks(): Promise<void> {
          if (this.packs.length) return
          try {
              const res = await $fetch('/api/packs') as { packs?: Pack[] }
              const packs = res?.packs ?? []
              if (packs.length) this.packs = packs
          } catch (error) {
              console.error('Failed to load packs:', error)
          }
      },
1358 
      /** Starts checkout for a pack; returns the Stripe Checkout URL to redirect
       *  to (null on failure). The caller does the redirect. */
      async buyPack(packId: string): Promise<string | null> {
          try {
              const res = await $fetch('/api/checkout', {
                  method: 'POST',
                  headers: { 'Content-Type': 'application/json' },
                  body: { packId }
              }) as { url?: string }
              return res?.url ?? null
          } catch (error) {
              console.error('Failed to start checkout:', error)
              return null
          }
      },
1374 
      getVictoryEfficiency() {
          if (this.gameStatus === 'victory') {
              const messagesSaved = this.remainingMessages
              const messagesUsed = TOTAL_MESSAGES - this.remainingMessages
              const efficiencyPercentage = Math.round((messagesSaved / TOTAL_MESSAGES) * 100)
1380 
              const efficiencyRating = rateEfficiency(messagesSaved)
1382 
              return {
                  messagesSaved,
                  messagesUsed,
                  efficiencyPercentage,
                  efficiencyRating,
                  isEarlyVictory: messagesSaved > 0
              }
          }
          return null
      },
1393 
      /**
       * Persist the finished run's snapshot to the player's account, best-effort.
       * Captures exactly what the end screen shows — objective, verdict, ledger,
       * dispatches, rolls, and the Chronicle epilogue — keyed by the run id, so the
       * run survives reload and feeds the read-only "your runs" view. Fires and
       * forgets like refreshChronicle: a save failure must never disturb the end
       * screen. Only a completed (victory/defeat), server-backed (uuid run id) run
       * is saved; a degraded local id is dropped server-side.
       */
      async saveRunSnapshot(): Promise<void> {
          const epoch = this.runEpoch
          const status = this.gameStatus
          if (status !== 'victory' && status !== 'defeat') return
          const objective = this.currentObjective
          const runId = this.runId
          if (!objective || !runId) return
1410 
          const summary = this.gameSummary
          const events = this.timelineEvents
          // The dispatch keepsake — the player's verbatim messages, paired with
          // whom/when they reached (the same zip the end screen renders).
          const dispatches = this.messageHistory
              .filter((m) => m.sender === 'user')
              .map((m, i) => ({
                  text: m.text,
                  figure: m.figureName || events[i]?.figureName || 'the past',
                  era: events[i]?.era || ''
              }))
          const mark = (m: typeof summary.bestRoll) =>
              m && m.diceRoll != null && m.diceOutcome != null
                  ? { diceRoll: m.diceRoll, diceOutcome: m.diceOutcome }
                  : null
1426 
          const snapshot: RunSnapshot = {
              version: RUN_SNAPSHOT_VERSION,
              runId,
              status,
              objective,
              objectiveProgress: this.objectiveProgress,
              // The high-water mark, so a snapshot-backed view can show "Peaked at X%"
              // (the live store zeroes it on reset, so it's only meaningful here at end).
              peakProgress: this.peakProgress,
              messagesUsed: TOTAL_MESSAGES - this.remainingMessages,
              totalMessages: TOTAL_MESSAGES,
              bestRoll: mark(summary.bestRoll),
              worstRoll: mark(summary.worstRoll),
              efficiency: this.getVictoryEfficiency(),
              dispatches,
              timeline: events.map((e) => ({
                  id: e.id,
                  figureName: e.figureName,
                  era: e.era,
                  headline: e.headline,
                  detail: e.detail,
                  diceRoll: e.diceRoll,
                  diceOutcome: e.diceOutcome,
                  progressChange: e.progressChange,
                  baseProgressChange: e.baseProgressChange,
                  valence: e.valence,
                  craft: e.craft,
                  anachronism: e.anachronism,
                  staked: e.staked
              })),
              chronicle: this.chronicle
          }
1459 
          // A replay (issue #89) rides its source's share token alongside the snapshot
          // (a sibling field, not part of the immutable blob); the server resolves it to
          // the parent run id and stamps the lineage pointer. replayState set ⟺ this run
          // committed the seeded objective (the briefing clears it on any other choice).
          const body = this.replayState
              ? { ...snapshot, remixedFromToken: this.replayState.sourceToken }
              : snapshot
1467 
          try {
              const res = (await $fetch('/api/run-save', {
                  method: 'POST',
                  headers: { 'Content-Type': 'application/json' },
                  body
              })) as { saved?: boolean }
              // Mark saved (for the share affordance) only if this run is still current
              // and the server actually persisted it (a degraded run returns saved:false).
              if (epoch === this.runEpoch && res?.saved) this.runSnapshotSaved = true
          } catch (error) {
              // Saving the run is a nicety; a failure must not break the end screen.
              if (epoch === this.runEpoch) console.error('Could not save the run:', error)
          }
      },
1482 
      resetGame() {
          // Tear the epoch first: anything still in flight belongs to the old run
          // and must find no purchase here. (The seq counters deliberately survive.)
          this.runEpoch++
          this.remainingMessages = TOTAL_MESSAGES
          this.messageHistory = []
          this.gameStatus = 'playing'
          this.isLoading = false
          this.error = null
          this.lastMessageTime = null
          this.isRateLimited = false
          // A new run gets a fresh id on its next server call; abandon any
          // in-flight mint so a dead run's id can't land in the new run.
          this.runId = null
          this.runIdInflight = null
          this.runSnapshotSaved = false
          // The paywall / capacity notices re-check on the next commit.
          this.outOfRuns = false
          this.atCapacity = false
          this.currentObjective = null
          // A fresh run carries no replay lineage (preseedReplay re-sets it after).
          this.replayState = null
          this.objectiveProgress = 0
          this.peakProgress = 0
          this.momentum = 0
          this.timelineEvents = []
          this.figures = []
          this.activeFigureName = ''
          this.figureGrounding = null
          this.groundingLoading = false
          this.contactWhen = null
          this.contactMoment = null
          this.figureSuggestions = []
          this.suggestionsLoading = false
          this.suggestionsFor = ''
          this.chronicle = null
          this.chronicleLoading = false
          this.epiloguePending = false
          this.figureStudy = null
          this.studyLoading = false
          this.studyFor = ''
          this.studyWhen = null
          this.archiveResult = null
          this.lookupLoading = false
          this.moderationNotice = null
          this.archiveNotice = null
          this.studyNotice = null
          this.suggestionsNotice = null
      }
  }
1533})

Fired next to refreshChronicle, only on a turn that actually changed the world.

stores/game.ts · 1533 lines

stores/game.ts1533 lines · TypeScript

⋯ 1169 lines hidden (lines 1–1169)1import { defineStore } from 'pinia'
2import type { GameObjective, ObjectiveSteer } from '~/server/utils/objectives'
3import type { Pack } from '~/server/utils/packs'
4import type { GroundedFigure } from '~/server/utils/figure-grounding'
5import { formatContactMoment, type ContactMoment } from '~/utils/contact-moment'
6import type { FigureSuggestion } from '~/server/utils/figure-suggester'
7import type { ChronicleEntry } from '~/server/utils/openai'
8import type { FigureStudy, ArchiveLookup } from '~/server/utils/prompt-builder'
9import type { Anachronism } from '~/server/utils/anachronism'
10import { chainStatus, type ChainStatus } from '~/utils/causal-chain'
11import type { Craft } from '~/utils/craft'
12import type { Continuity } from '~/utils/continuity'
13import type { DiceOutcome } from '~/utils/dice'
14import { generateGameSummary, rateEfficiency, type GameSummary } from '~/utils/game-summary'
15import { TOTAL_MESSAGES, MAX_PROGRESS_SWING, MAX_PROGRESS } from '~/utils/game-config'
16import { RUN_SNAPSHOT_VERSION, type RunSnapshot } from '~/utils/run-snapshot'
17 
18export type Valence = 'positive' | 'negative' | 'neutral'
19 
20/**
* A historical figure the player has reached out to. Figures are freeform — the
* player can write to anyone, in any era. The AI infers each figure's era and a
* short descriptor on first contact, which we cache here for the UI.
*/
25export interface HistoricalFigure {
  name: string
  era: string
  descriptor: string
29}
30 
31/**
* Timeline Ledger entry — a single recorded change to history.
*
* The ledger is the heart of the game: every resolved turn appends one entry
* describing how the world bent, so the player literally watches the timeline
* rewrite itself as they play.
*/
38export interface TimelineEvent {
  id: string
  figureName: string
  era: string
  headline: string
  detail: string
  diceRoll: number
  diceOutcome: DiceOutcome
  progressChange: number
  /** The engine's swing BEFORE the anachronism amplifier — shown so the player
   *  can see exactly what their wager did ("+8 ⚡ far-ahead → +11%"). */
  baseProgressChange?: number
  valence: Valence
  /** How anachronistic the player's nudge was — it widened this swing. */
  anachronism?: Anachronism
  /** How far this landed from the nearest foothold — it decayed this swing. */
  causalChain?: ChainStatus
  /** The Judge's grade of the dispatch that caused this change. */
  craft?: Craft
  /** Signed year of the intervention, when the contact was grounded. */
  whenSigned?: number
  /** True when this was the run's staked last stand (doubled swing). */
  staked?: boolean
  timestamp: Date
62}
63 
64/**
* Message Interface — one line in the conversation with a figure.
* Dice / outcome / action / impact / progress are recorded on the AI (figure)
* turn, since that is the resolved result of the roll.
*/
69export interface Message {
  text: string
  sender: 'user' | 'ai' | 'system'
  timestamp: Date
  figureName?: string
  /** The effective (craft-tilted) roll — what the bands judged. */
  diceRoll?: number
  diceOutcome?: DiceOutcome
  /** The die as it actually landed, before the craft modifier. */
  naturalRoll?: number
  /** The Judge's tilt on the roll (±2..0), and the grade + reason behind it. */
  rollModifier?: number
  craft?: Craft
  craftReason?: string
  /** Whether the dispatch built on the run's thread (issue #62) — drives the
   *  momentum meter and the 'builds' badge in the reveal. */
  continuity?: Continuity
  characterAction?: string
  timelineImpact?: string
  progressChange?: number
  /** The pre-amplifier swing + the wager level, for the reveal's equation. */
  baseProgressChange?: number
  /** The PRE-turn momentum that amplified this swing — for the reveal's equation. */
  momentumAtSwing?: number
  anachronism?: Anachronism
  /** The causal-chain decay applied to this swing (for the reveal's equation). */
  causalChain?: ChainStatus
  /** True when this turn was the staked last stand. */
  staked?: boolean
98}
99 
100export type GameStatus = 'playing' | 'victory' | 'defeat'
101 
102/**
* Shape returned by `POST /api/send-message` (see `server/api/send-message.post.ts`).
* Discriminated by `success`: when `true`, all fields downstream of the dice roll are
* guaranteed; when `false`, only `userMessage` + `error` are guaranteed (and the
* Character-AI-failure path doesn't even surface a dice roll). The discriminant lets
* the consumer destructure without optional chaining or null gymnastics.
*/
109type SendMessageApiResponse =
  | {
      success: true
      message: string
      data: {
          userMessage: string
          figure: { name: string; era: string; descriptor: string }
          diceRoll: number
          diceOutcome: DiceOutcome
          // Judge-of-craft fields (optional so older mocks/fixtures stay valid;
          // the live server always sends them).
          naturalRoll?: number
          rollModifier?: number
          craft?: Craft
          craftReason?: string
          continuity?: Continuity
          momentum?: number
          staked?: boolean
          characterResponse: { message: string; action: string }
          timeline: {
              headline: string
              detail: string
              era: string
              progressChange: number
              baseProgressChange?: number
              momentumAtSwing?: number
              valence: Valence
              anachronism?: Anachronism
              causalChain?: ChainStatus
          }
          error: null
      }
  }
  | {
      success: false
      message: string
      data: {
          userMessage: string
          diceRoll?: number
          diceOutcome?: DiceOutcome
          characterResponse?: { message: string; action: string }
          error: string
          /** A content-moderation block (not an infra failure): the dispatch was
           *  refused by the detector, the Sentinel, or the model itself. */
          blocked?: boolean
          moderationReason?: string
      }
  }
157 
158const RATE_LIMIT_MS = 1000 // message cooldown window, in ms
159 
160// Turn-reveal pacing. A resolved turn releases its beats one at a time — a beat of
161// suspense, then the die lands and the figure's reply writes itself in, then the
162// timeline shift, then the ledger node — so the resolution reads as one conducted
163// moment instead of everything firing in the same tick. Each component already
164// animates when its own slice of state changes; sequencing the WRITES sequences the
165// animations, with no component coordination. Tuned so the swing lands with the
166// reply's own "ripple" line (~0.55s into its staged reveal).
167export const REVEAL = { suspense: 450, swing: 550, node: 250 } as const
168const wait = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms))
169/** Stagger the reveal only in a real browser with motion allowed. SSR and the test
*  env (no `matchMedia`) collapse to an instant, atomic apply — so the store's
*  contract (state present the moment sendMessage resolves) is unchanged for tests. */
172function canAnimateReveal(): boolean {
  return typeof window !== 'undefined'
      && typeof window.matchMedia === 'function'
      && !window.matchMedia('(prefers-reduced-motion: reduce)').matches
176}
177 
178function valenceOf(progressChange: number): Valence {
  if (progressChange > 0) return 'positive'
  if (progressChange < 0) return 'negative'
  return 'neutral'
182}
183 
184/** Formats a signed timeline year (AD positive, BCE negative) for display. */
185export function formatContactYear(signed: number): string {
  return signed < 0 ? `${-signed} BC` : `${signed}`
187}
188 
189/** The landed ledger as {era, headline} for the suggester's altered-timeline brief
*  (issue #131) — the server bounds + caps it. Drops changes without a headline. */
191function ledgerForSuggester(events: TimelineEvent[]): { era: string; headline: string }[] {
  return events.filter(e => e.headline).map(e => ({ era: e.era, headline: e.headline }))
193}
194 
195/** Human lifespan line for a grounded figure, e.g. "69 BC – 30 BC" or "1942 – present". */
196function lifespanText(g: GroundedFigure): string | undefined {
  if (!g.born) return undefined
  if (g.died) return `${g.born.display} – ${g.died.display}`
  return g.living ? `${g.born.display} – present` : g.born.display
200}
201 
202/** True when a $fetch error is a 402 (out of runs) — the paywall signal. ofetch
*  surfaces the status as statusCode and on the response, so check both. */
204function isPaymentRequired(error: unknown): boolean {
  const e = error as { statusCode?: number; status?: number; response?: { status?: number } }
  return e?.statusCode === 402 || e?.status === 402 || e?.response?.status === 402
207}
208 
209/** True when a $fetch error is a 503 / at-capacity — the spend cap paused new
*  runs (distinct from the per-device 402 paywall). */
211function isAtCapacity(error: unknown): boolean {
  const e = error as { statusCode?: number; status?: number; response?: { status?: number }; data?: { atCapacity?: boolean } }
  return e?.statusCode === 503 || e?.status === 503 || e?.response?.status === 503 || e?.data?.atCapacity === true
214}
215 
216export type ContactLiveness = 'ok' | 'before-birth' | 'after-death' | 'living' | 'unresolved' | 'unknown'
217 
218/**
* A replay seed (issue #89) — when a player starts a run from a shared run's captured
* objective. It carries the objective to seed (verbatim, no generation), the SOURCE run's
* public share token (rides along to /api/run-save to stamp the lineage pointer), and the
* source's display name at seed time (for the "remixed from" credit shown before/after the
* run; the public page re-derives the credit live, honoring the source's current opt-in).
*/
225export interface ReplaySeed {
  objective: GameObjective
  sourceToken: string
  sourceAttribution: string | null
229}
230 
231/**
* Game Store — core state for a session of freeform timeline editing.
*/
234export const useGameStore = defineStore('game', {
  state: () => ({
      remainingMessages: TOTAL_MESSAGES,
      messageHistory: [] as Message[],
      gameStatus: 'playing' as GameStatus,
      isLoading: false,
      error: null as string | null,
      lastMessageTime: null as number | null,
      isRateLimited: false,
      // Staleness plumbing, not run state. runEpoch increments on every reset so an
      // async result from a dead run can never write into a fresh one; the seq
      // counters order overlapping requests of the same kind so only the latest
      // lands (an earlier chronicle rewrite must not overwrite a later one).
      // Deliberately NOT restored by resetGame — they must survive it to work.
      runEpoch: 0,
      chronicleSeq: 0,
      suggestionsSeq: 0,
      groundingSeq: 0,
      // The current run's id — lazily minted on the run's first server call and
      // cleared by resetGame so each run gets a fresh one. Tags every AI call
      // (via the x-run-id header) so the gateway's cost telemetry groups per
      // run: the GTM cost instrument.
      runId: null as string | null,
      // The in-flight begin-run, so concurrent first-calls of a run share one
      // mint (one POST /api/run, one runs row) instead of racing two. Cleared
      // by resetGame. (Vue leaves a Promise unproxied, so awaiting it is safe.)
      runIdInflight: null as Promise<string> | null,
      // True once this run's snapshot is durably saved (POST /api/run-save returned
      // saved). Gates the end-screen Share affordance (issue #88) so it appears only for
      // a run that actually exists server-side to share — never for a degraded local id.
      // Reset per run.
      runSnapshotSaved: false,
      // outOfRuns gates the mission screen's paywall (set when a commit is
      // refused with 402). The run packs offered there are loaded into `packs`.
      outOfRuns: false,
      // atCapacity gates the "at capacity" notice (set when a commit is refused
      // with 503 because the global spend cap paused new runs).
      atCapacity: false,
      packs: [] as Pack[],
      // The device's run balance, for the header gauge + account popover. null
      // until first loaded (GET /api/balance); the run-commit response also
      // refreshes it so the gauge stays live without a second round-trip.
      runsRemaining: null as number | null,
      freeRuns: 1,
      deviceRef: '' as string,
      // Account state (from /api/balance): the signed-in email, and whether the
      // current user is anonymous (→ must sign in before buying). Drives the
      // account UI + the sign-in-to-buy gate. false/null in device-fallback mode.
      accountEmail: null as string | null,
      accountAnonymous: false,
      // The run-packs sales modal — opened on demand (header) or automatically
      // when a commit is refused for being out of runs.
      buyModalOpen: false,
      // A one-shot notice after returning from Stripe Checkout ('success' shows a
      // credited confirmation; 'cancel' a gentle "no charge" note). Cleared by the UI.
      purchaseNotice: null as 'success' | 'cancel' | null,
      currentObjective: null as GameObjective | null,
      // Set when this run is a REPLAY of a shared run's objective (issue #89): seeded
      // verbatim from the public projection, no generation. Survives chooseObjective so
      // it can stamp the lineage pointer at save time and credit the source on the end
      // screen; cleared by resetGame (a fresh "new timeline" carries no lineage).
      replayState: null as ReplaySeed | null,
      objectiveProgress: 0,
      // The run's high-water mark (0..MAX_PROGRESS): the highest objectiveProgress ever
      // reached this run. Tracked so the end screen can show "peaked at X%" when a run
      // loses ground from its peak — classically a staked final dispatch that crit-fails
      // to 0% — instead of the floored final % erasing the player's real effort (#129).
      peakProgress: 0,
      // The run-level momentum meter (0..MOMENTUM_MAX): a coherent arc compounds its
      // gains amplifier; a reset or catastrophe shatters it back to 0 (issue #62).
      momentum: 0,
      timelineEvents: [] as TimelineEvent[],
      figures: [] as HistoricalFigure[],
      activeFigureName: '' as string,
      // Grounding for the active contact: real facts + the chosen year to reach them.
      figureGrounding: null as GroundedFigure | null,
      groundingLoading: false,
      contactWhen: null as number | null,
      /** Optional sub-year refinement of contactWhen — display/prompt flavor
       *  only; every mechanic keeps doing arithmetic on the YEAR (issue #32). */
      contactMoment: null as ContactMoment | null,
      // Era-relevant figure suggestions for the current objective (the on-ramp).
      figureSuggestions: [] as FigureSuggestion[],
      suggestionsLoading: false,
      suggestionsFor: '' as string,
      // The living Chronicle (Layer 3): a prose telling of the altered timeline,
      // rewritten each turn. Non-blocking — see refreshChronicle.
      chronicle: null as ChronicleEntry | null,
      chronicleLoading: false,
      // The run's epilogue — the TERMINAL telling carrying the verdict — is being
      // written. Set when the final turn fires its refresh and cleared when that
      // telling lands or the refresh fails. Distinct from chronicleLoading (any
      // refresh): it lets the end screen show "the final account…" instead of
      // presenting the prior turn's stale, pre-ending telling as the epilogue.
      epiloguePending: false,
      // The Archive (prototype): an objective-blind brief on the active figure, so
      // the player can research who they're reaching without leaving the game. The
      // brief is moment-specific, so it's cached against the figure AND the year.
      figureStudy: null as FigureStudy | null,
      studyLoading: false,
      studyFor: '' as string,
      studyWhen: null as number | null,
      // Archive topic lookup (the "yellow" layer): concrete domain facts on demand.
      archiveResult: null as ArchiveLookup | null,
      lookupLoading: false,
      // A content-moderation block — distinct from `error` (an infra hiccup) so
      // the UI shows an honest, visibly different banner. One per surface that
      // takes untrusted input into a model: the dispatch/turn, the Archive lookup,
      // the Archivist study, and the figure-suggestions step.
      moderationNotice: null as string | null,
      archiveNotice: null as string | null,
      studyNotice: null as string | null,
      suggestionsNotice: null as string | null
  }),
348 
  getters: {
      /**
       * Can the player send right now? (messages left, still playing, not
       * mid-request, not rate-limited)
       */
      canSendMessage(): boolean {
          return this.remainingMessages > 0 &&
                 this.gameStatus === 'playing' &&
                 !this.isLoading &&
                 !this.isRateLimited
      },
360 
      /**
       * The conversation thread with a single figure (their turns + the
       * player's turns addressed to them). Each figure keeps a coherent,
       * independent thread.
       */
      conversationWith(): (name: string) => Message[] {
          return (name: string) => this.messageHistory.filter(
              m => m.figureName === name && m.sender !== 'system'
          )
      },
371 
      /** Total progress, net of setbacks, the player has clawed back. */
      gameSummary(): GameSummary {
          return generateGameSummary(this)
      },
376 
      /**
       * Whether the active figure can be reached at the chosen `when`.
       *
       * Require grounding (#73): an UNRESOLVED name can't be reached at all —
       * 'unresolved' (free-form contact is removed; the picker guides you to a real
       * match). Deceased-only floor (#72): a RESOLVED figure with no confirmed
       * death is living/undatable and never contactable — 'living', fail closed. A
       * resolved, deceased figure is gated to their lifetime (before-birth /
       * after-death). 'unknown' remains only for a resolved, deceased figure we
       * can't fully place (no birth year, or no contact year chosen yet), which
       * stays permissible.
       */
      contactLiveness(): ContactLiveness {
          const g = this.figureGrounding
          if (!g || !g.resolved) return 'unresolved'
          if (!g.died) return 'living'
          if (!g.born || this.contactWhen == null) return 'unknown'
          if (this.contactWhen < g.born.signed) return 'before-birth'
          if (this.contactWhen > g.died.signed) return 'after-death'
          return 'ok'
      },
398 
      /** Can the chosen contact + when actually be reached? */
      canContact(): boolean {
          return this.contactLiveness === 'ok' || this.contactLiveness === 'unknown'
      },
403 
      /**
       * The last stand is offered ONLY when the final dispatch can no longer win
       * inside the normal per-turn fuse — from any nearer position an unstaked
       * throw can still land it, and offering the (strictly win-probability-
       * increasing) doubling there would be a dominance trap, not a decision.
       */
      canStake(): boolean {
          return this.remainingMessages === 1 &&
                 this.gameStatus === 'playing' &&
                 (MAX_PROGRESS - this.objectiveProgress) > MAX_PROGRESS_SWING
      },
415 
      /**
       * The active figure's age at the chosen `when` — so the player never has to
       * do lifetime math in their head. Null when we lack a birth year or a chosen
       * year (a resolved figure we can't date, or before a year is chosen). Corrects for the missing year zero
       * when a life spans the BC→AD boundary (1 BC → AD 1 is one year, not two).
       */
      contactAge(): number | null {
          const g = this.figureGrounding
          if (!g?.resolved || !g.born || this.contactWhen == null) return null
          const bornSigned = g.born.signed
          const whenSigned = this.contactWhen
          if (whenSigned < bornSigned) return null // before birth — no meaningful age
          const crossedZero = bornSigned < 0 && whenSigned > 0 ? 1 : 0
          return whenSigned - bornSigned - crossedZero
      },
431 
      /**
       * The causal-chain read for the CURRENT contact — the pre-send ⏳ chip's
       * source, mirroring what the Timeline Engine will compute. Footholds are the
       * objective's anchor year plus every dated change already on the ledger; the
       * gap to the nearest one decays the swing. Null (no chip) for ungrounded
       * contacts or an anchorless objective with no dated changes yet.
       */
      causalChainRead(): ChainStatus | null {
          const footholds = [
              this.currentObjective?.anchorYear,
              ...this.timelineEvents.map(e => e.whenSigned)
          ]
          return chainStatus(this.contactWhen, footholds)
      }
  },
447 
  actions: {
      // ---------- message helpers ----------
      addUserMessage(text: string, figureName?: string) {
          if (this.gameStatus !== 'playing') return
          this.messageHistory.push({
              text,
              sender: 'user',
              timestamp: new Date(),
              figureName
          })
      },
459 
      addAIMessage(text: string, figureName?: string) {
          this.messageHistory.push({
              text,
              sender: 'ai',
              timestamp: new Date(),
              figureName
          })
      },
468 
      addAIMessageWithData(messageData: Partial<Message> & { text: string, sender: 'ai' }) {
          this.messageHistory.push({
              text: messageData.text,
              sender: messageData.sender,
              timestamp: messageData.timestamp || new Date(),
              figureName: messageData.figureName,
              diceRoll: messageData.diceRoll,
              diceOutcome: messageData.diceOutcome,
              naturalRoll: messageData.naturalRoll,
              rollModifier: messageData.rollModifier,
              craft: messageData.craft,
              craftReason: messageData.craftReason,
              continuity: messageData.continuity,
              characterAction: messageData.characterAction,
              timelineImpact: messageData.timelineImpact,
              progressChange: messageData.progressChange,
              baseProgressChange: messageData.baseProgressChange,
              momentumAtSwing: messageData.momentumAtSwing,
              anachronism: messageData.anachronism,
              causalChain: messageData.causalChain,
              staked: messageData.staked
          })
      },
492 
      // ---------- figures ----------
      registerFigure(figure: HistoricalFigure) {
          const existing = this.figures.find(f => f.name === figure.name)
          if (existing) {
              if (figure.era) existing.era = figure.era
              if (figure.descriptor) existing.descriptor = figure.descriptor
          } else {
              this.figures.push({ ...figure })
          }
      },
503 
      setActiveFigure(name: string) {
          this.activeFigureName = name
      },
507 
      /**
       * Synchronously clears the dossier the moment the contact NAME changes, so
       * a send racing the grounding debounce/fetch is gated as ungrounded (#73)
       * instead of wearing the PREVIOUS figure's facts, year, and liveness gate —
       * and so the wrong year can never be written into the ledger's whenSigned.
       */
      clearGrounding() {
          this.groundingSeq++ // invalidate any lookup still in flight
          this.figureGrounding = null
          this.contactWhen = null
          this.contactMoment = null
          this.groundingLoading = false
          this.figureStudy = null
          this.studyFor = ''
          this.studyWhen = null
          this.studyNotice = null
      },
525 
      /**
       * Resolves the active figure against the grounding service and defaults the
       * "when" to a point inside any known lifetime. Never throws: an unresolved
       * figure simply clears grounding; an ungrounded contact is then blocked (#73).
       */
      async groundActiveFigure(name: string): Promise<void> {
          const target = (name || '').trim()
          // A new contact makes any prior Archive study stale.
          this.figureStudy = null
          this.studyFor = ''
          this.studyWhen = null
          this.studyNotice = null
          if (!target) {
              this.groundingSeq++ // invalidate any lookup still in flight
              this.figureGrounding = null
              this.contactWhen = null
              this.contactMoment = null
              this.groundingLoading = false
              return
          }
          // Out-of-order guard: only the LATEST lookup may land. Without it, a slow
          // response for the previous name attaches the wrong dossier (and a wrong
          // figureContext on a fast send) to whatever the player typed next.
          const epoch = this.runEpoch
          const seq = ++this.groundingSeq
          this.groundingLoading = true
          try {
              const grounded = await $fetch('/api/figure', { params: { name: target }, headers: await this.aiHeaders() }) as GroundedFigure
              if (epoch !== this.runEpoch || seq !== this.groundingSeq) return
              this.figureGrounding = grounded
              this.contactMoment = null
              if (grounded?.resolved && grounded.born) {
                  const latest = grounded.died ? grounded.died.signed : new Date().getFullYear()
                  this.contactWhen = Math.round((grounded.born.signed + latest) / 2)
              } else {
                  this.contactWhen = null
              }
          } catch (error) {
              if (epoch !== this.runEpoch || seq !== this.groundingSeq) return
              console.error('Figure grounding failed:', error)
              this.figureGrounding = null
              this.contactWhen = null
              this.contactMoment = null
          } finally {
              if (epoch === this.runEpoch && seq === this.groundingSeq) this.groundingLoading = false
          }
      },
573 
      /** The current run's id, minted server-side via POST /api/run on first
       *  need. The run is a server fact (a persisted, charged row); the id then
       *  tags every AI call so cost telemetry groups per run, and the gameplay
       *  gate verifies it. Fails CLOSED: if begin-run can't return an id this
       *  REJECTS (no local fallback) — a run we can't back server-side must not
       *  start, or the paywall gate would reject it mid-run anyway. */
      async ensureRunId(): Promise<string> {
          if (this.runId) return this.runId
          // Collapse concurrent first-calls onto ONE begin-run (two overlapping
          // calls would otherwise mint two rows). The epoch guards a resetGame
          // mid-flight — a dead run's id must not become the fresh run's.
          if (!this.runIdInflight) {
              const epoch = this.runEpoch
              this.runIdInflight = (async () => {
                  const res = await $fetch('/api/run', { method: 'POST' }) as { runId?: string }
                  if (!res?.runId) throw new Error('begin-run returned no run id')
                  if (epoch === this.runEpoch) {
                      this.runId = res.runId
                      this.runIdInflight = null
                  }
                  return res.runId
              })().catch((err) => {
                  if (epoch === this.runEpoch) this.runIdInflight = null
                  throw err
              })
          }
          return this.runIdInflight
      },
602 
      /** Headers that tag a server call with the current run (the cost
       *  instrument), minting the run id first if needed. */
      async aiHeaders(base: Record<string, string> = {}): Promise<Record<string, string>> {
          return { ...base, 'x-run-id': await this.ensureRunId() }
      },
608 
      setContactWhen(year: number | null) {
          // Scrubbing the year keeps any pinned month/day — the pin refines
          // whichever year is chosen, it doesn't belong to one.
          this.contactWhen = year
      },
614 
      setContactMoment(moment: ContactMoment | null) {
          this.contactMoment = moment
      },
618 
      /**
       * Studies the active (grounded) figure via the Archivist — an objective-blind
       * brief on who they are AT THE CHOSEN MOMENT, so the player can research in the
       * game instead of a browser tab. The brief is moment-specific, so it's cached
       * against the figure AND the year: move the contact slider and the player can
       * re-study them at the new moment. Graceful on failure (leaves the prior brief).
       * Only resolved figures can be studied — an unresolved name has no record.
       */
      async studyActiveFigure(): Promise<void> {
          const g = this.figureGrounding
          if (!g?.resolved) {
              this.figureStudy = null
              return
          }
          // Cache hit only when both the figure AND the studied year still match.
          if (this.studyFor === g.name && this.studyWhen === this.contactWhen && this.figureStudy) return
635 
          // Capture the moment being studied NOW: the brief describes this figure at
          // this year. If the slider moves mid-flight, recording the live value would
          // mislabel the brief and silently suppress the Re-study button.
          const epoch = this.runEpoch
          const studiedName = g.name
          const studiedWhen = this.contactWhen
          this.studyLoading = true
          this.studyNotice = null
          try {
              const res = await $fetch('/api/research', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: {
                      figureName: studiedName,
                      when: studiedWhen != null ? formatContactYear(studiedWhen) : undefined,
                      description: g.description,
                      extract: g.extract
                  }
              }) as { success?: boolean; study?: FigureStudy; blocked?: boolean; error?: string }
              if (epoch !== this.runEpoch) return
              // If the contact changed mid-flight, the stale-study clear in
              // groundActiveFigure already ran — don't resurrect the old brief.
              if (res?.blocked && this.figureGrounding?.name === studiedName) {
                  this.studyNotice = res.error || 'That study was blocked by content moderation.'
              } else if (res?.success && res.study && this.figureGrounding?.name === studiedName) {
                  this.figureStudy = res.study
                  this.studyFor = studiedName
                  this.studyWhen = studiedWhen
              }
          } catch (error) {
              if (epoch !== this.runEpoch) return
              console.error('Failed to study the figure:', error)
          } finally {
              if (epoch === this.runEpoch) this.studyLoading = false
          }
      },
672 
      /**
       * Asks the Archive about a freeform topic (the "yellow" layer) — concrete
       * domain facts: what it is, what it takes, and when it first became known
       * (the player's anachronism read). Graceful on failure. Topic-scoped, so it
       * persists across figure changes within a run.
       */
      async askArchive(query: string): Promise<void> {
          const q = (query || '').trim()
          if (!q) return
          const epoch = this.runEpoch
          this.lookupLoading = true
          this.archiveNotice = null
          try {
              const res = await $fetch('/api/lookup', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: { query: q }
              }) as { success?: boolean; lookup?: ArchiveLookup; blocked?: boolean; error?: string }
              if (epoch !== this.runEpoch) return
              if (res?.blocked) {
                  // The Archive is the sharpest elicitation vector — a block here is
                  // honest and visible, not a silent empty result.
                  this.archiveNotice = res.error || 'That lookup was blocked by content moderation.'
              } else if (res?.success && res.lookup) {
                  this.archiveResult = res.lookup
              }
          } catch (error) {
              if (epoch !== this.runEpoch) return
              console.error('Archive lookup failed:', error)
          } finally {
              if (epoch === this.runEpoch) this.lookupLoading = false
          }
      },
706 
      /**
       * Loads era-relevant figure suggestions for the current objective (the
       * educational on-ramp). Cached per objective; on any failure it leaves the
       * list empty so the UI falls back to its generic starters.
       */
      async loadSuggestions(): Promise<void> {
          const objective = this.currentObjective
          if (!objective) {
              this.figureSuggestions = []
              this.suggestionsFor = ''
              return
          }
          if (this.suggestionsFor === objective.title && this.figureSuggestions.length) return
720 
          const epoch = this.runEpoch
          const seq = ++this.suggestionsSeq
          this.suggestionsLoading = true
          this.suggestionsNotice = null
          try {
              const res = await $fetch('/api/suggestions', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: {
                      objective: {
                          title: objective.title,
                          description: objective.description,
                          era: objective.era
                      },
                      // Usually empty here (the initial load fires at run start), but a
                      // mid-run remount carries the ledger so even the first paint is
                      // timeline-aware. refreshSuggestions re-sends it after each change.
                      ledger: ledgerForSuggester(this.timelineEvents)
                  }
              }) as { success?: boolean; suggestions?: FigureSuggestion[]; blocked?: boolean; reason?: string }
              if (epoch !== this.runEpoch || seq !== this.suggestionsSeq) return
              // A blocked objective must not masquerade as an empty result — surface it.
              if (res?.blocked) this.suggestionsNotice = res.reason || 'That objective was blocked by content moderation.'
              this.figureSuggestions = res?.suggestions ?? []
              this.suggestionsFor = objective.title
          } catch (error) {
              if (epoch !== this.runEpoch || seq !== this.suggestionsSeq) return
              console.error('Failed to load figure suggestions:', error)
              this.figureSuggestions = []
              // Record that this objective WAS asked, even though it failed — the
              // picker uses suggestionsFor to tell "not yet asked" (skeletons)
              // from "asked and came up empty" (the honest famous-names fallback).
              this.suggestionsFor = objective.title
          } finally {
              if (epoch === this.runEpoch && seq === this.suggestionsSeq) this.suggestionsLoading = false
          }
      },
758 
      /**
       * Re-narrate the figure-suggestion blurbs against the altered timeline (issue
       * #131). The suggester is re-run with the landed ledger so a blurb stops
       * asserting a fate the player has already overturned. Fired non-blocking after
       * a landed change, like refreshChronicle — the turn reveal waits on neither.
       * A failed, blocked, or curated-fallback refresh KEEPS the prior list: a
       * populated panel never blanks, and a model outage never regresses good
       * era-specific picks to the generic fallback.
       *
       * loadSuggestions and refreshSuggestions share `suggestionsSeq` so the newest
       * call of EITHER wins. Whichever holds the latest seq therefore owns settling
       * `suggestionsLoading` + `suggestionsFor` (in the finally), so a refresh fired
       * while the initial load is still in flight can never strand the skeletons.
       */
      async refreshSuggestions(): Promise<void> {
          const objective = this.currentObjective
          if (!objective) return
          const epoch = this.runEpoch
          const seq = ++this.suggestionsSeq
          try {
              const res = await $fetch('/api/suggestions', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: {
                      objective: {
                          title: objective.title,
                          description: objective.description,
                          era: objective.era
                      },
                      ledger: ledgerForSuggester(this.timelineEvents)
                  }
              }) as { success?: boolean; suggestions?: FigureSuggestion[]; fallback?: boolean; blocked?: boolean }
              if (epoch !== this.runEpoch || seq !== this.suggestionsSeq) return
              // Only a genuine, model-built list may overwrite the panel — a curated
              // fallback (model unavailable) or an empty/blocked result keeps the
              // better existing suggestions rather than regressing to generic names.
              if (res?.success && res.suggestions?.length && !res.fallback) {
                  this.figureSuggestions = res.suggestions
              }
              this.suggestionsFor = objective.title
          } catch (error) {
              if (epoch !== this.runEpoch || seq !== this.suggestionsSeq) return
              console.error('Failed to refresh figure suggestions:', error)
              // Keep the prior list — a failed refresh never blanks the panel.
          } finally {
              // This refresh bumped the shared seq; if it's still the latest, it owns
              // the resolution — clear a loading flag an invalidated in-flight load
              // can no longer clear itself (the stuck-skeletons race).
              if (epoch === this.runEpoch && seq === this.suggestionsSeq) this.suggestionsLoading = false
          }
      },
810 
      // ---------- timeline ledger ----------
      addTimelineEvent(
          evt: Omit<TimelineEvent, 'id' | 'timestamp' | 'valence'> & { valence?: Valence; timestamp?: Date }
      ) {
          this.timelineEvents.push({
              id: `evt-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
              figureName: evt.figureName,
              era: evt.era,
              headline: evt.headline,
              detail: evt.detail,
              diceRoll: evt.diceRoll,
              diceOutcome: evt.diceOutcome,
              progressChange: evt.progressChange,
              baseProgressChange: evt.baseProgressChange,
              valence: evt.valence ?? valenceOf(evt.progressChange),
              anachronism: evt.anachronism,
              causalChain: evt.causalChain,
              craft: evt.craft,
              whenSigned: evt.whenSigned,
              staked: evt.staked,
              timestamp: evt.timestamp ?? new Date()
          })
      },
834 
      // ---------- the living chronicle (Layer 3) ----------
      /**
       * Re-narrates the Chronicle from the freshly-bent timeline. Fired
       * non-blocking after a resolved turn (and at game end): the dice/progress
       * reveal never waits on prose. The WHOLE account is rewritten each turn —
       * a later change can re-frame how earlier events read.
       * Graceful: a failed refresh keeps the prior telling, so the panel never
       * blanks; an empty timeline clears it (nothing to chronicle yet).
       */
      async refreshChronicle(): Promise<void> {
          if (!this.timelineEvents.length) {
              this.chronicle = null
              return
          }
          // Sequencing: rewrites overlap (each turn fires one, never awaited), so
          // only the LATEST issued refresh may land — an earlier telling arriving
          // late must not regress the account (or worse, the epilogue). The epoch
          // guard keeps a dead run's telling out of a fresh run entirely.
          const epoch = this.runEpoch
          const seq = ++this.chronicleSeq
          this.chronicleLoading = true
          try {
              const res = await $fetch('/api/chronicle', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: {
                      objective: this.currentObjective,
                      status: this.gameStatus,
                      progress: this.objectiveProgress,
                      timeline: this.timelineEvents.map(e => ({
                          era: e.era,
                          figureName: e.figureName,
                          headline: e.headline,
                          detail: e.detail,
                          progressChange: e.progressChange
                      }))
                  }
              }) as { success?: boolean; chronicle?: ChronicleEntry }
              if (epoch !== this.runEpoch || seq !== this.chronicleSeq) return
              if (res?.success && res.chronicle) this.chronicle = res.chronicle
          } catch (error) {
              if (epoch !== this.runEpoch || seq !== this.chronicleSeq) return
              console.error('Failed to refresh the chronicle:', error)
              // Keep the prior chronicle — a failed refresh never blanks the panel.
          } finally {
              if (epoch === this.runEpoch && seq === this.chronicleSeq) this.chronicleLoading = false
          }
      },
883 
      // ---------- simple setters ----------
      setLoading(loading: boolean) { this.isLoading = loading },
      setError(error: string | null) { this.error = error },
      clearModerationNotice() { this.moderationNotice = null },
      clearArchiveNotice() { this.archiveNotice = null },
889 
      // ---------- rate limiting ----------
      checkRateLimit(): boolean {
          const now = Date.now()
          if (this.lastMessageTime && (now - this.lastMessageTime) < RATE_LIMIT_MS) return false
          return true
      },
896 
      setRateLimit() {
          this.isRateLimited = true
          const remainingTime = this.lastMessageTime
              ? Math.max(0, RATE_LIMIT_MS - (Date.now() - this.lastMessageTime))
              : 0
          setTimeout(() => { this.isRateLimited = false }, remainingTime || RATE_LIMIT_MS)
      },
904 
      // ---------- counter & status ----------
      decrementMessages() {
          if (this.remainingMessages > 0) this.remainingMessages--
      },
909 
      /**
       * Rolls back an unresolved turn: refunds the spent message and drops the
       * dangling user entry, so the counter and history can't drift out of sync.
       * Used for BOTH failure shapes — a thrown request and a graceful HTTP-200
       * `success:false` — an infra hiccup must never burn one of the five
       * dispatches (or, on the last one, convert into an instant unearned defeat).
       */
      refundUnresolvedTurn() {
          if (this.remainingMessages < TOTAL_MESSAGES) this.remainingMessages++
          for (let i = this.messageHistory.length - 1; i >= 0; i--) {
              if (this.messageHistory[i].sender === 'user') {
                  this.messageHistory.splice(i, 1)
                  break
              }
          }
      },
926 
      applyProgress(progressChange: number) {
          this.objectiveProgress = Math.max(0, Math.min(MAX_PROGRESS, this.objectiveProgress + progressChange))
          this.peakProgress = Math.max(this.peakProgress, this.objectiveProgress)
      },
931 
      /**
       * Resolves win/lose AFTER a turn's progress has been applied.
       *
       * Victory the instant the objective hits 100%; defeat only once the
       * final message is spent without reaching it. This fixes the old
       * premature-defeat bug, where status flipped on the last decrement
       * BEFORE that turn's progress had a chance to land.
       */
      resolveGameStatus() {
          if (this.objectiveProgress >= MAX_PROGRESS) {
              this.gameStatus = 'victory'
          } else if (this.remainingMessages <= 0) {
              this.gameStatus = 'defeat'
          }
      },
947 
      // ---------- the turn ----------
      /**
       * Sends a 160-char message to a chosen figure and folds the result back
       * into the world: the figure replies + acts, the dice decide the swing,
       * and the Timeline Engine records how history bent.
       *
       * Returns `true` only when the turn actually RESOLVED (a ledger entry
       * landed). A blocked or failed send returns `false` so the composer can
       * keep the player's crafted words instead of wiping them.
       *
       * `opts.stake` arms the last stand — honored only when `canStake` holds
       * (final message, win out of normal reach; the server doubles the resolved
       * swing, both ways, past the usual cap).
       */
      async sendMessage(text: string, figureName?: string, opts?: { stake?: boolean }): Promise<boolean> {
          const target = (figureName ?? this.activeFigureName ?? '').trim()
          const stake = opts?.stake === true && this.canStake
965 
          if (!this.canSendMessage) return false
          if (!target) {
              this.setError('Choose who in history to send your message to first.')
              return false
          }
          if (!this.checkRateLimit()) {
              this.setRateLimit()
              this.setError('The timeline needs a moment — wait before sending again.')
              return false
          }
          if (!this.canContact) {
              const who = this.figureGrounding?.name || target
              this.setError(
                  this.contactLiveness === 'unresolved'
                      ? (this.figureGrounding?.transient
                          ? `Couldn't reach the record to verify "${target}" — try again in a moment.`
                          : `No historical record found for "${target}" — reach for a real figure (pick a match as you type).`)
                      : this.contactLiveness === 'before-birth'
                          ? `${who} isn't born yet in that year — choose a later moment to reach them.`
                          : this.contactLiveness === 'living'
                              ? (this.figureGrounding?.born
                                  ? `${who} is still living — Everwhen only reaches figures from history.`
                                  : `${who} couldn't be dated — Everwhen can only reach figures it can place in history.`)
                              : `${who} has died by that year — choose an earlier moment to reach them.`
              )
              return false
          }
993 
          this.setError(null)
          this.moderationNotice = null
          this.setActiveFigure(target)
          this.addUserMessage(text, target)
          this.decrementMessages()
          this.setLoading(true)
          this.lastMessageTime = Date.now()
1001 
          // If the run is reset while this request is in flight, every write below
          // would land in a world that no longer exists — the epoch guard drops the
          // response (no fold-in, no refund: the new run's counter is not ours).
          const epoch = this.runEpoch
          const ledgerBefore = this.timelineEvents.length
          // Capture the contact year NOW: the slider can move while the request is
          // in flight, and the ledger must record the year this turn was SENT to.
          const sentWhen = this.contactWhen
          const sentMoment = this.contactMoment
          let resolved = false
          // Decide once whether to stagger the reveal (browser + motion allowed).
          const animate = canAnimateReveal()
1014 
          try {
              const response = await $fetch<SendMessageApiResponse>('/api/send-message', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: {
                      message: text,
                      figureName: target,
                      when: sentWhen != null ? formatContactMoment(sentWhen, sentMoment) : undefined,
                      whenSigned: sentWhen ?? undefined,
                      // The pinned moment travels as validated integers; the server
                      // re-derives the display string rather than trusting ours.
                      whenMonth: sentWhen != null ? sentMoment?.month : undefined,
                      whenDay: sentWhen != null ? sentMoment?.day : undefined,
                      stake,
                      // The pre-turn momentum the server amplifies the swing by, and
                      // returns advanced (the client stays the system of record).
                      momentum: this.momentum,
                      figureContext: this.figureGrounding?.resolved
                          ? {
                              description: this.figureGrounding.description,
                              lifespan: lifespanText(this.figureGrounding)
                          }
                          : undefined,
                      objective: this.currentObjective,
                      timeline: this.timelineEvents.map(e => ({
                          era: e.era,
                          figureName: e.figureName,
                          headline: e.headline,
                          detail: e.detail,
                          progressChange: e.progressChange,
                          whenSigned: e.whenSigned
                      })),
                      conversationHistory: this.conversationWith(target)
                  }
              })
1050 
              if (epoch !== this.runEpoch) return false
1052 
              if (response?.success && response.data?.characterResponse) {
                  const { figure, characterResponse, diceRoll, diceOutcome, timeline } = response.data
1055 
                  if (figure?.name) {
                      this.registerFigure({
                          name: figure.name,
                          era: figure.era || '',
                          descriptor: figure.descriptor || ''
                      })
                  }
1063 
                  // ---- conducted reveal ----
                  // A beat of suspense (the die keeps shaking) before the result
                  // lands, so the resolution has a moment of anticipation.
                  if (animate) {
                      await wait(REVEAL.suspense)
                      if (epoch !== this.runEpoch) return false
                  }
1071 
                  // Beat 1 — the die lands and the figure's reply writes itself in
                  // (its parts stage over ~0.55s via CSS). Flipping loading here
                  // (mid-sequence) is what lands the die now; the finally's flip
                  // becomes a no-op.
                  this.addAIMessageWithData({
                      text: characterResponse.message,
                      sender: 'ai',
                      figureName: target,
                      timestamp: new Date(),
                      diceRoll,
                      diceOutcome,
                      naturalRoll: response.data.naturalRoll ?? diceRoll,
                      rollModifier: response.data.rollModifier ?? 0,
                      craft: response.data.craft,
                      craftReason: response.data.craftReason,
                      continuity: response.data.continuity,
                      characterAction: characterResponse.action,
                      timelineImpact: timeline?.detail,
                      progressChange: timeline?.progressChange,
                      baseProgressChange: timeline?.baseProgressChange,
                      momentumAtSwing: timeline?.momentumAtSwing,
                      anachronism: timeline?.anachronism,
                      causalChain: timeline?.causalChain,
                      staked: response.data.staked
                  })
                  if (animate) this.setLoading(false)
1098 
                  if (timeline) {
                      // Beat 2 — the timeline shift (the % gauge flies its delta),
                      // timed to land with the reply's own "ripple" line.
                      if (animate) {
                          await wait(REVEAL.swing)
                          if (epoch !== this.runEpoch) return false
                      }
                      // Use !== undefined so a genuine neutral (0%) turn still
                      // registers instead of silently vanishing.
                      if (timeline.progressChange !== undefined) {
                          this.applyProgress(timeline.progressChange)
                      }
                      // The arc meter is server-authoritative for the result; advance
                      // it WITH the swing it amplified — and only past the epoch check
                      // above, so a stale turn never moves the meter (issue #62).
                      this.momentum = response.data.momentum ?? this.momentum
1115 
                      // Beat 3 — the change drops onto the Spine ledger.
                      if (animate) {
                          await wait(REVEAL.node)
                          if (epoch !== this.runEpoch) return false
                      }
                      this.addTimelineEvent({
                          figureName: target,
                          era: timeline.era || figure?.era || (this.currentObjective?.era ?? ''),
                          headline: timeline.headline,
                          detail: timeline.detail,
                          diceRoll,
                          diceOutcome,
                          progressChange: timeline.progressChange ?? 0,
                          baseProgressChange: timeline.baseProgressChange,
                          valence: timeline.valence,
                          anachronism: timeline.anachronism,
                          causalChain: timeline.causalChain,
                          craft: response.data.craft,
                          whenSigned: sentWhen ?? undefined,
                          staked: response.data.staked
                      })
                      resolved = true
                  }
              } else {
                  // A graceful failure (HTTP 200, success:false): an AI layer gave
                  // out mid-turn. No ripple landed, so the dispatch is refunded —
                  // exactly like the thrown path below.
                  // Narrow to the failure variant (its data carries `blocked`).
                  const failed = response && !response.success ? response.data : undefined
                  if (failed?.blocked) {
                      // A content-moderation block, not an infra hiccup — show an
                      // honest, distinct banner (not "try again"). The composer
                      // keeps the player's words (sendMessage returns false).
                      this.moderationNotice = failed.moderationReason || 'That dispatch was blocked by content moderation and cannot be sent.'
                  } else {
                      this.setError(failed?.error || 'History did not answer. Try again.')
                  }
                  this.refundUnresolvedTurn()
              }
          } catch (error) {
              if (epoch !== this.runEpoch) return false
              console.error('Error sending message:', error)
              this.setError('The timeline resisted your message. Please try again.')
              this.refundUnresolvedTurn()
          } finally {
              if (epoch === this.runEpoch) {
                  this.setLoading(false)
                  this.resolveGameStatus()
              }
          }
1166 
          // The living chronicle re-narrates the world from the new timeline — but
          // only when this turn actually added a change, and never awaited: the turn
          // reveal must not wait on prose. By here the status is resolved, so the
          // final turn's chronicle carries the victory/defeat framing (the epilogue).
          let refresh: Promise<void> | null = null
          if (resolved && this.timelineEvents.length > ledgerBefore) {
              refresh = this.refreshChronicle()
              void refresh
              // The on-ramp blurbs re-narrate against the altered timeline (issue
              // #131), non-blocking like the chronicle — neither holds the reveal.
              void this.refreshSuggestions()
          }
⋯ 355 lines hidden (lines 1179–1533)1179            // The run just ended: persist it (best-effort) so it survives reload, then
          // re-save once the epilogue's telling lands — the immediate save guards
          // against that refresh failing, the second captures the final Chronicle.
          if (this.gameStatus === 'victory' || this.gameStatus === 'defeat') {
              // This turn's refresh writes the EPILOGUE — the terminal telling that
              // carries the verdict. Mark it pending so the end screen shows "the
              // final account…" instead of the prior turn's stale telling. Cleared
              // when the telling lands OR the refresh fails (refreshChronicle keeps
              // the prior telling on failure) — so the panel reveals or falls back,
              // never hanging on the loading state.
              if (refresh) {
                  this.epiloguePending = true
                  void refresh.finally(() => { if (epoch === this.runEpoch) this.epiloguePending = false })
              }
              void this.saveRunSnapshot()
              if (refresh) void refresh.finally(() => { void this.saveRunSnapshot() })
          }
          return resolved
      },
1198 
      /**
       * Seed a replay (issue #89): start a fresh run on a shared run's captured
       * objective. Resets first (the share page may follow an abandoned run in the
       * same tab) so the run starts clean, THEN records the seed — so the mission
       * briefing opens focused on this objective, and the lineage + credit ride
       * through to the end. No generation: the objective is reused verbatim, and the
       * player still commits (and is charged) by pressing Begin.
       */
      preseedReplay(objective: GameObjective, sourceToken: string, sourceAttribution: string | null): void {
          this.resetGame()
          this.replayState = { objective, sourceToken, sourceAttribution }
      },
1211 
      /** Drop the replay seed — the player chose to start from scratch instead, so this
       *  run is an original (no "remixed from" lineage). */
      clearReplayState(): void {
          this.replayState = null
      },
1217 
      /**
       * Commits a chosen objective and starts the run from a clean slate of
       * progress. Used by the mission-select screen for both curated picks and
       * freshly composed ones.
       */
      async chooseObjective(objective: GameObjective): Promise<boolean> {
          // Commit = the run is charged here. Mint the run id server-side, then
          // spend one run from the device's balance. Fails CLOSED: out of runs →
          // raise the paywall; begin-run or commit failing → surface an error and
          // do NOT start. A run that isn't a charged, server-backed run would be
          // rejected by the gameplay gate anyway, so starting it only strands the
          // player mid-run. The spend cap (not free play) is the outage backstop.
          let runId: string
          try {
              runId = await this.ensureRunId()
          } catch (error) {
              console.error('Could not begin the run:', error)
              this.error = 'Could not start the run. Please try again.'
              return false
          }
          try {
              const res = await $fetch('/api/run-commit', {
                  method: 'POST',
                  headers: { 'Content-Type': 'application/json' },
                  body: { runId }
              }) as { runsRemaining?: number }
              this.outOfRuns = false
              // Keep the header gauge live: the commit returns the post-charge
              // balance (−1 marks a degraded, ungated run — leave the gauge as is).
              if (typeof res?.runsRemaining === 'number' && res.runsRemaining >= 0) {
                  this.runsRemaining = res.runsRemaining
              }
          } catch (error) {
              if (isPaymentRequired(error)) {
                  this.outOfRuns = true
                  this.openBuyModal()
                  return false
              }
              if (isAtCapacity(error)) {
                  this.atCapacity = true
                  return false
              }
              console.error('Could not charge the run:', error)
              this.error = 'Could not start the run. Please try again.'
              return false
          }
          this.currentObjective = objective
          this.objectiveProgress = 0
          this.peakProgress = 0
          this.momentum = 0
          this.error = null
          return true
      },
1271 
      /**
       * Asks the server to compose a fresh objective with the model, WITHOUT
       * committing it — the caller previews it, then commits via chooseObjective.
       * Generation lives server-side because it needs the OpenAI key (the client
       * has no access to it). An optional steer (era + theme, closed enums) biases
       * the composition; the server re-validates it against the enums, so a bad
       * value is harmless. `avoid` is the titles already composed this session, so
       * a reroll lands somewhere new (#95) — the stateless server only knows what
       * the client supplies. Returns null rather than throwing if composing fails,
       * so the UI can quietly fall back to the curated pool.
       */
      async fetchAIObjective(steer: ObjectiveSteer = {}, avoid: string[] = []): Promise<GameObjective | null> {
          try {
              const query: Record<string, string | string[]> = {}
              if (steer.era) query.era = steer.era
              if (steer.theme) query.theme = steer.theme
              if (avoid.length) query.avoid = avoid
              const res = await $fetch('/api/objective', { method: 'GET', query, headers: await this.aiHeaders() }) as {
                  success?: boolean
                  objective?: GameObjective
              }
              return res?.success && res.objective ? res.objective : null
          } catch (error) {
              console.error('Failed to compose a fresh objective:', error)
              return null
          }
      },
1299 
      /**
       * Loads the device's run balance for the header gauge + account popover.
       * Grants the free trial on a brand-new device (server-side). Graceful: on
       * failure it leaves the prior value (the gauge simply doesn't update).
       */
      async loadBalance(): Promise<void> {
          try {
              const res = await $fetch('/api/balance') as { runsRemaining?: number; freeRuns?: number; deviceRef?: string; email?: string | null; isAnonymous?: boolean }
              if (typeof res?.runsRemaining === 'number') this.runsRemaining = res.runsRemaining
              if (typeof res?.freeRuns === 'number') this.freeRuns = res.freeRuns
              if (typeof res?.deviceRef === 'string') this.deviceRef = res.deviceRef
              this.accountEmail = res?.email ?? null
              this.accountAnonymous = res?.isAnonymous === true
          } catch (error) {
              console.error('Failed to load balance:', error)
          }
      },
1317 
      /** Opens the run-packs sales modal, loading the catalog first. */
      async openBuyModal(): Promise<void> {
          this.buyModalOpen = true
          await this.loadPacks()
      },
1323 
      /** Closes the sales modal. */
      closeBuyModal(): void {
          this.buyModalOpen = false
      },
1328 
      /** Records the Stripe-return outcome and refreshes the balance on success
       *  (the webhook credits asynchronously; re-read so the gauge reflects it). */
      async notePurchaseReturn(outcome: 'success' | 'cancel'): Promise<void> {
          this.purchaseNotice = outcome
          this.buyModalOpen = false
          if (outcome === 'success') {
              this.outOfRuns = false
              await this.loadBalance()
          }
      },
1339 
      /** Dismisses the post-purchase notice. */
      clearPurchaseNotice(): void {
          this.purchaseNotice = null
      },
1344 
      /** Loads the run-pack catalog for the paywall. Caches only a NON-empty
       *  result: a transient empty/failed read must not poison the cache and
       *  strand the modal with zero packs for the rest of the session. */
      async loadPacks(): Promise<void> {
          if (this.packs.length) return
          try {
              const res = await $fetch('/api/packs') as { packs?: Pack[] }
              const packs = res?.packs ?? []
              if (packs.length) this.packs = packs
          } catch (error) {
              console.error('Failed to load packs:', error)
          }
      },
1358 
      /** Starts checkout for a pack; returns the Stripe Checkout URL to redirect
       *  to (null on failure). The caller does the redirect. */
      async buyPack(packId: string): Promise<string | null> {
          try {
              const res = await $fetch('/api/checkout', {
                  method: 'POST',
                  headers: { 'Content-Type': 'application/json' },
                  body: { packId }
              }) as { url?: string }
              return res?.url ?? null
          } catch (error) {
              console.error('Failed to start checkout:', error)
              return null
          }
      },
1374 
      getVictoryEfficiency() {
          if (this.gameStatus === 'victory') {
              const messagesSaved = this.remainingMessages
              const messagesUsed = TOTAL_MESSAGES - this.remainingMessages
              const efficiencyPercentage = Math.round((messagesSaved / TOTAL_MESSAGES) * 100)
1380 
              const efficiencyRating = rateEfficiency(messagesSaved)
1382 
              return {
                  messagesSaved,
                  messagesUsed,
                  efficiencyPercentage,
                  efficiencyRating,
                  isEarlyVictory: messagesSaved > 0
              }
          }
          return null
      },
1393 
      /**
       * Persist the finished run's snapshot to the player's account, best-effort.
       * Captures exactly what the end screen shows — objective, verdict, ledger,
       * dispatches, rolls, and the Chronicle epilogue — keyed by the run id, so the
       * run survives reload and feeds the read-only "your runs" view. Fires and
       * forgets like refreshChronicle: a save failure must never disturb the end
       * screen. Only a completed (victory/defeat), server-backed (uuid run id) run
       * is saved; a degraded local id is dropped server-side.
       */
      async saveRunSnapshot(): Promise<void> {
          const epoch = this.runEpoch
          const status = this.gameStatus
          if (status !== 'victory' && status !== 'defeat') return
          const objective = this.currentObjective
          const runId = this.runId
          if (!objective || !runId) return
1410 
          const summary = this.gameSummary
          const events = this.timelineEvents
          // The dispatch keepsake — the player's verbatim messages, paired with
          // whom/when they reached (the same zip the end screen renders).
          const dispatches = this.messageHistory
              .filter((m) => m.sender === 'user')
              .map((m, i) => ({
                  text: m.text,
                  figure: m.figureName || events[i]?.figureName || 'the past',
                  era: events[i]?.era || ''
              }))
          const mark = (m: typeof summary.bestRoll) =>
              m && m.diceRoll != null && m.diceOutcome != null
                  ? { diceRoll: m.diceRoll, diceOutcome: m.diceOutcome }
                  : null
1426 
          const snapshot: RunSnapshot = {
              version: RUN_SNAPSHOT_VERSION,
              runId,
              status,
              objective,
              objectiveProgress: this.objectiveProgress,
              // The high-water mark, so a snapshot-backed view can show "Peaked at X%"
              // (the live store zeroes it on reset, so it's only meaningful here at end).
              peakProgress: this.peakProgress,
              messagesUsed: TOTAL_MESSAGES - this.remainingMessages,
              totalMessages: TOTAL_MESSAGES,
              bestRoll: mark(summary.bestRoll),
              worstRoll: mark(summary.worstRoll),
              efficiency: this.getVictoryEfficiency(),
              dispatches,
              timeline: events.map((e) => ({
                  id: e.id,
                  figureName: e.figureName,
                  era: e.era,
                  headline: e.headline,
                  detail: e.detail,
                  diceRoll: e.diceRoll,
                  diceOutcome: e.diceOutcome,
                  progressChange: e.progressChange,
                  baseProgressChange: e.baseProgressChange,
                  valence: e.valence,
                  craft: e.craft,
                  anachronism: e.anachronism,
                  staked: e.staked
              })),
              chronicle: this.chronicle
          }
1459 
          // A replay (issue #89) rides its source's share token alongside the snapshot
          // (a sibling field, not part of the immutable blob); the server resolves it to
          // the parent run id and stamps the lineage pointer. replayState set ⟺ this run
          // committed the seeded objective (the briefing clears it on any other choice).
          const body = this.replayState
              ? { ...snapshot, remixedFromToken: this.replayState.sourceToken }
              : snapshot
1467 
          try {
              const res = (await $fetch('/api/run-save', {
                  method: 'POST',
                  headers: { 'Content-Type': 'application/json' },
                  body
              })) as { saved?: boolean }
              // Mark saved (for the share affordance) only if this run is still current
              // and the server actually persisted it (a degraded run returns saved:false).
              if (epoch === this.runEpoch && res?.saved) this.runSnapshotSaved = true
          } catch (error) {
              // Saving the run is a nicety; a failure must not break the end screen.
              if (epoch === this.runEpoch) console.error('Could not save the run:', error)
          }
      },
1482 
      resetGame() {
          // Tear the epoch first: anything still in flight belongs to the old run
          // and must find no purchase here. (The seq counters deliberately survive.)
          this.runEpoch++
          this.remainingMessages = TOTAL_MESSAGES
          this.messageHistory = []
          this.gameStatus = 'playing'
          this.isLoading = false
          this.error = null
          this.lastMessageTime = null
          this.isRateLimited = false
          // A new run gets a fresh id on its next server call; abandon any
          // in-flight mint so a dead run's id can't land in the new run.
          this.runId = null
          this.runIdInflight = null
          this.runSnapshotSaved = false
          // The paywall / capacity notices re-check on the next commit.
          this.outOfRuns = false
          this.atCapacity = false
          this.currentObjective = null
          // A fresh run carries no replay lineage (preseedReplay re-sets it after).
          this.replayState = null
          this.objectiveProgress = 0
          this.peakProgress = 0
          this.momentum = 0
          this.timelineEvents = []
          this.figures = []
          this.activeFigureName = ''
          this.figureGrounding = null
          this.groundingLoading = false
          this.contactWhen = null
          this.contactMoment = null
          this.figureSuggestions = []
          this.suggestionsLoading = false
          this.suggestionsFor = ''
          this.chronicle = null
          this.chronicleLoading = false
          this.epiloguePending = false
          this.figureStudy = null
          this.studyLoading = false
          this.studyFor = ''
          this.studyWhen = null
          this.archiveResult = null
          this.lookupLoading = false
          this.moderationNotice = null
          this.archiveNotice = null
          this.studyNotice = null
          this.suggestionsNotice = null
      }
  }
1533})

The 'history rewritten' flourish

The animation is a self-contained component, RewriteText. Its trigger is purely the text prop changing — so callers need no diffing. A chip kept across a refresh (same :key) sees its blurb change and animates; a brand-new chip mounts fresh and just appears. The watch never fires on the initial value, and it guards on a prior value existing and reduced-motion.

Change-only trigger: stash the old text as a ghost, arm a self-clearing timer.

components/RewriteText.vue · 132 lines

components/RewriteText.vue132 lines · Vue

⋯ 43 lines hidden (lines 1–43)1<template>
2  <span class="rw" :class="{ 'rw-active': animating }" :style="{ '--rw-dur': REWRITE_MS + 'ms' }">
3    <!-- The fallthrough class (e.g. the blurb's `ew-faint text-[11px]`) lands on the
4         root above, so both layers inherit one type style and the ghost overlay aligns
5         to the live box. Keep the root a SINGLE node (no leading sibling comment) so
6         attribute fallthrough and class reads stay unambiguous.
7         The erased history: the prior wording, struck through and bled away beneath. -->
8    <span v-if="animating" data-testid="rewrite-ghost" class="rw-ghost" aria-hidden="true">{{ ghost }}</span>
9    <!-- The rewritten history: the new wording, written in over the old. -->
10    <span class="rw-live" :class="{ 'rw-in': animating }">{{ text }}</span>
11  </span>
12</template>
13 
14<script setup lang="ts">
15/**
16 * RewriteText — text that, when it CHANGES, plays a "history rewritten" transition:
17 * the old wording is struck through and bleeds away while the new wording is written
18 * in over it, left to right (a palimpsest — old ink showing under new). First paint
19 * and reduced-motion just show the text, no flourish.
20 *
21 * Built for the figure-suggestion blurbs, which re-narrate against the altered
22 * timeline after a landed change (issue #131) — but text-agnostic and reusable. The
23 * trigger is purely the `text` prop changing, so callers need no diffing: a chip kept
24 * across a refresh (same `:key`) sees its blurb change and animates; a brand-new chip
25 * mounts fresh and just appears.
26 */
27import { ref, watch, onUnmounted } from 'vue'
28import { usePrefersReducedMotion } from '~/composables/usePrefersReducedMotion'
29 
30const props = defineProps<{ text: string }>()
31const reduced = usePrefersReducedMotion()
32 
33// The full span of the flourish. CSS reads it via --rw-dur so the keyframes and this
34// JS cleanup can never drift apart. ~900ms: expressive, a beat longer than the
35// chronicle cross-fade, fitting "history being rewritten".
36const REWRITE_MS = 900
37 
38const ghost = ref('')
39const animating = ref(false)
40let timer: ReturnType<typeof setTimeout> | null = null
41 
42// Only a real CHANGE animates: watch never fires on the initial value, and we guard
43// on a prior value existing (a blurb appearing for the first time just shows).
44// Reduced-motion swaps instantly.
45watch(() => props.text, (next, prev) => {
46    if (reduced.value || !prev || next === prev) return
47    ghost.value = prev
48    animating.value = true
49    if (timer) clearTimeout(timer)
50    timer = setTimeout(() => {
51        animating.value = false
52        ghost.value = ''
53    }, REWRITE_MS)
54})
55 
⋯ 77 lines hidden (lines 56–132)56onUnmounted(() => { if (timer) clearTimeout(timer) })
57</script>
58 
59<style scoped>
60.rw {
61    /* Establish the containing block for the absolute ghost + sweep, without forcing
62       a display: the caller's class governs that (the blurb passes `block`). */
63    position: relative;
64}
65 
66/* The rewritten wording rides above the fading ghost, so the new ink visibly
67   replaces the old rather than the other way round. */
68.rw-live {
69    position: relative;
70    z-index: 1;
71}
72.rw-in {
73    animation: rw-write var(--rw-dur) var(--ew-ease) both;
74}
75/* Written in left to right; the ink starts "wet" (accent) and dries to rest. */
76@keyframes rw-write {
77    0%   { clip-path: inset(0 100% 0 0); color: var(--ew-accent); }
78    30%  { color: var(--ew-accent); }
79    100% { clip-path: inset(0 0 0 0); color: inherit; }
80}
81 
82/* The old wording, struck through (every line, via text-decoration) then bled away
83   beneath the new line — a manuscript correction: the struck passage running off the
84   page as the new ink takes its place. */
85.rw-ghost {
86    position: absolute;
87    inset: 0;
88    z-index: 0;
89    pointer-events: none;
90    color: inherit;
91    text-decoration: line-through;
92    text-decoration-color: var(--ew-accent);
93    animation: rw-erase var(--rw-dur) var(--ew-ease) forwards;
94}
95@keyframes rw-erase {
96    0%   { opacity: 1; filter: blur(0); transform: translateY(0); }
97    40%  { opacity: 1; filter: blur(0); }
98    100% { opacity: 0; filter: blur(2px); transform: translateY(2px); }
99}
100 
101/* A temporal sheen sweeping across as the line is rewritten — a wash of the one
102   accent, drawing the eye to the entry that just changed. */
103.rw-active::before {
104    content: '';
105    position: absolute;
106    inset: -1px -3px;
107    z-index: 2;
108    pointer-events: none;
109    background: linear-gradient(90deg, transparent 0%, color-mix(in srgb, var(--ew-accent) 26%, transparent) 50%, transparent 100%);
110    background-size: 55% 100%;
111    background-repeat: no-repeat;
112    animation: rw-sweep var(--rw-dur) var(--ew-ease) forwards;
113}
114@keyframes rw-sweep {
115    0%   { background-position: -60% 0; opacity: 0; }
116    20%  { opacity: 1; }
117    80%  { opacity: 1; }
118    100% { background-position: 170% 0; opacity: 0; }
119}
120 
121/* The JS guard already skips the flourish under reduced motion (these layers never
122   render), so this is the CSS-level backstop the project favors everywhere: it
123   neutralizes the keyframes should a render ever apply an animating class while the OS
124   preference is set — e.g. the reactive flag briefly lagging a mid-session OS toggle. */
125@media (prefers-reduced-motion: reduce) {
126    .rw-in,
127    .rw-ghost,
128    .rw-active::before {
129        animation: none;
130    }
131}
132</style>

The visual is a palimpsest — old ink showing under new. The old wording is struck through (every line, via text-decoration) and bled away beneath, while the new wording writes in left-to-right with the ink starting "wet" (the one accent colour) and drying to rest.

The new line writes in (clip-path); the old line strikes through and fades.

components/RewriteText.vue · 132 lines

components/RewriteText.vue132 lines · Vue

⋯ 65 lines hidden (lines 1–65)1<template>
2  <span class="rw" :class="{ 'rw-active': animating }" :style="{ '--rw-dur': REWRITE_MS + 'ms' }">
3    <!-- The fallthrough class (e.g. the blurb's `ew-faint text-[11px]`) lands on the
4         root above, so both layers inherit one type style and the ghost overlay aligns
5         to the live box. Keep the root a SINGLE node (no leading sibling comment) so
6         attribute fallthrough and class reads stay unambiguous.
7         The erased history: the prior wording, struck through and bled away beneath. -->
8    <span v-if="animating" data-testid="rewrite-ghost" class="rw-ghost" aria-hidden="true">{{ ghost }}</span>
9    <!-- The rewritten history: the new wording, written in over the old. -->
10    <span class="rw-live" :class="{ 'rw-in': animating }">{{ text }}</span>
11  </span>
12</template>
13 
14<script setup lang="ts">
15/**
16 * RewriteText — text that, when it CHANGES, plays a "history rewritten" transition:
17 * the old wording is struck through and bleeds away while the new wording is written
18 * in over it, left to right (a palimpsest — old ink showing under new). First paint
19 * and reduced-motion just show the text, no flourish.
20 *
21 * Built for the figure-suggestion blurbs, which re-narrate against the altered
22 * timeline after a landed change (issue #131) — but text-agnostic and reusable. The
23 * trigger is purely the `text` prop changing, so callers need no diffing: a chip kept
24 * across a refresh (same `:key`) sees its blurb change and animates; a brand-new chip
25 * mounts fresh and just appears.
26 */
27import { ref, watch, onUnmounted } from 'vue'
28import { usePrefersReducedMotion } from '~/composables/usePrefersReducedMotion'
29 
30const props = defineProps<{ text: string }>()
31const reduced = usePrefersReducedMotion()
32 
33// The full span of the flourish. CSS reads it via --rw-dur so the keyframes and this
34// JS cleanup can never drift apart. ~900ms: expressive, a beat longer than the
35// chronicle cross-fade, fitting "history being rewritten".
36const REWRITE_MS = 900
37 
38const ghost = ref('')
39const animating = ref(false)
40let timer: ReturnType<typeof setTimeout> | null = null
41 
42// Only a real CHANGE animates: watch never fires on the initial value, and we guard
43// on a prior value existing (a blurb appearing for the first time just shows).
44// Reduced-motion swaps instantly.
45watch(() => props.text, (next, prev) => {
46    if (reduced.value || !prev || next === prev) return
47    ghost.value = prev
48    animating.value = true
49    if (timer) clearTimeout(timer)
50    timer = setTimeout(() => {
51        animating.value = false
52        ghost.value = ''
53    }, REWRITE_MS)
54})
55 
56onUnmounted(() => { if (timer) clearTimeout(timer) })
57</script>
58 
59<style scoped>
60.rw {
61    /* Establish the containing block for the absolute ghost + sweep, without forcing
62       a display: the caller's class governs that (the blurb passes `block`). */
63    position: relative;
64}
65 
66/* The rewritten wording rides above the fading ghost, so the new ink visibly
67   replaces the old rather than the other way round. */
68.rw-live {
69    position: relative;
70    z-index: 1;
71}
72.rw-in {
73    animation: rw-write var(--rw-dur) var(--ew-ease) both;
74}
75/* Written in left to right; the ink starts "wet" (accent) and dries to rest. */
76@keyframes rw-write {
77    0%   { clip-path: inset(0 100% 0 0); color: var(--ew-accent); }
78    30%  { color: var(--ew-accent); }
79    100% { clip-path: inset(0 0 0 0); color: inherit; }
80}
81 
82/* The old wording, struck through (every line, via text-decoration) then bled away
83   beneath the new line — a manuscript correction: the struck passage running off the
84   page as the new ink takes its place. */
85.rw-ghost {
86    position: absolute;
87    inset: 0;
88    z-index: 0;
89    pointer-events: none;
90    color: inherit;
91    text-decoration: line-through;
92    text-decoration-color: var(--ew-accent);
93    animation: rw-erase var(--rw-dur) var(--ew-ease) forwards;
94}
95@keyframes rw-erase {
96    0%   { opacity: 1; filter: blur(0); transform: translateY(0); }
97    40%  { opacity: 1; filter: blur(0); }
98    100% { opacity: 0; filter: blur(2px); transform: translateY(2px); }
99}
⋯ 33 lines hidden (lines 100–132)100 
101/* A temporal sheen sweeping across as the line is rewritten — a wash of the one
102   accent, drawing the eye to the entry that just changed. */
103.rw-active::before {
104    content: '';
105    position: absolute;
106    inset: -1px -3px;
107    z-index: 2;
108    pointer-events: none;
109    background: linear-gradient(90deg, transparent 0%, color-mix(in srgb, var(--ew-accent) 26%, transparent) 50%, transparent 100%);
110    background-size: 55% 100%;
111    background-repeat: no-repeat;
112    animation: rw-sweep var(--rw-dur) var(--ew-ease) forwards;
113}
114@keyframes rw-sweep {
115    0%   { background-position: -60% 0; opacity: 0; }
116    20%  { opacity: 1; }
117    80%  { opacity: 1; }
118    100% { background-position: 170% 0; opacity: 0; }
119}
120 
121/* The JS guard already skips the flourish under reduced motion (these layers never
122   render), so this is the CSS-level backstop the project favors everywhere: it
123   neutralizes the keyframes should a render ever apply an animating class while the OS
124   preference is set — e.g. the reactive flag briefly lagging a mid-session OS toggle. */
125@media (prefers-reduced-motion: reduce) {
126    .rw-in,
127    .rw-ghost,
128    .rw-active::before {
129        animation: none;
130    }
131}
132</style>

Wiring it into the picker

One line changes in the picker: the blurb's <span> becomes a <RewriteText> carrying the same classes. The chip is keyed by name, so the same DOM node persists across a refresh and the component sees its text prop change — which is what makes only the blurbs that actually changed animate, while unchanged ones sit still.

The reason line, now a RewriteText; data-testid + classes fall through to its root.

components/FigurePicker.vue · 559 lines

components/FigurePicker.vue559 lines · Vue

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