Peaked at X% — a code-level reading (PR #146)

What changed, and why

A run can climb to real progress and then fall back. The sharpest case: the player stakes their final message, the dice crit-fail, and the staked swing doubles them all the way down to 0%. The end screen then read 0% rewritten — as if the run had never happened. The store knew the peak each turn and threw it away.

This change keeps it. The store now tracks a high-water mark as each swing lands, and the end screen shows "peaked at X%" — but only when the run actually slipped below its peak. Two source files move, both additively: the store holds the new field, the end-screen component reads it. No existing behavior changes.

The high-water mark in the store

peakProgress is a per-run number that only ever rises. It updates in applyProgress, the single place a swing lands, right after objectiveProgress is clamped into 0..100. Because it reads the already-clamped value, the mark can never exceed 100 or fall below 0 — it inherits those bounds for free.

The field, the one update site, and both resets — the whole store change.

stores/game.ts · 1463 lines

stores/game.ts1463 lines · TypeScript

⋯ 288 lines hidden (lines 1–288)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/**
* A replay seed (issue #89) — when a player starts a run from a shared run's captured
* objective. It carries the objective to seed (verbatim, no generation), the SOURCE run's
* public share token (rides along to /api/run-save to stamp the lineage pointer), and the
* source's display name at seed time (for the "remixed from" credit shown before/after the
* run; the public page re-derives the credit live, honoring the source's current opt-in).
*/
219export interface ReplaySeed {
  objective: GameObjective
  sourceToken: string
  sourceAttribution: string | null
223}
224 
225/**
* Game Store — core state for a session of freeform timeline editing.
*/
228export 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,
      // True once this run's snapshot is durably saved (POST /api/run-save returned
      // saved). Gates the end-screen Share affordance (issue #88) so it appears only for
      // a run that actually exists server-side to share — never for a degraded local id.
      // Reset per run.
      runSnapshotSaved: false,
      // outOfRuns gates the mission screen's paywall (set when a commit is
      // refused with 402). The run packs offered there are loaded into `packs`.
      outOfRuns: false,
      // atCapacity gates the "at capacity" notice (set when a commit is refused
      // with 503 because the global spend cap paused new runs).
      atCapacity: false,
      packs: [] as Pack[],
      // The device's run balance, for the header gauge + account popover. null
      // until first loaded (GET /api/balance); the run-commit response also
      // refreshes it so the gauge stays live without a second round-trip.
      runsRemaining: null as number | null,
      freeRuns: 1,
      deviceRef: '' as string,
      // Account state (from /api/balance): the signed-in email, and whether the
      // current user is anonymous (→ must sign in before buying). Drives the
      // account UI + the sign-in-to-buy gate. false/null in device-fallback mode.
      accountEmail: null as string | null,
      accountAnonymous: false,
      // The run-packs sales modal — opened on demand (header) or automatically
      // when a commit is refused for being out of runs.
      buyModalOpen: false,
      // A one-shot notice after returning from Stripe Checkout ('success' shows a
      // credited confirmation; 'cancel' a gentle "no charge" note). Cleared by the UI.
      purchaseNotice: null as 'success' | 'cancel' | null,
      currentObjective: null as GameObjective | null,
      // Set when this run is a REPLAY of a shared run's objective (issue #89): seeded
      // verbatim from the public projection, no generation. Survives chooseObjective so
      // it can stamp the lineage pointer at save time and credit the source on the end
      // screen; cleared by resetGame (a fresh "new timeline" carries no lineage).
      replayState: null as ReplaySeed | null,
      objectiveProgress: 0,
      // The run's high-water mark (0..MAX_PROGRESS): the highest objectiveProgress ever
      // reached this run. Tracked so the end screen can show "peaked at X%" when a run
      // loses ground from its peak — classically a staked final dispatch that crit-fails
      // to 0% — instead of the floored final % erasing the player's real effort (#129).
      peakProgress: 0,
⋯ 568 lines hidden (lines 295–862)295        // 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
  }),
341 
  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
      },
353 
      /**
       * 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'
          )
      },
364 
      /** Total progress, net of setbacks, the player has clawed back. */
      gameSummary(): GameSummary {
          return generateGameSummary(this)
      },
369 
      /**
       * 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'
      },
391 
      /** Can the chosen contact + when actually be reached? */
      canContact(): boolean {
          return this.contactLiveness === 'ok' || this.contactLiveness === 'unknown'
      },
396 
      /**
       * 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
      },
408 
      /**
       * 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
      },
424 
      /**
       * 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)
      }
  },
440 
  actions: {
      // ---------- message helpers ----------
      addUserMessage(text: string, figureName?: string) {
          if (this.gameStatus !== 'playing') return
          this.messageHistory.push({
              text,
              sender: 'user',
              timestamp: new Date(),
              figureName
          })
      },
452 
      addAIMessage(text: string, figureName?: string) {
          this.messageHistory.push({
              text,
              sender: 'ai',
              timestamp: new Date(),
              figureName
          })
      },
461 
      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
          })
      },
485 
      // ---------- 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 })
          }
      },
496 
      setActiveFigure(name: string) {
          this.activeFigureName = name
      },
500 
      /**
       * 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
      },
518 
      /**
       * 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
          }
      },
566 
      /** 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
      },
595 
      /** 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() }
      },
601 
      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
      },
607 
      setContactMoment(moment: ContactMoment | null) {
          this.contactMoment = moment
      },
611 
      /**
       * 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
628 
          // 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
          }
      },
665 
      /**
       * 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
          }
      },
699 
      /**
       * 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
713 
          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
          }
      },
746 
      // ---------- 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()
          })
      },
770 
      // ---------- the living chronicle (Layer 3) ----------
      /**
       * Re-narrates the Chronicle from the freshly-bent timeline. Fired
       * non-blocking after a resolved turn (and at game end): the dice/progress
       * reveal never waits on prose. The WHOLE account is rewritten each turn —
       * a later change can re-frame how earlier events read.
       * Graceful: a failed refresh keeps the prior telling, so the panel never
       * blanks; an empty timeline clears it (nothing to chronicle yet).
       */
      async refreshChronicle(): Promise<void> {
          if (!this.timelineEvents.length) {
              this.chronicle = null
              return
          }
          // Sequencing: rewrites overlap (each turn fires one, never awaited), so
          // only the LATEST issued refresh may land — an earlier telling arriving
          // late must not regress the account (or worse, the epilogue). The epoch
          // guard keeps a dead run's telling out of a fresh run entirely.
          const epoch = this.runEpoch
          const seq = ++this.chronicleSeq
          this.chronicleLoading = true
          try {
              const res = await $fetch('/api/chronicle', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: {
                      objective: this.currentObjective,
                      status: this.gameStatus,
                      progress: this.objectiveProgress,
                      timeline: this.timelineEvents.map(e => ({
                          era: e.era,
                          figureName: e.figureName,
                          headline: e.headline,
                          detail: e.detail,
                          progressChange: e.progressChange
                      }))
                  }
              }) as { success?: boolean; chronicle?: ChronicleEntry }
              if (epoch !== this.runEpoch || seq !== this.chronicleSeq) return
              if (res?.success && res.chronicle) this.chronicle = res.chronicle
          } catch (error) {
              if (epoch !== this.runEpoch || seq !== this.chronicleSeq) return
              console.error('Failed to refresh the chronicle:', error)
              // Keep the prior chronicle — a failed refresh never blanks the panel.
          } finally {
              if (epoch === this.runEpoch && seq === this.chronicleSeq) this.chronicleLoading = false
          }
      },
