Conduct the turn reveal — a code-level reading

What changed, and why

A resolved turn applied all its state in one synchronous block — the AI reply, the ledger node, the progress swing — and flipped loading off. Every component watches its own slice and animates on change, so they all fired in the same tick: the die landing, the reply, the %-swing, and the spine node moved at once, with no suspense and no path for the eye.

The fix doesn't touch any component. It sequences the writes in the store, which sequences the existing animations for free — into one conducted beat.

The pacing, and when it applies

Three small constants and a guard. canAnimateReveal() is the seam: only a real browser with motion allowed staggers the reveal. SSR and the test env have no matchMedia, so they collapse to the instant, atomic apply — which is why the store's contract (all state present the moment sendMessage resolves) is unchanged and every other test is unaffected.

REVEAL timings + the matchMedia gate that keeps SSR/tests instant.

stores/game.ts · 1249 lines

stores/game.ts1249 lines · TypeScript

⋯ 149 lines hidden (lines 1–149)1import { defineStore } from 'pinia'
2import type { GameObjective } 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 { DiceOutcome } from '~/utils/dice'
13import { generateGameSummary, rateEfficiency, type GameSummary } from '~/utils/game-summary'
14import { TOTAL_MESSAGES, MAX_PROGRESS_SWING } from '~/utils/game-config'
15 
16export type Valence = 'positive' | 'negative' | 'neutral'
17 
18/**
* 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.
*/
23export interface HistoricalFigure {
  name: string
  era: string
  descriptor: string
27}
28 
29/**
* 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.
*/
36export 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
60}
61 
62/**
* 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.
*/
67export 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
  characterAction?: string
  timelineImpact?: string
  progressChange?: number
  /** The pre-amplifier swing + the wager level, for the reveal's equation. */
  baseProgressChange?: 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
91}
92 
93export type GameStatus = 'playing' | 'victory' | 'defeat'
94 
95/**
* 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.
*/
102type 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
          staked?: boolean
          characterResponse: { message: string; action: string }
          timeline: {
              headline: string
              detail: string
              era: string
              progressChange: number
              baseProgressChange?: 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
      }
  }
147 
148const RATE_LIMIT_MS = 1000 // message cooldown window, in ms
149const MAX_PROGRESS = 100 // objective progress is clamped to 0..MAX_PROGRESS
150 
151// Turn-reveal pacing. A resolved turn releases its beats one at a time — a beat of
152// suspense, then the die lands and the figure's reply writes itself in, then the
153// timeline shift, then the ledger node — so the resolution reads as one conducted
154// moment instead of everything firing in the same tick. Each component already
155// animates when its own slice of state changes; sequencing the WRITES sequences the
156// animations, with no component coordination. Tuned so the swing lands with the
157// reply's own "ripple" line (~0.55s into its staged reveal).
158export const REVEAL = { suspense: 450, swing: 550, node: 250 } as const
159const wait = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms))
160/** 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. */
163function canAnimateReveal(): boolean {
  return typeof window !== 'undefined'
      && typeof window.matchMedia === 'function'
      && !window.matchMedia('(prefers-reduced-motion: reduce)').matches
167}
168 
169function valenceOf(progressChange: number): Valence {
  if (progressChange > 0) return 'positive'
  if (progressChange < 0) return 'negative'
  return 'neutral'
⋯ 1077 lines hidden (lines 173–1249)173}
174 
175/** Formats a signed timeline year (AD positive, BCE negative) for display. */
176export function formatContactYear(signed: number): string {
  return signed < 0 ? `${-signed} BC` : `${signed}`
178}
179 
180/** Human lifespan line for a grounded figure, e.g. "69 BC – 30 BC" or "1942 – present". */
181function 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
185}
186 
187/** 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. */
189function 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
192}
193 
194/** True when a $fetch error is a 503 / at-capacity — the spend cap paused new
*  runs (distinct from the per-device 402 paywall). */
196function 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
199}
200 
201export type ContactLiveness = 'ok' | 'before-birth' | 'after-death' | 'unknown'
202 
203/**
* Game Store — core state for a session of freeform timeline editing.
*/
206export const useGameStore = defineStore('game', {
  state: () => ({
      remainingMessages: TOTAL_MESSAGES,
      messageHistory: [] as Message[],
      gameStatus: 'playing' as GameStatus,
      isLoading: false,
      error: null as string | null,
      lastMessageTime: null as number | null,
      isRateLimited: false,
      // Staleness plumbing, not run state. runEpoch increments on every reset so an
      // async result from a dead run can never write into a fresh one; the seq
      // counters order overlapping requests of the same kind so only the latest
      // lands (an earlier chronicle rewrite must not overwrite a later one).
      // Deliberately NOT restored by resetGame — they must survive it to work.
      runEpoch: 0,
      chronicleSeq: 0,
      groundingSeq: 0,
      // The current run's id — lazily minted on the run's first server call and
      // cleared by resetGame so each run gets a fresh one. Tags every AI call
      // (via the x-run-id header) so the gateway's cost telemetry groups per
      // run: the GTM cost instrument.
      runId: null as string | null,
      // The in-flight begin-run, so concurrent first-calls of a run share one
      // mint (one POST /api/run, one runs row) instead of racing two. Cleared
      // by resetGame. (Vue leaves a Promise unproxied, so awaiting it is safe.)
      runIdInflight: null as Promise<string> | null,
      // outOfRuns gates the mission screen's paywall (set when a commit is
      // refused with 402). The run packs offered there are loaded into `packs`.
      outOfRuns: false,
      // atCapacity gates the "at capacity" notice (set when a commit is refused
      // with 503 because the global spend cap paused new runs).
      atCapacity: false,
      packs: [] as Pack[],
      // The device's run balance, for the header gauge + account popover. null
      // until first loaded (GET /api/balance); the run-commit response also
      // refreshes it so the gauge stays live without a second round-trip.
      runsRemaining: null as number | null,
      freeRuns: 1,
      deviceRef: '' as string,
      // Account state (from /api/balance): the signed-in email, and whether the
      // current user is anonymous (→ must sign in before buying). Drives the
      // account UI + the sign-in-to-buy gate. false/null in device-fallback mode.
      accountEmail: null as string | null,
      accountAnonymous: false,
      // The run-packs sales modal — opened on demand (header) or automatically
      // when a commit is refused for being out of runs.
      buyModalOpen: false,
      // A one-shot notice after returning from Stripe Checkout ('success' shows a
      // credited confirmation; 'cancel' a gentle "no charge" note). Cleared by the UI.
      purchaseNotice: null as 'success' | 'cancel' | null,
      currentObjective: null as GameObjective | null,
      objectiveProgress: 0,
      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 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
  }),
295 
  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
      },
307 
      /**
       * 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'
          )
      },
318 
      /** Total progress, net of setbacks, the player has clawed back. */
      gameSummary(): GameSummary {
          return generateGameSummary(this)
      },
323 
      /**
       * Whether the chosen `when` falls within the active figure's lifetime.
       * 'unknown' (permissive) whenever we lack solid dates — we never block a
       * figure we couldn't ground, only one we know you can't reach yet/anymore.
       */
      contactLiveness(): ContactLiveness {
          const g = this.figureGrounding
          if (!g || !g.resolved || !g.born || this.contactWhen == null) return 'unknown'
          if (this.contactWhen < g.born.signed) return 'before-birth'
          const latest = g.died ? g.died.signed : new Date().getFullYear()
          if (this.contactWhen > latest) return 'after-death'
          return 'ok'
      },
337 
      /** Can the chosen contact + when actually be reached? */
      canContact(): boolean {
          return this.contactLiveness === 'ok' || this.contactLiveness === 'unknown'
      },
342 
      /**
       * 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
      },
354 
      /**
       * 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 (unresolved / free-form contact). 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
      },
370 
      /**
       * 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)
      }
  },
386 
  actions: {
      // ---------- message helpers ----------
      addUserMessage(text: string, figureName?: string) {
          if (this.gameStatus !== 'playing') return
          this.messageHistory.push({
              text,
              sender: 'user',
              timestamp: new Date(),
              figureName
          })
      },
398 
      addAIMessage(text: string, figureName?: string) {
          this.messageHistory.push({
              text,
              sender: 'ai',
              timestamp: new Date(),
              figureName
          })
      },
407 
      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,
              characterAction: messageData.characterAction,
              timelineImpact: messageData.timelineImpact,
              progressChange: messageData.progressChange,
              baseProgressChange: messageData.baseProgressChange,
              anachronism: messageData.anachronism,
              causalChain: messageData.causalChain,
              staked: messageData.staked
          })
      },
429 
      // ---------- 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 })
          }
      },
440 
      setActiveFigure(name: string) {
          this.activeFigureName = name
      },
444 
      /**
       * Synchronously clears the dossier the moment the contact NAME changes, so
       * a send racing the grounding debounce/fetch goes out clean (free-form)
       * 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
      },
462 
      /**
       * 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, leaving the contact free-form.
       */
      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
          }
      },
