Don't flash the prior turn's Chronicle before the epilogue

What changed, and why

The Chronicle is the game's prose telling of the altered timeline, rewritten after every turn. The final telling — the one that carries the win/loss framing — is the run's epilogue, shown on the end screen.

The bug: that refresh is fired non-blocking (so mid-game the dice reveal never waits on prose), but the end screen renders the instant the run ends. At that moment the epilogue is still being written, so chronicle still holds the previous turn's telling. The loading placeholder was gated on !chronicle && chronicleLoading, so with a stale telling present it never showed. The end screen presented the prior-turn article as the epilogue, then snapped to the real one when it landed — a misleading double-take on the run's payoff moment.

The fix is one new store flag, epiloguePending, that means specifically the epilogue is being written. The end screen shows the "final account…" wait while it's set, then cross-fades the epilogue in. Three files of logic, two of tests; no change to how the Chronicle is generated or to mid-game behavior.

epiloguePending: tracking the terminal telling

A new piece of store state. It's deliberately distinct from the existing chronicleLoading, which is true during any refresh (every turn fires one). epiloguePending is true only while the terminal telling is in flight.

The flag, beside the chronicle state it qualifies.

stores/game.ts · 1397 lines

stores/game.ts1397 lines · TypeScript

⋯ 283 lines hidden (lines 1–283)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/** Human lifespan line for a grounded figure, e.g. "69 BC – 30 BC" or "1942 – present". */
190function 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
194}
195 
196/** 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. */
198function 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
201}
202 
203/** True when a $fetch error is a 503 / at-capacity — the spend cap paused new
*  runs (distinct from the per-device 402 paywall). */
205function 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
208}
209 
210export type ContactLiveness = 'ok' | 'before-birth' | 'after-death' | 'living' | 'unresolved' | 'unknown'
211 
212/**
* Game Store — core state for a session of freeform timeline editing.
*/
215export 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,
      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,
      // 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,
      objectiveProgress: 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,
⋯ 1104 lines hidden (lines 294–1397)294        // 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
  }),
313 
  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
      },
325 
      /**
       * 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'
          )
      },
336 
      /** Total progress, net of setbacks, the player has clawed back. */
      gameSummary(): GameSummary {
          return generateGameSummary(this)
      },
341 
      /**
       * 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'
      },
363 
      /** Can the chosen contact + when actually be reached? */
      canContact(): boolean {
          return this.contactLiveness === 'ok' || this.contactLiveness === 'unknown'
      },
368 
      /**
       * 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
      },
380 
      /**
       * 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
      },
396 
      /**
       * 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)
      }
  },
412 
  actions: {
      // ---------- message helpers ----------
      addUserMessage(text: string, figureName?: string) {
          if (this.gameStatus !== 'playing') return
          this.messageHistory.push({
              text,
              sender: 'user',
              timestamp: new Date(),
              figureName
          })
      },
424 
      addAIMessage(text: string, figureName?: string) {
          this.messageHistory.push({
              text,
              sender: 'ai',
              timestamp: new Date(),
              figureName
          })
      },
433 
      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
          })
      },
457 
      // ---------- 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 })
          }
      },
468 
      setActiveFigure(name: string) {
          this.activeFigureName = name
      },
472 
      /**
       * 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
      },
490 
      /**
       * 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
          }
      },
538 
      /** 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
      },
567 
      /** 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() }
      },
573 
      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
      },
579 
      setContactMoment(moment: ContactMoment | null) {
          this.contactMoment = moment
      },
583 
      /**
       * 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
600 
          // 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
          }
      },
637 
      /**
       * 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
          }
      },
671 
      /**
       * 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
685 
          const epoch = this.runEpoch
          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
                      }
                  }
              }) as { success?: boolean; suggestions?: FigureSuggestion[]; blocked?: boolean; reason?: string }
              if (epoch !== this.runEpoch) 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) 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) this.suggestionsLoading = false
          }
      },
718 
      // ---------- 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()
          })
      },
742 
      // ---------- 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. True to the game's name, 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
          }
      },
791 
      // ---------- simple setters ----------
      setLoading(loading: boolean) { this.isLoading = loading },
      setError(error: string | null) { this.error = error },
      clearModerationNotice() { this.moderationNotice = null },
      clearArchiveNotice() { this.archiveNotice = null },
797 
      // ---------- rate limiting ----------
      checkRateLimit(): boolean {
          const now = Date.now()
          if (this.lastMessageTime && (now - this.lastMessageTime) < RATE_LIMIT_MS) return false
          return true
      },
804 
      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)
      },
812 
      // ---------- counter & status ----------
      decrementMessages() {
          if (this.remainingMessages > 0) this.remainingMessages--
      },
817 
      /**
       * 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
              }
          }
      },
834 
      applyProgress(progressChange: number) {
          this.objectiveProgress = Math.max(0, Math.min(MAX_PROGRESS, this.objectiveProgress + progressChange))
      },
838 
      /**
       * 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'
          }
      },
854 
      // ---------- 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
872 
          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 — Revisionist only reaches figures from history.`
                                  : `${who} couldn't be dated — Revisionist can only reach figures it can place in history.`)
                              : `${who} has died by that year — choose an earlier moment to reach them.`
              )
              return false
          }
900 
          this.setError(null)
          this.moderationNotice = null
          this.setActiveFigure(target)
          this.addUserMessage(text, target)
          this.decrementMessages()
          this.setLoading(true)
          this.lastMessageTime = Date.now()
908 
          // 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()
921 
          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)
                  }
              })
957 
              if (epoch !== this.runEpoch) return false
959 
              if (response?.success && response.data?.characterResponse) {
                  const { figure, characterResponse, diceRoll, diceOutcome, timeline } = response.data
962 
                  if (figure?.name) {
                      this.registerFigure({
                          name: figure.name,
                          era: figure.era || '',
                          descriptor: figure.descriptor || ''
                      })
                  }
970 
                  // ---- 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
                  }
978 
                  // 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)
1005 
                  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
1022 
                      // 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()
              }
          }
1073 
          // 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 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
      },
1102 
      /**
       * 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.momentum = 0
          this.error = null
          return true
      },
1155 
      /**
       * 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
          }
      },
1183 
      /**
       * 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)
          }
      },
1201 
      /** Opens the run-packs sales modal, loading the catalog first. */
      async openBuyModal(): Promise<void> {
          this.buyModalOpen = true
          await this.loadPacks()
      },
1207 
      /** Closes the sales modal. */
      closeBuyModal(): void {
          this.buyModalOpen = false
      },
1212 
      /** 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()
          }
      },
1223 
      /** Dismisses the post-purchase notice. */
      clearPurchaseNotice(): void {
          this.purchaseNotice = null
      },
1228 
      /** 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)
          }
      },
1242 
      /** 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
          }
      },
1258 
      getVictoryEfficiency() {
          if (this.gameStatus === 'victory') {
              const messagesSaved = this.remainingMessages
              const messagesUsed = TOTAL_MESSAGES - this.remainingMessages
              const efficiencyPercentage = Math.round((messagesSaved / TOTAL_MESSAGES) * 100)
1264 
              const efficiencyRating = rateEfficiency(messagesSaved)
1266 
              return {
                  messagesSaved,
                  messagesUsed,
                  efficiencyPercentage,
                  efficiencyRating,
                  isEarlyVictory: messagesSaved > 0
              }
          }
          return null
      },
1277 
      /**
       * 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
1294 
          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
1310 
          const snapshot: RunSnapshot = {
              version: RUN_SNAPSHOT_VERSION,
              runId,
              status,
              objective,
              objectiveProgress: this.objectiveProgress,
              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,
                  valence: e.valence,
                  craft: e.craft,
                  anachronism: e.anachronism
              })),
              chronicle: this.chronicle
          }
1338 
          try {
              await $fetch('/api/run-save', {
                  method: 'POST',
                  headers: { 'Content-Type': 'application/json' },
                  body: snapshot
              })
          } 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)
          }
      },
1350 
      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
          // The paywall / capacity notices re-check on the next commit.
          this.outOfRuns = false
          this.atCapacity = false
          this.currentObjective = null
          this.objectiveProgress = 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
      }
  }
1397})

It's set where the run actually ends. After a resolved turn, sendMessage fires the (non-blocking) refresh, then — only on a terminal status — marks the epilogue pending and arranges to clear it when that refresh settles.

The terminal turn: fire the refresh, mark it pending, clear it when it settles.

stores/game.ts · 1397 lines

stores/game.ts1397 lines · TypeScript

⋯ 1077 lines hidden (lines 1–1077)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/** Human lifespan line for a grounded figure, e.g. "69 BC – 30 BC" or "1942 – present". */
190function 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
194}
195 
196/** 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. */
198function 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
201}
202 
203/** True when a $fetch error is a 503 / at-capacity — the spend cap paused new
*  runs (distinct from the per-device 402 paywall). */
205function 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
208}
209 
210export type ContactLiveness = 'ok' | 'before-birth' | 'after-death' | 'living' | 'unresolved' | 'unknown'
211 
212/**
* Game Store — core state for a session of freeform timeline editing.
*/
215export 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,
      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,
      // 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,
      objectiveProgress: 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
  }),
313 
  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
      },
325 
      /**
       * 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'
          )
      },
336 
      /** Total progress, net of setbacks, the player has clawed back. */
      gameSummary(): GameSummary {
          return generateGameSummary(this)
      },
341 
      /**
       * 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'
      },
363 
      /** Can the chosen contact + when actually be reached? */
      canContact(): boolean {
          return this.contactLiveness === 'ok' || this.contactLiveness === 'unknown'
      },
368 
      /**
       * 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
      },
380 
      /**
       * 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
      },
396 
      /**
       * 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)
      }
  },
412 
  actions: {
      // ---------- message helpers ----------
      addUserMessage(text: string, figureName?: string) {
          if (this.gameStatus !== 'playing') return
          this.messageHistory.push({
              text,
              sender: 'user',
              timestamp: new Date(),
              figureName
          })
      },
424 
      addAIMessage(text: string, figureName?: string) {
          this.messageHistory.push({
              text,
              sender: 'ai',
              timestamp: new Date(),
              figureName
          })
      },
433 
      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
          })
      },
457 
      // ---------- 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 })
          }
      },
468 
      setActiveFigure(name: string) {
          this.activeFigureName = name
      },
472 
      /**
       * 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
      },
490 
      /**
       * 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
          }
      },
538 
      /** 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
      },
567 
      /** 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() }
      },
573 
      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
      },
579 
      setContactMoment(moment: ContactMoment | null) {
          this.contactMoment = moment
      },
583 
      /**
       * 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
600 
          // 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
          }
      },
637 
      /**
       * 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
          }
      },
671 
      /**
       * 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
685 
          const epoch = this.runEpoch
          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
                      }
                  }
              }) as { success?: boolean; suggestions?: FigureSuggestion[]; blocked?: boolean; reason?: string }
              if (epoch !== this.runEpoch) 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) 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) this.suggestionsLoading = false
          }
      },
718 
      // ---------- 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()
          })
      },
742 
      // ---------- 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. True to the game's name, 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
          }
      },
791 
      // ---------- simple setters ----------
      setLoading(loading: boolean) { this.isLoading = loading },
      setError(error: string | null) { this.error = error },
      clearModerationNotice() { this.moderationNotice = null },
      clearArchiveNotice() { this.archiveNotice = null },
797 
      // ---------- rate limiting ----------
      checkRateLimit(): boolean {
          const now = Date.now()
          if (this.lastMessageTime && (now - this.lastMessageTime) < RATE_LIMIT_MS) return false
          return true
      },
804 
      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)
      },
812 
      // ---------- counter & status ----------
      decrementMessages() {
          if (this.remainingMessages > 0) this.remainingMessages--
      },
817 
      /**
       * 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
              }
          }
      },
834 
      applyProgress(progressChange: number) {
          this.objectiveProgress = Math.max(0, Math.min(MAX_PROGRESS, this.objectiveProgress + progressChange))
      },
838 
      /**
       * 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'
          }
      },
854 
      // ---------- 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
872 
          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 — Revisionist only reaches figures from history.`
                                  : `${who} couldn't be dated — Revisionist can only reach figures it can place in history.`)
                              : `${who} has died by that year — choose an earlier moment to reach them.`
              )
              return false
          }
900 
          this.setError(null)
          this.moderationNotice = null
          this.setActiveFigure(target)
          this.addUserMessage(text, target)
          this.decrementMessages()
          this.setLoading(true)
          this.lastMessageTime = Date.now()
908 
          // 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()
921 
          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)
                  }
              })
957 
              if (epoch !== this.runEpoch) return false
959 
              if (response?.success && response.data?.characterResponse) {
                  const { figure, characterResponse, diceRoll, diceOutcome, timeline } = response.data
962 
                  if (figure?.name) {
                      this.registerFigure({
                          name: figure.name,
                          era: figure.era || '',
                          descriptor: figure.descriptor || ''
                      })
                  }
970 
                  // ---- 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
                  }
978 
                  // 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)
1005 
                  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
1022 
                      // 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()
              }
          }
1073 
          // 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 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() })
⋯ 299 lines hidden (lines 1099–1397)1099            }
          return resolved
      },
1102 
      /**
       * 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.momentum = 0
          this.error = null
          return true
      },
1155 
      /**
       * 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
          }
      },
1183 
      /**
       * 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)
          }
      },
1201 
      /** Opens the run-packs sales modal, loading the catalog first. */
      async openBuyModal(): Promise<void> {
          this.buyModalOpen = true
          await this.loadPacks()
      },
1207 
      /** Closes the sales modal. */
      closeBuyModal(): void {
          this.buyModalOpen = false
      },
1212 
      /** 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()
          }
      },
1223 
      /** Dismisses the post-purchase notice. */
      clearPurchaseNotice(): void {
          this.purchaseNotice = null
      },
1228 
      /** 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)
          }
      },
1242 
      /** 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
          }
      },
1258 
      getVictoryEfficiency() {
          if (this.gameStatus === 'victory') {
              const messagesSaved = this.remainingMessages
              const messagesUsed = TOTAL_MESSAGES - this.remainingMessages
              const efficiencyPercentage = Math.round((messagesSaved / TOTAL_MESSAGES) * 100)
1264 
              const efficiencyRating = rateEfficiency(messagesSaved)
1266 
              return {
                  messagesSaved,
                  messagesUsed,
                  efficiencyPercentage,
                  efficiencyRating,
                  isEarlyVictory: messagesSaved > 0
              }
          }
          return null
      },
1277 
      /**
       * 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
1294 
          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
1310 
          const snapshot: RunSnapshot = {
              version: RUN_SNAPSHOT_VERSION,
              runId,
              status,
              objective,
              objectiveProgress: this.objectiveProgress,
              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,
                  valence: e.valence,
                  craft: e.craft,
                  anachronism: e.anachronism
              })),
              chronicle: this.chronicle
          }
1338 
          try {
              await $fetch('/api/run-save', {
                  method: 'POST',
                  headers: { 'Content-Type': 'application/json' },
                  body: snapshot
              })
          } 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)
          }
      },
1350 
      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
          // The paywall / capacity notices re-check on the next commit.
          this.outOfRuns = false
          this.atCapacity = false
          this.currentObjective = null
          this.objectiveProgress = 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
      }
  }
1397})

The never-blanks guarantee still holds

A failed final refresh must fall back to the prior telling, never hang on the loading state. That guarantee is unchanged: refreshChronicle catches its own errors and keeps whatever telling was already there, returning a promise that resolves (never rejects).

On failure: keep the prior chronicle, clear loading — the panel never blanks.

stores/game.ts · 1397 lines

stores/game.ts1397 lines · TypeScript

⋯ 774 lines hidden (lines 1–774)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/** Human lifespan line for a grounded figure, e.g. "69 BC – 30 BC" or "1942 – present". */
190function 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
194}
195 
196/** 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. */
198function 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
201}
202 
203/** True when a $fetch error is a 503 / at-capacity — the spend cap paused new
*  runs (distinct from the per-device 402 paywall). */
205function 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
208}
209 
210export type ContactLiveness = 'ok' | 'before-birth' | 'after-death' | 'living' | 'unresolved' | 'unknown'
211 
212/**
* Game Store — core state for a session of freeform timeline editing.
*/
215export 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,
      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,
      // 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,
      objectiveProgress: 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
  }),
313 
  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
      },
325 
      /**
       * 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'
          )
      },
336 
      /** Total progress, net of setbacks, the player has clawed back. */
      gameSummary(): GameSummary {
          return generateGameSummary(this)
      },
341 
      /**
       * 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'
      },
363 
      /** Can the chosen contact + when actually be reached? */
      canContact(): boolean {
          return this.contactLiveness === 'ok' || this.contactLiveness === 'unknown'
      },