819 
      // ---------- simple setters ----------
      setLoading(loading: boolean) { this.isLoading = loading },
      setError(error: string | null) { this.error = error },
      clearModerationNotice() { this.moderationNotice = null },
      clearArchiveNotice() { this.archiveNotice = null },
825 
      // ---------- rate limiting ----------
      checkRateLimit(): boolean {
          const now = Date.now()
          if (this.lastMessageTime && (now - this.lastMessageTime) < RATE_LIMIT_MS) return false
          return true
      },
832 
      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)
      },
840 
      // ---------- counter & status ----------
      decrementMessages() {
          if (this.remainingMessages > 0) this.remainingMessages--
      },
845 
      /**
       * 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
              }
          }
      },
862 
      applyProgress(progressChange: number) {
          this.objectiveProgress = Math.max(0, Math.min(MAX_PROGRESS, this.objectiveProgress + progressChange))
          this.peakProgress = Math.max(this.peakProgress, this.objectiveProgress)
      },
⋯ 330 lines hidden (lines 867–1196)867 
      /**
       * 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'
          }
      },
883 
      // ---------- 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
901 
          if (!this.canSendMessage) return false
          if (!target) {
              this.setError('Choose who in history to send your message to first.')
              return false
          }
          if (!this.checkRateLimit()) {
              this.setRateLimit()
              this.setError('The timeline needs a moment — wait before sending again.')
              return false
          }
          if (!this.canContact) {
              const who = this.figureGrounding?.name || target
              this.setError(
                  this.contactLiveness === 'unresolved'
                      ? (this.figureGrounding?.transient
                          ? `Couldn't reach the record to verify "${target}" — try again in a moment.`
                          : `No historical record found for "${target}" — reach for a real figure (pick a match as you type).`)
                      : this.contactLiveness === 'before-birth'
                          ? `${who} isn't born yet in that year — choose a later moment to reach them.`
                          : this.contactLiveness === 'living'
                              ? (this.figureGrounding?.born
                                  ? `${who} is still living — Everwhen only reaches figures from history.`
                                  : `${who} couldn't be dated — Everwhen can only reach figures it can place in history.`)
                              : `${who} has died by that year — choose an earlier moment to reach them.`
              )
              return false
          }
929 
          this.setError(null)
          this.moderationNotice = null
          this.setActiveFigure(target)
          this.addUserMessage(text, target)
          this.decrementMessages()
          this.setLoading(true)
          this.lastMessageTime = Date.now()
937 
          // 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()
950 
          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)
                  }
              })
986 
              if (epoch !== this.runEpoch) return false
988 
              if (response?.success && response.data?.characterResponse) {
                  const { figure, characterResponse, diceRoll, diceOutcome, timeline } = response.data
991 
                  if (figure?.name) {
                      this.registerFigure({
                          name: figure.name,
                          era: figure.era || '',
                          descriptor: figure.descriptor || ''
                      })
                  }
999 
                  // ---- 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
                  }
1007 
                  // 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)
1034 
                  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
1051 
                      // 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()
              }
          }
1102 
          // 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
      },
1131 
      /**
       * Seed a replay (issue #89): start a fresh run on a shared run's captured
       * objective. Resets first (the share page may follow an abandoned run in the
       * same tab) so the run starts clean, THEN records the seed — so the mission
       * briefing opens focused on this objective, and the lineage + credit ride
       * through to the end. No generation: the objective is reused verbatim, and the
       * player still commits (and is charged) by pressing Begin.
       */
      preseedReplay(objective: GameObjective, sourceToken: string, sourceAttribution: string | null): void {
          this.resetGame()
          this.replayState = { objective, sourceToken, sourceAttribution }
      },
1144 
      /** Drop the replay seed — the player chose to start from scratch instead, so this
       *  run is an original (no "remixed from" lineage). */
      clearReplayState(): void {
          this.replayState = null
      },
1150 
      /**
       * Commits a chosen objective and starts the run from a clean slate of
       * progress. Used by the mission-select screen for both curated picks and
       * freshly composed ones.
       */
      async chooseObjective(objective: GameObjective): Promise<boolean> {
          // Commit = the run is charged here. Mint the run id server-side, then
          // spend one run from the device's balance. Fails CLOSED: out of runs →
          // raise the paywall; begin-run or commit failing → surface an error and
          // do NOT start. A run that isn't a charged, server-backed run would be
          // rejected by the gameplay gate anyway, so starting it only strands the
          // player mid-run. The spend cap (not free play) is the outage backstop.
          let runId: string
          try {
              runId = await this.ensureRunId()
          } catch (error) {
              console.error('Could not begin the run:', error)
              this.error = 'Could not start the run. Please try again.'
              return false
          }
          try {
              const res = await $fetch('/api/run-commit', {
                  method: 'POST',
                  headers: { 'Content-Type': 'application/json' },
                  body: { runId }
              }) as { runsRemaining?: number }
              this.outOfRuns = false
              // Keep the header gauge live: the commit returns the post-charge
              // balance (−1 marks a degraded, ungated run — leave the gauge as is).
              if (typeof res?.runsRemaining === 'number' && res.runsRemaining >= 0) {
                  this.runsRemaining = res.runsRemaining
              }
          } catch (error) {
              if (isPaymentRequired(error)) {
                  this.outOfRuns = true
                  this.openBuyModal()
                  return false
              }
              if (isAtCapacity(error)) {
                  this.atCapacity = true
                  return false
              }
              console.error('Could not charge the run:', error)
              this.error = 'Could not start the run. Please try again.'
              return false
          }
          this.currentObjective = objective
          this.objectiveProgress = 0
          this.peakProgress = 0
          this.momentum = 0
⋯ 233 lines hidden (lines 1201–1433)1201            this.error = null
          return true
      },
1204 
      /**
       * 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
          }
      },
1232 
      /**
       * 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)
          }
      },
1250 
      /** Opens the run-packs sales modal, loading the catalog first. */
      async openBuyModal(): Promise<void> {
          this.buyModalOpen = true
          await this.loadPacks()
      },
1256 
      /** Closes the sales modal. */
      closeBuyModal(): void {
          this.buyModalOpen = false
      },
1261 
      /** 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()
          }
      },
1272 
      /** Dismisses the post-purchase notice. */
      clearPurchaseNotice(): void {
          this.purchaseNotice = null
      },