510 
      /** 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
      },
539 
      /** 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() }
      },
545 
      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
      },
551 
      setContactMoment(moment: ContactMoment | null) {
          this.contactMoment = moment
      },
555 
      /**
       * 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
572 
          // 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
          }
      },
609 
      /**
       * 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
          }
      },
643 
      /**
       * 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
657 
          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
          }
      },
690 
      // ---------- 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()
          })
      },
714 
      // ---------- the living chronicle (Layer 3) ----------
      /**
       * Re-narrates the Chronicle from the freshly-bent timeline. Fired
       * non-blocking after a resolved turn (and at game end): the dice/progress
       * reveal never waits on prose. True to the game's name, the WHOLE account is
       * rewritten each turn — a later change can re-frame how earlier events read.
       * Graceful: a failed refresh keeps the prior telling, so the panel never
       * blanks; an empty timeline clears it (nothing to chronicle yet).
       */
      async refreshChronicle(): Promise<void> {
          if (!this.timelineEvents.length) {
              this.chronicle = null
              return
          }
          // Sequencing: rewrites overlap (each turn fires one, never awaited), so
          // only the LATEST issued refresh may land — an earlier telling arriving
          // late must not regress the account (or worse, the epilogue). The epoch
          // guard keeps a dead run's telling out of a fresh run entirely.
          const epoch = this.runEpoch
          const seq = ++this.chronicleSeq
          this.chronicleLoading = true
          try {
              const res = await $fetch('/api/chronicle', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: {
                      objective: this.currentObjective,
                      status: this.gameStatus,
                      progress: this.objectiveProgress,
                      timeline: this.timelineEvents.map(e => ({
                          era: e.era,
                          figureName: e.figureName,
                          headline: e.headline,
                          detail: e.detail,
                          progressChange: e.progressChange
                      }))
                  }
              }) as { success?: boolean; chronicle?: ChronicleEntry }
              if (epoch !== this.runEpoch || seq !== this.chronicleSeq) return
              if (res?.success && res.chronicle) this.chronicle = res.chronicle
          } catch (error) {
              if (epoch !== this.runEpoch || seq !== this.chronicleSeq) return
              console.error('Failed to refresh the chronicle:', error)
              // Keep the prior chronicle — a failed refresh never blanks the panel.
          } finally {
              if (epoch === this.runEpoch && seq === this.chronicleSeq) this.chronicleLoading = false
          }
      },
763 
      // ---------- simple setters ----------
      setLoading(loading: boolean) { this.isLoading = loading },
      setError(error: string | null) { this.error = error },
      clearModerationNotice() { this.moderationNotice = null },
      clearArchiveNotice() { this.archiveNotice = null },
769 
      // ---------- rate limiting ----------
      checkRateLimit(): boolean {
          const now = Date.now()
          if (this.lastMessageTime && (now - this.lastMessageTime) < RATE_LIMIT_MS) return false
          return true
      },
776 
      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)
      },
784 
      // ---------- counter & status ----------
      decrementMessages() {
          if (this.remainingMessages > 0) this.remainingMessages--
      },