368 
      /**
       * 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
      },
380 
      /**
       * 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
      },
396 
      /**
       * 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)
      }
  },
412 
  actions: {
      // ---------- message helpers ----------
      addUserMessage(text: string, figureName?: string) {
          if (this.gameStatus !== 'playing') return
          this.messageHistory.push({
              text,
              sender: 'user',
              timestamp: new Date(),
              figureName
          })
      },
424 
      addAIMessage(text: string, figureName?: string) {
          this.messageHistory.push({
              text,
              sender: 'ai',
              timestamp: new Date(),
              figureName
          })
      },
433 
      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
          })
      },
457 
      // ---------- 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 })
          }
      },
468 
      setActiveFigure(name: string) {
          this.activeFigureName = name
      },
472 
      /**
       * 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
      },
490 
      /**
       * 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
          }
      },
538 
      /** 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
      },
567 
      /** 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() }
      },
573 
      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
      },
579 
      setContactMoment(moment: ContactMoment | null) {
          this.contactMoment = moment
      },
583 
      /**
       * 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
600 
          // 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
          }
      },
637 
      /**
       * 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
          }
      },
671 
      /**
       * 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
685 
          const epoch = this.runEpoch
          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
                      }
                  }
              }) as { success?: boolean; suggestions?: FigureSuggestion[]; blocked?: boolean; reason?: string }
              if (epoch !== this.runEpoch) 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) 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) this.suggestionsLoading = false
          }
      },
718 
      // ---------- 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()
          })
      },
742 
      // ---------- 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. True to the game's name, 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
          }
⋯ 608 lines hidden (lines 790–1397)790        },
791 
      // ---------- simple setters ----------
      setLoading(loading: boolean) { this.isLoading = loading },
      setError(error: string | null) { this.error = error },
      clearModerationNotice() { this.moderationNotice = null },
      clearArchiveNotice() { this.archiveNotice = null },
797 
      // ---------- rate limiting ----------
      checkRateLimit(): boolean {
          const now = Date.now()
          if (this.lastMessageTime && (now - this.lastMessageTime) < RATE_LIMIT_MS) return false
          return true
      },
804 
      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)
      },
812 
      // ---------- counter & status ----------
      decrementMessages() {
          if (this.remainingMessages > 0) this.remainingMessages--
      },
817 
      /**
       * 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
              }
          }
      },
834 
      applyProgress(progressChange: number) {
          this.objectiveProgress = Math.max(0, Math.min(MAX_PROGRESS, this.objectiveProgress + progressChange))
      },
838 
      /**
       * 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'
          }
      },
854 
      // ---------- 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
872 
          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 — Revisionist only reaches figures from history.`
                                  : `${who} couldn't be dated — Revisionist can only reach figures it can place in history.`)
                              : `${who} has died by that year — choose an earlier moment to reach them.`
              )
              return false
          }
900 
          this.setError(null)
          this.moderationNotice = null
          this.setActiveFigure(target)
          this.addUserMessage(text, target)
          this.decrementMessages()
          this.setLoading(true)
          this.lastMessageTime = Date.now()
908 
          // 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()
921 
          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)
                  }
              })
957 
              if (epoch !== this.runEpoch) return false
959 
              if (response?.success && response.data?.characterResponse) {
                  const { figure, characterResponse, diceRoll, diceOutcome, timeline } = response.data
962 
                  if (figure?.name) {
                      this.registerFigure({
                          name: figure.name,
                          era: figure.era || '',
                          descriptor: figure.descriptor || ''
                      })
                  }
970 
                  // ---- 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
                  }
978 
                  // 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)
1005 
                  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
1022 
                      // 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()
              }
          }
1073 
          // 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 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
      },
1102 
      /**
       * 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.momentum = 0
          this.error = null
          return true
      },
1155 
      /**
       * 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
          }
      },
1183 
      /**
       * 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)
          }
      },
1201 
      /** Opens the run-packs sales modal, loading the catalog first. */
      async openBuyModal(): Promise<void> {
          this.buyModalOpen = true
          await this.loadPacks()
      },
1207 
      /** Closes the sales modal. */
      closeBuyModal(): void {
          this.buyModalOpen = false
      },
1212 
      /** 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()
          }
      },
1223 
      /** Dismisses the post-purchase notice. */
      clearPurchaseNotice(): void {
          this.purchaseNotice = null
      },
1228 
      /** 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)
          }
      },
1242 
      /** 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
          }
      },
1258 
      getVictoryEfficiency() {
          if (this.gameStatus === 'victory') {
              const messagesSaved = this.remainingMessages
              const messagesUsed = TOTAL_MESSAGES - this.remainingMessages
              const efficiencyPercentage = Math.round((messagesSaved / TOTAL_MESSAGES) * 100)
1264 
              const efficiencyRating = rateEfficiency(messagesSaved)
1266 
              return {
                  messagesSaved,
                  messagesUsed,
                  efficiencyPercentage,
                  efficiencyRating,
                  isEarlyVictory: messagesSaved > 0
              }
          }
          return null
      },
1277 
      /**
       * 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
1294 
          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
1310 
          const snapshot: RunSnapshot = {
              version: RUN_SNAPSHOT_VERSION,
              runId,
              status,
              objective,
              objectiveProgress: this.objectiveProgress,
              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,
                  valence: e.valence,
                  craft: e.craft,
                  anachronism: e.anachronism
              })),
              chronicle: this.chronicle
          }
1338 
          try {
              await $fetch('/api/run-save', {
                  method: 'POST',
                  headers: { 'Content-Type': 'application/json' },
                  body: snapshot
              })
          } 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)
          }
      },
1350 
      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
          // The paywall / capacity notices re-check on the next commit.
          this.outOfRuns = false
          this.atCapacity = false
          this.currentObjective = null
          this.objectiveProgress = 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
      }
  }
1397})

Because that promise always resolves, the .finally from the previous section always fires and clears epiloguePending. So on a failed epilogue the end screen leaves the loading state and falls back to rendering the prior telling (see the v-else-if next) — it reveals or it falls back, but it never spins. And resetGame clears the flag too, so Play Again starts clean (stores/game.ts:1384).

The end screen: the wait, then a cross-fade

The epilogue block now keys off epiloguePending. While pending, it shows the "final account…" line; otherwise it renders the telling. The two are wrapped in a Transition so the swap is a gentle opacity cross-fade rather than an abrupt text replacement.

Loading while pending; the epilogue article otherwise; a cross-fade between them.

components/EndGameScreen.vue · 260 lines

components/EndGameScreen.vue260 lines · Vue

⋯ 34 lines hidden (lines 1–34)1<template>
2  <div v-if="gameStore.gameStatus === 'victory' || gameStore.gameStatus === 'defeat'" ref="dialogRef" data-testid="end-game-screen"
3    role="dialog" aria-modal="true" :aria-labelledby="headingId" @keydown="onKeydown"
4    class="end-screen fixed inset-0 z-50 overflow-y-auto" :class="isVictory ? 'end--win' : 'end--loss'">
5    <div class="max-w-4xl mx-auto px-5 py-8">
6      <!-- Verdict masthead: a struck seal, the verdict, the objective + final %. The
7           win is illuminated (glowing terracotta seal, serif verdict in ink); the loss
8           is somber (a flat, cold seal and a muted verdict) — the two read apart instantly. -->
9      <div class="text-center border-b rv-line pb-6">
10        <div class="verdict-seal" :class="isVictory ? 'is-win' : 'is-loss'" aria-hidden="true">{{ isVictory ? '✦' : '⊘' }}</div>
11        <h2 v-if="isVictory" :id="headingId" ref="headingRef" tabindex="-1" data-testid="victory-message" class="rv-serif text-3xl sm:text-4xl font-bold rv-fg mt-3 outline-none">History Rewritten</h2>
12        <h2 v-else :id="headingId" ref="headingRef" tabindex="-1" data-testid="defeat-message" class="rv-serif text-3xl sm:text-4xl font-bold rv-muted mt-3 outline-none">The Timeline Held</h2>
13        <p class="text-sm mt-2.5 flex items-center justify-center gap-2 flex-wrap">
14          <span class="rv-muted inline-flex items-center gap-1.5">
15            <span aria-hidden="true">{{ gameStore.currentObjective?.icon }}</span>
16            <strong data-testid="objective-title" class="font-semibold">{{ gameStore.currentObjective?.title || 'Historical Mission' }}</strong>
17          </span>
18          <span class="rv-hair-c" aria-hidden="true">·</span>
19          <span class="rv-mono font-bold" :class="isVictory ? 'rv-ok' : 'rv-bad'">
20            <span data-testid="final-progress">{{ gameStore.objectiveProgress }}%</span> rewritten
21          </span>
22        </p>
23 
24        <p v-if="!isVictory" data-testid="defeat-explanation" class="rv-muted text-sm mt-3 max-w-prose mx-auto">
25          Your five messages are spent. What you changed remains — but it was not enough, and the objective slipped away.
26        </p>
27 
28        <div v-if="victoryEfficiency" data-testid="efficiency-display" class="mt-3 rv-mono text-sm">
29          <span class="rv-ok font-semibold">{{ victoryPhrase }}</span>
30          <span class="rv-muted"> · {{ victoryEfficiency.messagesUsed }}/5 used<span v-if="victoryEfficiency.messagesSaved > 0"> · {{ victoryEfficiency.messagesSaved }} saved</span></span>
31          <span v-if="victoryEfficiency.isEarlyVictory" class="rv-ok"> · 🌟 to spare</span>
32        </div>
33      </div>
34 
35      <!-- The Chronicle's final telling — the epilogue. While the terminal telling is
36           still being written (epiloguePending), we show the "final account…" wait, NOT
37           the prior turn's stale, pre-ending telling. When it lands it cross-fades in
38           (mirroring Chronicle.vue's rewrite reveal); a failed final refresh clears
39           pending and falls back to the prior telling, so the panel never hangs. -->
40      <div v-if="chronicle || epiloguePending" data-testid="end-chronicle" class="mt-6">
41        <span class="rv-label rv-label--rule"><span aria-hidden="true">📖</span> The Chronicle</span>
42        <Transition :name="epilogueTransition" mode="out-in">
43          <div v-if="epiloguePending" key="epilogue-loading" data-testid="end-chronicle-loading" class="rv-faint italic text-sm">
44            The chronicler sets down the final account…
45          </div>
46          <article v-else-if="chronicle" key="epilogue-body" data-testid="end-chronicle-body">
47            <h4 data-testid="end-chronicle-title" class="rv-serif text-xl font-semibold rv-fg mb-2.5 leading-tight">{{ chronicle.title }}</h4>
48            <p v-for="(para, i) in chronicle.paragraphs" :key="i" class="rv-serif rv-muted text-[15px] leading-relaxed mb-2.5 last:mb-0">{{ para }}</p>
49          </article>
50        </Transition>
51      </div>
⋯ 209 lines hidden (lines 52–260)52 
53      <!-- The words you sent — the keepsake: your actual messages into the past -->
54      <div v-if="dispatches.length" data-testid="dispatches" class="mt-7">
55        <span class="rv-label rv-label--rule">The words you sent</span>
56        <ul class="space-y-3.5">
57          <li v-for="(d, i) in dispatches" :key="i">
58            <p class="rv-label">to {{ d.figure }}<span v-if="d.era"> · {{ d.era }}</span></p>
59            <blockquote class="rv-serif rv-fg text-base leading-relaxed border-l-2 rv-line pl-3 mt-1">"{{ d.text }}"</blockquote>
60          </li>
61        </ul>
62      </div>
63 
64      <!-- Stats — derived from the real resolved turns -->
65      <div data-testid="game-summary" class="mt-7">
66        <span class="rv-label rv-label--rule">How it played out</span>
67        <div class="flex flex-wrap gap-10">
68          <div data-testid="message-efficiency">
69            <div class="rv-mono text-3xl font-extrabold rv-fg leading-none">{{ messagesUsed }}</div>
70            <div class="rv-label mt-1">{{ messagesUsed === 1 ? 'message' : 'messages' }} sent</div>
71          </div>
72          <div v-if="gameSummary.bestRoll" data-testid="best-roll">
73            <div class="rv-mono text-3xl font-extrabold rv-ok leading-none">{{ gameSummary.bestRoll.diceRoll }}</div>
74            <div class="rv-label mt-1">{{ messagesUsed >= 2 ? 'best roll' : 'the roll that did it' }} · {{ gameSummary.bestRoll.diceOutcome }}</div>
75          </div>
76          <div v-if="gameSummary.worstRoll && messagesUsed >= 2" data-testid="worst-roll">
77            <div class="rv-mono text-3xl font-extrabold rv-bad leading-none">{{ gameSummary.worstRoll.diceRoll }}</div>
78            <div class="rv-label mt-1">worst roll · {{ gameSummary.worstRoll.diceOutcome }}</div>
79          </div>
80        </div>
81      </div>
82 
83      <!-- The history you wrote — the Spine itself, exactly as it filled in during
84           the run. Read-only here: no live "▷ now" present marker, no "the timeline
85           trembles…" empty state. Same component the player scrolled and tapped on
86           the board, so the verdict's history reads as richly as it did in play —
87           valence dots, ⚡/⚑ badges, the roll, and the Δ equation all carry over. -->
88      <div v-if="timeline.length > 0" class="mt-6">
89        <TimelineLedger readonly />
90      </div>
91 
92      <div class="mt-9 border-t rv-line pt-6 flex items-center gap-3 flex-wrap">
93        <button ref="playAgainRef" type="button" data-testid="play-again-button" class="rv-btn rv-btn--primary" @click="playAgain">
94          Try a new timeline <span aria-hidden="true">▷</span>
95        </button>
96        <span class="rv-faint text-xs inline-flex items-center gap-1.5">
97          <span class="rv-dot" :class="isVictory ? 'rv-dot--ok' : 'rv-dot--bad'" aria-hidden="true" /> this timeline is written.
98        </span>
99      </div>
100    </div>
101  </div>
102</template>
103 
104<script setup lang="ts">
105/**
106 * EndGameScreen — the mission debrief. A full-bleed takeover (not a modal card):
107 * verdict line, the Chronicle epilogue + big-number stat trio, and the history you
108 * wrote. All stats derive from the real resolved turns.
109 */
110import { ref, computed, watch, nextTick } from 'vue'
111import { useGameStore } from '~/stores/game'
112import { usePrefersReducedMotion } from '~/composables/usePrefersReducedMotion'
113 
114const gameStore = useGameStore()
115const reduced = usePrefersReducedMotion()
116 
117const headingId = `end-game-heading-${Math.random().toString(36).slice(2, 11)}`
118 
119// Modal focus management: it's a true takeover (aria-modal), so when it opens we
120// move focus to the VERDICT heading (tabindex=-1: announced, focusable, outside
121// the Tab cycle), trap Tab inside, and restore focus when the run ends. Focusing
122// the heading — not the bottom Play Again button — also means the screen opens at
123// the top: the verdict and the Chronicle epilogue are the first things seen, not
124// scrolled past below the fold.
125const dialogRef = ref<HTMLElement | null>(null)
126const headingRef = ref<HTMLElement | null>(null)
127const playAgainRef = ref<HTMLElement | null>(null)
128let prevFocus: HTMLElement | null = null
129 
130watch(() => gameStore.gameStatus, async (s) => {
131    if (typeof document === 'undefined') return
132    if (s === 'victory' || s === 'defeat') {
133        prevFocus = document.activeElement as HTMLElement | null
134        await nextTick()
135        if (dialogRef.value) dialogRef.value.scrollTop = 0
136        headingRef.value?.focus()
137    } else if (prevFocus) {
138        prevFocus.focus?.()
139        prevFocus = null
140    }
141})
142 
143function onKeydown(e: KeyboardEvent) {
144    if (e.key !== 'Tab' || !dialogRef.value) return
145    const focusables = dialogRef.value.querySelectorAll<HTMLElement>(
146        'a[href], button:not([disabled]), input:not([disabled]), [tabindex]:not([tabindex="-1"])'
147    )
148    if (!focusables.length) return
149    const first = focusables[0]
150    const last = focusables[focusables.length - 1]
151    const active = document.activeElement
152    if (e.shiftKey && active === first) { e.preventDefault(); last.focus() }
153    else if (!e.shiftKey && active === last) { e.preventDefault(); first.focus() }
154}
155 
156const isVictory = computed(() => gameStore.gameStatus === 'victory')
157const victoryEfficiency = computed(() => gameStore.getVictoryEfficiency())
158 
159// The verdict never deflates: spending every message is reframed as "Hard-won," not
160// the limp "Standard." Only the laudatory tiers keep their rating as an adjective.
161const victoryPhrase = computed(() => {
162    const rating = victoryEfficiency.value?.efficiencyRating
163    if (!rating) return 'Victory'
164    return rating === 'Standard' ? 'Hard-won victory' : `${rating} victory`
165})
166const messagesUsed = computed(() => 5 - gameStore.remainingMessages)
167const gameSummary = computed(() => gameStore.gameSummary)
168const timeline = computed(() => gameStore.timelineEvents)
169const chronicle = computed(() => gameStore.chronicle)
170// The epilogue (terminal telling) is still being written — show the wait, never the
171// prior turn's stale telling. The cross-fade mirrors Chronicle.vue and is dropped
172// under prefers-reduced-motion (the empty name disables the Transition's classes).
173const epiloguePending = computed(() => gameStore.epiloguePending)
174const epilogueTransition = computed(() => (reduced.value ? '' : 'epilogue'))
175 
176// The keepsake: the player's verbatim messages, paired with whom/when they reached.
177const dispatches = computed(() => {
178    const users = gameStore.messageHistory.filter(m => m.sender === 'user')
179    const events = gameStore.timelineEvents
180    return users.map((m, i) => ({
181        text: m.text,
182        figure: m.figureName || events[i]?.figureName || 'the past',
183        era: events[i]?.era || ''
184    }))
185})
186 
187// The page owns the FULL reset (store + figure input + composer), so Play Again
188// emits instead of resetting the store directly — the two reset paths used to
189// diverge here, leaving the previous run's figure stranded in the input.
190const emit = defineEmits<{ 'play-again': [] }>()
191const playAgain = () => {
192    emit('play-again')
193}
194</script>
195 
196<style scoped>
197/* The epilogue reveal — the terminal telling cross-fades in over the "final account…"
198   wait, the same gentle opacity fade Chronicle.vue uses for a rewrite. Gated by the
199   transition NAME (empty under prefers-reduced-motion), so reduced-motion gets an
200   instant swap with no classes attached. */
201.epilogue-enter-active,
202.epilogue-leave-active {
203    transition: opacity var(--rv-dur-3) var(--rv-ease);
204}
205.epilogue-enter-from,
206.epilogue-leave-to {
207    opacity: 0;
208}
209 
210/* Win and loss share the page frame but not its mood. The win is illuminated — a warm
211   wash blooms from the top; the loss is a colder, dimmer ground that has settled back. */
212.end-screen { background: var(--rv-bg); animation: end-in var(--rv-dur-3) var(--rv-ease) both; }
213@keyframes end-in { from { opacity: 0; } to { opacity: 1; } }
214@media (prefers-reduced-motion: reduce) { .end-screen { animation: none; } }
215.end--win {
216    background:
217        radial-gradient(135% 70% at 50% -12%, color-mix(in srgb, var(--rv-accent) 13%, transparent), transparent 68%),
218        var(--rv-bg);
219}
220.end--loss {
221    background:
222        radial-gradient(135% 70% at 50% -12%, color-mix(in srgb, var(--rv-bad) 6%, transparent), transparent 60%),
223        var(--rv-tint);
224}
225 
226/* The struck seal — the verdict's emblem. The win seal glows like fresh sealing wax;
227   the loss seal is a cold, flat stamp. */
228.verdict-seal {
229    display: inline-grid;
230    place-items: center;
231    width: 60px;
232    height: 60px;
233    border-radius: 50%;
234    border: 2px solid;
235    font-size: 1.6rem;
236    line-height: 1;
237}
238.verdict-seal.is-win {
239    color: var(--rv-accent);
240    border-color: var(--rv-accent);
241    box-shadow:
242        0 0 0 5px color-mix(in srgb, var(--rv-accent) 12%, transparent),
243        0 0 30px color-mix(in srgb, var(--rv-accent) 32%, transparent);
244    animation: seal-strike 0.6s var(--rv-ease-spring) both;
245}
246.verdict-seal.is-loss {
247    color: var(--rv-faint);
248    border-color: var(--rv-line);
249    box-shadow: inset 0 0 0 4px color-mix(in srgb, var(--rv-faint) 8%, transparent);
250}
251 
252@keyframes seal-strike {
253    0% { opacity: 0; transform: scale(.5) rotate(-12deg); }
254    60% { transform: scale(1.12) rotate(3deg); }
255    100% { opacity: 1; transform: scale(1) rotate(0); }
256}
257@media (prefers-reduced-motion: reduce) {
258    .verdict-seal.is-win { animation: none; }
259}
260</style>