1277 
      /** 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)
          }
      },
1291 
      /** 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
          }
      },
1307 
      getVictoryEfficiency() {
          if (this.gameStatus === 'victory') {
              const messagesSaved = this.remainingMessages
              const messagesUsed = TOTAL_MESSAGES - this.remainingMessages
              const efficiencyPercentage = Math.round((messagesSaved / TOTAL_MESSAGES) * 100)
1313 
              const efficiencyRating = rateEfficiency(messagesSaved)
1315 
              return {
                  messagesSaved,
                  messagesUsed,
                  efficiencyPercentage,
                  efficiencyRating,
                  isEarlyVictory: messagesSaved > 0
              }
          }
          return null
      },
1326 
      /**
       * 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
1343 
          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
1359 
          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,
                  baseProgressChange: e.baseProgressChange,
                  valence: e.valence,
                  craft: e.craft,
                  anachronism: e.anachronism,
                  staked: e.staked
              })),
              chronicle: this.chronicle
          }
1389 
          // A replay (issue #89) rides its source's share token alongside the snapshot
          // (a sibling field, not part of the immutable blob); the server resolves it to
          // the parent run id and stamps the lineage pointer. replayState set ⟺ this run
          // committed the seeded objective (the briefing clears it on any other choice).
          const body = this.replayState
              ? { ...snapshot, remixedFromToken: this.replayState.sourceToken }
              : snapshot
1397 
          try {
              const res = (await $fetch('/api/run-save', {
                  method: 'POST',
                  headers: { 'Content-Type': 'application/json' },
                  body
              })) as { saved?: boolean }
              // Mark saved (for the share affordance) only if this run is still current
              // and the server actually persisted it (a degraded run returns saved:false).
              if (epoch === this.runEpoch && res?.saved) this.runSnapshotSaved = true
          } catch (error) {
              // Saving the run is a nicety; a failure must not break the end screen.
              if (epoch === this.runEpoch) console.error('Could not save the run:', error)
          }
      },
1412 
      resetGame() {
          // Tear the epoch first: anything still in flight belongs to the old run
          // and must find no purchase here. (The seq counters deliberately survive.)
          this.runEpoch++
          this.remainingMessages = TOTAL_MESSAGES
          this.messageHistory = []
          this.gameStatus = 'playing'
          this.isLoading = false
          this.error = null
          this.lastMessageTime = null
          this.isRateLimited = false
          // A new run gets a fresh id on its next server call; abandon any
          // in-flight mint so a dead run's id can't land in the new run.
          this.runId = null
          this.runIdInflight = null
          this.runSnapshotSaved = false
          // The paywall / capacity notices re-check on the next commit.
          this.outOfRuns = false
          this.atCapacity = false
          this.currentObjective = null
          // A fresh run carries no replay lineage (preseedReplay re-sets it after).
          this.replayState = null
          this.objectiveProgress = 0
          this.peakProgress = 0
          this.momentum = 0
⋯ 26 lines hidden (lines 1438–1463)1438            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
      }
  }
1463})

Surfacing it on the end screen

The component decides visibility with one computed. showPeak is true only when the peak sits above the final %. A victory always ends at 100%, which is also its own peak, so showPeak is false on every clean win. The stat appears only on a run that lost ground — which, in practice, is the defeat the feature exists for.

The conditional stat in the existing summary row, and the one-line guard.

components/EndGameScreen.vue · 309 lines

components/EndGameScreen.vue309 lines · Vue

⋯ 69 lines hidden (lines 1–69)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        <RemixCreditLine v-if="remixCredit" :credit="remixCredit" class="mt-2.5" />
25 
26        <p v-if="!isVictory" data-testid="defeat-explanation" class="rv-muted text-sm mt-3 max-w-prose mx-auto">
27          Your five messages are spent. What you changed remains — but it was not enough, and the objective slipped away.
28        </p>
29 
30        <div v-if="victoryEfficiency" data-testid="efficiency-display" class="mt-3 rv-mono text-sm">
31          <span class="rv-ok font-semibold">{{ victoryPhrase }}</span>
32          <span class="rv-muted"> · {{ victoryEfficiency.messagesUsed }}/5 used<span v-if="victoryEfficiency.messagesSaved > 0"> · {{ victoryEfficiency.messagesSaved }} saved</span></span>
33          <span v-if="victoryEfficiency.isEarlyVictory" class="rv-ok"> · 🌟 to spare</span>
34        </div>
35      </div>
36 
37      <!-- The Chronicle's final telling — the epilogue. While the terminal telling is
38           still being written (epiloguePending), we show the "final account…" wait, NOT
39           the prior turn's stale, pre-ending telling. When it lands it cross-fades in
40           (mirroring Chronicle.vue's rewrite reveal); a failed final refresh clears
41           pending and falls back to the prior telling, so the panel never hangs. -->
42      <div v-if="chronicle || epiloguePending" data-testid="end-chronicle" class="mt-6">
43        <span class="rv-label rv-label--rule"><span aria-hidden="true">📖</span> The Chronicle</span>
44        <Transition :name="epilogueTransition" mode="out-in">
45          <div v-if="epiloguePending" key="epilogue-loading" data-testid="end-chronicle-loading" class="rv-faint italic text-sm">
46            The chronicler sets down the final account…
47          </div>
48          <article v-else-if="chronicle" key="epilogue-body" data-testid="end-chronicle-body">
49            <h4 data-testid="end-chronicle-title" class="rv-serif text-xl font-semibold rv-fg mb-2.5 leading-tight">{{ chronicle.title }}</h4>
50            <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>
51          </article>
52        </Transition>
53      </div>
54 
55      <!-- The words you sent — the keepsake: your actual messages into the past -->
56      <div v-if="dispatches.length" data-testid="dispatches" class="mt-7">
57        <span class="rv-label rv-label--rule">The words you sent</span>
58        <ul class="space-y-3.5">
59          <li v-for="(d, i) in dispatches" :key="i">
60            <p class="rv-label">to {{ d.figure }}<span v-if="d.era"> · {{ d.era }}</span></p>
61            <blockquote class="rv-serif rv-fg text-base leading-relaxed border-l-2 rv-line pl-3 mt-1">"{{ d.text }}"</blockquote>
62          </li>
63        </ul>
64      </div>
65 
66      <!-- Stats — derived from the real resolved turns -->
67      <div data-testid="game-summary" class="mt-7">
68        <span class="rv-label rv-label--rule">How it played out</span>
69        <div class="flex flex-wrap gap-10">
70          <!-- "Peaked at X%" — shown only when the run slipped from its high point
71               (the peak sits above the floored final %). The case it exists for is a
72               staked last dispatch that crit-fails to 0% from a real peak, where the
73               final % alone reads "as if you did nothing" (#129). A clean win never
74               shows it: its peak IS the final 100%. -->
75          <div v-if="showPeak" data-testid="peak-progress">
76            <div class="rv-mono text-3xl font-extrabold rv-accent leading-none">{{ gameStore.peakProgress }}%</div>
77            <div class="rv-label mt-1">peaked at</div>
78          </div>
79          <div data-testid="message-efficiency">
⋯ 124 lines hidden (lines 80–203)80            <div class="rv-mono text-3xl font-extrabold rv-fg leading-none">{{ messagesUsed }}</div>
81            <div class="rv-label mt-1">{{ messagesUsed === 1 ? 'message' : 'messages' }} sent</div>
82          </div>
83          <div v-if="gameSummary.bestRoll" data-testid="best-roll">
84            <div class="rv-mono text-3xl font-extrabold rv-ok leading-none">{{ gameSummary.bestRoll.diceRoll }}</div>
85            <div class="rv-label mt-1">{{ messagesUsed >= 2 ? 'best roll' : 'the roll that did it' }} · {{ gameSummary.bestRoll.diceOutcome }}</div>
86          </div>
87          <div v-if="gameSummary.worstRoll && messagesUsed >= 2" data-testid="worst-roll">
88            <div class="rv-mono text-3xl font-extrabold rv-bad leading-none">{{ gameSummary.worstRoll.diceRoll }}</div>
89            <div class="rv-label mt-1">worst roll · {{ gameSummary.worstRoll.diceOutcome }}</div>
90          </div>
91        </div>
92      </div>
93 
94      <!-- The history you wrote — the Spine itself, exactly as it filled in during
95           the run. Read-only here: no live "▷ now" present marker, no "the timeline
96           trembles…" empty state. Same component the player scrolled and tapped on
97           the board, so the verdict's history reads as richly as it did in play —
98           valence dots, ⚡/⚑ badges, the roll, and the Δ equation all carry over. -->
99      <div v-if="timeline.length > 0" class="mt-6">
100        <TimelineLedger readonly />
101      </div>
102 
103      <!-- Share this run (issue #88) — once the snapshot is durably saved. Proud of the
104           rewrite? Post it: the public page, the unfurl, the share card. -->
105      <div v-if="canShare" class="mt-8">
106        <ShareControls :run-id="shareRunId" :share-text="shareText" />
107      </div>
108 
109      <div class="mt-9 border-t rv-line pt-6 flex items-center gap-3 flex-wrap">
110        <button ref="playAgainRef" type="button" data-testid="play-again-button" class="rv-btn rv-btn--primary" @click="playAgain">
111          Try a new timeline <span aria-hidden="true">▷</span>
112        </button>
113        <!-- The finished run just joined your saved-runs history, so the end screen
114             offers an obvious way to reach it: a secondary button beside the primary
115             "Try a new timeline" (the button-styled /runs link mirrors the
116             retrospective's "Back to your runs", pages/runs/[id].vue), carrying the ◷
117             glyph and "Your runs" wording from the account popover (RunsBalance.vue). -->
118        <NuxtLink to="/runs" data-testid="end-your-runs-link" class="rv-btn inline-flex items-center gap-1.5">
119          <span aria-hidden="true">◷</span> Your runs
120        </NuxtLink>
121        <span class="rv-faint text-xs inline-flex items-center gap-1.5">
122          <span class="rv-dot" :class="isVictory ? 'rv-dot--ok' : 'rv-dot--bad'" aria-hidden="true" /> this timeline is written.
123        </span>
124      </div>
125    </div>
126  </div>
127</template>
128 
129<script setup lang="ts">
130/**
131 * EndGameScreen — the mission debrief. A full-bleed takeover (not a modal card):
132 * verdict line, the Chronicle epilogue + big-number stat trio, and the history you
133 * wrote. All stats derive from the real resolved turns.
134 */
135import { ref, computed, watch, nextTick } from 'vue'
136import { useGameStore } from '~/stores/game'
137import { usePrefersReducedMotion } from '~/composables/usePrefersReducedMotion'
138import { buildShareText, type RemixCredit } from '~/utils/run-snapshot'
139 
140const gameStore = useGameStore()
141 
142// When this run is a replay (issue #89), the "remixed from" credit, from the live seed —
143// shown on the end screen the moment the replay resolves. The title is omitted (the
144// objective is already in the masthead above), so it reads "Remixed from <source>".
145const remixCredit = computed<RemixCredit | null>(() =>
146    gameStore.replayState
147        ? { attribution: gameStore.replayState.sourceAttribution, objectiveTitle: '', sourceToken: gameStore.replayState.sourceToken }
148        : null
149)
150const reduced = usePrefersReducedMotion()
151 
152const headingId = `end-game-heading-${Math.random().toString(36).slice(2, 11)}`
153 
154// Modal focus management: it's a true takeover (aria-modal), so when it opens we
155// move focus to the VERDICT heading (tabindex=-1: announced, focusable, outside
156// the Tab cycle), trap Tab inside, and restore focus when the run ends. Focusing
157// the heading — not the bottom Play Again button — also means the screen opens at
158// the top: the verdict and the Chronicle epilogue are the first things seen, not
159// scrolled past below the fold.
160const dialogRef = ref<HTMLElement | null>(null)
161const headingRef = ref<HTMLElement | null>(null)
162const playAgainRef = ref<HTMLElement | null>(null)
163let prevFocus: HTMLElement | null = null
164 
165watch(() => gameStore.gameStatus, async (s) => {
166    if (typeof document === 'undefined') return
167    if (s === 'victory' || s === 'defeat') {
168        prevFocus = document.activeElement as HTMLElement | null
169        await nextTick()
170        if (dialogRef.value) dialogRef.value.scrollTop = 0
171        headingRef.value?.focus()
172    } else if (prevFocus) {
173        prevFocus.focus?.()
174        prevFocus = null
175    }
176})
177 
178function onKeydown(e: KeyboardEvent) {
179    if (e.key !== 'Tab' || !dialogRef.value) return
180    const focusables = dialogRef.value.querySelectorAll<HTMLElement>(
181        'a[href], button:not([disabled]), input:not([disabled]), [tabindex]:not([tabindex="-1"])'
182    )
183    if (!focusables.length) return
184    const first = focusables[0]
185    const last = focusables[focusables.length - 1]
186    const active = document.activeElement
187    if (e.shiftKey && active === first) { e.preventDefault(); last.focus() }
188    else if (!e.shiftKey && active === last) { e.preventDefault(); first.focus() }
189}
190 
191const isVictory = computed(() => gameStore.gameStatus === 'victory')
192const victoryEfficiency = computed(() => gameStore.getVictoryEfficiency())
193 
194// The verdict never deflates: spending every message is reframed as "Hard-won," not
195// the limp "Standard." Only the laudatory tiers keep their rating as an adjective.
196const victoryPhrase = computed(() => {
197    const rating = victoryEfficiency.value?.efficiencyRating
198    if (!rating) return 'Victory'
199    return rating === 'Standard' ? 'Hard-won victory' : `${rating} victory`
200})
201const messagesUsed = computed(() => 5 - gameStore.remainingMessages)
202const gameSummary = computed(() => gameStore.gameSummary)
203 
204// "Peaked at X%" surfaces only when the run lost ground from its high-water mark —
205// the peak above the final %. The case it answers is a staked last dispatch that
206// crit-fails to 0% from a real peak, where the floored final % alone would read "as
207// if the player did nothing" (#129). A clean win never shows it (peak === final 100%).
208const showPeak = computed(() => gameStore.peakProgress > gameStore.objectiveProgress)
⋯ 101 lines hidden (lines 209–309)209 
210// Share affordance (issue #88): only for a run that's been durably saved (so there's a
211// server-side record to make public). `canShare` true ⟹ runId is a real saved uuid.
212const canShare = computed(() => gameStore.runSnapshotSaved && !!gameStore.runId)
213const shareRunId = computed(() => gameStore.runId ?? '')
214const shareText = computed(() =>
215    buildShareText(gameStore.currentObjective?.title ?? '', isVictory.value ? 'victory' : 'defeat', gameStore.objectiveProgress)
216)
217const timeline = computed(() => gameStore.timelineEvents)
218const chronicle = computed(() => gameStore.chronicle)
219// The epilogue (terminal telling) is still being written — show the wait, never the
220// prior turn's stale telling. The cross-fade mirrors Chronicle.vue and is dropped
221// under prefers-reduced-motion (the empty name disables the Transition's classes).
222const epiloguePending = computed(() => gameStore.epiloguePending)
223const epilogueTransition = computed(() => (reduced.value ? '' : 'epilogue'))
224 
225// The keepsake: the player's verbatim messages, paired with whom/when they reached.
226const dispatches = computed(() => {
227    const users = gameStore.messageHistory.filter(m => m.sender === 'user')
228    const events = gameStore.timelineEvents
229    return users.map((m, i) => ({
230        text: m.text,
231        figure: m.figureName || events[i]?.figureName || 'the past',
232        era: events[i]?.era || ''
233    }))
234})
235 
236// The page owns the FULL reset (store + figure input + composer), so Play Again
237// emits instead of resetting the store directly — the two reset paths used to
238// diverge here, leaving the previous run's figure stranded in the input.
239const emit = defineEmits<{ 'play-again': [] }>()
240const playAgain = () => {
241    emit('play-again')
242}
243</script>
244 
245<style scoped>
246/* The epilogue reveal — the terminal telling cross-fades in over the "final account…"
247   wait, the same gentle opacity fade Chronicle.vue uses for a rewrite. Gated by the
248   transition NAME (empty under prefers-reduced-motion), so reduced-motion gets an
249   instant swap with no classes attached. */
250.epilogue-enter-active,
251.epilogue-leave-active {
252    transition: opacity var(--rv-dur-3) var(--rv-ease);
253}
254.epilogue-enter-from,
255.epilogue-leave-to {
256    opacity: 0;
257}
258 
259/* Win and loss share the page frame but not its mood. The win is illuminated — a warm
260   wash blooms from the top; the loss is a colder, dimmer ground that has settled back. */
261.end-screen { background: var(--rv-bg); animation: end-in var(--rv-dur-3) var(--rv-ease) both; }
262@keyframes end-in { from { opacity: 0; } to { opacity: 1; } }
263@media (prefers-reduced-motion: reduce) { .end-screen { animation: none; } }
264.end--win {
265    background:
266        radial-gradient(135% 70% at 50% -12%, color-mix(in srgb, var(--rv-accent) 13%, transparent), transparent 68%),
267        var(--rv-bg);
268}
269.end--loss {
270    background:
271        radial-gradient(135% 70% at 50% -12%, color-mix(in srgb, var(--rv-bad) 6%, transparent), transparent 60%),
272        var(--rv-tint);
273}
274 
275/* The struck seal — the verdict's emblem. The win seal glows like fresh sealing wax;
276   the loss seal is a cold, flat stamp. */
277.verdict-seal {
278    display: inline-grid;
279    place-items: center;
280    width: 60px;
281    height: 60px;
282    border-radius: 50%;
283    border: 2px solid;
284    font-size: 1.6rem;
285    line-height: 1;
286}
287.verdict-seal.is-win {
288    color: var(--rv-accent);
289    border-color: var(--rv-accent);
290    box-shadow:
291        0 0 0 5px color-mix(in srgb, var(--rv-accent) 12%, transparent),
292        0 0 30px color-mix(in srgb, var(--rv-accent) 32%, transparent);
293    animation: seal-strike 0.6s var(--rv-ease-spring) both;
294}
295.verdict-seal.is-loss {
296    color: var(--rv-faint);
297    border-color: var(--rv-line);
298    box-shadow: inset 0 0 0 4px color-mix(in srgb, var(--rv-faint) 8%, transparent);
299}
300 
301@keyframes seal-strike {
302    0% { opacity: 0; transform: scale(.5) rotate(-12deg); }
303    60% { transform: scale(1.12) rotate(3deg); }
304    100% { opacity: 1; transform: scale(1) rotate(0); }
305}
306@media (prefers-reduced-motion: reduce) {
307    .verdict-seal.is-win { animation: none; }
308}
309</style>