789 
      /**
       * 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
              }
          }
      },
806 
      applyProgress(progressChange: number) {
          this.objectiveProgress = Math.max(0, Math.min(MAX_PROGRESS, this.objectiveProgress + progressChange))
      },
810 
      /**
       * 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'
          }
      },
826 
      // ---------- 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
844 
          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 === 'before-birth'
                      ? `${who} isn't born yet in that year — choose a later moment to reach them.`
                      : `${who} has died by that year — choose an earlier moment to reach them.`
              )
              return false
          }
864 
          this.setError(null)
          this.moderationNotice = null
          this.setActiveFigure(target)
          this.addUserMessage(text, target)
          this.decrementMessages()
          this.setLoading(true)
          this.lastMessageTime = Date.now()
872 
          // 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()
885 
          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,
                      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)
                  }
              })
918 
              if (epoch !== this.runEpoch) return false
920 
              if (response?.success && response.data?.characterResponse) {
                  const { figure, characterResponse, diceRoll, diceOutcome, timeline } = response.data
923 
                  if (figure?.name) {
                      this.registerFigure({
                          name: figure.name,
                          era: figure.era || '',
                          descriptor: figure.descriptor || ''
                      })
                  }
931 
                  // ---- 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
                  }
939 
                  // 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,
                      characterAction: characterResponse.action,
                      timelineImpact: timeline?.detail,
                      progressChange: timeline?.progressChange,
                      baseProgressChange: timeline?.baseProgressChange,
                      anachronism: timeline?.anachronism,
                      causalChain: timeline?.causalChain,
                      staked: response.data.staked
                  })
                  if (animate) this.setLoading(false)
964 
                  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)
                      }
977 
                      // 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()
              }
          }
1028 
          // 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).
          if (resolved && this.timelineEvents.length > ledgerBefore) {
              void this.refreshChronicle()
          }
          return resolved
      },
1038 
      /**
       * 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.error = null
          return true
      },
1090 
      /**
       * 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). Returns null rather than throwing if composing
       * fails, so the UI can quietly fall back to the curated pool.
       */
      async fetchAIObjective(): Promise<GameObjective | null> {
          try {
              const res = await $fetch('/api/objective', { method: 'GET', 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
          }
      },
1110 
      /**
       * 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)
          }
      },
1128 
      /** Opens the run-packs sales modal, loading the catalog first. */
      async openBuyModal(): Promise<void> {
          this.buyModalOpen = true
          await this.loadPacks()
      },
1134 
      /** Closes the sales modal. */
      closeBuyModal(): void {
          this.buyModalOpen = false
      },
1139 
      /** 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()
          }
      },
1150 
      /** Dismisses the post-purchase notice. */
      clearPurchaseNotice(): void {
          this.purchaseNotice = null
      },
1155 
      /** 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)
          }
      },
1169 
      /** 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
          }
      },
1185 
      getVictoryEfficiency() {
          if (this.gameStatus === 'victory') {
              const messagesSaved = this.remainingMessages
              const messagesUsed = TOTAL_MESSAGES - this.remainingMessages
              const efficiencyPercentage = Math.round((messagesSaved / TOTAL_MESSAGES) * 100)
1191 
              const efficiencyRating = rateEfficiency(messagesSaved)
1193 
              return {
                  messagesSaved,
                  messagesUsed,
                  efficiencyPercentage,
                  efficiencyRating,
                  isEarlyVictory: messagesSaved > 0
              }
          }
          return null
      },
1204 
      resetGame() {
          // Tear the epoch first: anything still in flight belongs to the old run
          // and must find no purchase here. (The seq counters deliberately survive.)
          this.runEpoch++
          this.remainingMessages = TOTAL_MESSAGES
          this.messageHistory = []
          this.gameStatus = 'playing'
          this.isLoading = false
          this.error = null
          this.lastMessageTime = null
          this.isRateLimited = false
          // A new run gets a fresh id on its next server call; abandon any
          // in-flight mint so a dead run's id can't land in the new run.
          this.runId = null
          this.runIdInflight = null
          // The paywall / capacity notices re-check on the next commit.
          this.outOfRuns = false
          this.atCapacity = false
          this.currentObjective = null
          this.objectiveProgress = 0
          this.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.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
      }
  }
1249})

The conducted sequence

Inside sendMessage, after the response: a beat of suspense (the die keeps casting), then the reply lands and loading is flipped here (mid-sequence) so the die lands as its own beat; then the swing, timed to coincide with the reply's own staged "ripple" line; then the ledger node. Each await is epoch-guarded, so a reset mid-reveal returns without writing into the new run.

suspense → die+reply → swing → node, each gated by animate and the epoch.

stores/game.ts · 1249 lines

stores/game.ts1249 lines · TypeScript

⋯ 931 lines hidden (lines 1–931)1import { defineStore } from 'pinia'
2import type { GameObjective } 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 { DiceOutcome } from '~/utils/dice'
13import { generateGameSummary, rateEfficiency, type GameSummary } from '~/utils/game-summary'
14import { TOTAL_MESSAGES, MAX_PROGRESS_SWING } from '~/utils/game-config'
15 
16export type Valence = 'positive' | 'negative' | 'neutral'
17 
18/**
* 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.
*/
23export interface HistoricalFigure {
  name: string
  era: string
  descriptor: string
27}
28 
29/**
* 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.
*/
36export 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
60}
61 
62/**
* 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.
*/
67export 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
  characterAction?: string
  timelineImpact?: string
  progressChange?: number
  /** The pre-amplifier swing + the wager level, for the reveal's equation. */
  baseProgressChange?: 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
91}
92 
93export type GameStatus = 'playing' | 'victory' | 'defeat'
94 
95/**
* 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.
*/
102type 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
          staked?: boolean
          characterResponse: { message: string; action: string }
          timeline: {
              headline: string
              detail: string
              era: string
              progressChange: number
              baseProgressChange?: 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
      }
  }