The transition name is computed, and goes empty under prefers-reduced-motion — an empty name disables the CSS classes, so reduced-motion gets an instant, class-free swap. This mirrors Chronicle.vue's rewrite reveal exactly.

The pending flag and the motion-gated transition name.

components/EndGameScreen.vue · 260 lines

components/EndGameScreen.vue260 lines · Vue

⋯ 168 lines hidden (lines 1–168)1<template>
2  <div v-if="gameStore.gameStatus === 'victory' || gameStore.gameStatus === 'defeat'" ref="dialogRef" data-testid="end-game-screen"
3    role="dialog" aria-modal="true" :aria-labelledby="headingId" @keydown="onKeydown"
4    class="end-screen fixed inset-0 z-50 overflow-y-auto" :class="isVictory ? 'end--win' : 'end--loss'">
5    <div class="max-w-4xl mx-auto px-5 py-8">
6      <!-- Verdict masthead: a struck seal, the verdict, the objective + final %. The
7           win is illuminated (glowing terracotta seal, serif verdict in ink); the loss
8           is somber (a flat, cold seal and a muted verdict) — the two read apart instantly. -->
9      <div class="text-center border-b rv-line pb-6">
10        <div class="verdict-seal" :class="isVictory ? 'is-win' : 'is-loss'" aria-hidden="true">{{ isVictory ? '✦' : '⊘' }}</div>
11        <h2 v-if="isVictory" :id="headingId" ref="headingRef" tabindex="-1" data-testid="victory-message" class="rv-serif text-3xl sm:text-4xl font-bold rv-fg mt-3 outline-none">History Rewritten</h2>
12        <h2 v-else :id="headingId" ref="headingRef" tabindex="-1" data-testid="defeat-message" class="rv-serif text-3xl sm:text-4xl font-bold rv-muted mt-3 outline-none">The Timeline Held</h2>
13        <p class="text-sm mt-2.5 flex items-center justify-center gap-2 flex-wrap">
14          <span class="rv-muted inline-flex items-center gap-1.5">
15            <span aria-hidden="true">{{ gameStore.currentObjective?.icon }}</span>
16            <strong data-testid="objective-title" class="font-semibold">{{ gameStore.currentObjective?.title || 'Historical Mission' }}</strong>
17          </span>
18          <span class="rv-hair-c" aria-hidden="true">·</span>
19          <span class="rv-mono font-bold" :class="isVictory ? 'rv-ok' : 'rv-bad'">
20            <span data-testid="final-progress">{{ gameStore.objectiveProgress }}%</span> rewritten
21          </span>
22        </p>
23 
24        <p v-if="!isVictory" data-testid="defeat-explanation" class="rv-muted text-sm mt-3 max-w-prose mx-auto">
25          Your five messages are spent. What you changed remains — but it was not enough, and the objective slipped away.
26        </p>
27 
28        <div v-if="victoryEfficiency" data-testid="efficiency-display" class="mt-3 rv-mono text-sm">
29          <span class="rv-ok font-semibold">{{ victoryPhrase }}</span>
30          <span class="rv-muted"> · {{ victoryEfficiency.messagesUsed }}/5 used<span v-if="victoryEfficiency.messagesSaved > 0"> · {{ victoryEfficiency.messagesSaved }} saved</span></span>
31          <span v-if="victoryEfficiency.isEarlyVictory" class="rv-ok"> · 🌟 to spare</span>
32        </div>
33      </div>
34 
35      <!-- The Chronicle's final telling — the epilogue. While the terminal telling is
36           still being written (epiloguePending), we show the "final account…" wait, NOT
37           the prior turn's stale, pre-ending telling. When it lands it cross-fades in
38           (mirroring Chronicle.vue's rewrite reveal); a failed final refresh clears
39           pending and falls back to the prior telling, so the panel never hangs. -->
40      <div v-if="chronicle || epiloguePending" data-testid="end-chronicle" class="mt-6">
41        <span class="rv-label rv-label--rule"><span aria-hidden="true">📖</span> The Chronicle</span>
42        <Transition :name="epilogueTransition" mode="out-in">
43          <div v-if="epiloguePending" key="epilogue-loading" data-testid="end-chronicle-loading" class="rv-faint italic text-sm">
44            The chronicler sets down the final account…
45          </div>
46          <article v-else-if="chronicle" key="epilogue-body" data-testid="end-chronicle-body">
47            <h4 data-testid="end-chronicle-title" class="rv-serif text-xl font-semibold rv-fg mb-2.5 leading-tight">{{ chronicle.title }}</h4>
48            <p v-for="(para, i) in chronicle.paragraphs" :key="i" class="rv-serif rv-muted text-[15px] leading-relaxed mb-2.5 last:mb-0">{{ para }}</p>
49          </article>
50        </Transition>
51      </div>
52 
53      <!-- The words you sent — the keepsake: your actual messages into the past -->
54      <div v-if="dispatches.length" data-testid="dispatches" class="mt-7">
55        <span class="rv-label rv-label--rule">The words you sent</span>
56        <ul class="space-y-3.5">
57          <li v-for="(d, i) in dispatches" :key="i">
58            <p class="rv-label">to {{ d.figure }}<span v-if="d.era"> · {{ d.era }}</span></p>
59            <blockquote class="rv-serif rv-fg text-base leading-relaxed border-l-2 rv-line pl-3 mt-1">"{{ d.text }}"</blockquote>
60          </li>
61        </ul>
62      </div>
63 
64      <!-- Stats — derived from the real resolved turns -->
65      <div data-testid="game-summary" class="mt-7">
66        <span class="rv-label rv-label--rule">How it played out</span>
67        <div class="flex flex-wrap gap-10">
68          <div data-testid="message-efficiency">
69            <div class="rv-mono text-3xl font-extrabold rv-fg leading-none">{{ messagesUsed }}</div>
70            <div class="rv-label mt-1">{{ messagesUsed === 1 ? 'message' : 'messages' }} sent</div>
71          </div>
72          <div v-if="gameSummary.bestRoll" data-testid="best-roll">
73            <div class="rv-mono text-3xl font-extrabold rv-ok leading-none">{{ gameSummary.bestRoll.diceRoll }}</div>
74            <div class="rv-label mt-1">{{ messagesUsed >= 2 ? 'best roll' : 'the roll that did it' }} · {{ gameSummary.bestRoll.diceOutcome }}</div>
75          </div>
76          <div v-if="gameSummary.worstRoll && messagesUsed >= 2" data-testid="worst-roll">
77            <div class="rv-mono text-3xl font-extrabold rv-bad leading-none">{{ gameSummary.worstRoll.diceRoll }}</div>
78            <div class="rv-label mt-1">worst roll · {{ gameSummary.worstRoll.diceOutcome }}</div>
79          </div>
80        </div>
81      </div>
82 
83      <!-- The history you wrote — the Spine itself, exactly as it filled in during
84           the run. Read-only here: no live "▷ now" present marker, no "the timeline
85           trembles…" empty state. Same component the player scrolled and tapped on
86           the board, so the verdict's history reads as richly as it did in play —
87           valence dots, ⚡/⚑ badges, the roll, and the Δ equation all carry over. -->
88      <div v-if="timeline.length > 0" class="mt-6">
89        <TimelineLedger readonly />
90      </div>
91 
92      <div class="mt-9 border-t rv-line pt-6 flex items-center gap-3 flex-wrap">
93        <button ref="playAgainRef" type="button" data-testid="play-again-button" class="rv-btn rv-btn--primary" @click="playAgain">
94          Try a new timeline <span aria-hidden="true">▷</span>
95        </button>
96        <span class="rv-faint text-xs inline-flex items-center gap-1.5">
97          <span class="rv-dot" :class="isVictory ? 'rv-dot--ok' : 'rv-dot--bad'" aria-hidden="true" /> this timeline is written.
98        </span>
99      </div>
100    </div>
101  </div>
102</template>
103 
104<script setup lang="ts">
105/**
106 * EndGameScreen — the mission debrief. A full-bleed takeover (not a modal card):
107 * verdict line, the Chronicle epilogue + big-number stat trio, and the history you
108 * wrote. All stats derive from the real resolved turns.
109 */
110import { ref, computed, watch, nextTick } from 'vue'
111import { useGameStore } from '~/stores/game'
112import { usePrefersReducedMotion } from '~/composables/usePrefersReducedMotion'
113 
114const gameStore = useGameStore()
115const reduced = usePrefersReducedMotion()
116 
117const headingId = `end-game-heading-${Math.random().toString(36).slice(2, 11)}`
118 
119// Modal focus management: it's a true takeover (aria-modal), so when it opens we
120// move focus to the VERDICT heading (tabindex=-1: announced, focusable, outside
121// the Tab cycle), trap Tab inside, and restore focus when the run ends. Focusing
122// the heading — not the bottom Play Again button — also means the screen opens at
123// the top: the verdict and the Chronicle epilogue are the first things seen, not
124// scrolled past below the fold.
125const dialogRef = ref<HTMLElement | null>(null)
126const headingRef = ref<HTMLElement | null>(null)
127const playAgainRef = ref<HTMLElement | null>(null)
128let prevFocus: HTMLElement | null = null
129 
130watch(() => gameStore.gameStatus, async (s) => {
131    if (typeof document === 'undefined') return
132    if (s === 'victory' || s === 'defeat') {
133        prevFocus = document.activeElement as HTMLElement | null
134        await nextTick()
135        if (dialogRef.value) dialogRef.value.scrollTop = 0
136        headingRef.value?.focus()
137    } else if (prevFocus) {
138        prevFocus.focus?.()
139        prevFocus = null
140    }
141})
142 
143function onKeydown(e: KeyboardEvent) {
144    if (e.key !== 'Tab' || !dialogRef.value) return
145    const focusables = dialogRef.value.querySelectorAll<HTMLElement>(
146        'a[href], button:not([disabled]), input:not([disabled]), [tabindex]:not([tabindex="-1"])'
147    )
148    if (!focusables.length) return
149    const first = focusables[0]
150    const last = focusables[focusables.length - 1]
151    const active = document.activeElement
152    if (e.shiftKey && active === first) { e.preventDefault(); last.focus() }
153    else if (!e.shiftKey && active === last) { e.preventDefault(); first.focus() }
154}
155 
156const isVictory = computed(() => gameStore.gameStatus === 'victory')
157const victoryEfficiency = computed(() => gameStore.getVictoryEfficiency())
158 
159// The verdict never deflates: spending every message is reframed as "Hard-won," not
160// the limp "Standard." Only the laudatory tiers keep their rating as an adjective.
161const victoryPhrase = computed(() => {
162    const rating = victoryEfficiency.value?.efficiencyRating
163    if (!rating) return 'Victory'
164    return rating === 'Standard' ? 'Hard-won victory' : `${rating} victory`
165})
166const messagesUsed = computed(() => 5 - gameStore.remainingMessages)
167const gameSummary = computed(() => gameStore.gameSummary)
168const timeline = computed(() => gameStore.timelineEvents)
169const chronicle = computed(() => gameStore.chronicle)
170// The epilogue (terminal telling) is still being written — show the wait, never the
171// prior turn's stale telling. The cross-fade mirrors Chronicle.vue and is dropped
172// under prefers-reduced-motion (the empty name disables the Transition's classes).
173const epiloguePending = computed(() => gameStore.epiloguePending)
174const epilogueTransition = computed(() => (reduced.value ? '' : 'epilogue'))
⋯ 86 lines hidden (lines 175–260)175 
176// The keepsake: the player's verbatim messages, paired with whom/when they reached.
177const dispatches = computed(() => {
178    const users = gameStore.messageHistory.filter(m => m.sender === 'user')
179    const events = gameStore.timelineEvents
180    return users.map((m, i) => ({
181        text: m.text,
182        figure: m.figureName || events[i]?.figureName || 'the past',
183        era: events[i]?.era || ''
184    }))
185})
186 
187// The page owns the FULL reset (store + figure input + composer), so Play Again
188// emits instead of resetting the store directly — the two reset paths used to
189// diverge here, leaving the previous run's figure stranded in the input.
190const emit = defineEmits<{ 'play-again': [] }>()
191const playAgain = () => {
192    emit('play-again')
193}
194</script>
195 
196<style scoped>
197/* The epilogue reveal — the terminal telling cross-fades in over the "final account…"
198   wait, the same gentle opacity fade Chronicle.vue uses for a rewrite. Gated by the
199   transition NAME (empty under prefers-reduced-motion), so reduced-motion gets an
200   instant swap with no classes attached. */
201.epilogue-enter-active,
202.epilogue-leave-active {
203    transition: opacity var(--rv-dur-3) var(--rv-ease);
204}
205.epilogue-enter-from,
206.epilogue-leave-to {
207    opacity: 0;
208}
209 
210/* Win and loss share the page frame but not its mood. The win is illuminated — a warm
211   wash blooms from the top; the loss is a colder, dimmer ground that has settled back. */
212.end-screen { background: var(--rv-bg); animation: end-in var(--rv-dur-3) var(--rv-ease) both; }
213@keyframes end-in { from { opacity: 0; } to { opacity: 1; } }
214@media (prefers-reduced-motion: reduce) { .end-screen { animation: none; } }
215.end--win {
216    background:
217        radial-gradient(135% 70% at 50% -12%, color-mix(in srgb, var(--rv-accent) 13%, transparent), transparent 68%),
218        var(--rv-bg);
219}
220.end--loss {
221    background:
222        radial-gradient(135% 70% at 50% -12%, color-mix(in srgb, var(--rv-bad) 6%, transparent), transparent 60%),
223        var(--rv-tint);
224}
225 
226/* The struck seal — the verdict's emblem. The win seal glows like fresh sealing wax;
227   the loss seal is a cold, flat stamp. */
228.verdict-seal {
229    display: inline-grid;
230    place-items: center;
231    width: 60px;
232    height: 60px;
233    border-radius: 50%;
234    border: 2px solid;
235    font-size: 1.6rem;
236    line-height: 1;
237}
238.verdict-seal.is-win {
239    color: var(--rv-accent);
240    border-color: var(--rv-accent);
241    box-shadow:
242        0 0 0 5px color-mix(in srgb, var(--rv-accent) 12%, transparent),
243        0 0 30px color-mix(in srgb, var(--rv-accent) 32%, transparent);
244    animation: seal-strike 0.6s var(--rv-ease-spring) both;
245}
246.verdict-seal.is-loss {
247    color: var(--rv-faint);
248    border-color: var(--rv-line);
249    box-shadow: inset 0 0 0 4px color-mix(in srgb, var(--rv-faint) 8%, transparent);
250}
251 
252@keyframes seal-strike {
253    0% { opacity: 0; transform: scale(.5) rotate(-12deg); }
254    60% { transform: scale(1.12) rotate(3deg); }
255    100% { opacity: 1; transform: scale(1) rotate(0); }
256}
257@media (prefers-reduced-motion: reduce) {
258    .verdict-seal.is-win { animation: none; }
259}
260</style>

The fade itself — the same opacity/duration tokens Chronicle.vue uses.

components/EndGameScreen.vue · 260 lines

components/EndGameScreen.vue260 lines · Vue

⋯ 195 lines hidden (lines 1–195)1<template>
2  <div v-if="gameStore.gameStatus === 'victory' || gameStore.gameStatus === 'defeat'" ref="dialogRef" data-testid="end-game-screen"
3    role="dialog" aria-modal="true" :aria-labelledby="headingId" @keydown="onKeydown"
4    class="end-screen fixed inset-0 z-50 overflow-y-auto" :class="isVictory ? 'end--win' : 'end--loss'">
5    <div class="max-w-4xl mx-auto px-5 py-8">
6      <!-- Verdict masthead: a struck seal, the verdict, the objective + final %. The
7           win is illuminated (glowing terracotta seal, serif verdict in ink); the loss
8           is somber (a flat, cold seal and a muted verdict) — the two read apart instantly. -->
9      <div class="text-center border-b rv-line pb-6">
10        <div class="verdict-seal" :class="isVictory ? 'is-win' : 'is-loss'" aria-hidden="true">{{ isVictory ? '✦' : '⊘' }}</div>
11        <h2 v-if="isVictory" :id="headingId" ref="headingRef" tabindex="-1" data-testid="victory-message" class="rv-serif text-3xl sm:text-4xl font-bold rv-fg mt-3 outline-none">History Rewritten</h2>
12        <h2 v-else :id="headingId" ref="headingRef" tabindex="-1" data-testid="defeat-message" class="rv-serif text-3xl sm:text-4xl font-bold rv-muted mt-3 outline-none">The Timeline Held</h2>
13        <p class="text-sm mt-2.5 flex items-center justify-center gap-2 flex-wrap">
14          <span class="rv-muted inline-flex items-center gap-1.5">
15            <span aria-hidden="true">{{ gameStore.currentObjective?.icon }}</span>
16            <strong data-testid="objective-title" class="font-semibold">{{ gameStore.currentObjective?.title || 'Historical Mission' }}</strong>
17          </span>
18          <span class="rv-hair-c" aria-hidden="true">·</span>
19          <span class="rv-mono font-bold" :class="isVictory ? 'rv-ok' : 'rv-bad'">
20            <span data-testid="final-progress">{{ gameStore.objectiveProgress }}%</span> rewritten
21          </span>
22        </p>
23 
24        <p v-if="!isVictory" data-testid="defeat-explanation" class="rv-muted text-sm mt-3 max-w-prose mx-auto">
25          Your five messages are spent. What you changed remains — but it was not enough, and the objective slipped away.
26        </p>
27 
28        <div v-if="victoryEfficiency" data-testid="efficiency-display" class="mt-3 rv-mono text-sm">
29          <span class="rv-ok font-semibold">{{ victoryPhrase }}</span>
30          <span class="rv-muted"> · {{ victoryEfficiency.messagesUsed }}/5 used<span v-if="victoryEfficiency.messagesSaved > 0"> · {{ victoryEfficiency.messagesSaved }} saved</span></span>
31          <span v-if="victoryEfficiency.isEarlyVictory" class="rv-ok"> · 🌟 to spare</span>
32        </div>
33      </div>
34 
35      <!-- The Chronicle's final telling — the epilogue. While the terminal telling is
36           still being written (epiloguePending), we show the "final account…" wait, NOT
37           the prior turn's stale, pre-ending telling. When it lands it cross-fades in
38           (mirroring Chronicle.vue's rewrite reveal); a failed final refresh clears
39           pending and falls back to the prior telling, so the panel never hangs. -->
40      <div v-if="chronicle || epiloguePending" data-testid="end-chronicle" class="mt-6">
41        <span class="rv-label rv-label--rule"><span aria-hidden="true">📖</span> The Chronicle</span>
42        <Transition :name="epilogueTransition" mode="out-in">
43          <div v-if="epiloguePending" key="epilogue-loading" data-testid="end-chronicle-loading" class="rv-faint italic text-sm">
44            The chronicler sets down the final account…
45          </div>
46          <article v-else-if="chronicle" key="epilogue-body" data-testid="end-chronicle-body">
47            <h4 data-testid="end-chronicle-title" class="rv-serif text-xl font-semibold rv-fg mb-2.5 leading-tight">{{ chronicle.title }}</h4>
48            <p v-for="(para, i) in chronicle.paragraphs" :key="i" class="rv-serif rv-muted text-[15px] leading-relaxed mb-2.5 last:mb-0">{{ para }}</p>
49          </article>
50        </Transition>
51      </div>
52 
53      <!-- The words you sent — the keepsake: your actual messages into the past -->
54      <div v-if="dispatches.length" data-testid="dispatches" class="mt-7">
55        <span class="rv-label rv-label--rule">The words you sent</span>
56        <ul class="space-y-3.5">
57          <li v-for="(d, i) in dispatches" :key="i">
58            <p class="rv-label">to {{ d.figure }}<span v-if="d.era"> · {{ d.era }}</span></p>
59            <blockquote class="rv-serif rv-fg text-base leading-relaxed border-l-2 rv-line pl-3 mt-1">"{{ d.text }}"</blockquote>
60          </li>
61        </ul>
62      </div>
63 
64      <!-- Stats — derived from the real resolved turns -->
65      <div data-testid="game-summary" class="mt-7">
66        <span class="rv-label rv-label--rule">How it played out</span>
67        <div class="flex flex-wrap gap-10">
68          <div data-testid="message-efficiency">
69            <div class="rv-mono text-3xl font-extrabold rv-fg leading-none">{{ messagesUsed }}</div>
70            <div class="rv-label mt-1">{{ messagesUsed === 1 ? 'message' : 'messages' }} sent</div>
71          </div>
72          <div v-if="gameSummary.bestRoll" data-testid="best-roll">
73            <div class="rv-mono text-3xl font-extrabold rv-ok leading-none">{{ gameSummary.bestRoll.diceRoll }}</div>
74            <div class="rv-label mt-1">{{ messagesUsed >= 2 ? 'best roll' : 'the roll that did it' }} · {{ gameSummary.bestRoll.diceOutcome }}</div>
75          </div>
76          <div v-if="gameSummary.worstRoll && messagesUsed >= 2" data-testid="worst-roll">
77            <div class="rv-mono text-3xl font-extrabold rv-bad leading-none">{{ gameSummary.worstRoll.diceRoll }}</div>
78            <div class="rv-label mt-1">worst roll · {{ gameSummary.worstRoll.diceOutcome }}</div>
79          </div>
80        </div>
81      </div>
82 
83      <!-- The history you wrote — the Spine itself, exactly as it filled in during
84           the run. Read-only here: no live "▷ now" present marker, no "the timeline
85           trembles…" empty state. Same component the player scrolled and tapped on
86           the board, so the verdict's history reads as richly as it did in play —
87           valence dots, ⚡/⚑ badges, the roll, and the Δ equation all carry over. -->
88      <div v-if="timeline.length > 0" class="mt-6">
89        <TimelineLedger readonly />
90      </div>
91 
92      <div class="mt-9 border-t rv-line pt-6 flex items-center gap-3 flex-wrap">
93        <button ref="playAgainRef" type="button" data-testid="play-again-button" class="rv-btn rv-btn--primary" @click="playAgain">
94          Try a new timeline <span aria-hidden="true">▷</span>
95        </button>
96        <span class="rv-faint text-xs inline-flex items-center gap-1.5">
97          <span class="rv-dot" :class="isVictory ? 'rv-dot--ok' : 'rv-dot--bad'" aria-hidden="true" /> this timeline is written.
98        </span>
99      </div>
100    </div>
101  </div>
102</template>
103 
104<script setup lang="ts">
105/**
106 * EndGameScreen — the mission debrief. A full-bleed takeover (not a modal card):
107 * verdict line, the Chronicle epilogue + big-number stat trio, and the history you
108 * wrote. All stats derive from the real resolved turns.
109 */
110import { ref, computed, watch, nextTick } from 'vue'
111import { useGameStore } from '~/stores/game'
112import { usePrefersReducedMotion } from '~/composables/usePrefersReducedMotion'
113 
114const gameStore = useGameStore()
115const reduced = usePrefersReducedMotion()
116 
117const headingId = `end-game-heading-${Math.random().toString(36).slice(2, 11)}`
118 
119// Modal focus management: it's a true takeover (aria-modal), so when it opens we
120// move focus to the VERDICT heading (tabindex=-1: announced, focusable, outside
121// the Tab cycle), trap Tab inside, and restore focus when the run ends. Focusing
122// the heading — not the bottom Play Again button — also means the screen opens at
123// the top: the verdict and the Chronicle epilogue are the first things seen, not
124// scrolled past below the fold.
125const dialogRef = ref<HTMLElement | null>(null)
126const headingRef = ref<HTMLElement | null>(null)
127const playAgainRef = ref<HTMLElement | null>(null)
128let prevFocus: HTMLElement | null = null
129 
130watch(() => gameStore.gameStatus, async (s) => {
131    if (typeof document === 'undefined') return
132    if (s === 'victory' || s === 'defeat') {
133        prevFocus = document.activeElement as HTMLElement | null
134        await nextTick()
135        if (dialogRef.value) dialogRef.value.scrollTop = 0
136        headingRef.value?.focus()
137    } else if (prevFocus) {
138        prevFocus.focus?.()
139        prevFocus = null
140    }
141})
142 
143function onKeydown(e: KeyboardEvent) {
144    if (e.key !== 'Tab' || !dialogRef.value) return
145    const focusables = dialogRef.value.querySelectorAll<HTMLElement>(
146        'a[href], button:not([disabled]), input:not([disabled]), [tabindex]:not([tabindex="-1"])'
147    )
148    if (!focusables.length) return
149    const first = focusables[0]
150    const last = focusables[focusables.length - 1]
151    const active = document.activeElement
152    if (e.shiftKey && active === first) { e.preventDefault(); last.focus() }
153    else if (!e.shiftKey && active === last) { e.preventDefault(); first.focus() }
154}
155 
156const isVictory = computed(() => gameStore.gameStatus === 'victory')
157const victoryEfficiency = computed(() => gameStore.getVictoryEfficiency())
158 
159// The verdict never deflates: spending every message is reframed as "Hard-won," not
160// the limp "Standard." Only the laudatory tiers keep their rating as an adjective.
161const victoryPhrase = computed(() => {
162    const rating = victoryEfficiency.value?.efficiencyRating
163    if (!rating) return 'Victory'
164    return rating === 'Standard' ? 'Hard-won victory' : `${rating} victory`
165})
166const messagesUsed = computed(() => 5 - gameStore.remainingMessages)
167const gameSummary = computed(() => gameStore.gameSummary)
168const timeline = computed(() => gameStore.timelineEvents)
169const chronicle = computed(() => gameStore.chronicle)
170// The epilogue (terminal telling) is still being written — show the wait, never the
171// prior turn's stale telling. The cross-fade mirrors Chronicle.vue and is dropped
172// under prefers-reduced-motion (the empty name disables the Transition's classes).
173const epiloguePending = computed(() => gameStore.epiloguePending)
174const epilogueTransition = computed(() => (reduced.value ? '' : 'epilogue'))
175 
176// The keepsake: the player's verbatim messages, paired with whom/when they reached.
177const dispatches = computed(() => {
178    const users = gameStore.messageHistory.filter(m => m.sender === 'user')
179    const events = gameStore.timelineEvents
180    return users.map((m, i) => ({
181        text: m.text,
182        figure: m.figureName || events[i]?.figureName || 'the past',
183        era: events[i]?.era || ''
184    }))
185})
186 
187// The page owns the FULL reset (store + figure input + composer), so Play Again
188// emits instead of resetting the store directly — the two reset paths used to
189// diverge here, leaving the previous run's figure stranded in the input.
190const emit = defineEmits<{ 'play-again': [] }>()
191const playAgain = () => {
192    emit('play-again')
193}
194</script>
195 
196<style scoped>
197/* The epilogue reveal — the terminal telling cross-fades in over the "final account…"
198   wait, the same gentle opacity fade Chronicle.vue uses for a rewrite. Gated by the
199   transition NAME (empty under prefers-reduced-motion), so reduced-motion gets an
200   instant swap with no classes attached. */
201.epilogue-enter-active,
202.epilogue-leave-active {
203    transition: opacity var(--rv-dur-3) var(--rv-ease);
204}
205.epilogue-enter-from,
206.epilogue-leave-to {
207    opacity: 0;
208}
⋯ 52 lines hidden (lines 209–260)209 
210/* Win and loss share the page frame but not its mood. The win is illuminated — a warm
211   wash blooms from the top; the loss is a colder, dimmer ground that has settled back. */
212.end-screen { background: var(--rv-bg); animation: end-in var(--rv-dur-3) var(--rv-ease) both; }
213@keyframes end-in { from { opacity: 0; } to { opacity: 1; } }
214@media (prefers-reduced-motion: reduce) { .end-screen { animation: none; } }
215.end--win {
216    background:
217        radial-gradient(135% 70% at 50% -12%, color-mix(in srgb, var(--rv-accent) 13%, transparent), transparent 68%),
218        var(--rv-bg);
219}
220.end--loss {
221    background:
222        radial-gradient(135% 70% at 50% -12%, color-mix(in srgb, var(--rv-bad) 6%, transparent), transparent 60%),
223        var(--rv-tint);
224}
225 
226/* The struck seal — the verdict's emblem. The win seal glows like fresh sealing wax;
227   the loss seal is a cold, flat stamp. */
228.verdict-seal {
229    display: inline-grid;
230    place-items: center;
231    width: 60px;
232    height: 60px;
233    border-radius: 50%;
234    border: 2px solid;
235    font-size: 1.6rem;
236    line-height: 1;
237}
238.verdict-seal.is-win {
239    color: var(--rv-accent);
240    border-color: var(--rv-accent);
241    box-shadow:
242        0 0 0 5px color-mix(in srgb, var(--rv-accent) 12%, transparent),
243        0 0 30px color-mix(in srgb, var(--rv-accent) 32%, transparent);
244    animation: seal-strike 0.6s var(--rv-ease-spring) both;
245}
246.verdict-seal.is-loss {
247    color: var(--rv-faint);
248    border-color: var(--rv-line);
249    box-shadow: inset 0 0 0 4px color-mix(in srgb, var(--rv-faint) 8%, transparent);
250}
251 
252@keyframes seal-strike {
253    0% { opacity: 0; transform: scale(.5) rotate(-12deg); }
254    60% { transform: scale(1.12) rotate(3deg); }
255    100% { opacity: 1; transform: scale(1) rotate(0); }
256}
257@media (prefers-reduced-motion: reduce) {
258    .verdict-seal.is-win { animation: none; }
259}
260</style>

Tests that pin the behavior

Two suites. The store tests are the discriminating ones — they'd fail if the flag were never set, never cleared, or set for a non-terminal turn.

Pending during the in-flight terminal refresh; cleared on resolve (epilogue stored) and on failure (prior telling kept); not set mid-run; cleared by reset.

tests/unit/stores/game.spec.ts · 1473 lines

tests/unit/stores/game.spec.ts1473 lines · TypeScript

⋯ 470 lines hidden (lines 1–470)1import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
2import { flushPromises } from '@vue/test-utils'
3import { setActivePinia, createPinia } from 'pinia'
4import { useGameStore, REVEAL } from '../../../stores/game'
5import { DiceOutcome } from '../../../utils/dice'
6 
7/**
* Builds a successful /api/send-message response. Overrides are merged into data.
*/
10function okResponse(over: Record<string, unknown> = {}) {
  return {
      success: true,
      data: {
          figure: { name: 'Nikola Tesla', era: 'New York, 1900', descriptor: 'Electrical inventor' },
          characterResponse: { message: 'A bold notion!', action: 'Builds a resonant transmitter' },
          diceRoll: 14,
          diceOutcome: 'Success',
          timeline: { headline: 'Wireless power demonstrated', detail: 'Cities begin to electrify early', era: 'New York, 1900', progressChange: 20, valence: 'positive' },
          error: null,
          ...over
      }
  }
23}
24 
25describe('game store', () => {
  let store: ReturnType<typeof useGameStore>
  let fetchMock: ReturnType<typeof vi.fn>
28 
  beforeEach(() => {
      setActivePinia(createPinia())
      store = useGameStore()
      fetchMock = vi.fn()
      vi.stubGlobal('$fetch', fetchMock)
      // Pre-seed the run id so AI actions don't fire a begin-run (POST /api/run)
      // fetch ahead of the call under test. The run-id block below nulls it to
      // exercise server-side minting explicitly.
      store.runId = 'test-run'
      // #73 requires a grounded, deceased figure to contact. Most sendMessage tests
      // exercise the turn pipeline, not the contact gate, so default to a resolved
      // deceased figure with no chosen year (contactLiveness 'unknown', permissive).
      // Gate-specific tests below override figureGrounding / contactWhen directly.
      store.figureGrounding = {
          name: 'Nikola Tesla', resolved: true,
          born: { year: 1856, bce: false, signed: 1856, display: '1856' },
          died: { year: 1943, bce: false, signed: 1943, display: '1943' }
      } as never
  })
48 
  afterEach(() => {
      vi.unstubAllGlobals()
      vi.restoreAllMocks()
  })
53 
  describe('initial state', () => {
      it('starts a fresh run', () => {
          expect(store.remainingMessages).toBe(5)
          expect(store.gameStatus).toBe('playing')
          expect(store.objectiveProgress).toBe(0)
          expect(store.messageHistory).toEqual([])
          expect(store.timelineEvents).toEqual([])
          expect(store.figures).toEqual([])
          expect(store.canSendMessage).toBe(true)
      })
  })
65 
  describe('progress + status resolution', () => {
      it('clamps progress between 0 and 100', () => {
          store.applyProgress(150)
          expect(store.objectiveProgress).toBe(100)
          store.applyProgress(-999)
          expect(store.objectiveProgress).toBe(0)
      })
73 
      it('decrementMessages does not, by itself, end the game', () => {
          store.decrementMessages()
          expect(store.remainingMessages).toBe(4)
          expect(store.gameStatus).toBe('playing')
      })
79 
      it('resolves victory the moment progress hits 100', () => {
          store.objectiveProgress = 100
          store.resolveGameStatus()
          expect(store.gameStatus).toBe('victory')
      })
85 
      it('resolves defeat only once messages run out unmet', () => {
          store.remainingMessages = 0
          store.objectiveProgress = 50
          store.resolveGameStatus()
          expect(store.gameStatus).toBe('defeat')
      })
92 
      it('prefers victory over defeat on the final message', () => {
          store.remainingMessages = 0
          store.objectiveProgress = 100
          store.resolveGameStatus()
          expect(store.gameStatus).toBe('victory')
      })
99 
      it('stays playing while messages remain and the objective is unmet', () => {
          store.remainingMessages = 3
          store.objectiveProgress = 50
          store.resolveGameStatus()
          expect(store.gameStatus).toBe('playing')
      })
  })
107 
  describe('figures', () => {
      it('registers a new figure and refines it on later contact', () => {
          store.registerFigure({ name: 'Cleopatra', era: '', descriptor: '' })
          expect(store.figures).toHaveLength(1)
112 
          store.registerFigure({ name: 'Cleopatra', era: 'Alexandria, 40 BC', descriptor: 'Queen of Egypt' })
          expect(store.figures).toHaveLength(1)
          expect(store.figures[0].era).toBe('Alexandria, 40 BC')
          expect(store.figures[0].descriptor).toBe('Queen of Egypt')
      })
  })
119 
  describe('timeline ledger', () => {
      it('derives valence from the progress change when not given', () => {
          store.addTimelineEvent({ figureName: 'X', era: 'e', headline: 'h', detail: 'd', diceRoll: 5, diceOutcome: DiceOutcome.FAILURE, progressChange: -5 })
          store.addTimelineEvent({ figureName: 'Y', era: 'e', headline: 'h', detail: 'd', diceRoll: 16, diceOutcome: DiceOutcome.SUCCESS, progressChange: 12 })
          store.addTimelineEvent({ figureName: 'Z', era: 'e', headline: 'h', detail: 'd', diceRoll: 10, diceOutcome: DiceOutcome.NEUTRAL, progressChange: 0 })
125 
          expect(store.timelineEvents.map(e => e.valence)).toEqual(['negative', 'positive', 'neutral'])
      })
  })
129 
  describe('conversation threads', () => {
      it('keeps each figure’s thread independent', () => {
          store.addUserMessage('To Tesla', 'Tesla')
          store.addAIMessage('From Tesla', 'Tesla')
          store.addUserMessage('To Cleopatra', 'Cleopatra')
135 
          expect(store.conversationWith('Tesla')).toHaveLength(2)
          expect(store.conversationWith('Cleopatra')).toHaveLength(1)
      })
139 
      it('carries the continuity verdict onto the figure turn (issue #62)', () => {
          store.addAIMessageWithData({ text: 'It is done.', sender: 'ai', figureName: 'Caesar', continuity: 'builds' })
          expect(store.conversationWith('Caesar')[0].continuity).toBe('builds')
      })
  })
145 
  describe('sendMessage — conducted reveal cadence (animated)', () => {
      // In a browser with motion allowed, a resolved turn releases its beats one at
      // a time: suspense → die + reply → swing → ledger node. We stub matchMedia
      // (motion on) + fake timers and step through. (The default test env has no
      // matchMedia, so every OTHER test takes the instant, atomic path.)
      beforeEach(() => {
          vi.stubGlobal('window', { matchMedia: () => ({ matches: false }) })
          vi.useFakeTimers()
      })
      afterEach(() => vi.useRealTimers())
156 
      it('staggers the beats: suspense → reply → swing → node', async () => {
          fetchMock.mockResolvedValue(okResponse())
          const p = store.sendMessage('Light the world', 'Nikola Tesla')
160 
          // Through the fetch and into the suspense hold — nothing revealed yet.
          await vi.advanceTimersByTimeAsync(0)
          expect(store.messageHistory.some((m) => m.sender === 'ai')).toBe(false)
          expect(store.isLoading).toBe(true)
165 
          // Beat 1 (after the hold): the reply lands and the die stops rolling, but
          // the swing and the ledger node have NOT landed.
          await vi.advanceTimersByTimeAsync(REVEAL.suspense)
          expect(store.messageHistory.some((m) => m.sender === 'ai')).toBe(true)
          expect(store.isLoading).toBe(false)
          expect(store.objectiveProgress).toBe(0)
          expect(store.timelineEvents.length).toBe(0)
173 
          // Beat 2: the timeline shift lands; the node still hasn't.
          await vi.advanceTimersByTimeAsync(REVEAL.swing)
          expect(store.objectiveProgress).toBe(20)
          expect(store.timelineEvents.length).toBe(0)
178 
          // Beat 3: the node drops and the turn resolves.
          await vi.advanceTimersByTimeAsync(REVEAL.node)
          expect(store.timelineEvents.length).toBe(1)
          expect(await p).toBe(true)
      })
184 
      it('aborts cleanly if the run is reset mid-reveal', async () => {
          fetchMock.mockResolvedValue(okResponse())
          const p = store.sendMessage('Light the world', 'Nikola Tesla')
          await vi.advanceTimersByTimeAsync(REVEAL.suspense) // reply landed, swing pending
          store.resetGame() // bump the epoch mid-cascade
          await vi.advanceTimersByTimeAsync(REVEAL.swing + REVEAL.node)
          expect(await p).toBe(false)
          // The reset wiped state; the aborted reveal added nothing into the new run.
          expect(store.timelineEvents.length).toBe(0)
          expect(store.objectiveProgress).toBe(0)
      })
  })
197 
  describe('sendMessage', () => {
      it('folds a successful turn into messages, ledger, progress, and figures', async () => {
          fetchMock.mockResolvedValue(okResponse())
201 
          await store.sendMessage('Light the world wirelessly', 'Nikola Tesla')
203 
          // The turn hits /api/send-message (a resolved turn also fires a
          // non-blocking /api/chronicle refresh — see the chronicle suite below).
          expect(fetchMock).toHaveBeenCalledWith('/api/send-message', expect.objectContaining({ method: 'POST' }))
          expect(store.activeFigureName).toBe('Nikola Tesla')
208 
          // user + figure turns
          expect(store.messageHistory).toHaveLength(2)
          const ai = store.messageHistory[1]
          expect(ai.sender).toBe('ai')
          expect(ai.diceRoll).toBe(14)
          expect(ai.characterAction).toBe('Builds a resonant transmitter')
          expect(ai.timelineImpact).toBe('Cities begin to electrify early')
          expect(ai.figureName).toBe('Nikola Tesla')
217 
          // ledger + progress + figure cache
          expect(store.timelineEvents).toHaveLength(1)
          expect(store.timelineEvents[0].headline).toBe('Wireless power demonstrated')
          expect(store.timelineEvents[0].valence).toBe('positive')
          expect(store.objectiveProgress).toBe(20)
          expect(store.figures[0]).toMatchObject({ name: 'Nikola Tesla', era: 'New York, 1900' })
224 
          expect(store.remainingMessages).toBe(4)
          expect(store.isLoading).toBe(false)
      })
228 
      it('overwrites the momentum meter from the server’s advanced value (issue #62)', async () => {
          fetchMock.mockResolvedValue(okResponse({ momentum: 3 }))
          await store.sendMessage('Build on what he asked', 'Nikola Tesla')
          expect(store.momentum).toBe(3)
      })
234 
      it('records a neutral (0%) turn instead of letting it vanish', async () => {
          fetchMock.mockResolvedValue(okResponse({
              timeline: { headline: 'Nothing much changes', detail: 'A pause in history', era: 'x', progressChange: 0, valence: 'neutral' }
          }))
239 
          await store.sendMessage('Hmm', 'Tesla')
241 
          expect(store.timelineEvents).toHaveLength(1)
          expect(store.timelineEvents[0].valence).toBe('neutral')
          expect(store.objectiveProgress).toBe(0)
      })
246 
      it('refuses to send without a target figure', async () => {
          await store.sendMessage('Hello?', '')
          expect(fetchMock).not.toHaveBeenCalled()
          expect(store.error).toBeTruthy()
          expect(store.messageHistory).toHaveLength(0)
          expect(store.remainingMessages).toBe(5)
      })
254 
      it('refunds the message and drops the dangling prompt on a network error', async () => {
          fetchMock.mockRejectedValue(new Error('network down'))
257 
          await store.sendMessage('A message that fails', 'Tesla')
259 
          expect(store.error).toBeTruthy()
          expect(store.remainingMessages).toBe(5)
          expect(store.messageHistory).toHaveLength(0)
          expect(store.gameStatus).toBe('playing')
      })
265 
      it('refunds the message when the server reports a graceful failure (success:false)', async () => {
          fetchMock.mockResolvedValue({
              success: false,
              message: 'Failed to generate character response',
              data: { userMessage: 'x', error: 'Character AI failed' }
          })
272 
          const resolved = await store.sendMessage('A doomed dispatch', 'Tesla')
274 
          expect(resolved).toBe(false)
          expect(store.error).toBe('Character AI failed')
          expect(store.remainingMessages).toBe(5)
          expect(store.messageHistory).toHaveLength(0)
          expect(store.timelineEvents).toHaveLength(0)
      })
281 
      it('a moderation block shows a distinct notice (not an infra error) and refunds the turn', async () => {
          fetchMock.mockResolvedValue({
              success: false,
              message: 'Blocked by moderation',
              data: {
                  userMessage: 'x',
                  blocked: true,
                  moderationReason: 'This dispatch was blocked by content moderation and cannot be sent.',
                  error: 'This dispatch was blocked by content moderation and cannot be sent.'
              }
          })
293 
          const resolved = await store.sendMessage('Synthesize a nerve agent at scale', 'Fritz Haber')
295 
          expect(resolved).toBe(false)
          // Distinct from an infra hiccup: the block banner is set, `error` is not.
          expect(store.moderationNotice).toContain('blocked by content moderation')
          expect(store.error).toBeNull()
          expect(store.remainingMessages).toBe(5) // refunded, never burned
          expect(store.messageHistory).toHaveLength(0)
      })
303 
      it('a graceful failure on the FINAL message does not convert to instant defeat', async () => {
          store.remainingMessages = 1
          store.objectiveProgress = 60
          fetchMock.mockResolvedValue({
              success: false,
              message: 'Failed to generate timeline analysis',
              data: { userMessage: 'x', diceRoll: 17, diceOutcome: 'Success', error: 'Timeline AI failed' }
          })
312 
          await store.sendMessage('The last word', 'Tesla')
314 
          // The dispatch is refunded, the run lives on — an infra hiccup is not a loss.
          expect(store.remainingMessages).toBe(1)
          expect(store.gameStatus).toBe('playing')
      })
319 
      it('reports resolution truthfully: true when a turn lands, false when refunded', async () => {
          fetchMock.mockResolvedValueOnce(okResponse())
          expect(await store.sendMessage('First', 'Tesla')).toBe(true)
323 
          store.lastMessageTime = null // clear the rate-limit window
          fetchMock.mockRejectedValueOnce(new Error('down'))
          expect(await store.sendMessage('Second', 'Tesla')).toBe(false)
      })
328 
      it('arms the stake only on the final message — never earlier', async () => {
          fetchMock.mockResolvedValue(okResponse())
331 
          await store.sendMessage('Early gambit', 'Tesla', { stake: true })
          let body = fetchMock.mock.calls[0][1].body
          expect(body.stake).toBe(false) // 5 messages left: the stake is refused
335 
          store.lastMessageTime = null
          store.remainingMessages = 1
          await store.sendMessage('The last stand', 'Tesla', { stake: true })
          body = fetchMock.mock.calls.find((c: unknown[]) => c[0] === '/api/send-message' && (c[1] as { body: { message: string } }).body.message === 'The last stand')![1].body
          expect(body.stake).toBe(true)
      })
342 
      it('refuses the stake when the final throw can win unstaked (no dominance trap)', async () => {
          store.remainingMessages = 1
          store.objectiveProgress = 60 // need 40 ≤ the 50-point fuse — winnable clean
          fetchMock.mockResolvedValue(okResponse())
347 
          await store.sendMessage('One clean throw', 'Tesla', { stake: true })
349 
          const body = fetchMock.mock.calls[0][1].body
          expect(body.stake).toBe(false)
      })
353 
      it('records the staked badge and the turn’s grounded year on ledger AND thread', async () => {
          store.contactWhen = 1900 // within the default grounded figure's lifetime
          fetchMock.mockResolvedValue(okResponse({
              staked: true,
              craft: 'sharp',
              naturalRoll: 12,
              rollModifier: 1,
              timeline: { headline: 'All in', detail: 'Everything on one throw', era: 'x', progressChange: 60, baseProgressChange: 30, valence: 'positive', anachronism: 'far-ahead' }
          }))
363 
          await store.sendMessage('Stake it all', 'Tesla')
365 
          const evt = store.timelineEvents[0]
          expect(evt.staked).toBe(true)
          expect(evt.craft).toBe('sharp')
          expect(evt.whenSigned).toBe(1900)
          expect(evt.baseProgressChange).toBe(30)
          const ai = store.messageHistory[1]
          expect(ai.naturalRoll).toBe(12)
          expect(ai.rollModifier).toBe(1)
          // The thread message carries the stake too — the reveal's equation must
          // attribute the doubling to the ⚑, not to the anachronism tier.
          expect(ai.staked).toBe(true)
      })
378 
      it('does NOT prematurely defeat: a winning final message is a victory', async () => {
          store.remainingMessages = 1
          store.objectiveProgress = 90
          fetchMock.mockResolvedValue(okResponse({
              timeline: { headline: 'The last push', detail: 'It is done', era: 'x', progressChange: 20, valence: 'positive' }
          }))
385 
          await store.sendMessage('The decisive word', 'Tesla')
387 
          expect(store.objectiveProgress).toBe(100)
          expect(store.remainingMessages).toBe(0)
          expect(store.gameStatus).toBe('victory')
      })
392 
      it('declares defeat when the final message falls short', async () => {
          store.remainingMessages = 1
          store.objectiveProgress = 10
          fetchMock.mockResolvedValue(okResponse({
              timeline: { headline: 'Not enough', detail: 'History resists', era: 'x', progressChange: 5, valence: 'positive' }
          }))
399 
          await store.sendMessage('A last try', 'Tesla')
401 
          expect(store.objectiveProgress).toBe(15)
          expect(store.remainingMessages).toBe(0)
          expect(store.gameStatus).toBe('defeat')
      })
  })
407 
  describe('living chronicle (refreshChronicle)', () => {
      const telling = { title: 'The Peace That Held', paragraphs: ['In 1878, Bismarck chose trade.', 'By 1914, no war came.'] }
410 
      function seedOneChange() {
          store.addTimelineEvent({
              figureName: 'Bismarck', era: '1878', headline: 'Bismarck chooses trade',
              detail: 'Alliances soften into commerce.', diceRoll: 16, diceOutcome: DiceOutcome.SUCCESS, progressChange: 20
          })
      }
417 
      it('re-narrates the timeline and stores the telling', async () => {
          seedOneChange()
          fetchMock.mockResolvedValue({ success: true, chronicle: telling })
421 
          await store.refreshChronicle()
423 
          expect(fetchMock).toHaveBeenCalledWith('/api/chronicle', expect.objectContaining({ method: 'POST' }))
          expect(store.chronicle).toEqual(telling)
          expect(store.chronicleLoading).toBe(false)
      })
428 
      it('skips (and clears) when no changes exist to chronicle', async () => {
          store.chronicle = telling
          await store.refreshChronicle()
          expect(fetchMock).not.toHaveBeenCalled()
          expect(store.chronicle).toBeNull()
      })
435 
      it('keeps the prior telling when a refresh fails (never blanks)', async () => {
          seedOneChange()
          store.chronicle = telling
          fetchMock.mockRejectedValue(new Error('chronicler offline'))
440 
          await store.refreshChronicle()
442 
          expect(store.chronicle).toEqual(telling)
          expect(store.chronicleLoading).toBe(false)
      })
446 
      it('fires a non-blocking refresh after a turn actually changes the world', async () => {
          fetchMock.mockResolvedValue(okResponse())
449 
          await store.sendMessage('Light the world wirelessly', 'Nikola Tesla')
          // The refresh is fired but not awaited; aiHeaders is async, so let the
          // microtasks settle before checking the chronicle fetch went out.
          await flushPromises()
454 
          // The refresh is fired (not awaited) once the turn added a ledger entry.
          expect(fetchMock).toHaveBeenCalledWith('/api/chronicle', expect.objectContaining({ method: 'POST' }))
      })
458 
      it('does NOT refresh when a turn fails to change the world', async () => {
          fetchMock.mockRejectedValue(new Error('network down'))
461 
          await store.sendMessage('A message that fails', 'Tesla')
463 
          expect(fetchMock).not.toHaveBeenCalledWith('/api/chronicle', expect.anything())
      })
  })
467 
  // The end screen reads epiloguePending to show "the final account…" while the
  // TERMINAL telling is being written — never the prior turn's stale, pre-ending
  // telling presented as the epilogue (issue #107).
  describe('the epilogue pending flag (terminal chronicle)', () => {
      const epilogue = { title: 'The World Remade', paragraphs: ['And so the timeline was rewritten.'] }
473 
      function deferred<T>() {
          let resolve!: (v: T) => void
          let reject!: (e: unknown) => void
          const promise = new Promise<T>((res, rej) => { resolve = res; reject = rej })
          return { promise, resolve, reject }
      }
480 
      // Route the turn, the epilogue refresh, and the snapshot saves independently so
      // the chronicle refresh can be held in flight.
      function route(chroniclePromise: Promise<unknown>, progressChange = 20) {
          fetchMock.mockImplementation((url: string) => {
              if (url === '/api/chronicle') return chroniclePromise
              if (url === '/api/send-message') return Promise.resolve(okResponse({
                  timeline: { headline: 'The last push', detail: 'It is done', era: 'x', progressChange, valence: 'positive' }
              }))
              return Promise.resolve({ success: true }) // /api/run-save and the rest
          })
      }
492 
      it('marks the epilogue pending while the terminal telling is written, then clears it when the telling lands', async () => {
          store.remainingMessages = 1
          store.objectiveProgress = 90
          const chronicle = deferred<{ success: boolean; chronicle: typeof epilogue }>()
          route(chronicle.promise)
498 
          await store.sendMessage('The decisive word', 'Tesla')
          await flushPromises() // aiHeaders is async; let the non-blocking refresh fire
501 
          expect(store.gameStatus).toBe('victory')
          expect(store.epiloguePending).toBe(true) // the end screen shows "the final account…"
504 
          chronicle.resolve({ success: true, chronicle: epilogue })
          await flushPromises()
507 
          expect(store.epiloguePending).toBe(false)
          expect(store.chronicle).toEqual(epilogue) // the epilogue, not a stale prior telling
      })
511 
      it('clears the pending flag if the terminal refresh fails — falls back, never hangs on loading', async () => {
          store.remainingMessages = 1
          store.objectiveProgress = 90
          const prior = { title: 'The Account So Far', paragraphs: ['the world a turn before the end'] }
          store.chronicle = prior
          const chronicle = deferred<never>()
          route(chronicle.promise)
519 
          await store.sendMessage('The decisive word', 'Tesla')
          await flushPromises()
          expect(store.epiloguePending).toBe(true)
523 
          chronicle.reject(new Error('chronicler offline'))
          await flushPromises()
526 
          expect(store.epiloguePending).toBe(false) // not stuck on the loading state
          expect(store.chronicle).toEqual(prior) // the prior telling is kept (never blanks)
      })
530 
      it('does NOT mark the epilogue pending for a non-terminal turn', async () => {
          store.remainingMessages = 3
          store.objectiveProgress = 10
          route(Promise.resolve({ success: true, chronicle: epilogue }), 5) // a small, non-winning nudge
535 
          await store.sendMessage('A mid-run move', 'Tesla')
          await flushPromises()
538 
          expect(store.gameStatus).toBe('playing')
          expect(store.epiloguePending).toBe(false)
      })
542 
      it('resetGame clears a pending epilogue', () => {
          store.epiloguePending = true
          store.resetGame()
          expect(store.epiloguePending).toBe(false)
      })
  })
⋯ 925 lines hidden (lines 549–1473)549 
  describe('staleness guards (epoch + sequencing)', () => {
      function deferred<T>() {
          let resolve!: (v: T) => void
          let reject!: (e: unknown) => void
          const promise = new Promise<T>((res, rej) => { resolve = res; reject = rej })
          return { promise, resolve, reject }
      }
557 
      it('a reset mid-send drops the stale response instead of haunting the new run', async () => {
          const slow = deferred<ReturnType<typeof okResponse>>()
          fetchMock.mockReturnValue(slow.promise)
561 
          const inFlight = store.sendMessage('From the old world', 'Tesla')
          store.resetGame()
          slow.resolve(okResponse())
          const resolved = await inFlight
566 
          // The dead run's turn finds no purchase in the fresh one.
          expect(resolved).toBe(false)
          expect(store.remainingMessages).toBe(5)
          expect(store.messageHistory).toHaveLength(0)
          expect(store.timelineEvents).toHaveLength(0)
          expect(store.objectiveProgress).toBe(0)
      })
574 
      it('a reset mid-send must not "refund" the new run on failure either', async () => {
          const slow = deferred<never>()
          fetchMock.mockReturnValue(slow.promise)
578 
          const inFlight = store.sendMessage('Doomed', 'Tesla')
          store.resetGame()
          store.remainingMessages = 3 // the new run has its own spent counter
          slow.reject(new Error('old run network error'))
          await inFlight
584 
          expect(store.remainingMessages).toBe(3) // untouched by the stale refund
      })
587 
      it('an earlier chronicle rewrite cannot overwrite a later one', async () => {
          store.addTimelineEvent({ figureName: 'X', era: 'e', headline: 'h', detail: 'd', diceRoll: 16, diceOutcome: DiceOutcome.SUCCESS, progressChange: 20 })
590 
          const first = deferred<{ success: boolean; chronicle: { title: string; paragraphs: string[] } }>()
          const second = deferred<{ success: boolean; chronicle: { title: string; paragraphs: string[] } }>()
          fetchMock.mockReturnValueOnce(first.promise).mockReturnValueOnce(second.promise)
594 
          const a = store.refreshChronicle()
          const b = store.refreshChronicle()
          // The LATER telling lands first; the earlier one limps in afterwards.
          second.resolve({ success: true, chronicle: { title: 'The Later Telling', paragraphs: ['b'] } })
          await b
          first.resolve({ success: true, chronicle: { title: 'The Earlier Telling', paragraphs: ['a'] } })
          await a
602 
          expect(store.chronicle?.title).toBe('The Later Telling')
          expect(store.chronicleLoading).toBe(false)
      })
606 
      it('a reset mid-chronicle keeps the old run’s telling out of the new run', async () => {
          store.addTimelineEvent({ figureName: 'X', era: 'e', headline: 'h', detail: 'd', diceRoll: 16, diceOutcome: DiceOutcome.SUCCESS, progressChange: 20 })
          const slow = deferred<{ success: boolean; chronicle: { title: string; paragraphs: string[] } }>()
          fetchMock.mockReturnValue(slow.promise)
611 
          const inFlight = store.refreshChronicle()
          store.resetGame()
          slow.resolve({ success: true, chronicle: { title: 'A Ghost Epilogue', paragraphs: ['boo'] } })
          await inFlight
616 
          expect(store.chronicle).toBeNull()
      })
619 
      it('out-of-order grounding keeps the latest figure’s dossier', async () => {
          const slowA = deferred<Record<string, unknown>>()
          const fastB = deferred<Record<string, unknown>>()
          fetchMock.mockReturnValueOnce(slowA.promise).mockReturnValueOnce(fastB.promise)
624 
          const a = store.groundActiveFigure('Aristotle')
          const b = store.groundActiveFigure('Bismarck')
          fastB.resolve({ name: 'Otto von Bismarck', resolved: true, born: { year: 1815, bce: false, signed: 1815, display: '1815' }, died: { year: 1898, bce: false, signed: 1898, display: '1898' }, living: false })
          await b
          slowA.resolve({ name: 'Aristotle', resolved: true, born: { year: 384, bce: true, signed: -384, display: '384 BC' }, died: { year: 322, bce: true, signed: -322, display: '322 BC' }, living: false })
          await a
631 
          expect(store.figureGrounding?.name).toBe('Otto von Bismarck')
          expect(store.groundingLoading).toBe(false)
      })
635 
      it('clearGrounding drops the dossier instantly and a lookup still in flight finds no purchase', async () => {
          const slow = deferred<Record<string, unknown>>()
          fetchMock.mockReturnValue(slow.promise)
639 
          const inFlight = store.groundActiveFigure('Napoleon')
          store.clearGrounding() // the player typed a new name — the old dossier dies NOW
          slow.resolve({ name: 'Napoleon', resolved: true, born: { year: 1769, bce: false, signed: 1769, display: '1769' }, died: { year: 1821, bce: false, signed: 1821, display: '1821' }, living: false })
          await inFlight
644 
          expect(store.figureGrounding).toBeNull()
          expect(store.contactWhen).toBeNull()
          expect(store.groundingLoading).toBe(false)
      })
649 
      it('study records the moment it was asked for, not where the slider moved mid-flight', async () => {
          store.figureGrounding = {
              name: 'Cleopatra', resolved: true,
              born: { year: 69, bce: true, signed: -69, display: '69 BC' },
              died: { year: 30, bce: true, signed: -30, display: '30 BC' }, living: false
          } as never
          store.setContactWhen(-40)
          const slow = deferred<{ success: boolean; study: Record<string, unknown> }>()
          fetchMock.mockReturnValue(slow.promise)
659 
          const inFlight = store.studyActiveFigure()
          store.setContactWhen(-35) // the player keeps exploring while the Archivist works
          slow.resolve({ success: true, study: { atThisMoment: 'x', grasp: ['a'], reaching: ['b'], cannotYetKnow: 'c' } })
          await inFlight
664 
          // The brief is FOR -40; recording -35 would mislabel it and hide Re-study.
          expect(store.studyWhen).toBe(-40)
          expect(store.studyFor).toBe('Cleopatra')
      })
  })
670 
  describe('victory efficiency', () => {
      it('rates an early win and reports messages saved', () => {
          store.gameStatus = 'victory'
          store.remainingMessages = 4
          const eff = store.getVictoryEfficiency()
          expect(eff?.efficiencyRating).toBe('Legendary')
          expect(eff?.messagesUsed).toBe(1)
          expect(eff?.isEarlyVictory).toBe(true)
      })
680 
      it('returns null when not a victory', () => {
          store.gameStatus = 'playing'
          expect(store.getVictoryEfficiency()).toBeNull()
      })
  })
686 
  describe('resetGame', () => {
      it('returns everything to a fresh run', () => {
          store.remainingMessages = 1
          store.objectiveProgress = 80
          store.momentum = 3
          store.gameStatus = 'defeat'
          store.messageHistory.push({ text: 'x', sender: 'user', timestamp: new Date() })
          store.timelineEvents.push({ id: '1', figureName: 'x', era: 'e', headline: 'h', detail: 'd', diceRoll: 1, diceOutcome: DiceOutcome.FAILURE, progressChange: -1, valence: 'negative', timestamp: new Date() })
          store.figures.push({ name: 'x', era: 'e', descriptor: 'd' })
          store.activeFigureName = 'x'
          store.chronicle = { title: 'A History', paragraphs: ['It happened.'] }
          store.figureStudy = { atThisMoment: 'x', grasp: [], reaching: [], cannotYetKnow: '' }
          store.studyFor = 'x'
          store.studyWhen = 1500
          store.archiveResult = { topic: 't', summary: 's', requires: [], knownSince: '' }
702 
          store.resetGame()
704 
          expect(store.remainingMessages).toBe(5)
          expect(store.objectiveProgress).toBe(0)
          expect(store.momentum).toBe(0)
          expect(store.gameStatus).toBe('playing')
          expect(store.messageHistory).toEqual([])
          expect(store.timelineEvents).toEqual([])
          expect(store.figures).toEqual([])
          expect(store.activeFigureName).toBe('')
          expect(store.chronicle).toBeNull()
          expect(store.figureStudy).toBeNull()
          expect(store.studyFor).toBe('')
          expect(store.studyWhen).toBeNull()
          expect(store.archiveResult).toBeNull()
      })
  })
720 
  describe('objective selection', () => {
      const objective = {
          title: 'Save the Library of Alexandria',
          description: 'Keep the ancient world’s knowledge intact into the modern age.',
          era: 'Alexandria, antiquity',
          icon: '📜'
      }
728 
      it('chooseObjective commits the objective and resets progress', async () => {
          fetchMock.mockResolvedValue({ runsRemaining: 5 })
          store.objectiveProgress = 40
          store.momentum = 2
          store.setError('a stale error')
734 
          const started = await store.chooseObjective(objective)
736 
          expect(started).toBe(true)
          expect(store.currentObjective).toEqual(objective)
          expect(store.objectiveProgress).toBe(0)
          expect(store.momentum).toBe(0)
          expect(store.error).toBeNull()
      })
743 
      it('fetchAIObjective returns a composed objective WITHOUT committing it', async () => {
          fetchMock.mockResolvedValue({ success: true, objective })
746 
          const result = await store.fetchAIObjective()
748 
          expect(fetchMock).toHaveBeenCalledWith('/api/objective', expect.objectContaining({
              method: 'GET',
              headers: expect.objectContaining({ 'x-run-id': expect.any(String) })
          }))
          expect(result).toEqual(objective)
          // The caller previews it, then commits via chooseObjective — not here.
          expect(store.currentObjective).toBeNull()
      })
757 
      it('fetchAIObjective returns null (never throws) when composing fails', async () => {
          fetchMock.mockRejectedValue(new Error('archives offline'))
          expect(await store.fetchAIObjective()).toBeNull()
          expect(store.currentObjective).toBeNull()
      })
763 
      it('fetchAIObjective returns null when the server reports failure', async () => {
          fetchMock.mockResolvedValue({ success: false })
          expect(await store.fetchAIObjective()).toBeNull()
      })
  })
769 
  describe('grounded contacts (who · when · liveness)', () => {
      const cleopatra = {
          name: 'Cleopatra',
          resolved: true,
          description: 'Pharaoh of Egypt from 51 to 30 BC',
          born: { year: 69, bce: true, signed: -69, display: '69 BC' },
          died: { year: 30, bce: true, signed: -30, display: '30 BC' },
          living: false
      }
779 
      it('grounds the active figure and defaults the when inside their lifetime', async () => {
          fetchMock.mockResolvedValue(cleopatra)
782 
          await store.groundActiveFigure('Cleopatra')
784 
          expect(fetchMock).toHaveBeenCalledWith('/api/figure', expect.objectContaining({
              params: { name: 'Cleopatra' },
              headers: expect.objectContaining({ 'x-run-id': expect.any(String) })
          }))
          expect(store.figureGrounding?.resolved).toBe(true)
          expect(store.contactWhen).toBeGreaterThanOrEqual(-69)
          expect(store.contactWhen).toBeLessThanOrEqual(-30)
          expect(store.contactLiveness).toBe('ok')
          expect(store.canContact).toBe(true)
      })
795 
      it('flags a when before birth or after death', async () => {
          fetchMock.mockResolvedValue(cleopatra)
          await store.groundActiveFigure('Cleopatra')
799 
          store.setContactWhen(-200) // 200 BC — long before she was born
          expect(store.contactLiveness).toBe('before-birth')
          expect(store.canContact).toBe(false)
803 
          store.setContactWhen(1990) // long after she died
          expect(store.contactLiveness).toBe('after-death')
          expect(store.canContact).toBe(false)
807 
          store.setContactWhen(-50) // 50 BC — within her life
          expect(store.contactLiveness).toBe('ok')
      })
811 
      it('blocks contact to an unresolved figure — require grounding (#73)', async () => {
          fetchMock.mockResolvedValue({ name: 'Nobody', resolved: false })
          await store.groundActiveFigure('Nobody Atall')
815 
          expect(store.figureGrounding?.resolved).toBe(false)
          expect(store.contactWhen).toBeNull()
          expect(store.contactLiveness).toBe('unresolved')
          expect(store.canContact).toBe(false)
      })
821 
      it('blocks a living figure — deceased only (#72)', async () => {
          fetchMock.mockResolvedValue({
              name: 'Paul McCartney', resolved: true,
              born: { year: 1942, bce: false, signed: 1942, display: '1942' },
              living: true
          })
          await store.groundActiveFigure('Paul McCartney')
829 
          // A figure with no confirmed death is never contactable, at any year.
          store.setContactWhen(1965)
          expect(store.contactLiveness).toBe('living')
          expect(store.canContact).toBe(false)
      })
835 
      it('pins, rescrubs, and clears the contact moment (issue #32)', async () => {
          fetchMock.mockResolvedValue(cleopatra)
          await store.groundActiveFigure('Cleopatra')
839 
          store.setContactMoment({ month: 6, day: 28 })
          expect(store.contactMoment).toEqual({ month: 6, day: 28 })
842 
          // Scrubbing the year keeps the pin — it refines whichever year is chosen.
          store.setContactWhen(-44)
          expect(store.contactMoment).toEqual({ month: 6, day: 28 })
846 
          // A name change clears it with the rest of the dossier.
          store.clearGrounding()
          expect(store.contactMoment).toBeNull()
      })
851 
      it('sends the refined when string + raw moment integers (issue #32)', async () => {
          fetchMock.mockResolvedValue(cleopatra)
          await store.groundActiveFigure('Cleopatra')
          store.setContactWhen(-48)
          store.setContactMoment({ month: 3, day: 15 })
          fetchMock.mockClear()
          fetchMock.mockResolvedValue({ success: false, message: 'x', data: { userMessage: 'm', error: 'x' } })
859 
          await store.sendMessage('Hold court away from the palace today.', 'Cleopatra')
861 
          const body = (fetchMock.mock.calls[0][1] as { body: Record<string, unknown> }).body
          expect(body.when).toBe('March 15, 48 BC')
          expect(body.whenSigned).toBe(-48)
          expect(body.whenMonth).toBe(3)
          expect(body.whenDay).toBe(15)
      })
868 
      it('clears grounding when the figure is cleared', async () => {
          fetchMock.mockResolvedValue(cleopatra)
          await store.groundActiveFigure('Cleopatra')
          await store.groundActiveFigure('')
          expect(store.figureGrounding).toBeNull()
          expect(store.contactWhen).toBeNull()
      })
876 
      it('refuses to send to someone outside their lifetime', async () => {
          fetchMock.mockResolvedValue(cleopatra)
          await store.groundActiveFigure('Cleopatra')
          store.setContactWhen(-300) // before birth
          fetchMock.mockClear()
882 
          await store.sendMessage('Beware the Ides', 'Cleopatra')
884 
          expect(fetchMock).not.toHaveBeenCalled() // never reached /api/send-message
          expect(store.error).toMatch(/born yet/i)
          expect(store.messageHistory).toHaveLength(0)
          expect(store.remainingMessages).toBe(5)
      })
890 
      it('refuses to send to a living figure — deceased only (#72)', async () => {
          fetchMock.mockResolvedValue({
              name: 'Paul McCartney', resolved: true,
              born: { year: 1942, bce: false, signed: 1942, display: '1942' },
              living: true
          })
          await store.groundActiveFigure('Paul McCartney')
          store.setContactWhen(1965)
          fetchMock.mockClear()
900 
          await store.sendMessage('Write a song about the timeline', 'Paul McCartney')
902 
          expect(fetchMock).not.toHaveBeenCalled() // gated before the network
          expect(store.error).toMatch(/still living/i)
          expect(store.messageHistory).toHaveLength(0)
          expect(store.remainingMessages).toBe(5) // no message burned
      })
908 
      it('refuses to send to an unresolved figure — require grounding (#73)', async () => {
          fetchMock.mockResolvedValue({ name: 'Nobody', resolved: false })
          await store.groundActiveFigure('Nobody Atall')
          fetchMock.mockClear()
913 
          await store.sendMessage('Into the void', 'Nobody Atall')
915 
          expect(fetchMock).not.toHaveBeenCalled() // gated before the network
          expect(store.error).toMatch(/no historical record/i)
          expect(store.messageHistory).toHaveLength(0)
          expect(store.remainingMessages).toBe(5) // no message burned
      })
  })
922 
  describe('contactAge (so the player skips the lifetime math)', () => {
      const cleopatra = {
          name: 'Cleopatra', resolved: true,
          born: { year: 69, bce: true, signed: -69, display: '69 BC' },
          died: { year: 30, bce: true, signed: -30, display: '30 BC' },
          living: false
      }
930 
      it('reports the age at the chosen year for a grounded figure', () => {
          store.figureGrounding = cleopatra as never
          store.setContactWhen(-50) // 50 BC
          expect(store.contactAge).toBe(19) // -50 - (-69)
      })
936 
      it('is 0 in the birth year', () => {
          store.figureGrounding = cleopatra as never
          store.setContactWhen(-69)
          expect(store.contactAge).toBe(0)
      })
942 
      it('corrects for the missing year zero across the BC→AD boundary', () => {
          store.figureGrounding = {
              name: 'Augustus', resolved: true,
              born: { year: 63, bce: true, signed: -63, display: '63 BC' },
              died: { year: 14, bce: false, signed: 14, display: '14' },
              living: false
          } as never
          store.setContactWhen(14) // AD 14
          expect(store.contactAge).toBe(76) // 14 - (-63) - 1 (no year zero)
      })
953 
      it('handles a modern living figure', () => {
          store.figureGrounding = {
              name: 'Paul McCartney', resolved: true,
              born: { year: 1942, bce: false, signed: 1942, display: '1942' }, living: true
          } as never
          store.setContactWhen(1965)
          expect(store.contactAge).toBe(23)
      })
962 
      it('is null when the figure is unresolved or has no birth year', () => {
          store.figureGrounding = { name: 'Nobody', resolved: false } as never
          store.setContactWhen(1500)
          expect(store.contactAge).toBeNull()
967 
          store.figureGrounding = null
          expect(store.contactAge).toBeNull()
      })
971 
      it('is null before birth rather than a negative age', () => {
          store.figureGrounding = cleopatra as never
          store.setContactWhen(-200) // long before she was born
          expect(store.contactAge).toBeNull()
      })
  })
978 
  describe('the Archive — studyActiveFigure (prototype)', () => {
      const cleopatra = {
          name: 'Cleopatra', resolved: true,
          description: 'Pharaoh of Egypt', extract: 'Cleopatra was the last active ruler of Ptolemaic Egypt.',
          born: { year: 69, bce: true, signed: -69, display: '69 BC' },
          died: { year: 30, bce: true, signed: -30, display: '30 BC' }, living: false
      }
      const study = {
          atThisMoment: 'Queen at the height of her power.',
          grasp: ['statecraft', 'Hellenistic science'],
          reaching: ['securing Egypt against Rome'],
          cannotYetKnow: 'the fall of the Roman Republic'
      }
992 
      it('studies a grounded figure and stores the brief', async () => {
          store.figureGrounding = cleopatra as never
          store.setContactWhen(-40)
          fetchMock.mockResolvedValue({ success: true, study })
997 
          await store.studyActiveFigure()
999 
          expect(fetchMock).toHaveBeenCalledWith('/api/research', expect.objectContaining({ method: 'POST' }))
          expect(store.figureStudy).toEqual(study)
          expect(store.studyFor).toBe('Cleopatra')
          expect(store.studyLoading).toBe(false)
      })
1005 
      it('caches per figure + year (no refetch on a second study at the same moment)', async () => {
          store.figureGrounding = cleopatra as never
          store.setContactWhen(-40)
          fetchMock.mockResolvedValue({ success: true, study })
          await store.studyActiveFigure()
          fetchMock.mockClear()
1012 
          await store.studyActiveFigure()
          expect(fetchMock).not.toHaveBeenCalled()
      })
1016 
      it('re-studies the figure when the contact year changes', async () => {
          store.figureGrounding = cleopatra as never
          store.setContactWhen(-40)
          fetchMock.mockResolvedValue({ success: true, study })
          await store.studyActiveFigure()
          expect(store.studyWhen).toBe(-40)
          fetchMock.mockClear()
1024 
          store.setContactWhen(-35) // move the slider
          await store.studyActiveFigure()
1027 
          expect(fetchMock).toHaveBeenCalledWith('/api/research', expect.objectContaining({ method: 'POST' }))
          expect(store.studyWhen).toBe(-35)
      })
1031 
      it('does nothing for an unresolved figure (no record to consult)', async () => {
          store.figureGrounding = { name: 'Nobody', resolved: false } as never
          await store.studyActiveFigure()
          expect(fetchMock).not.toHaveBeenCalled()
          expect(store.figureStudy).toBeNull()
      })
1038 
      it('leaves the study empty (no throw) when research fails', async () => {
          store.figureGrounding = cleopatra as never
          fetchMock.mockRejectedValue(new Error('archive offline'))
          await store.studyActiveFigure()
          expect(store.figureStudy).toBeNull()
          expect(store.studyLoading).toBe(false)
      })
1046 
      it('surfaces a moderation block as a distinct notice, not a study', async () => {
          store.figureGrounding = cleopatra as never
          store.setContactWhen(-40)
          fetchMock.mockResolvedValue({ success: false, blocked: true, error: 'That study was blocked by content moderation.' })
1051 
          await store.studyActiveFigure()
1053 
          expect(store.studyNotice).toContain('blocked by content moderation')
          expect(store.figureStudy).toBeNull()
          expect(store.studyLoading).toBe(false)
      })
1058 
      it('drops a stale study when the contact changes', async () => {
          store.figureStudy = study as never
          store.studyFor = 'Cleopatra'
          fetchMock.mockResolvedValue({ name: 'Tesla', resolved: false })
1063 
          await store.groundActiveFigure('Nikola Tesla')
1065 
          expect(store.figureStudy).toBeNull()
          expect(store.studyFor).toBe('')
      })
  })
1070 
  describe('the Archive — askArchive lookup (prototype, yellow)', () => {
      const lookup = {
          topic: 'Gunpowder',
          summary: 'An explosive mix of saltpeter, charcoal, and sulfur.',
          requires: ['saltpeter', 'charcoal', 'sulfur'],
          knownSince: 'China, ~9th century'
      }
1078 
      it('looks up a topic and stores the result', async () => {
          fetchMock.mockResolvedValue({ success: true, lookup })
1081 
          await store.askArchive('gunpowder')
1083 
          expect(fetchMock).toHaveBeenCalledWith('/api/lookup', expect.objectContaining({ method: 'POST' }))
          expect(store.archiveResult).toEqual(lookup)
          expect(store.lookupLoading).toBe(false)
      })
1088 
      it('ignores an empty query', async () => {
          await store.askArchive('   ')
          expect(fetchMock).not.toHaveBeenCalled()
      })
1093 
      it('leaves the result empty (no throw) when the lookup fails', async () => {
          fetchMock.mockRejectedValue(new Error('archive offline'))
          await store.askArchive('gunpowder')
          expect(store.archiveResult).toBeNull()
          expect(store.lookupLoading).toBe(false)
      })
  })
1101 
  describe('anachronism risk-coupling (prototype)', () => {
      it('records the anachronism level on the resolved ledger entry', async () => {
          fetchMock.mockResolvedValue(okResponse({
              timeline: { headline: 'A leap', detail: 'Generations early', era: 'x', progressChange: 40, valence: 'positive', anachronism: 'far-ahead' }
          }))
1107 
          await store.sendMessage('Build a flying machine and aim higher', 'Leonardo da Vinci')
1109 
          expect(store.timelineEvents[0].anachronism).toBe('far-ahead')
      })
1112 
      it('leaves the ledger entry anachronism undefined when the server omits it', async () => {
          fetchMock.mockResolvedValue(okResponse())
          await store.sendMessage('A modest note', 'Tesla')
          expect(store.timelineEvents[0].anachronism).toBeUndefined()
      })
  })
1119 
  describe('figure suggestions (era-aware on-ramp)', () => {
      const objective = {
          title: 'Prevent the Great War',
          description: 'Keep 1914 from collapsing into world war.',
          era: 'Europe, 1914',
          icon: '🕊️'
      }
1127 
      it('loads era-relevant suggestions for the current objective', async () => {
          store.currentObjective = objective
          fetchMock.mockResolvedValue({
              success: true,
              suggestions: [{ name: 'Wilhelm II', reason: 'Could restrain Vienna.', lifespan: '1859 – 1941' }],
              fallback: false
          })
1135 
          await store.loadSuggestions()
1137 
          expect(fetchMock).toHaveBeenCalledWith('/api/suggestions', expect.objectContaining({ method: 'POST' }))
          expect(store.figureSuggestions).toHaveLength(1)
          expect(store.figureSuggestions[0].name).toBe('Wilhelm II')
          expect(store.suggestionsFor).toBe('Prevent the Great War')
      })
1143 
      it('caches per objective (no refetch on a second call)', async () => {
          store.currentObjective = objective
          fetchMock.mockResolvedValue({ success: true, suggestions: [{ name: 'X', reason: 'y' }] })
          await store.loadSuggestions()
          fetchMock.mockClear()
1149 
          await store.loadSuggestions()
          expect(fetchMock).not.toHaveBeenCalled()
      })
1153 
      it('clears suggestions when there is no objective', async () => {
          store.currentObjective = null
          await store.loadSuggestions()
          expect(store.figureSuggestions).toEqual([])
          expect(fetchMock).not.toHaveBeenCalled()
      })
1160 
      it('surfaces a blocked objective instead of a silent empty list', async () => {
          store.currentObjective = objective
          fetchMock.mockResolvedValue({ success: true, suggestions: [], blocked: true, reason: 'That objective was blocked by content moderation.' })
1164 
          await store.loadSuggestions()
1166 
          expect(store.suggestionsNotice).toContain('blocked by content moderation')
          expect(store.figureSuggestions).toEqual([])
      })
1170 
      it('leaves suggestions empty (no throw) when the request fails — but records the ask', async () => {
          store.currentObjective = objective
          fetchMock.mockRejectedValue(new Error('suggester down'))
          await store.loadSuggestions()
          expect(store.figureSuggestions).toEqual([])
          // "Asked and failed" must be distinguishable from "not yet asked": the
          // picker shows skeletons for the latter, the honest fallback for this.
          expect(store.suggestionsFor).toBe('Prevent the Great War')
      })
  })
1181 
  describe('causal chain read (the pre-send ⏳ chip)', () => {
      const moonObjective = {
          title: 'Reach the Moon by 1900', description: 'Half a century early.',
          era: '19th century', icon: '🚀', anchorYear: 1900
      }
1187 
      it('reads the gap to the objective anchor when no stones are laid yet', () => {
          store.currentObjective = moonObjective
          store.setContactWhen(1500) // Leonardo — 400yr from the 1900 anchor
          expect(store.causalChainRead?.tier).toBe('bridged')
      })
1193 
      it('a landed change becomes a foothold that bridges the next move', () => {
          store.currentObjective = moonObjective
          // Plant a stone at 1500, then reach a 1650 figure — bridged off the stone.
          store.addTimelineEvent({ figureName: 'Leonardo', era: 'Florence, 1500', headline: 'h', detail: 'd', diceRoll: 16, diceOutcome: DiceOutcome.SUCCESS, progressChange: 10, whenSigned: 1500 })
          store.setContactWhen(1650)
          expect(store.causalChainRead?.tier).toBe('at-hinge') // 150yr from the 1500 stone
      })
1201 
      it('no-ops (no chip) for an anchorless objective with no stones', () => {
          store.currentObjective = { title: 'Across the ages', description: 'x', era: 'all', icon: '🕰️' }
          store.setContactWhen(1500)
          expect(store.causalChainRead).toBeNull()
      })
  })
1208 
  describe('run id (cost-instrument tagging)', () => {
      it('mints the run id server-side (POST /api/run) on first need and reuses it', async () => {
          store.runId = null
          fetchMock.mockResolvedValue({ runId: 'server-run-1' })
          const h1 = await store.aiHeaders()
          expect(h1['x-run-id']).toBe('server-run-1')
          expect(store.runId).toBe('server-run-1')
          expect(fetchMock).toHaveBeenCalledWith('/api/run', { method: 'POST' })
          // Same run → reused, no second begin-run; base headers preserved.
          fetchMock.mockClear()
          const h2 = await store.aiHeaders({ 'Content-Type': 'application/json' })
          expect(h2['x-run-id']).toBe('server-run-1')
          expect(h2['Content-Type']).toBe('application/json')
          expect(fetchMock).not.toHaveBeenCalled()
      })
1224 
      it('rejects when begin-run fails — fail closed, no local fallback', async () => {
          store.runId = null
          fetchMock.mockRejectedValue(new Error('store down'))
          await expect(store.ensureRunId()).rejects.toThrow()
          expect(fetchMock).toHaveBeenCalledWith('/api/run', { method: 'POST' })
          expect(store.runId).toBeNull() // no fabricated id landed
      })
1232 
      it('resetGame clears the id so the next run begins fresh', async () => {
          store.runId = null
          fetchMock.mockResolvedValueOnce({ runId: 'run-a' })
          const first = await store.ensureRunId()
          expect(first).toBe('run-a')
          store.resetGame()
          expect(store.runId).toBeNull()
          fetchMock.mockResolvedValueOnce({ runId: 'run-b' })
          const second = await store.ensureRunId()
          expect(second).toBe('run-b')
          expect(second).not.toBe(first)
      })
1245 
      it('tags an outgoing AI call with the x-run-id header', async () => {
          store.runId = 'run-tag'
          fetchMock.mockResolvedValue({ success: false })
          await store.fetchAIObjective()
          expect(fetchMock).toHaveBeenCalledWith(
              '/api/objective',
              expect.objectContaining({
                  method: 'GET',
                  headers: expect.objectContaining({ 'x-run-id': 'run-tag' })
              })
          )
      })
1258 
      it('collapses concurrent first-calls onto a single begin-run', async () => {
          store.runId = null
          let resolveRun: (v: { runId: string }) => void = () => {}
          const deferred = new Promise<{ runId: string }>((r) => { resolveRun = r })
          fetchMock.mockReturnValue(deferred)
          // Two AI calls race at run start, both before the mint resolves.
          const p1 = store.ensureRunId()
          const p2 = store.ensureRunId()
          resolveRun({ runId: 'shared' })
          const [a, b] = await Promise.all([p1, p2])
          expect(a).toBe('shared')
          expect(b).toBe('shared')
          expect(fetchMock).toHaveBeenCalledTimes(1) // one POST, not two
      })
1273 
      it('a resetGame mid-mint does not bleed the old run id into the new run', async () => {
          store.runId = null
          let resolveRun: (v: { runId: string }) => void = () => {}
          const deferred = new Promise<{ runId: string }>((r) => { resolveRun = r })
          fetchMock.mockReturnValueOnce(deferred)
          const inflight = store.ensureRunId() // old run's mint, still pending
          store.resetGame() // a new run begins mid-flight
          resolveRun({ runId: 'old-run' })
          expect(await inflight).toBe('old-run') // the old caller still gets its id
          expect(store.runId).toBeNull() // but it did NOT land in the fresh run
          fetchMock.mockResolvedValueOnce({ runId: 'new-run' })
          expect(await store.ensureRunId()).toBe('new-run') // new run mints fresh
      })
1287 
      it('begins the run then tags the AI call within one action (mint precedes the call)', async () => {
          store.runId = null
          fetchMock.mockImplementation((url: string) =>
              url === '/api/run' ? Promise.resolve({ runId: 'minted' }) : Promise.resolve(okResponse())
          )
          await store.sendMessage('Light the world wirelessly', 'Nikola Tesla')
          const urls = fetchMock.mock.calls.map((c: unknown[]) => c[0])
          expect(urls.indexOf('/api/run')).toBeGreaterThanOrEqual(0)
          expect(urls.indexOf('/api/run')).toBeLessThan(urls.indexOf('/api/send-message'))
          expect(fetchMock).toHaveBeenCalledWith(
              '/api/send-message',
              expect.objectContaining({ headers: expect.objectContaining({ 'x-run-id': 'minted' }) })
          )
      })
  })
1303 
  describe('run balance (the paywall gate)', () => {
      const objective = { title: 'Spare the library', description: 'The scrolls survive.', era: 'Alexandria', icon: '📜' }
1306 
      it('charges a run and starts when the device has balance', async () => {
          store.runId = 'run-x'
          fetchMock.mockResolvedValue({ runsRemaining: 2 })
          const started = await store.chooseObjective(objective)
          expect(started).toBe(true)
          expect(fetchMock).toHaveBeenCalledWith(
              '/api/run-commit',
              expect.objectContaining({ method: 'POST', body: { runId: 'run-x' } })
          )
          expect(store.outOfRuns).toBe(false)
          expect(store.currentObjective?.title).toBe('Spare the library')
          expect(store.runsRemaining).toBe(2) // gauge stays live off the commit response
      })
1320 
      it('raises the paywall, opens the packs modal, and does NOT start when out of runs (402)', async () => {
          store.runId = 'run-y'
          // 402 on commit; openBuyModal then fetches the catalog.
          fetchMock.mockImplementation((url: string) =>
              url === '/api/packs' ? Promise.resolve({ packs: [] }) : Promise.reject({ statusCode: 402 })
          )
          const started = await store.chooseObjective(objective)
          expect(started).toBe(false)
          expect(store.outOfRuns).toBe(true)
          expect(store.buyModalOpen).toBe(true) // the sales modal opens automatically
          expect(store.currentObjective).toBeNull() // the run did not start
      })
1333 
      it('raises the at-capacity notice (not the paywall) and does NOT start on a 503', async () => {
          store.runId = 'run-cap'
          fetchMock.mockRejectedValue({ statusCode: 503, data: { atCapacity: true } })
          const started = await store.chooseObjective(objective)
          expect(started).toBe(false)
          expect(store.atCapacity).toBe(true)
          expect(store.outOfRuns).toBe(false) // distinct from the paywall
          expect(store.currentObjective).toBeNull()
      })
1343 
      it('treats all three 402 error shapes as out of runs', async () => {
          for (const shape of [{ statusCode: 402 }, { status: 402 }, { response: { status: 402 } }]) {
              store.runId = 'run-shape'
              store.outOfRuns = false
              fetchMock.mockRejectedValue(shape)
              expect(await store.chooseObjective(objective)).toBe(false)
              expect(store.outOfRuns).toBe(true)
          }
      })
1353 
      it('starts the run on a degraded (non-server) commit response', async () => {
          store.runId = 'run-d'
          fetchMock.mockResolvedValue({ runsRemaining: -1, degraded: true })
          const started = await store.chooseObjective(objective)
          expect(started).toBe(true)
          expect(store.outOfRuns).toBe(false)
          expect(store.currentObjective?.title).toBe('Spare the library')
      })
1362 
      it('does NOT start (surfaces an error) when the commit fails for a non-payment reason', async () => {
          store.runId = 'run-z'
          fetchMock.mockRejectedValue({ statusCode: 500 })
          const started = await store.chooseObjective(objective)
          expect(started).toBe(false) // fail closed — don't start a run we couldn't charge
          expect(store.outOfRuns).toBe(false)
          expect(store.currentObjective).toBeNull()
          expect(store.error).toBeTruthy()
      })
1372 
      it('does NOT start when begin-run fails (fail closed)', async () => {
          store.runId = null
          fetchMock.mockRejectedValue(new Error('store down')) // /api/run fails
          const started = await store.chooseObjective(objective)
          expect(started).toBe(false)
          expect(store.currentObjective).toBeNull()
          expect(store.error).toBeTruthy()
      })
  })
1382 
  describe('run packs (paywall purchase)', () => {
      it('loadPacks fetches the catalog, then caches it', async () => {
          fetchMock.mockResolvedValue({ packs: [{ id: 'courier', label: 'Courier', priceCents: 500, runs: 7 }] })
          await store.loadPacks()
          expect(store.packs).toHaveLength(1)
          expect(store.packs[0].id).toBe('courier')
          fetchMock.mockClear()
          await store.loadPacks() // cached → no second fetch
          expect(fetchMock).not.toHaveBeenCalled()
      })
1393 
      it('buyPack returns the Stripe checkout url', async () => {
          fetchMock.mockResolvedValue({ url: 'https://checkout.stripe.com/x' })
          expect(await store.buyPack('courier')).toBe('https://checkout.stripe.com/x')
          expect(fetchMock).toHaveBeenCalledWith(
              '/api/checkout',
              expect.objectContaining({ method: 'POST', body: { packId: 'courier' } })
          )
      })
1402 
      it('buyPack returns null on failure', async () => {
          fetchMock.mockRejectedValue(new Error('stripe down'))
          expect(await store.buyPack('courier')).toBeNull()
      })
1407 
      it('does NOT cache an empty catalog — a transient empty read retries', async () => {
          fetchMock.mockResolvedValueOnce({ packs: [] }) // transient empty
          await store.loadPacks()
          expect(store.packs).toHaveLength(0) // not populated…
          fetchMock.mockResolvedValueOnce({ packs: [{ id: 'courier', label: 'Courier', priceCents: 500, runs: 7 }] })
          await store.loadPacks() // …and not poisoned: it refetches
          expect(store.packs).toHaveLength(1)
      })
  })
1417 
  describe('run balance gauge + sales modal + purchase return', () => {
      it('loadBalance populates the gauge + account fields', async () => {
          fetchMock.mockResolvedValue({ runsRemaining: 5, freeRuns: 1, deviceRef: 'abcd1234', email: 'a@b.co', isAnonymous: false })
          await store.loadBalance()
          expect(store.runsRemaining).toBe(5)
          expect(store.freeRuns).toBe(1)
          expect(store.deviceRef).toBe('abcd1234')
          expect(store.accountEmail).toBe('a@b.co')
          expect(store.accountAnonymous).toBe(false)
      })
1428 
      it('loadBalance marks an anonymous user (no email)', async () => {
          fetchMock.mockResolvedValue({ runsRemaining: 1, freeRuns: 1, deviceRef: 'xy', email: null, isAnonymous: true })
          await store.loadBalance()
          expect(store.accountEmail).toBeNull()
          expect(store.accountAnonymous).toBe(true)
      })
1435 
      it('loadBalance leaves the prior value on failure', async () => {
          store.runsRemaining = 9
          fetchMock.mockRejectedValue(new Error('down'))
          await store.loadBalance()
          expect(store.runsRemaining).toBe(9)
      })
1442 
      it('openBuyModal opens the modal and loads the catalog; closeBuyModal closes it', async () => {
          fetchMock.mockResolvedValue({ packs: [{ id: 'courier', label: 'Courier', priceCents: 500, runs: 7 }] })
          await store.openBuyModal()
          expect(store.buyModalOpen).toBe(true)
          expect(store.packs).toHaveLength(1)
          store.closeBuyModal()
          expect(store.buyModalOpen).toBe(false)
      })
1451 
      it('notePurchaseReturn(success) refreshes the balance and clears the paywall', async () => {
          store.outOfRuns = true
          fetchMock.mockResolvedValue({ runsRemaining: 8, freeRuns: 1, deviceRef: 'xy' })
          await store.notePurchaseReturn('success')
          expect(store.purchaseNotice).toBe('success')
          expect(store.outOfRuns).toBe(false)
          expect(store.runsRemaining).toBe(8) // re-read after the webhook credited
      })
1460 
      it('notePurchaseReturn(cancel) records the notice without refetching', async () => {
          await store.notePurchaseReturn('cancel')
          expect(store.purchaseNotice).toBe('cancel')
          expect(fetchMock).not.toHaveBeenCalled()
      })
1466 
      it('clearPurchaseNotice dismisses the notice', () => {
          store.purchaseNotice = 'success'
          store.clearPurchaseNotice()
          expect(store.purchaseNotice).toBeNull()
      })
  })
1473})

The component tests assert what the end screen renders for each store state — the three acceptance cases.

Pending → loading, not the stale article; landed → the epilogue; failed → the prior telling, never stuck on loading.

tests/unit/components/EndGameScreen.spec.ts · 247 lines

tests/unit/components/EndGameScreen.spec.ts247 lines · TypeScript

⋯ 87 lines hidden (lines 1–87)1import { mount } from '@vue/test-utils'
2import { describe, it, expect, beforeEach } from 'vitest'
3import { setActivePinia, createPinia } from 'pinia'
4import EndGameScreen from '../../../components/EndGameScreen.vue'
5import { useGameStore } from '../../../stores/game'
6import { DiceOutcome } from '../../../utils/dice'
7import type { GameObjective } from '../../../server/utils/objectives'
8import type { Message } from '../../../stores/game'
9 
10const OBJ: GameObjective = {
  title: 'Reach the Moon by 1900',
  description: 'Leave Earth half a century early.',
  era: '19th century',
  icon: '🚀'
15}
16 
17function resolvedTurn(diceRoll: number, diceOutcome: DiceOutcome, progressChange: number): Message {
  return {
      text: 'reply', sender: 'ai', figureName: 'Tesla', timestamp: new Date(),
      diceRoll, diceOutcome, progressChange, timelineImpact: 'history shifts'
  }
22}
23function prompt(): Message {
  return { text: 'prompt', sender: 'user', figureName: 'Tesla', timestamp: new Date() }
25}
26 
27describe('EndGameScreen', () => {
  let gameStore: ReturnType<typeof useGameStore>
29 
  beforeEach(() => {
      setActivePinia(createPinia())
      gameStore = useGameStore()
  })
34 
  describe('Victory', () => {
      beforeEach(() => {
          gameStore.gameStatus = 'victory'
          gameStore.objectiveProgress = 100
          gameStore.currentObjective = OBJ
          gameStore.remainingMessages = 2
      })
42 
      it('shows a victory headline', () => {
          const v = mount(EndGameScreen).find('[data-testid="victory-message"]')
          expect(v.exists()).toBe(true)
          expect(v.text()).toContain('History Rewritten')
      })
48 
      it('shows the objective and final progress', () => {
          const w = mount(EndGameScreen)
          expect(w.find('[data-testid="objective-title"]').text()).toContain('Reach the Moon by 1900')
          expect(w.find('[data-testid="final-progress"]').text()).toContain('100%')
      })
54 
      it('shows efficiency with messages saved', () => {
          const e = mount(EndGameScreen).find('[data-testid="efficiency-display"]')
          expect(e.exists()).toBe(true)
          expect(e.text()).toContain('saved')
      })
  })
61 
  describe('Defeat', () => {
      beforeEach(() => {
          gameStore.gameStatus = 'defeat'
          gameStore.objectiveProgress = 45
          gameStore.currentObjective = OBJ
          gameStore.remainingMessages = 0
      })
69 
      it('shows a defeat headline', () => {
          const d = mount(EndGameScreen).find('[data-testid="defeat-message"]')
          expect(d.exists()).toBe(true)
          expect(d.text()).toContain('Timeline Held')
      })
75 
      it('shows final progress below 100%', () => {
          expect(mount(EndGameScreen).find('[data-testid="final-progress"]').text()).toContain('45%')
      })
79 
      it('explains the loss', () => {
          expect(mount(EndGameScreen).find('[data-testid="defeat-explanation"]').exists()).toBe(true)
      })
  })
84 
  // The epilogue is the run's payoff — the terminal telling that carries the verdict.
  // While it's still being written we must never present the prior turn's stale,
  // pre-ending telling as the epilogue (issue #107).
  describe('The Chronicle epilogue — pending, reveal, and fallback', () => {
      const stale = { title: 'Mid-run Telling', paragraphs: ['the world as it stood a turn ago'] }
      const epilogue = { title: 'The World Remade', paragraphs: ['and so the timeline was rewritten'] }
91 
      beforeEach(() => {
          gameStore.gameStatus = 'victory'
          gameStore.currentObjective = OBJ
      })
96 
      it('shows the "final account" wait while the epilogue is pending — not the stale prior telling', () => {
          gameStore.chronicle = stale // a stale, pre-ending telling is still held
          gameStore.epiloguePending = true // the terminal refresh is in flight
          const w = mount(EndGameScreen)
          expect(w.find('[data-testid="end-chronicle-loading"]').exists()).toBe(true)
          // The prior-turn telling must NOT be presented as the epilogue.
          expect(w.find('[data-testid="end-chronicle-body"]').exists()).toBe(false)
          expect(w.text()).not.toContain('Mid-run Telling')
      })
106 
      it('reveals the epilogue once the terminal telling lands', () => {
          gameStore.chronicle = epilogue
          gameStore.epiloguePending = false
          const w = mount(EndGameScreen)
          expect(w.find('[data-testid="end-chronicle-loading"]').exists()).toBe(false)
          expect(w.find('[data-testid="end-chronicle-body"]').exists()).toBe(true)
          expect(w.find('[data-testid="end-chronicle-title"]').text()).toContain('The World Remade')
      })
115 
      it('falls back to the prior telling if the final refresh failed — never stuck on loading', () => {
          // refreshChronicle keeps the prior telling on failure and clears pending.
          gameStore.chronicle = stale
          gameStore.epiloguePending = false
          const w = mount(EndGameScreen)
          expect(w.find('[data-testid="end-chronicle-loading"]').exists()).toBe(false)
          expect(w.find('[data-testid="end-chronicle-body"]').exists()).toBe(true)
          expect(w.find('[data-testid="end-chronicle-title"]').text()).toContain('Mid-run Telling')
      })
  })
⋯ 122 lines hidden (lines 126–247)126 
  describe('Summary stats — derived from resolved AI turns', () => {
      beforeEach(() => {
          gameStore.gameStatus = 'victory'
          gameStore.remainingMessages = 3 // 2 used
          gameStore.messageHistory = [
              prompt(), resolvedTurn(18, DiceOutcome.SUCCESS, 25),
              prompt(), resolvedTurn(20, DiceOutcome.CRITICAL_SUCCESS, 75)
          ]
      })
136 
      it('renders the summary block', () => {
          expect(mount(EndGameScreen).find('[data-testid="game-summary"]').exists()).toBe(true)
      })
140 
      it('highlights the best roll from the AI turns', () => {
          const best = mount(EndGameScreen).find('[data-testid="best-roll"]')
          expect(best.exists()).toBe(true)
          expect(best.text()).toContain('20')
      })
146 
      it('highlights the worst roll from the AI turns', () => {
          gameStore.messageHistory[1] = resolvedTurn(2, DiceOutcome.CRITICAL_FAILURE, -10)
          const worst = mount(EndGameScreen).find('[data-testid="worst-roll"]')
          expect(worst.exists()).toBe(true)
          expect(worst.text()).toContain('2')
      })
153 
      it('shows the number of messages sent', () => {
          const eff = mount(EndGameScreen).find('[data-testid="message-efficiency"]')
          expect(eff.exists()).toBe(true)
          expect(eff.text()).toContain('2')
      })
  })
160 
  // The "history you wrote" renders through the shared Spine (TimelineLedger),
  // not a bespoke list — so the verdict's history reads exactly like the in-game
  // timeline (valence dots, badges, the Δ equation), per issue #84.
  describe('The history you wrote — the shared Spine', () => {
      beforeEach(() => {
          gameStore.gameStatus = 'victory'
          gameStore.addTimelineEvent({
              figureName: 'Tesla', era: '1890s',
              headline: 'The grid hums to life', detail: 'Alternating current spreads.',
              diceRoll: 18, diceOutcome: DiceOutcome.SUCCESS, progressChange: 25
          })
      })
173 
      it('renders via the shared TimelineLedger, not the old hand-rolled list', () => {
          const w = mount(EndGameScreen)
          expect(w.find('[data-testid="timeline-ledger"]').exists()).toBe(true)
          expect(w.find('[data-testid="timeline-event"]').exists()).toBe(true)
          // The bespoke block folded into the Spine's testid.
          expect(w.find('[data-testid="final-timeline"]').exists()).toBe(false)
      })
181 
      it('renders the Spine read-only: no live "▷ now · your move" present marker', () => {
          expect(mount(EndGameScreen).find('.spine-now').exists()).toBe(false)
      })
  })
186 
  // The Chronicle epilogue fills the full debrief column like its siblings (the
  // dispatches / stats / timeline). It used to carry an inner max-w-[62ch] measure
  // that read as ~2/3 width next to those full-width sections (#109).
  describe('Chronicle epilogue', () => {
      beforeEach(() => {
          gameStore.gameStatus = 'victory'
          gameStore.chronicle = { title: 'The Library Stands', paragraphs: ['It did not burn.'] }
      })
195 
      it('renders the epilogue body', () => {
          const body = mount(EndGameScreen).find('[data-testid="end-chronicle-body"]')
          expect(body.exists()).toBe(true)
          expect(body.text()).toContain('It did not burn.')
      })
201 
      it('fills the column — no max-w-[62ch] cap', () => {
          const body = mount(EndGameScreen).find('[data-testid="end-chronicle-body"]')
          expect(body.classes()).not.toContain('max-w-[62ch]')
      })
  })
207 
  describe('Play again', () => {
      beforeEach(() => { gameStore.gameStatus = 'victory' })
210 
      it('offers a restart', () => {
          const btn = mount(EndGameScreen).find('[data-testid="play-again-button"]')
          expect(btn.exists()).toBe(true)
          expect(btn.text()).toContain('new timeline')
      })
216 
      it('asks the page for the unified reset when clicked (it never resets the store itself)', async () => {
          const wrapper = mount(EndGameScreen)
          await wrapper.find('[data-testid="play-again-button"]').trigger('click')
220 
          // The page owns the FULL reset (store + figure input + composer); the
          // old direct store reset left the previous run's figure in the input.
          expect(wrapper.emitted('play-again')).toHaveLength(1)
          expect(gameStore.gameStatus).toBe('victory') // untouched by the component
      })
  })
227 
  describe('Edge cases', () => {
      it('handles a missing objective', () => {
          gameStore.gameStatus = 'victory'
          gameStore.currentObjective = null
          expect(() => mount(EndGameScreen)).not.toThrow()
      })
234 
      it('does not render while still playing', () => {
          gameStore.gameStatus = 'playing'
          expect(mount(EndGameScreen).find('[data-testid="end-game-screen"]').exists()).toBe(false)
      })
239 
      it('exposes dialog semantics', () => {
          gameStore.gameStatus = 'victory'
          const screen = mount(EndGameScreen).find('[data-testid="end-game-screen"]')
          expect(screen.attributes('role')).toBe('dialog')
          expect(screen.attributes('aria-labelledby')).toBeTruthy()
      })
  })
247})