Tests that pin the behavior

Two discriminating pairs, not coverage padding. In the store, the peak must survive a setback: climb to 25%, crit-fail to 0%, and the mark holds at 25% — plus both resets clear it. In the component, the stat shows when the run slipped and stays hidden on a clean 100% win.

The mark holds through a setback; resetGame clears it.

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

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

⋯ 74 lines hidden (lines 1–74)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.peakProgress).toBe(0)
          expect(store.messageHistory).toEqual([])
          expect(store.timelineEvents).toEqual([])
          expect(store.figures).toEqual([])
          expect(store.canSendMessage).toBe(true)
      })
  })
66 
  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)
      })
74 
      // The high-water mark must SURVIVE a setback so the end screen can show
      // "peaked at X%" — the staked-crit-fail case where the final % erases the
      // player's real progress (#129).
      it('tracks the peak high-water mark and holds it when progress slips', () => {
          store.applyProgress(25)
          expect(store.peakProgress).toBe(25)
          store.applyProgress(-25) // crit-fail back to nothing
          expect(store.objectiveProgress).toBe(0)
          expect(store.peakProgress).toBe(25) // the peak is preserved
      })
⋯ 476 lines hidden (lines 85–560)85 
      it('decrementMessages does not, by itself, end the game', () => {
          store.decrementMessages()
          expect(store.remainingMessages).toBe(4)
          expect(store.gameStatus).toBe('playing')
      })