147 
148const RATE_LIMIT_MS = 1000 // message cooldown window, in ms
149const MAX_PROGRESS = 100 // objective progress is clamped to 0..MAX_PROGRESS
150 
151// Turn-reveal pacing. A resolved turn releases its beats one at a time — a beat of
152// suspense, then the die lands and the figure's reply writes itself in, then the
153// timeline shift, then the ledger node — so the resolution reads as one conducted
154// moment instead of everything firing in the same tick. Each component already
155// animates when its own slice of state changes; sequencing the WRITES sequences the
156// animations, with no component coordination. Tuned so the swing lands with the
157// reply's own "ripple" line (~0.55s into its staged reveal).
158export const REVEAL = { suspense: 450, swing: 550, node: 250 } as const
159const wait = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms))
160/** 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. */
163function canAnimateReveal(): boolean {
  return typeof window !== 'undefined'
      && typeof window.matchMedia === 'function'
      && !window.matchMedia('(prefers-reduced-motion: reduce)').matches
167}
168 
169function valenceOf(progressChange: number): Valence {
  if (progressChange > 0) return 'positive'
  if (progressChange < 0) return 'negative'
  return 'neutral'
173}
174 
175/** Formats a signed timeline year (AD positive, BCE negative) for display. */
176export function formatContactYear(signed: number): string {
  return signed < 0 ? `${-signed} BC` : `${signed}`
178}
179 
180/** Human lifespan line for a grounded figure, e.g. "69 BC – 30 BC" or "1942 – present". */
181function 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
185}
186 
187/** 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. */
189function 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
192}
193 
194/** True when a $fetch error is a 503 / at-capacity — the spend cap paused new
*  runs (distinct from the per-device 402 paywall). */
196function 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
199}
200 
201export type ContactLiveness = 'ok' | 'before-birth' | 'after-death' | 'unknown'
202 
203/**
* Game Store — core state for a session of freeform timeline editing.
*/
206export const useGameStore = defineStore('game', {
  state: () => ({
      remainingMessages: TOTAL_MESSAGES,
      messageHistory: [] as Message[],
      gameStatus: 'playing' as GameStatus,
      isLoading: false,
      error: null as string | null,
      lastMessageTime: null as number | null,
      isRateLimited: false,
      // Staleness plumbing, not run state. runEpoch increments on every reset so an
      // async result from a dead run can never write into a fresh one; the seq
      // counters order overlapping requests of the same kind so only the latest
      // lands (an earlier chronicle rewrite must not overwrite a later one).
      // Deliberately NOT restored by resetGame — they must survive it to work.
      runEpoch: 0,
      chronicleSeq: 0,
      groundingSeq: 0,
      // The current run's id — lazily minted on the run's first server call and
      // cleared by resetGame so each run gets a fresh one. Tags every AI call
      // (via the x-run-id header) so the gateway's cost telemetry groups per
      // run: the GTM cost instrument.
      runId: null as string | null,
      // The in-flight begin-run, so concurrent first-calls of a run share one
      // mint (one POST /api/run, one runs row) instead of racing two. Cleared
      // by resetGame. (Vue leaves a Promise unproxied, so awaiting it is safe.)
      runIdInflight: null as Promise<string> | null,
      // outOfRuns gates the mission screen's paywall (set when a commit is
      // refused with 402). The run packs offered there are loaded into `packs`.
      outOfRuns: false,
      // atCapacity gates the "at capacity" notice (set when a commit is refused
      // with 503 because the global spend cap paused new runs).
      atCapacity: false,
      packs: [] as Pack[],
      // The device's run balance, for the header gauge + account popover. null
      // until first loaded (GET /api/balance); the run-commit response also
      // refreshes it so the gauge stays live without a second round-trip.
      runsRemaining: null as number | null,
      freeRuns: 1,
      deviceRef: '' as string,
      // Account state (from /api/balance): the signed-in email, and whether the
      // current user is anonymous (→ must sign in before buying). Drives the
      // account UI + the sign-in-to-buy gate. false/null in device-fallback mode.
      accountEmail: null as string | null,
      accountAnonymous: false,
      // The run-packs sales modal — opened on demand (header) or automatically
      // when a commit is refused for being out of runs.
      buyModalOpen: false,
      // A one-shot notice after returning from Stripe Checkout ('success' shows a
      // credited confirmation; 'cancel' a gentle "no charge" note). Cleared by the UI.
      purchaseNotice: null as 'success' | 'cancel' | null,
      currentObjective: null as GameObjective | null,
      objectiveProgress: 0,
      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 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
  }),
295 
  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
      },
307 
      /**
       * 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'
          )
      },
318 
      /** Total progress, net of setbacks, the player has clawed back. */
      gameSummary(): GameSummary {
          return generateGameSummary(this)
      },
323 
      /**
       * Whether the chosen `when` falls within the active figure's lifetime.
       * 'unknown' (permissive) whenever we lack solid dates — we never block a
       * figure we couldn't ground, only one we know you can't reach yet/anymore.
       */
      contactLiveness(): ContactLiveness {
          const g = this.figureGrounding
          if (!g || !g.resolved || !g.born || this.contactWhen == null) return 'unknown'
          if (this.contactWhen < g.born.signed) return 'before-birth'
          const latest = g.died ? g.died.signed : new Date().getFullYear()
          if (this.contactWhen > latest) return 'after-death'
          return 'ok'
      },
337 
      /** Can the chosen contact + when actually be reached? */
      canContact(): boolean {
          return this.contactLiveness === 'ok' || this.contactLiveness === 'unknown'
      },
342 
      /**
       * 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
      },
354 
      /**
       * 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 (unresolved / free-form contact). 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
      },
370 
      /**
       * 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)
      }
  },
386 
  actions: {
      // ---------- message helpers ----------
      addUserMessage(text: string, figureName?: string) {
          if (this.gameStatus !== 'playing') return
          this.messageHistory.push({
              text,
              sender: 'user',
              timestamp: new Date(),
              figureName
          })
      },
398 
      addAIMessage(text: string, figureName?: string) {
          this.messageHistory.push({
              text,
              sender: 'ai',
              timestamp: new Date(),
              figureName
          })
      },
407 
      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,
              characterAction: messageData.characterAction,
              timelineImpact: messageData.timelineImpact,
              progressChange: messageData.progressChange,
              baseProgressChange: messageData.baseProgressChange,
              anachronism: messageData.anachronism,
              causalChain: messageData.causalChain,
              staked: messageData.staked
          })
      },
429 
      // ---------- 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 })
          }
      },
440 
      setActiveFigure(name: string) {
          this.activeFigureName = name
      },
444 
      /**
       * Synchronously clears the dossier the moment the contact NAME changes, so
       * a send racing the grounding debounce/fetch goes out clean (free-form)
       * 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
      },
462 
      /**
       * 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, leaving the contact free-form.
       */
      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
          }
      },
510 
      /** 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
      },
539 
      /** 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() }
      },
545 
      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
      },
551 
      setContactMoment(moment: ContactMoment | null) {
          this.contactMoment = moment
      },
555 
      /**
       * 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
572 
          // 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
          }
      },
609 
      /**
       * 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
          }
      },
643 
      /**
       * 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
657 
          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
          }
      },
690 
      // ---------- 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()
          })
      },
714 
      // ---------- the living chronicle (Layer 3) ----------
      /**
       * Re-narrates the Chronicle from the freshly-bent timeline. Fired
       * non-blocking after a resolved turn (and at game end): the dice/progress
       * reveal never waits on prose. True to the game's name, the WHOLE account is
       * rewritten each turn — a later change can re-frame how earlier events read.
       * Graceful: a failed refresh keeps the prior telling, so the panel never
       * blanks; an empty timeline clears it (nothing to chronicle yet).
       */
      async refreshChronicle(): Promise<void> {
          if (!this.timelineEvents.length) {
              this.chronicle = null
              return
          }
          // Sequencing: rewrites overlap (each turn fires one, never awaited), so
          // only the LATEST issued refresh may land — an earlier telling arriving
          // late must not regress the account (or worse, the epilogue). The epoch
          // guard keeps a dead run's telling out of a fresh run entirely.
          const epoch = this.runEpoch
          const seq = ++this.chronicleSeq
          this.chronicleLoading = true
          try {
              const res = await $fetch('/api/chronicle', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: {
                      objective: this.currentObjective,
                      status: this.gameStatus,
                      progress: this.objectiveProgress,
                      timeline: this.timelineEvents.map(e => ({
                          era: e.era,
                          figureName: e.figureName,
                          headline: e.headline,
                          detail: e.detail,
                          progressChange: e.progressChange
                      }))
                  }
              }) as { success?: boolean; chronicle?: ChronicleEntry }
              if (epoch !== this.runEpoch || seq !== this.chronicleSeq) return
              if (res?.success && res.chronicle) this.chronicle = res.chronicle
          } catch (error) {
              if (epoch !== this.runEpoch || seq !== this.chronicleSeq) return
              console.error('Failed to refresh the chronicle:', error)
              // Keep the prior chronicle — a failed refresh never blanks the panel.
          } finally {
              if (epoch === this.runEpoch && seq === this.chronicleSeq) this.chronicleLoading = false
          }
      },
763 
      // ---------- simple setters ----------
      setLoading(loading: boolean) { this.isLoading = loading },
      setError(error: string | null) { this.error = error },
      clearModerationNotice() { this.moderationNotice = null },
      clearArchiveNotice() { this.archiveNotice = null },
769 
      // ---------- rate limiting ----------
      checkRateLimit(): boolean {
          const now = Date.now()
          if (this.lastMessageTime && (now - this.lastMessageTime) < RATE_LIMIT_MS) return false
          return true
      },
776 
      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)
      },
784 
      // ---------- counter & status ----------
      decrementMessages() {
          if (this.remainingMessages > 0) this.remainingMessages--
      },