91 
      it('resolves victory the moment progress hits 100', () => {
          store.objectiveProgress = 100
          store.resolveGameStatus()
          expect(store.gameStatus).toBe('victory')
      })
97 
      it('resolves defeat only once messages run out unmet', () => {
          store.remainingMessages = 0
          store.objectiveProgress = 50
          store.resolveGameStatus()
          expect(store.gameStatus).toBe('defeat')
      })
104 
      it('prefers victory over defeat on the final message', () => {
          store.remainingMessages = 0
          store.objectiveProgress = 100
          store.resolveGameStatus()
          expect(store.gameStatus).toBe('victory')
      })
111 
      it('stays playing while messages remain and the objective is unmet', () => {
          store.remainingMessages = 3
          store.objectiveProgress = 50
          store.resolveGameStatus()
          expect(store.gameStatus).toBe('playing')
      })
  })
119 
  describe('figures', () => {
      it('registers a new figure and refines it on later contact', () => {
          store.registerFigure({ name: 'Cleopatra', era: '', descriptor: '' })
          expect(store.figures).toHaveLength(1)
124 
          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')
      })
  })
131 
  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 })
137 
          expect(store.timelineEvents.map(e => e.valence)).toEqual(['negative', 'positive', 'neutral'])
      })
  })
141 
  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')
147 
          expect(store.conversationWith('Tesla')).toHaveLength(2)
          expect(store.conversationWith('Cleopatra')).toHaveLength(1)
      })
151 
      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')
      })
  })
157 
  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())
168 
      it('staggers the beats: suspense → reply → swing → node', async () => {
          fetchMock.mockResolvedValue(okResponse())
          const p = store.sendMessage('Light the world', 'Nikola Tesla')
172 
          // 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)
177 
          // 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)
185 
          // 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)
190 
          // 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)
      })
196 
      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)
      })
  })
209 
  describe('sendMessage', () => {
      it('folds a successful turn into messages, ledger, progress, and figures', async () => {
          fetchMock.mockResolvedValue(okResponse())
213 
          await store.sendMessage('Light the world wirelessly', 'Nikola Tesla')
215 
          // 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')
220 
          // 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')
229 
          // 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' })
236 
          expect(store.remainingMessages).toBe(4)
          expect(store.isLoading).toBe(false)
      })
240 
      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)
      })
246 
      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' }
          }))
251 
          await store.sendMessage('Hmm', 'Tesla')
253 
          expect(store.timelineEvents).toHaveLength(1)
          expect(store.timelineEvents[0].valence).toBe('neutral')
          expect(store.objectiveProgress).toBe(0)
      })
258 
      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)
      })
266 
      it('refunds the message and drops the dangling prompt on a network error', async () => {
          fetchMock.mockRejectedValue(new Error('network down'))
269 
          await store.sendMessage('A message that fails', 'Tesla')
271 
          expect(store.error).toBeTruthy()
          expect(store.remainingMessages).toBe(5)
          expect(store.messageHistory).toHaveLength(0)
          expect(store.gameStatus).toBe('playing')
      })
277 
      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' }
          })
284 
          const resolved = await store.sendMessage('A doomed dispatch', 'Tesla')
286 
          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)
      })
293 
      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.'
              }
          })
305 
          const resolved = await store.sendMessage('Synthesize a nerve agent at scale', 'Fritz Haber')
307 
          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)
      })
315 
      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' }
          })
324 
          await store.sendMessage('The last word', 'Tesla')
326 
          // 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')
      })
331 
      it('reports resolution truthfully: true when a turn lands, false when refunded', async () => {
          fetchMock.mockResolvedValueOnce(okResponse())
          expect(await store.sendMessage('First', 'Tesla')).toBe(true)
335 
          store.lastMessageTime = null // clear the rate-limit window
          fetchMock.mockRejectedValueOnce(new Error('down'))
          expect(await store.sendMessage('Second', 'Tesla')).toBe(false)
      })
340 
      it('arms the stake only on the final message — never earlier', async () => {
          fetchMock.mockResolvedValue(okResponse())
343 
          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
347 
          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)
      })
354 
      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())