789 
      /**
       * 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
              }
          }
      },
806 
      applyProgress(progressChange: number) {
          this.objectiveProgress = Math.max(0, Math.min(MAX_PROGRESS, this.objectiveProgress + progressChange))
      },
810 
      /**
       * 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'
          }
      },
826 
      // ---------- 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
844 
          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 === 'before-birth'
                      ? `${who} isn't born yet in that year — choose a later moment to reach them.`
                      : `${who} has died by that year — choose an earlier moment to reach them.`
              )
              return false
          }
864 
          this.setError(null)
          this.moderationNotice = null
          this.setActiveFigure(target)
          this.addUserMessage(text, target)
          this.decrementMessages()
          this.setLoading(true)
          this.lastMessageTime = Date.now()
872 
          // 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()
885 
          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,
                      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)
                  }
              })
918 
              if (epoch !== this.runEpoch) return false
920 
              if (response?.success && response.data?.characterResponse) {
                  const { figure, characterResponse, diceRoll, diceOutcome, timeline } = response.data
923 
                  if (figure?.name) {
                      this.registerFigure({
                          name: figure.name,
                          era: figure.era || '',
                          descriptor: figure.descriptor || ''
                      })
                  }
931 
                  // ---- 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
                  }
939 
                  // 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,
                      characterAction: characterResponse.action,
                      timelineImpact: timeline?.detail,
                      progressChange: timeline?.progressChange,
                      baseProgressChange: timeline?.baseProgressChange,
                      anachronism: timeline?.anachronism,
                      causalChain: timeline?.causalChain,
                      staked: response.data.staked
                  })
                  if (animate) this.setLoading(false)
964 
                  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)
                      }
977 
                      // 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,
⋯ 259 lines hidden (lines 991–1249)991                            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()
              }
          }
1028 
          // 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).
          if (resolved && this.timelineEvents.length > ledgerBefore) {
              void this.refreshChronicle()
          }
          return resolved
      },
1038 
      /**
       * 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.error = null
          return true
      },
1090 
      /**
       * 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). Returns null rather than throwing if composing
       * fails, so the UI can quietly fall back to the curated pool.
       */
      async fetchAIObjective(): Promise<GameObjective | null> {
          try {
              const res = await $fetch('/api/objective', { method: 'GET', 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
          }
      },
1110 
      /**
       * 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)
          }
      },
1128 
      /** Opens the run-packs sales modal, loading the catalog first. */
      async openBuyModal(): Promise<void> {
          this.buyModalOpen = true
          await this.loadPacks()
      },
1134 
      /** Closes the sales modal. */
      closeBuyModal(): void {
          this.buyModalOpen = false
      },
1139 
      /** 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()
          }
      },
1150 
      /** Dismisses the post-purchase notice. */
      clearPurchaseNotice(): void {
          this.purchaseNotice = null
      },
1155 
      /** 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)
          }
      },
1169 
      /** 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
          }
      },
1185 
      getVictoryEfficiency() {
          if (this.gameStatus === 'victory') {
              const messagesSaved = this.remainingMessages
              const messagesUsed = TOTAL_MESSAGES - this.remainingMessages
              const efficiencyPercentage = Math.round((messagesSaved / TOTAL_MESSAGES) * 100)
1191 
              const efficiencyRating = rateEfficiency(messagesSaved)
1193 
              return {
                  messagesSaved,
                  messagesUsed,
                  efficiencyPercentage,
                  efficiencyRating,
                  isEarlyVictory: messagesSaved > 0
              }
          }
          return null
      },
1204 
      resetGame() {
          // Tear the epoch first: anything still in flight belongs to the old run
          // and must find no purchase here. (The seq counters deliberately survive.)
          this.runEpoch++
          this.remainingMessages = TOTAL_MESSAGES
          this.messageHistory = []
          this.gameStatus = 'playing'
          this.isLoading = false
          this.error = null
          this.lastMessageTime = null
          this.isRateLimited = false
          // A new run gets a fresh id on its next server call; abandon any
          // in-flight mint so a dead run's id can't land in the new run.
          this.runId = null
          this.runIdInflight = null
          // The paywall / capacity notices re-check on the next commit.
          this.outOfRuns = false
          this.atCapacity = false
          this.currentObjective = null
          this.objectiveProgress = 0
          this.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.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
      }
  }
1249})

Tests

The cadence is asserted deterministically with fake timers + a stubbed matchMedia: step the clock and check each beat lands in order (suspense → reply → swing → node), and that a reset mid-reveal aborts without leaking state into the new run. The instant path stays covered by every existing sendMessage test.

Advance timers beat-by-beat; assert the ordering and the mid-reveal abort.

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

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

⋯ 131 lines hidden (lines 1–131)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, any> = {}) {
  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'
  })
39 
  afterEach(() => {
      vi.unstubAllGlobals()
      vi.restoreAllMocks()
  })
44 
  describe('initial state', () => {
      it('starts a fresh run', () => {
          expect(store.remainingMessages).toBe(5)
          expect(store.gameStatus).toBe('playing')
          expect(store.objectiveProgress).toBe(0)
          expect(store.messageHistory).toEqual([])
          expect(store.timelineEvents).toEqual([])
          expect(store.figures).toEqual([])
          expect(store.canSendMessage).toBe(true)
      })
  })
56 
  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)
      })
64 
      it('decrementMessages does not, by itself, end the game', () => {
          store.decrementMessages()
          expect(store.remainingMessages).toBe(4)
          expect(store.gameStatus).toBe('playing')
      })
70 
      it('resolves victory the moment progress hits 100', () => {
          store.objectiveProgress = 100
          store.resolveGameStatus()
          expect(store.gameStatus).toBe('victory')
      })
76 
      it('resolves defeat only once messages run out unmet', () => {
          store.remainingMessages = 0
          store.objectiveProgress = 50
          store.resolveGameStatus()
          expect(store.gameStatus).toBe('defeat')
      })
83 
      it('prefers victory over defeat on the final message', () => {
          store.remainingMessages = 0
          store.objectiveProgress = 100
          store.resolveGameStatus()
          expect(store.gameStatus).toBe('victory')
      })
90 
      it('stays playing while messages remain and the objective is unmet', () => {
          store.remainingMessages = 3
          store.objectiveProgress = 50
          store.resolveGameStatus()
          expect(store.gameStatus).toBe('playing')
      })
  })
98 
  describe('figures', () => {
      it('registers a new figure and refines it on later contact', () => {
          store.registerFigure({ name: 'Cleopatra', era: '', descriptor: '' })
          expect(store.figures).toHaveLength(1)
103 
          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')
      })
  })
110 
  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 })
116 
          expect(store.timelineEvents.map(e => e.valence)).toEqual(['negative', 'positive', 'neutral'])
      })
  })
120 
  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')
126 
          expect(store.conversationWith('Tesla')).toHaveLength(2)
          expect(store.conversationWith('Cleopatra')).toHaveLength(1)
      })
  })
131 
  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())
142 
      it('staggers the beats: suspense → reply → swing → node', async () => {
          fetchMock.mockResolvedValue(okResponse())
          const p = store.sendMessage('Light the world', 'Nikola Tesla')
146 
          // 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)
151 
          // 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)
159 
          // 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)
164 
          // 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)
      })
170 
      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)
      })
  })
183 
  describe('sendMessage', () => {
⋯ 1152 lines hidden (lines 185–1336)185        it('folds a successful turn into messages, ledger, progress, and figures', async () => {
          fetchMock.mockResolvedValue(okResponse())
187 
          await store.sendMessage('Light the world wirelessly', 'Nikola Tesla')
189 
          // 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')
194 
          // 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')
203 
          // 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' })
210 
          expect(store.remainingMessages).toBe(4)
          expect(store.isLoading).toBe(false)
      })
214 
      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' }
          }))
219 
          await store.sendMessage('Hmm', 'Tesla')
221 
          expect(store.timelineEvents).toHaveLength(1)
          expect(store.timelineEvents[0].valence).toBe('neutral')
          expect(store.objectiveProgress).toBe(0)
      })
226 
      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)
      })
234 
      it('refunds the message and drops the dangling prompt on a network error', async () => {
          fetchMock.mockRejectedValue(new Error('network down'))
237 
          await store.sendMessage('A message that fails', 'Tesla')
239 
          expect(store.error).toBeTruthy()
          expect(store.remainingMessages).toBe(5)
          expect(store.messageHistory).toHaveLength(0)
          expect(store.gameStatus).toBe('playing')
      })
245 
      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' }
          })
252 
          const resolved = await store.sendMessage('A doomed dispatch', 'Tesla')
254 
          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)
      })
261 
      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.'
              }
          })
273 
          const resolved = await store.sendMessage('Synthesize a nerve agent at scale', 'Fritz Haber')
275 
          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)
      })
283 
      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' }
          })
292 
          await store.sendMessage('The last word', 'Tesla')
294 
          // 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')
      })
299 
      it('reports resolution truthfully: true when a turn lands, false when refunded', async () => {
          fetchMock.mockResolvedValueOnce(okResponse())
          expect(await store.sendMessage('First', 'Tesla')).toBe(true)
303 
          store.lastMessageTime = null // clear the rate-limit window
          fetchMock.mockRejectedValueOnce(new Error('down'))
          expect(await store.sendMessage('Second', 'Tesla')).toBe(false)
      })
308 
      it('arms the stake only on the final message — never earlier', async () => {
          fetchMock.mockResolvedValue(okResponse())
311 
          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
315 
          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)
      })
322 
      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())
327 
          await store.sendMessage('One clean throw', 'Tesla', { stake: true })
329 
          const body = fetchMock.mock.calls[0][1].body
          expect(body.stake).toBe(false)
      })
333 
      it('records the staked badge and the turn’s grounded year on ledger AND thread', async () => {
          store.contactWhen = -48
          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' }
          }))
343 
          await store.sendMessage('Stake it all', 'Tesla')
345 
          const evt = store.timelineEvents[0]
          expect(evt.staked).toBe(true)
          expect(evt.craft).toBe('sharp')
          expect(evt.whenSigned).toBe(-48)
          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)
      })
358 
      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' }
          }))
365 
          await store.sendMessage('The decisive word', 'Tesla')
367 
          expect(store.objectiveProgress).toBe(100)
          expect(store.remainingMessages).toBe(0)
          expect(store.gameStatus).toBe('victory')
      })
372 
      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' }
          }))
379 
          await store.sendMessage('A last try', 'Tesla')
381 
          expect(store.objectiveProgress).toBe(15)
          expect(store.remainingMessages).toBe(0)
          expect(store.gameStatus).toBe('defeat')
      })
  })
387 
  describe('living chronicle (refreshChronicle)', () => {
      const telling = { title: 'The Peace That Held', paragraphs: ['In 1878, Bismarck chose trade.', 'By 1914, no war came.'] }
390 
      function seedOneChange() {
          store.addTimelineEvent({
              figureName: 'Bismarck', era: '1878', headline: 'Bismarck chooses trade',
              detail: 'Alliances soften into commerce.', diceRoll: 16, diceOutcome: DiceOutcome.SUCCESS, progressChange: 20
          })
      }
397 
      it('re-narrates the timeline and stores the telling', async () => {
          seedOneChange()
          fetchMock.mockResolvedValue({ success: true, chronicle: telling })
401 
          await store.refreshChronicle()
403 
          expect(fetchMock).toHaveBeenCalledWith('/api/chronicle', expect.objectContaining({ method: 'POST' }))
          expect(store.chronicle).toEqual(telling)
          expect(store.chronicleLoading).toBe(false)
      })
408 
      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()
      })
415 
      it('keeps the prior telling when a refresh fails (never blanks)', async () => {
          seedOneChange()
          store.chronicle = telling
          fetchMock.mockRejectedValue(new Error('chronicler offline'))
420 
          await store.refreshChronicle()
422 
          expect(store.chronicle).toEqual(telling)
          expect(store.chronicleLoading).toBe(false)
      })
426 
      it('fires a non-blocking refresh after a turn actually changes the world', async () => {
          fetchMock.mockResolvedValue(okResponse())
429 
          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()
434 
          // The refresh is fired (not awaited) once the turn added a ledger entry.
          expect(fetchMock).toHaveBeenCalledWith('/api/chronicle', expect.objectContaining({ method: 'POST' }))
      })
438 
      it('does NOT refresh when a turn fails to change the world', async () => {
          fetchMock.mockRejectedValue(new Error('network down'))
441 
          await store.sendMessage('A message that fails', 'Tesla')
443 
          expect(fetchMock).not.toHaveBeenCalledWith('/api/chronicle', expect.anything())
      })
  })
447 
  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 }
      }
455 
      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)
459 
          const inFlight = store.sendMessage('From the old world', 'Tesla')
          store.resetGame()
          slow.resolve(okResponse())
          const resolved = await inFlight
464 
          // 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)
      })
472 
      it('a reset mid-send must not "refund" the new run on failure either', async () => {
          const slow = deferred<never>()
          fetchMock.mockReturnValue(slow.promise)
476 
          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
482 
          expect(store.remainingMessages).toBe(3) // untouched by the stale refund
      })
485 
      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 })
488 
          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)
492 
          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
500 
          expect(store.chronicle?.title).toBe('The Later Telling')
          expect(store.chronicleLoading).toBe(false)
      })
504 
      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)
509 
          const inFlight = store.refreshChronicle()
          store.resetGame()
          slow.resolve({ success: true, chronicle: { title: 'A Ghost Epilogue', paragraphs: ['boo'] } })
          await inFlight
514 
          expect(store.chronicle).toBeNull()
      })
517 
      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)
522 
          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
529 
          expect(store.figureGrounding?.name).toBe('Otto von Bismarck')
          expect(store.groundingLoading).toBe(false)
      })
533 
      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)
537 
          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
542 
          expect(store.figureGrounding).toBeNull()
          expect(store.contactWhen).toBeNull()
          expect(store.groundingLoading).toBe(false)
      })
547 
      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)
557 
          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
562 
          // The brief is FOR -40; recording -35 would mislabel it and hide Re-study.
          expect(store.studyWhen).toBe(-40)
          expect(store.studyFor).toBe('Cleopatra')
      })
  })
568 
  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)
      })
578 
      it('returns null when not a victory', () => {
          store.gameStatus = 'playing'
          expect(store.getVictoryEfficiency()).toBeNull()
      })
  })
584 
  describe('resetGame', () => {
      it('returns everything to a fresh run', () => {
          store.remainingMessages = 1
          store.objectiveProgress = 80
          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: '' }
599 
          store.resetGame()
601 
          expect(store.remainingMessages).toBe(5)
          expect(store.objectiveProgress).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()
      })
  })
616 
  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: '📜'
      }
624 
      it('chooseObjective commits the objective and resets progress', async () => {
          fetchMock.mockResolvedValue({ runsRemaining: 5 })
          store.objectiveProgress = 40
          store.setError('a stale error')
629 
          const started = await store.chooseObjective(objective)
631 
          expect(started).toBe(true)
          expect(store.currentObjective).toEqual(objective)
          expect(store.objectiveProgress).toBe(0)
          expect(store.error).toBeNull()
      })
637 
      it('fetchAIObjective returns a composed objective WITHOUT committing it', async () => {
          fetchMock.mockResolvedValue({ success: true, objective })
640 
          const result = await store.fetchAIObjective()
642 
          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()
      })
651 
      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()
      })
657 
      it('fetchAIObjective returns null when the server reports failure', async () => {
          fetchMock.mockResolvedValue({ success: false })
          expect(await store.fetchAIObjective()).toBeNull()
      })
  })
663 
  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
      }
673 
      it('grounds the active figure and defaults the when inside their lifetime', async () => {
          fetchMock.mockResolvedValue(cleopatra)
676 
          await store.groundActiveFigure('Cleopatra')
678 
          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)
      })
689 
      it('flags a when before birth or after death', async () => {
          fetchMock.mockResolvedValue(cleopatra)
          await store.groundActiveFigure('Cleopatra')
693 
          store.setContactWhen(-200) // 200 BC — long before she was born
          expect(store.contactLiveness).toBe('before-birth')
          expect(store.canContact).toBe(false)
697 
          store.setContactWhen(1990) // long after she died
          expect(store.contactLiveness).toBe('after-death')
          expect(store.canContact).toBe(false)
701 
          store.setContactWhen(-50) // 50 BC — within her life
          expect(store.contactLiveness).toBe('ok')
      })
705 
      it('stays permissive when a figure cannot be grounded', async () => {
          fetchMock.mockResolvedValue({ name: 'Nobody', resolved: false })
          await store.groundActiveFigure('Nobody Atall')
709 
          expect(store.figureGrounding?.resolved).toBe(false)
          expect(store.contactWhen).toBeNull()
          expect(store.contactLiveness).toBe('unknown')
          expect(store.canContact).toBe(true)
      })
715 
      it('treats a living figure as reachable up to the present', async () => {
          fetchMock.mockResolvedValue({
              name: 'Paul McCartney', resolved: true,
              born: { year: 1942, bce: false, signed: 1942, display: '1942' },
              living: true
          })
          await store.groundActiveFigure('Paul McCartney')
723 
          store.setContactWhen(1965)
          expect(store.contactLiveness).toBe('ok')
          store.setContactWhen(1900) // before birth
          expect(store.contactLiveness).toBe('before-birth')
      })
729 
      it('pins, rescrubs, and clears the contact moment (issue #32)', async () => {
          fetchMock.mockResolvedValue(cleopatra)
          await store.groundActiveFigure('Cleopatra')
733 
          store.setContactMoment({ month: 6, day: 28 })
          expect(store.contactMoment).toEqual({ month: 6, day: 28 })
736 
          // Scrubbing the year keeps the pin — it refines whichever year is chosen.
          store.setContactWhen(-44)
          expect(store.contactMoment).toEqual({ month: 6, day: 28 })
740 
          // A name change clears it with the rest of the dossier.
          store.clearGrounding()
          expect(store.contactMoment).toBeNull()
      })
745 
      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' } })
753 
          await store.sendMessage('Hold court away from the palace today.', 'Cleopatra')
755 
          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)
      })
762 
      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()
      })
770 
      it('refuses to send to someone outside their lifetime', async () => {
          fetchMock.mockResolvedValue(cleopatra)
          await store.groundActiveFigure('Cleopatra')
          store.setContactWhen(-300) // before birth
          fetchMock.mockClear()
776 
          await store.sendMessage('Beware the Ides', 'Cleopatra')
778 
          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)
      })
  })
785 
  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
      }
793 
      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)
      })
799 
      it('is 0 in the birth year', () => {
          store.figureGrounding = cleopatra as never
          store.setContactWhen(-69)
          expect(store.contactAge).toBe(0)
      })
805 
      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)
      })
816 
      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)
      })
825 
      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()
830 
          store.figureGrounding = null
          expect(store.contactAge).toBeNull()
      })
834 
      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()
      })
  })
841 
  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'
      }
855 
      it('studies a grounded figure and stores the brief', async () => {
          store.figureGrounding = cleopatra as never
          store.setContactWhen(-40)
          fetchMock.mockResolvedValue({ success: true, study })
860 
          await store.studyActiveFigure()
862 
          expect(fetchMock).toHaveBeenCalledWith('/api/research', expect.objectContaining({ method: 'POST' }))
          expect(store.figureStudy).toEqual(study)
          expect(store.studyFor).toBe('Cleopatra')
          expect(store.studyLoading).toBe(false)
      })
868 
      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()
875 
          await store.studyActiveFigure()
          expect(fetchMock).not.toHaveBeenCalled()
      })
879 
      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()
887 
          store.setContactWhen(-35) // move the slider
          await store.studyActiveFigure()
890 
          expect(fetchMock).toHaveBeenCalledWith('/api/research', expect.objectContaining({ method: 'POST' }))
          expect(store.studyWhen).toBe(-35)
      })
894 
      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()
      })
901 
      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)
      })
909 
      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.' })
914 
          await store.studyActiveFigure()
916 
          expect(store.studyNotice).toContain('blocked by content moderation')
          expect(store.figureStudy).toBeNull()
          expect(store.studyLoading).toBe(false)
      })
921 
      it('drops a stale study when the contact changes', async () => {
          store.figureStudy = study as never
          store.studyFor = 'Cleopatra'
          fetchMock.mockResolvedValue({ name: 'Tesla', resolved: false })
926 
          await store.groundActiveFigure('Nikola Tesla')
928 
          expect(store.figureStudy).toBeNull()
          expect(store.studyFor).toBe('')
      })
  })
933 
  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'
      }
941 
      it('looks up a topic and stores the result', async () => {
          fetchMock.mockResolvedValue({ success: true, lookup })
944 
          await store.askArchive('gunpowder')
946 
          expect(fetchMock).toHaveBeenCalledWith('/api/lookup', expect.objectContaining({ method: 'POST' }))
          expect(store.archiveResult).toEqual(lookup)
          expect(store.lookupLoading).toBe(false)
      })
951 
      it('ignores an empty query', async () => {
          await store.askArchive('   ')
          expect(fetchMock).not.toHaveBeenCalled()
      })
956 
      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)
      })
  })
964 
  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' }
          }))
970 
          await store.sendMessage('Build a flying machine and aim higher', 'Leonardo da Vinci')
972 
          expect(store.timelineEvents[0].anachronism).toBe('far-ahead')
      })
975 
      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()
      })
  })
982 
  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: '🕊️'
      }
990 
      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
          })
998 
          await store.loadSuggestions()
1000 
          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')
      })
1006 
      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()
1012 
          await store.loadSuggestions()
          expect(fetchMock).not.toHaveBeenCalled()
      })
1016 
      it('clears suggestions when there is no objective', async () => {
          store.currentObjective = null
          await store.loadSuggestions()
          expect(store.figureSuggestions).toEqual([])
          expect(fetchMock).not.toHaveBeenCalled()
      })
1023 
      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.' })
1027 
          await store.loadSuggestions()
1029 
          expect(store.suggestionsNotice).toContain('blocked by content moderation')
          expect(store.figureSuggestions).toEqual([])
      })
1033 
      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')
      })
  })
1044 
  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
      }
1050 
      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')
      })
1056 
      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
      })
1064 
      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()
      })
  })
1071 
  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()
      })
1087 
      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
      })
1095 
      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)
      })
1108 
      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' })
              })
          )
      })
1121 
      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
      })
1136 
      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
      })
1150 
      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' }) })
          )
      })
  })
1166 
  describe('run balance (the paywall gate)', () => {
      const objective = { title: 'Spare the library', description: 'The scrolls survive.', era: 'Alexandria', icon: '📜' }
1169 
      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
      })
1183 
      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
      })
1196 
      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()
      })
1206 
      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)
          }
      })
1216 
      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')
      })
1225 
      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()
      })
1235 
      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()
      })
  })
1245 
  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()
      })
1256 
      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' } })
          )
      })
1265 
      it('buyPack returns null on failure', async () => {
          fetchMock.mockRejectedValue(new Error('stripe down'))
          expect(await store.buyPack('courier')).toBeNull()
      })
1270 
      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)
      })
  })
1280 
  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)
      })
1291 
      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)
      })
1298 
      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)
      })
1305 
      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)
      })
1314 
      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
      })
1323 
      it('notePurchaseReturn(cancel) records the notice without refetching', async () => {
          await store.notePurchaseReturn('cancel')
          expect(store.purchaseNotice).toBe('cancel')
          expect(fetchMock).not.toHaveBeenCalled()
      })
1329 
      it('clearPurchaseNotice dismisses the notice', () => {
          store.purchaseNotice = 'success'
          store.clearPurchaseNotice()
          expect(store.purchaseNotice).toBeNull()
      })
  })
1336})