359 
          await store.sendMessage('One clean throw', 'Tesla', { stake: true })
361 
          const body = fetchMock.mock.calls[0][1].body
          expect(body.stake).toBe(false)
      })
365 
      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' }
          }))
375 
          await store.sendMessage('Stake it all', 'Tesla')
377 
          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)
      })
390 
      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' }
          }))
397 
          await store.sendMessage('The decisive word', 'Tesla')
399 
          expect(store.objectiveProgress).toBe(100)
          expect(store.remainingMessages).toBe(0)
          expect(store.gameStatus).toBe('victory')
      })
404 
      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' }
          }))
411 
          await store.sendMessage('A last try', 'Tesla')
413 
          expect(store.objectiveProgress).toBe(15)
          expect(store.remainingMessages).toBe(0)
          expect(store.gameStatus).toBe('defeat')
      })
  })
419 
  describe('living chronicle (refreshChronicle)', () => {
      const telling = { title: 'The Peace That Held', paragraphs: ['In 1878, Bismarck chose trade.', 'By 1914, no war came.'] }
422 
      function seedOneChange() {
          store.addTimelineEvent({
              figureName: 'Bismarck', era: '1878', headline: 'Bismarck chooses trade',
              detail: 'Alliances soften into commerce.', diceRoll: 16, diceOutcome: DiceOutcome.SUCCESS, progressChange: 20
          })
      }
429 
      it('re-narrates the timeline and stores the telling', async () => {
          seedOneChange()
          fetchMock.mockResolvedValue({ success: true, chronicle: telling })
433 
          await store.refreshChronicle()
435 
          expect(fetchMock).toHaveBeenCalledWith('/api/chronicle', expect.objectContaining({ method: 'POST' }))
          expect(store.chronicle).toEqual(telling)
          expect(store.chronicleLoading).toBe(false)
      })
440 
      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()
      })
447 
      it('keeps the prior telling when a refresh fails (never blanks)', async () => {
          seedOneChange()
          store.chronicle = telling
          fetchMock.mockRejectedValue(new Error('chronicler offline'))
452 
          await store.refreshChronicle()
454 
          expect(store.chronicle).toEqual(telling)
          expect(store.chronicleLoading).toBe(false)
      })
458 
      it('fires a non-blocking refresh after a turn actually changes the world', async () => {
          fetchMock.mockResolvedValue(okResponse())
461 
          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()
466 
          // The refresh is fired (not awaited) once the turn added a ledger entry.
          expect(fetchMock).toHaveBeenCalledWith('/api/chronicle', expect.objectContaining({ method: 'POST' }))
      })
470 
      it('does NOT refresh when a turn fails to change the world', async () => {
          fetchMock.mockRejectedValue(new Error('network down'))
473 
          await store.sendMessage('A message that fails', 'Tesla')
475 
          expect(fetchMock).not.toHaveBeenCalledWith('/api/chronicle', expect.anything())
      })
  })
479 
  // 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.'] }
485 
      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 }
      }
492 
      // 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
          })
      }
504 
      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)
510 
          await store.sendMessage('The decisive word', 'Tesla')
          await flushPromises() // aiHeaders is async; let the non-blocking refresh fire
513 
          expect(store.gameStatus).toBe('victory')
          expect(store.epiloguePending).toBe(true) // the end screen shows "the final account…"
516 
          chronicle.resolve({ success: true, chronicle: epilogue })
          await flushPromises()
519 
          expect(store.epiloguePending).toBe(false)
          expect(store.chronicle).toEqual(epilogue) // the epilogue, not a stale prior telling
      })
523 
      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)
531 
          await store.sendMessage('The decisive word', 'Tesla')
          await flushPromises()
          expect(store.epiloguePending).toBe(true)
535 
          chronicle.reject(new Error('chronicler offline'))
          await flushPromises()
538 
          expect(store.epiloguePending).toBe(false) // not stuck on the loading state
          expect(store.chronicle).toEqual(prior) // the prior telling is kept (never blanks)
      })
542 
      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
547 
          await store.sendMessage('A mid-run move', 'Tesla')
          await flushPromises()
550 
          expect(store.gameStatus).toBe('playing')
          expect(store.epiloguePending).toBe(false)
      })
554 
      it('resetGame clears a pending epilogue', () => {
          store.epiloguePending = true
          store.resetGame()
          expect(store.epiloguePending).toBe(false)
      })
560 
      it('resetGame clears the peak high-water mark', () => {
          store.applyProgress(40)
          expect(store.peakProgress).toBe(40)
          store.resetGame()
          expect(store.peakProgress).toBe(0)
      })
⋯ 926 lines hidden (lines 567–1492)567    })
568 
  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 }
      }
576 
      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)
580 
          const inFlight = store.sendMessage('From the old world', 'Tesla')
          store.resetGame()
          slow.resolve(okResponse())
          const resolved = await inFlight
585 
          // 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)
      })
593 
      it('a reset mid-send must not "refund" the new run on failure either', async () => {
          const slow = deferred<never>()
          fetchMock.mockReturnValue(slow.promise)
597 
          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
603 
          expect(store.remainingMessages).toBe(3) // untouched by the stale refund
      })
606 
      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 })
609 
          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)
613 
          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
621 
          expect(store.chronicle?.title).toBe('The Later Telling')
          expect(store.chronicleLoading).toBe(false)
      })
625 
      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)
630 
          const inFlight = store.refreshChronicle()
          store.resetGame()
          slow.resolve({ success: true, chronicle: { title: 'A Ghost Epilogue', paragraphs: ['boo'] } })
          await inFlight
635 
          expect(store.chronicle).toBeNull()
      })
638 
      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)
643 
          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
650 
          expect(store.figureGrounding?.name).toBe('Otto von Bismarck')
          expect(store.groundingLoading).toBe(false)
      })
654 
      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)
658 
          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
663 
          expect(store.figureGrounding).toBeNull()
          expect(store.contactWhen).toBeNull()
          expect(store.groundingLoading).toBe(false)
      })
668 
      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)
678 
          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
683 
          // The brief is FOR -40; recording -35 would mislabel it and hide Re-study.
          expect(store.studyWhen).toBe(-40)
          expect(store.studyFor).toBe('Cleopatra')
      })
  })
689 
  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)
      })
699 
      it('returns null when not a victory', () => {
          store.gameStatus = 'playing'
          expect(store.getVictoryEfficiency()).toBeNull()
      })
  })
705 
  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: '' }
721 
          store.resetGame()
723 
          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()
      })
  })
739 
  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: '📜'
      }
747 
      it('chooseObjective commits the objective and resets progress', async () => {
          fetchMock.mockResolvedValue({ runsRemaining: 5 })
          store.objectiveProgress = 40
          store.momentum = 2
          store.setError('a stale error')
753 
          const started = await store.chooseObjective(objective)
755 
          expect(started).toBe(true)
          expect(store.currentObjective).toEqual(objective)
          expect(store.objectiveProgress).toBe(0)
          expect(store.momentum).toBe(0)
          expect(store.error).toBeNull()
      })
762 
      it('fetchAIObjective returns a composed objective WITHOUT committing it', async () => {
          fetchMock.mockResolvedValue({ success: true, objective })
765 
          const result = await store.fetchAIObjective()
767 
          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()
      })
776 
      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()
      })
782 
      it('fetchAIObjective returns null when the server reports failure', async () => {
          fetchMock.mockResolvedValue({ success: false })
          expect(await store.fetchAIObjective()).toBeNull()
      })
  })
788 
  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
      }
798 
      it('grounds the active figure and defaults the when inside their lifetime', async () => {
          fetchMock.mockResolvedValue(cleopatra)
801 
          await store.groundActiveFigure('Cleopatra')
803 
          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)
      })
814 
      it('flags a when before birth or after death', async () => {
          fetchMock.mockResolvedValue(cleopatra)
          await store.groundActiveFigure('Cleopatra')
818 
          store.setContactWhen(-200) // 200 BC — long before she was born
          expect(store.contactLiveness).toBe('before-birth')
          expect(store.canContact).toBe(false)
822 
          store.setContactWhen(1990) // long after she died
          expect(store.contactLiveness).toBe('after-death')
          expect(store.canContact).toBe(false)
826 
          store.setContactWhen(-50) // 50 BC — within her life
          expect(store.contactLiveness).toBe('ok')
      })
830 
      it('blocks contact to an unresolved figure — require grounding (#73)', async () => {
          fetchMock.mockResolvedValue({ name: 'Nobody', resolved: false })
          await store.groundActiveFigure('Nobody Atall')
834 
          expect(store.figureGrounding?.resolved).toBe(false)
          expect(store.contactWhen).toBeNull()
          expect(store.contactLiveness).toBe('unresolved')
          expect(store.canContact).toBe(false)
      })
840 
      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')
848 
          // 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)
      })
854 
      it('pins, rescrubs, and clears the contact moment (issue #32)', async () => {
          fetchMock.mockResolvedValue(cleopatra)
          await store.groundActiveFigure('Cleopatra')
858 
          store.setContactMoment({ month: 6, day: 28 })
          expect(store.contactMoment).toEqual({ month: 6, day: 28 })
861 
          // Scrubbing the year keeps the pin — it refines whichever year is chosen.
          store.setContactWhen(-44)
          expect(store.contactMoment).toEqual({ month: 6, day: 28 })
865 
          // A name change clears it with the rest of the dossier.
          store.clearGrounding()
          expect(store.contactMoment).toBeNull()
      })
870 
      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' } })
878 
          await store.sendMessage('Hold court away from the palace today.', 'Cleopatra')
880 
          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)
      })
887 
      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()
      })
895 
      it('refuses to send to someone outside their lifetime', async () => {
          fetchMock.mockResolvedValue(cleopatra)
          await store.groundActiveFigure('Cleopatra')
          store.setContactWhen(-300) // before birth
          fetchMock.mockClear()
901 
          await store.sendMessage('Beware the Ides', 'Cleopatra')
903 
          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)
      })
909 
      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()
919 
          await store.sendMessage('Write a song about the timeline', 'Paul McCartney')
921 
          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
      })
927 
      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()
932 
          await store.sendMessage('Into the void', 'Nobody Atall')
934 
          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
      })
  })
941 
  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
      }
949 
      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)
      })
955 
      it('is 0 in the birth year', () => {
          store.figureGrounding = cleopatra as never
          store.setContactWhen(-69)
          expect(store.contactAge).toBe(0)
      })
961 
      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)
      })
972 
      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)
      })
981 
      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()
986 
          store.figureGrounding = null
          expect(store.contactAge).toBeNull()
      })
990 
      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()
      })
  })
997 
  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'
      }
1011 
      it('studies a grounded figure and stores the brief', async () => {
          store.figureGrounding = cleopatra as never
          store.setContactWhen(-40)
          fetchMock.mockResolvedValue({ success: true, study })
1016 
          await store.studyActiveFigure()
1018 
          expect(fetchMock).toHaveBeenCalledWith('/api/research', expect.objectContaining({ method: 'POST' }))
          expect(store.figureStudy).toEqual(study)
          expect(store.studyFor).toBe('Cleopatra')
          expect(store.studyLoading).toBe(false)
      })
1024 
      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()
1031 
          await store.studyActiveFigure()
          expect(fetchMock).not.toHaveBeenCalled()
      })
1035 
      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()
1043 
          store.setContactWhen(-35) // move the slider
          await store.studyActiveFigure()
1046 
          expect(fetchMock).toHaveBeenCalledWith('/api/research', expect.objectContaining({ method: 'POST' }))
          expect(store.studyWhen).toBe(-35)
      })
1050 
      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()
      })
1057 
      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)
      })
1065 
      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.' })
1070 
          await store.studyActiveFigure()
1072 
          expect(store.studyNotice).toContain('blocked by content moderation')
          expect(store.figureStudy).toBeNull()
          expect(store.studyLoading).toBe(false)
      })
1077 
      it('drops a stale study when the contact changes', async () => {
          store.figureStudy = study as never
          store.studyFor = 'Cleopatra'
          fetchMock.mockResolvedValue({ name: 'Tesla', resolved: false })
1082 
          await store.groundActiveFigure('Nikola Tesla')
1084 
          expect(store.figureStudy).toBeNull()
          expect(store.studyFor).toBe('')
      })
  })
1089 
  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'
      }
1097 
      it('looks up a topic and stores the result', async () => {
          fetchMock.mockResolvedValue({ success: true, lookup })
1100 
          await store.askArchive('gunpowder')
1102 
          expect(fetchMock).toHaveBeenCalledWith('/api/lookup', expect.objectContaining({ method: 'POST' }))
          expect(store.archiveResult).toEqual(lookup)
          expect(store.lookupLoading).toBe(false)
      })
1107 
      it('ignores an empty query', async () => {
          await store.askArchive('   ')
          expect(fetchMock).not.toHaveBeenCalled()
      })
1112 
      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)
      })
  })
1120 
  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' }
          }))
1126 
          await store.sendMessage('Build a flying machine and aim higher', 'Leonardo da Vinci')
1128 
          expect(store.timelineEvents[0].anachronism).toBe('far-ahead')
      })
1131 
      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()
      })
  })
1138 
  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: '🕊️'
      }
1146 
      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
          })
1154 
          await store.loadSuggestions()
1156 
          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')
      })
1162 
      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()
1168 
          await store.loadSuggestions()
          expect(fetchMock).not.toHaveBeenCalled()
      })
1172 
      it('clears suggestions when there is no objective', async () => {
          store.currentObjective = null
          await store.loadSuggestions()
          expect(store.figureSuggestions).toEqual([])
          expect(fetchMock).not.toHaveBeenCalled()
      })
1179 
      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.' })
1183 
          await store.loadSuggestions()
1185 
          expect(store.suggestionsNotice).toContain('blocked by content moderation')
          expect(store.figureSuggestions).toEqual([])
      })
1189 
      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')
      })
  })
1200 
  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
      }
1206 
      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')
      })
1212 
      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
      })
1220 
      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()
      })
  })
1227 
  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()
      })
1243 
      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
      })
1251 
      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)
      })
1264 
      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' })
              })
          )
      })
1277 
      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
      })
1292 
      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
      })
1306 
      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' }) })
          )
      })
  })
1322 
  describe('run balance (the paywall gate)', () => {
      const objective = { title: 'Spare the library', description: 'The scrolls survive.', era: 'Alexandria', icon: '📜' }
1325 
      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
      })
1339 
      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
      })
1352 
      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()
      })
1362 
      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)
          }
      })
1372 
      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')
      })
1381 
      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()
      })
1391 
      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()
      })
  })
1401 
  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()
      })
1412 
      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' } })
          )
      })
1421 
      it('buyPack returns null on failure', async () => {
          fetchMock.mockRejectedValue(new Error('stripe down'))
          expect(await store.buyPack('courier')).toBeNull()
      })
1426 
      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)
      })
  })
1436 
  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)
      })
1447 
      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)
      })
1454 
      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)
      })
1461 
      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)
      })
1470 
      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
      })
1479 
      it('notePurchaseReturn(cancel) records the notice without refetching', async () => {
          await store.notePurchaseReturn('cancel')
          expect(store.purchaseNotice).toBe('cancel')
          expect(fetchMock).not.toHaveBeenCalled()
      })
1485 
      it('clearPurchaseNotice dismisses the notice', () => {
          store.purchaseNotice = 'success'
          store.clearPurchaseNotice()
          expect(store.purchaseNotice).toBeNull()
      })
  })
1492})

Shown on a slipped defeat (final 0%, peak 25%); absent on a clean win.

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

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

⋯ 170 lines hidden (lines 1–170)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 
27// NuxtLink can't resolve RouterLink under a bare @vue/test-utils mount, so stub it
28// per-mount to a plain anchor (href ← `to`): the footer "Your runs" link is the only
29// NuxtLink here, so this keeps every mount free of the resolve warning and lets the
30// link's text/href be asserted directly. (The real render is covered by the e2e.)
31const mountEnd = () =>
  mount(EndGameScreen, { global: { stubs: { NuxtLink: { props: ['to'], template: '<a :href="to"><slot /></a>' } } } })
33 
34describe('EndGameScreen', () => {
  let gameStore: ReturnType<typeof useGameStore>
36 
  beforeEach(() => {
      setActivePinia(createPinia())
      gameStore = useGameStore()
  })
41 
  describe('Victory', () => {
      beforeEach(() => {
          gameStore.gameStatus = 'victory'
          gameStore.objectiveProgress = 100
          gameStore.currentObjective = OBJ
          gameStore.remainingMessages = 2
      })
49 
      it('shows a victory headline', () => {
          const v = mountEnd().find('[data-testid="victory-message"]')
          expect(v.exists()).toBe(true)
          expect(v.text()).toContain('History Rewritten')
      })
55 
      it('shows the objective and final progress', () => {
          const w = mountEnd()
          expect(w.find('[data-testid="objective-title"]').text()).toContain('Reach the Moon by 1900')
          expect(w.find('[data-testid="final-progress"]').text()).toContain('100%')
      })
61 
      it('shows efficiency with messages saved', () => {
          const e = mountEnd().find('[data-testid="efficiency-display"]')
          expect(e.exists()).toBe(true)
          expect(e.text()).toContain('saved')
      })
  })
68 
  describe('Defeat', () => {
      beforeEach(() => {
          gameStore.gameStatus = 'defeat'
          gameStore.objectiveProgress = 45
          gameStore.currentObjective = OBJ
          gameStore.remainingMessages = 0
      })
76 
      it('shows a defeat headline', () => {
          const d = mountEnd().find('[data-testid="defeat-message"]')
          expect(d.exists()).toBe(true)
          expect(d.text()).toContain('Timeline Held')
      })
82 
      it('shows final progress below 100%', () => {
          expect(mountEnd().find('[data-testid="final-progress"]').text()).toContain('45%')
      })
86 
      it('explains the loss', () => {
          expect(mountEnd().find('[data-testid="defeat-explanation"]').exists()).toBe(true)
      })
  })
91 
  // 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'] }
98 
      beforeEach(() => {
          gameStore.gameStatus = 'victory'
          gameStore.currentObjective = OBJ
      })
103 
      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')
      })
113 
      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')
      })
122 
      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')
      })
  })
133 
  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)
          ]
      })
143 
      it('renders the summary block', () => {
          expect(mountEnd().find('[data-testid="game-summary"]').exists()).toBe(true)
      })
147 
      it('highlights the best roll from the AI turns', () => {
          const best = mountEnd().find('[data-testid="best-roll"]')
          expect(best.exists()).toBe(true)
          expect(best.text()).toContain('20')
      })
153 
      it('highlights the worst roll from the AI turns', () => {
          gameStore.messageHistory[1] = resolvedTurn(2, DiceOutcome.CRITICAL_FAILURE, -10)
          const worst = mountEnd().find('[data-testid="worst-roll"]')
          expect(worst.exists()).toBe(true)
          expect(worst.text()).toContain('2')
      })
160 
      it('shows the number of messages sent', () => {
          const eff = mountEnd().find('[data-testid="message-efficiency"]')
          expect(eff.exists()).toBe(true)
          expect(eff.text()).toContain('2')
      })
  })
167 
  // A run that built progress then lost ground — classically a staked final dispatch
  // that crit-failed to 0% — must not read "as if the player did nothing." The summary
  // surfaces "peaked at X%" whenever the peak sits above the floored final % (#129).
  describe('Peaked at X% — when a run loses ground', () => {
      it('shows the peak in the summary when the run slipped from its high point', () => {
          gameStore.gameStatus = 'defeat'
          gameStore.objectiveProgress = 0   // a staked last dispatch crit-failed to nothing
          gameStore.peakProgress = 25       // but the run had really reached 25%
          const peak = mountEnd().find('[data-testid="peak-progress"]')
          expect(peak.exists()).toBe(true)
          expect(peak.text()).toContain('25%')
      })
180 
      it('stays hidden on a clean win, where the peak is the final 100%', () => {
          gameStore.gameStatus = 'victory'
          gameStore.objectiveProgress = 100
          gameStore.peakProgress = 100
          expect(mountEnd().find('[data-testid="peak-progress"]').exists()).toBe(false)
      })
⋯ 107 lines hidden (lines 187–293)187    })
188 
  // 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
          })
      })
201 
      it('renders via the shared TimelineLedger, not the old hand-rolled list', () => {
          const w = mountEnd()
          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)
      })
209 
      it('renders the Spine read-only: no live "▷ now · your move" present marker', () => {
          expect(mountEnd().find('.spine-now').exists()).toBe(false)
      })
  })
214 
  // 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.'] }
      })
223 
      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.')
      })
229 
      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]')
      })
  })
235 
  describe('Play again', () => {
      beforeEach(() => { gameStore.gameStatus = 'victory' })
238 
      it('offers a restart', () => {
          const btn = mountEnd().find('[data-testid="play-again-button"]')
          expect(btn.exists()).toBe(true)
          expect(btn.text()).toContain('new timeline')
      })
244 
      it('asks the page for the unified reset when clicked (it never resets the store itself)', async () => {
          const wrapper = mountEnd()
          await wrapper.find('[data-testid="play-again-button"]').trigger('click')
248 
          // 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
      })
  })
255 
  // The finished run becomes part of the player's history, so the end screen
  // surfaces the same "Your runs" affordance the retrospective side uses.
  describe('Your runs link', () => {
      beforeEach(() => { gameStore.gameStatus = 'victory' })
260 
      it('offers an obvious /runs link beside Play Again', () => {
          const link = mountEnd().find('[data-testid="end-your-runs-link"]')
          expect(link.exists()).toBe(true)
          expect(link.text()).toContain('Your runs')
          expect(link.attributes('href')).toContain('/runs')
      })
267 
      it('shows it on a loss too', () => {
          gameStore.gameStatus = 'defeat'
          expect(mountEnd().find('[data-testid="end-your-runs-link"]').exists()).toBe(true)
      })
  })
273 
  describe('Edge cases', () => {
      it('handles a missing objective', () => {
          gameStore.gameStatus = 'victory'
          gameStore.currentObjective = null
          expect(() => mountEnd()).not.toThrow()
      })
280 
      it('does not render while still playing', () => {
          gameStore.gameStatus = 'playing'
          expect(mountEnd().find('[data-testid="end-game-screen"]').exists()).toBe(false)
      })
285 
      it('exposes dialog semantics', () => {
          gameStore.gameStatus = 'victory'
          const screen = mountEnd().find('[data-testid="end-game-screen"]')
          expect(screen.attributes('role')).toBe('dialog')
          expect(screen.attributes('aria-labelledby')).toBeTruthy()
      })
  })
293})