Persist in-progress runs — a code-level reading (PR #160)

What changed, and why

A run in progress lived entirely in the Pinia store and vanished on any refresh or crash. That hurt: every turn is a model call, so a stray reload threw away minutes of play and real spend. The only persistence was end-state — saveRunSnapshot() fired once, at victory or defeat.

This adds the missing mid-run save. The server stays stateless per turn (the client is still the system of record), so the fix is storage, not a turn-engine rewrite: after each resolved-but-still-playing turn the client autosaves a draft of the live state to a new server table; on the next page load it reads that draft back and drops the player onto the in-progress board. The draft is keyed to the same subject runs and balances already use — a real Supabase user (anonymous by default), or the device cookie — so an anonymous player's run carries over to their account for free when they sign in with a magic link.

The blast radius is contained. run_snapshots (the finished-run record behind "your runs", share, and replay) is untouched; the draft is a separate table, a separate shape, and a separate set of endpoints. The terminal save path keeps working exactly as before — the draft just rides alongside it.

The draft contract

The draft's shape lives beside RunSnapshot in the client-safe contract module (types only, no runtime imports). It serializes the durable live state and nothing transient: the running totals, the full thread (both sides — the snapshot keeps only the player's dispatches, but the AI replies cost a model call to regenerate), the un-trimmed ledger with whenSigned and causalChain (the footholds the next turn reads back), the contacted figures, the active contact, the Chronicle, and any replay lineage.

It deliberately leaves out the loading flags, the runEpoch/sequence counters (those must survive a reset, not a reload), and figureGrounding — the active figure is re-grounded from the live record on resume, so a draft never carries a stale dossier. The in-memory Date stamps become ISO strings here, since jsonb is dateless.

The design note, the independent version stamp, and the RunDraft shape.

utils/run-snapshot.ts · 312 lines

utils/run-snapshot.ts312 lines · TypeScript

⋯ 205 lines hidden (lines 1–205)1/**
* The saved-run contract — the immutable, versioned record of a finished run.
*
* A run is otherwise client-only: the objective, the dispatches, the timeline
* ledger, the Chronicle epilogue, and the verdict all live in the Pinia store and
* evaporate on reload. This is the persisted form of that end-state: the store builds
* it on game end, the server stores it keyed by the run id, and a read-only "your
* runs" view replays it. It is a SNAPSHOT, not a live record — written ONCE, at
* victory/defeat, and immutable thereafter.
*
* The MID-run counterpart is the RunDraft at the foot of this file (#152): the live
* state, overwritten every turn, so a refresh or a crash can't lose a half-played run
* (every turn is a model call — expensive to redo). Two persistence contracts, two
* lifecycles, kept in one client-safe module.
*
* Naming: "run" is overloaded. The header gauge's balance ("runs remaining") is a
* purchasable CREDIT (the `balances` table); this is a PLAYED run (the game record,
* the `run_snapshots` table). Same noun, two states — kept distinct in the schema.
*
* The shape is VERSIONED (`version`) so a later change can't silently break runs
* saved under an older shape: a reader can branch on `version` and migrate. It is a
* flat, fully JSON-native projection of the store state — the `Date` timestamps on
* the in-memory ledger/thread are dropped (a snapshot needs none of the duration
* math), so the stored blob round-trips through jsonb cleanly.
*
* This module is the SHARED contract (types + version), client-safe by design: it
* carries no runtime imports, only type-only ones, so the client store can import the
* version + types without pulling any server-only code. The server-side boundary
* validator lives separately in `server/utils/run-snapshot.ts`.
*/
31import type { DiceOutcome } from '~/utils/dice'
32import type { Craft } from '~/utils/craft'
33import type { Continuity } from '~/utils/continuity'
34import type { ChainStatus } from '~/utils/causal-chain'
35import type { ContactMoment } from '~/utils/contact-moment'
36import type { Anachronism } from '~/server/utils/anachronism'
37import type { GameObjective } from '~/server/utils/objectives'
38import type { ChronicleEntry } from '~/server/utils/openai'
39 
40/** The current saved-run shape. Bump when the shape changes incompatibly; a reader
*  branches on it to migrate older snapshots rather than mis-reading them.
*  v2 (#151): added `peakProgress` — the run's high-water mark, persisted so the
*  "Peaked at X%" stat survives onto snapshot-backed (saved/shared) views. */
44export const RUN_SNAPSHOT_VERSION = 2
45 
46/** Only a finished run is ever saved — the two terminal verdicts. */
47export type RunOutcome = 'victory' | 'defeat'
48 
49/** The valence of a ledger swing (mirrors the store's `Valence`). */
50export type RunValence = 'positive' | 'negative' | 'neutral'
51 
52/** The five efficiency tiers a victory can earn (mirrors the store's rating). */
53export type EfficiencyRating = 'Legendary' | 'Excellent' | 'Great' | 'Good' | 'Standard'
54 
55/** The bit of a roll the read-only view shows: the number and its named outcome. */
56export interface RollMark {
  diceRoll: number
  diceOutcome: DiceOutcome
59}
60 
61/** A dispatch keepsake — the player's verbatim message and whom/when it reached. */
62export interface RunDispatch {
  text: string
  figure: string
  era: string
66}
67 
68/** The victory efficiency block (null on defeat) — the same data the end screen shows. */
69export interface RunEfficiency {
  messagesSaved: number
  messagesUsed: number
  efficiencyPercentage: number
  efficiencyRating: EfficiencyRating
  isEarlyVictory: boolean
75}
76 
77/** One ledger entry, trimmed to the fields a read-only run view renders (the live
*  `TimelineEvent` minus its `Date` timestamp and the internals the view ignores). */
79export interface RunLedgerEntry {
  id: string
  figureName: string
  era: string
  headline: string
  detail: string
  diceRoll: number
  diceOutcome: DiceOutcome
  progressChange: number
  /** The pre-amplifier swing — the Spine reads it to show the Δ equation
   *  (`base → final`). Absent on turns that didn't amplify (none to disclose). */
  baseProgressChange?: number
  valence: RunValence
  craft?: Craft
  anachronism?: Anachronism
  /** True when this was the run's staked last stand — the Spine's ⚑ badge. */
  staked?: boolean
96}
97 
98/** The full saved run — everything a read-only view needs to replay the end screen. */
99export interface RunSnapshot {
  version: number
  runId: string
  status: RunOutcome
  objective: GameObjective
  objectiveProgress: number
  /** The run's high-water mark (0..100) — the highest objectiveProgress it ever
   *  reached. Always ≥ objectiveProgress (peak only rises; the live total can fall),
   *  so a snapshot-backed view shows "Peaked at X%" exactly when peak > final, the
   *  same rule the live end screen uses (#151). v1 snapshots lack it; `migrateSnapshot`
   *  defaults them to their final objectiveProgress (so peak == final → stat hidden). */
  peakProgress: number
  messagesUsed: number
  totalMessages: number
  bestRoll: RollMark | null
  worstRoll: RollMark | null
  efficiency: RunEfficiency | null
  dispatches: RunDispatch[]
  timeline: RunLedgerEntry[]
  chronicle: ChronicleEntry | null
119}
120 
121/**
* Upgrade a stored snapshot to the current shape. Snapshots persist under the version
* current at save time, so a reader branches on `version` to normalize an older one
* rather than mis-reading a field it predates. A current snapshot passes through
* untouched; future bumps add their own step here, applied in sequence.
*
* v1 → v2: the high-water mark was live-session-only, so a v1 blob carries no
* `peakProgress`. Default it to the run's final objectiveProgress — peak == final, which
* renders as "no peak shown," exactly how those runs looked before the field existed.
*/
131export function migrateSnapshot(raw: RunSnapshot): RunSnapshot {
  if (raw.version >= RUN_SNAPSHOT_VERSION) return raw
  const peak = (raw as { peakProgress?: unknown }).peakProgress
  return {
      ...raw,
      version: RUN_SNAPSHOT_VERSION,
      peakProgress: typeof peak === 'number' ? peak : raw.objectiveProgress
  }
139}
140 
141/** The list projection — what the "your runs" list shows per run, without pulling
*  the full snapshot blob for every row. */
143export interface RunSummary {
  runId: string
  status: RunOutcome
  title: string
  progress: number
  createdAt: string
149}
150 
151/**
* "Remixed from" credit (issue #89) — the one-hop lineage of a replayed run: the run it
* was seeded from. It is a POINTER WALKED at render time (never a copy stamped into the
* child), so it always reflects the source's CURRENT privacy choice — a later un-share
* drops `attribution` back to anonymous and `sourceToken` to null. It carries only public
* game data + the opt-in display name: never the parent's run id, owner, or device.
*/
158export interface RemixCredit {
  /** The source sharer's opt-in display name, or null when they shared anonymously. */
  attribution: string | null
  /** The source run's objective title — the objective this run is a replay of. */
  objectiveTitle: string
  /** The source's live share token for an optional backlink, or null when un-shared. */
  sourceToken: string | null
165}
166 
167/**
* The PUBLIC, shareable projection of a saved run (issue #88) — the sanitized form
* served at an unguessable share URL to anyone, no login. It carries the GAME RECORD
* (verdict, ledger, dispatches, Chronicle epilogue) and an optional self-chosen display
* name, and DELIBERATELY nothing that identifies the player: no user id, no device id,
* no email — and not even the run id (the share token is the only handle). `run.runId`
* is blanked for that reason; the read-only view never renders it.
*/
175export interface PublicRun {
  run: RunSnapshot
  /** The sharer's opt-in display name, or null when shared anonymously. */
  attribution: string | null
  /** When this run is itself a replay (issue #89), the one-hop "remixed from" credit;
   *  null/absent for an original run. Walked from the parent's live snapshot, so it
   *  honors the source's current privacy opt-in. */
  remixedFrom?: RemixCredit | null
183}
184 
185/** What the OWNER sees about a run's share status: the live token (null = not shared)
*  and the current display name. Owner-only — never part of the public projection. */
187export interface ShareState {
  token: string | null
  name: string | null
190}
191 
192/** The brag line a share prefills (the X intent + the native sheet) — one source so the
*  end screen, the saved-run page, and the public page never drift (issue #88). */
194export function buildShareText(objectiveTitle: string, status: RunOutcome, progress: number): string {
  const verb = status === 'victory' ? 'I rewrote history' : 'I tried to rewrite history'
  return `${verb} in Everwhen: ${objectiveTitle || 'a historical mission'} — ${progress}% rewritten.`
197}
198 
199/* ──────────────────────────────────────────────────────────────────────────────
* The in-progress run DRAFT (#152) — the live counterpart to the terminal snapshot.
*
* The snapshot above is written once and frozen; the draft is its mirror image:
* overwritten after every resolved-but-still-playing turn so a refresh or a crash
* can't lose a half-played run. It serializes the DURABLE live state the store needs
* to drop the player straight back onto the in-progress board, and nothing else:
*
*   • the running totals — objective + progress + peak + momentum + remainingMessages
*   • the FULL thread, both sides (the snapshot keeps only the player's dispatches; a
*     resume needs the AI replies too, or it would re-pay for those model calls)
*   • the UN-trimmed ledger — with `whenSigned` and `causalChain`, which the next
*     turn's causal-chain dial and the figure world-brief read back
*   • the contacted figures and the active-contact selection (who & when)
*   • the live Chronicle and any replay lineage
*
* It DELIBERATELY omits: transient UI/loading flags, the runEpoch/seq staleness
* counters (they must survive a reset, not a reload), and `figureGrounding` — the
* active figure is RE-grounded from the live record on resume, so a draft never
* carries a stale dossier. The in-memory `Date` stamps on the thread/ledger serialize
* to ISO strings here (jsonb is dateless) and are revived on rehydrate.
*
* Versioned INDEPENDENTLY of the snapshot (RUN_DRAFT_VERSION, not RUN_SNAPSHOT_VERSION):
* the two shapes have different lifecycles and evolve on their own clocks, so a
* snapshot-only field change must never read as a draft migration, nor the reverse.
* ────────────────────────────────────────────────────────────────────────────── */
225 
226/** The current draft shape. Independent of RUN_SNAPSHOT_VERSION on purpose — a draft
*  and a snapshot are different records. Bump on an incompatible change; a future
*  reader branches on it to migrate rather than mis-read an older draft. */
229export const RUN_DRAFT_VERSION = 1
230 
231/** One thread line as it persists in a draft: the live store `Message` with its
*  `Date` stamp serialized to an ISO string. Both senders are kept (the snapshot's
*  RunDispatch keeps player dispatches only) — the AI replies are part of "where you
*  left off," and they cost a model call to regenerate. */
⋯ 61 lines hidden (lines 235–295)235export interface RunDraftMessage {
  text: string
  sender: 'user' | 'ai' | 'system'
  timestamp: string
  figureName?: string
  diceRoll?: number
  diceOutcome?: DiceOutcome
  naturalRoll?: number
  rollModifier?: number
  craft?: Craft
  craftReason?: string
  continuity?: Continuity
  characterAction?: string
  timelineImpact?: string
  progressChange?: number
  baseProgressChange?: number
  momentumAtSwing?: number
  anachronism?: Anachronism
  causalChain?: ChainStatus
  staked?: boolean
255}
256 
257/** One ledger entry as it persists in a draft: the FULL live `TimelineEvent` (not the
*  snapshot's trimmed RunLedgerEntry) — it keeps `whenSigned` and `causalChain`, the
*  footholds the next turn's causal chain measures against, with its `Date` stamp
*  serialized to an ISO string. */
261export interface RunDraftLedgerEntry {
  id: string
  figureName: string
  era: string
  headline: string
  detail: string
  diceRoll: number
  diceOutcome: DiceOutcome
  progressChange: number
  baseProgressChange?: number
  valence: RunValence
  anachronism?: Anachronism
  causalChain?: ChainStatus
  craft?: Craft
  whenSigned?: number
  staked?: boolean
  timestamp: string
278}
279 
280/** A contacted figure as the store caches it (mirrors the store's HistoricalFigure). */
281export interface RunDraftFigure {
  name: string
  era: string
  descriptor: string
285}
286 
287/** The replay seed (issue #89) as it persists in a draft — so a resumed replay still
*  stamps its lineage pointer and credits its source on the end screen. */
289export interface RunDraftReplay {
  objective: GameObjective
  sourceToken: string
  sourceAttribution: string | null
293}
294 
295/** The full in-progress draft — everything the store needs to rehydrate a live run. */
296export interface RunDraft {
  version: number
  runId: string
  currentObjective: GameObjective
  objectiveProgress: number
  peakProgress: number
  momentum: number
  remainingMessages: number
  messageHistory: RunDraftMessage[]
  timelineEvents: RunDraftLedgerEntry[]
  figures: RunDraftFigure[]
  activeFigureName: string
  contactWhen: number | null
  contactMoment: ContactMoment | null
  chronicle: ChronicleEntry | null
  replayState: RunDraftReplay | null
312}

Clamp the untrusted draft at the boundary

A draft is POSTed by the client and, on resume, rehydrates the live store — so it is trusted no more than a send-message body. The server-only validator coerces and bounds every field. The lines that matter most are the counter clamps: between turns there is no server-side turn engine, so remainingMessages is purely client-authoritative. A forged draft is the only lever a crafted request has over it.

The posture (top), and the clamps that make a forged draft harmless.

server/utils/run-draft.ts · 273 lines

server/utils/run-draft.ts273 lines · TypeScript

1/**
* Server-side boundary validation for an in-progress run draft (#152).
*
* The shared CONTRACT (types + version) lives in `~/utils/run-snapshot` so both the
* client store and the server import it without pulling server-only code into the
* client bundle. This is the server-only half: it coerces an untrusted POST body into
* a valid RunDraft (a direct POST can send anything), bounding every field with the
* same cleanString/cleanArray/clampInt helpers the other routes use.
*
* A draft is trusted LESS than a snapshot, not more: on resume it REHYDRATES the live
* store, and `remainingMessages` / `objectiveProgress` / `momentum` drive real game
* logic. The client is the system of record between turns (there is no server turn
* engine), so a forged draft is the only lever a crafted request has over those — clamp
* them into their legal ranges here so resume can never grant extra turns (each is a
* paid model call) or instant-win progress.
*/
17import {
  cleanString,
⋯ 168 lines hidden (lines 19–186)19    cleanArray,
  clampInt,
  MAX_ERA_CHARS,
  MAX_FIGURE_NAME_CHARS,
  MAX_LEDGER_DETAIL_CHARS,
  MAX_LEDGER_SWING,
  MAX_OBJECTIVE_DESC_CHARS,
  MAX_OBJECTIVE_TITLE_CHARS,
  MAX_SHARE_NAME_CHARS,
  MAX_TIMELINE_ENTRIES,
  MAX_HISTORY_ENTRIES
30} from './validate'
31import { sanitizeRunId } from './run-context'
32import { toAnachronism } from './anachronism'
33import { TOTAL_MESSAGES, MAX_PROGRESS } from '~/utils/game-config'
34import { MOMENTUM_MAX } from '~/utils/momentum'
35import { toCraft } from '~/utils/craft'
36import { toContinuity } from '~/utils/continuity'
37import { toContactMoment } from '~/utils/contact-moment'
38import { CHAIN_TIERS, type ChainStatus, type ChainTier } from '~/utils/causal-chain'
39import { DiceOutcome } from '~/utils/dice'
40import {
  RUN_DRAFT_VERSION,
  type RunDraft,
  type RunDraftMessage,
  type RunDraftLedgerEntry,
  type RunDraftFigure,
  type RunDraftReplay,
  type RunValence
48} from '~/utils/run-snapshot'
49import type { GameObjective } from '~/server/utils/objectives'
50import type { ChronicleEntry } from '~/server/utils/openai'
51 
52// Caps specific to the draft's own fields (the shared input caps live in validate.ts).
53const MAX_MSG_TEXT_CHARS = 320
54const MAX_ACTION_CHARS = 320
55const MAX_CRAFT_REASON_CHARS = 240
56const MAX_HEADLINE_CHARS = 200
57const MAX_DESCRIPTOR_CHARS = 200
58const MAX_ICON_CHARS = 16
59const MAX_OUTCOME_CHARS = 24
60const MAX_TS_CHARS = 40
61const MAX_ID_CHARS = 64
62const MAX_DICE = 40
63// A signed contact/anchor year (BC negative … AD positive). Mirrors the bound the
64// other routes clamp `whenSigned` to (server/api/send-message.post.ts).
65const MAX_YEAR = 12000
66 
67const VALENCES: RunValence[] = ['positive', 'negative', 'neutral']
68const coerceValence = (v: unknown): RunValence =>
  VALENCES.includes(v as RunValence) ? (v as RunValence) : 'neutral'
70 
71const clampNonNeg = (n: number): number => Math.max(0, n)
72 
73const DICE_OUTCOMES = Object.values(DiceOutcome) as string[]
74const cleanOutcome = (v: unknown): DiceOutcome | undefined => {
  const s = cleanString(v, MAX_OUTCOME_CHARS)
  return DICE_OUTCOMES.includes(s) ? (s as DiceOutcome) : undefined
77}
78 
79/** A finite signed int clamped to ±bound, or undefined when absent — keeps an
*  optional field's "absent" distinct from a real 0 (clampInt alone returns 0). */
81const optInt = (v: unknown, bound: number): number | undefined =>
  typeof v === 'number' && Number.isFinite(v) ? clampInt(v, bound) : undefined
83 
84/** Coerce an untrusted causal-chain read, or undefined when it isn't one. The factor
*  is a multiplier in [0, 1]; the gap is years (non-negative); the tier is an enum. */
86const cleanChain = (v: unknown): ChainStatus | undefined => {
  if (!v || typeof v !== 'object') return undefined
  const c = v as Record<string, unknown>
  const tier = c.tier as ChainTier
  if (!CHAIN_TIERS.includes(tier)) return undefined
  const factor = typeof c.factor === 'number' && Number.isFinite(c.factor)
      ? Math.max(0, Math.min(1, c.factor))
      : 1
  return { gap: clampNonNeg(clampInt(c.gap, MAX_YEAR)), factor, tier }
95}
96 
97/** Coerce one untrusted thread line into a bounded RunDraftMessage. Optional fields
*  are set only when present, so an absent grade/roll stays absent on rehydrate. */
99function cleanMessage(raw: unknown): RunDraftMessage {
  const m = (raw ?? {}) as Record<string, unknown>
  const sender: RunDraftMessage['sender'] =
      m.sender === 'user' || m.sender === 'ai' || m.sender === 'system' ? m.sender : 'system'
  const msg: RunDraftMessage = {
      text: cleanString(m.text, MAX_MSG_TEXT_CHARS),
      sender,
      timestamp: cleanString(m.timestamp, MAX_TS_CHARS)
  }
  const figureName = cleanString(m.figureName, MAX_FIGURE_NAME_CHARS)
  if (figureName) msg.figureName = figureName
  const diceRoll = optInt(m.diceRoll, MAX_DICE)
  if (diceRoll !== undefined) msg.diceRoll = clampNonNeg(diceRoll)
  const diceOutcome = cleanOutcome(m.diceOutcome)
  if (diceOutcome) msg.diceOutcome = diceOutcome
  const naturalRoll = optInt(m.naturalRoll, MAX_DICE)
  if (naturalRoll !== undefined) msg.naturalRoll = clampNonNeg(naturalRoll)
  const rollModifier = optInt(m.rollModifier, MAX_DICE)
  if (rollModifier !== undefined) msg.rollModifier = rollModifier
  if (typeof m.craft === 'string') msg.craft = toCraft(m.craft)
  const craftReason = cleanString(m.craftReason, MAX_CRAFT_REASON_CHARS)
  if (craftReason) msg.craftReason = craftReason
  if (typeof m.continuity === 'string') msg.continuity = toContinuity(m.continuity)
  const characterAction = cleanString(m.characterAction, MAX_ACTION_CHARS)
  if (characterAction) msg.characterAction = characterAction
  const timelineImpact = cleanString(m.timelineImpact, MAX_LEDGER_DETAIL_CHARS)
  if (timelineImpact) msg.timelineImpact = timelineImpact
  const progressChange = optInt(m.progressChange, MAX_LEDGER_SWING)
  if (progressChange !== undefined) msg.progressChange = progressChange
  const baseProgressChange = optInt(m.baseProgressChange, MAX_LEDGER_SWING)
  if (baseProgressChange !== undefined) msg.baseProgressChange = baseProgressChange
  const momentumAtSwing = optInt(m.momentumAtSwing, MOMENTUM_MAX)
  if (momentumAtSwing !== undefined) msg.momentumAtSwing = clampNonNeg(momentumAtSwing)
  if (typeof m.anachronism === 'string') msg.anachronism = toAnachronism(m.anachronism)
  const chain = cleanChain(m.causalChain)
  if (chain) msg.causalChain = chain
  if (m.staked === true) msg.staked = true
  return msg
137}
138 
139/** Coerce one untrusted ledger entry into a bounded RunDraftLedgerEntry. */
140function cleanLedgerEntry(raw: unknown): RunDraftLedgerEntry {
  const t = (raw ?? {}) as Record<string, unknown>
  const entry: RunDraftLedgerEntry = {
      id: cleanString(t.id, MAX_ID_CHARS),
      figureName: cleanString(t.figureName, MAX_FIGURE_NAME_CHARS),
      era: cleanString(t.era, MAX_ERA_CHARS),
      headline: cleanString(t.headline, MAX_HEADLINE_CHARS),
      detail: cleanString(t.detail, MAX_LEDGER_DETAIL_CHARS),
      diceRoll: clampNonNeg(clampInt(t.diceRoll, MAX_DICE)),
      diceOutcome: cleanOutcome(t.diceOutcome) ?? DiceOutcome.NEUTRAL,
      progressChange: clampInt(t.progressChange, MAX_LEDGER_SWING),
      valence: coerceValence(t.valence),
      timestamp: cleanString(t.timestamp, MAX_TS_CHARS)
  }
  const baseProgressChange = optInt(t.baseProgressChange, MAX_LEDGER_SWING)
  if (baseProgressChange !== undefined) entry.baseProgressChange = baseProgressChange
  if (typeof t.craft === 'string') entry.craft = toCraft(t.craft)
  if (typeof t.anachronism === 'string') entry.anachronism = toAnachronism(t.anachronism)
  const chain = cleanChain(t.causalChain)
  if (chain) entry.causalChain = chain
  const whenSigned = optInt(t.whenSigned, MAX_YEAR)
  if (whenSigned !== undefined) entry.whenSigned = whenSigned
  if (t.staked === true) entry.staked = true
  return entry
164}
165 
166/** Coerce an untrusted objective into the bounded GameObjective shape. */
167function cleanObjective(raw: Record<string, unknown>): GameObjective {
  const objective: GameObjective = {
      title: cleanString(raw.title, MAX_OBJECTIVE_TITLE_CHARS),
      description: cleanString(raw.description, MAX_OBJECTIVE_DESC_CHARS),
      era: cleanString(raw.era, MAX_ERA_CHARS),
      icon: cleanString(raw.icon, MAX_ICON_CHARS)
  }
  if (typeof raw.anchorYear === 'number' && Number.isFinite(raw.anchorYear)) {
      objective.anchorYear = Math.round(raw.anchorYear)
  }
  return objective
178}
179 
180/**
* Coerce an untrusted body into a valid RunDraft, or null when there is nothing
* resumable: no run id, or no objective (a run with no objective has no board to drop
* back onto). Bounds every field and stamps the server's own `version` — never the
* client's. The run-id is sanitized here; the route additionally gates it to a real
* uuid (the `run_drafts.run_id` FK is uuid).
*/
187export function sanitizeDraft(raw: unknown): RunDraft | null {
  if (!raw || typeof raw !== 'object') return null
  const r = raw as Record<string, unknown>
190 
  const runId = sanitizeRunId(r.runId)
  if (!runId) return null
193 
  if (!r.currentObjective || typeof r.currentObjective !== 'object') return null
  const currentObjective = cleanObjective(r.currentObjective as Record<string, unknown>)
196 
  // The counters that drive game logic on resume — clamped into their legal ranges so
  // a forged draft can't grant free turns or instant-win progress.
  const objectiveProgress = clampNonNeg(clampInt(r.objectiveProgress, MAX_PROGRESS))
  // The peak is a high-water mark, so it can't sit below the current progress.
  const peakProgress = Math.max(objectiveProgress, clampNonNeg(clampInt(r.peakProgress, MAX_PROGRESS)))
  const momentum = Math.min(MOMENTUM_MAX, clampNonNeg(clampInt(r.momentum, MOMENTUM_MAX)))
  const remainingMessages = Math.min(TOTAL_MESSAGES, clampNonNeg(clampInt(r.remainingMessages, TOTAL_MESSAGES)))
204 
⋯ 69 lines hidden (lines 205–273)205    const messageHistory = cleanArray(r.messageHistory, MAX_HISTORY_ENTRIES).map(cleanMessage)
  const timelineEvents = cleanArray(r.timelineEvents, MAX_TIMELINE_ENTRIES).map(cleanLedgerEntry)
  const figures: RunDraftFigure[] = cleanArray(r.figures, MAX_HISTORY_ENTRIES)
      .map((raw) => {
          const f = (raw ?? {}) as Record<string, unknown>
          return {
              name: cleanString(f.name, MAX_FIGURE_NAME_CHARS),
              era: cleanString(f.era, MAX_ERA_CHARS),
              descriptor: cleanString(f.descriptor, MAX_DESCRIPTOR_CHARS)
          }
      })
      .filter((f) => f.name)
217 
  const activeFigureName = cleanString(r.activeFigureName, MAX_FIGURE_NAME_CHARS)
  const contactWhen = typeof r.contactWhen === 'number' && Number.isFinite(r.contactWhen)
      ? clampInt(r.contactWhen, MAX_YEAR)
      : null
  // Re-derive the pinned moment from validated integers (the same posture as
  // send-message: never trust a client-formatted date).
  const m = (r.contactMoment ?? {}) as Record<string, unknown>
  const contactMoment = toContactMoment(m.month, m.day)
226 
  let chronicle: ChronicleEntry | null = null
  if (r.chronicle && typeof r.chronicle === 'object') {
      const c = r.chronicle as Record<string, unknown>
      chronicle = {
          title: cleanString(c.title, MAX_HEADLINE_CHARS),
          paragraphs: cleanArray(c.paragraphs, MAX_HISTORY_ENTRIES)
              .map((p) => cleanString(p, MAX_OBJECTIVE_DESC_CHARS))
              .filter(Boolean)
      }
  }
237 
  // The replay seed (issue #89) is kept only when intact — a source token AND the
  // captured objective; a partial seed couldn't stamp lineage anyway.
  let replayState: RunDraftReplay | null = null
  if (r.replayState && typeof r.replayState === 'object') {
      const s = r.replayState as Record<string, unknown>
      const sourceToken = cleanString(s.sourceToken, MAX_ID_CHARS)
      if (sourceToken && s.objective && typeof s.objective === 'object') {
          replayState = {
              objective: cleanObjective(s.objective as Record<string, unknown>),
              sourceToken,
              sourceAttribution: typeof s.sourceAttribution === 'string'
                  ? cleanString(s.sourceAttribution, MAX_SHARE_NAME_CHARS)
                  : null
          }
      }
  }
254 
  return {
      // The server owns the version stamp — never trust the client's.
      version: RUN_DRAFT_VERSION,
      runId,
      currentObjective,
      objectiveProgress,
      peakProgress,
      momentum,
      remainingMessages,
      messageHistory,
      timelineEvents,
      figures,
      activeFigureName,
      contactWhen,
      contactMoment,
      chronicle,
      replayState
  }
273}

The draft store

Storage follows the repo's env-degradation idiom exactly: one port, two adapters chosen by config. In-memory by default, so npm run dev and the unit tests need nothing; Supabase when the URL + secret key are present. The interface is just three verbs — upsert the draft, read the subject's latest, delete one — and reads are scoped to the owner, so a player only ever resumes their own run.

The port, and the durable read: the subject's latest draft, newest first.

server/utils/run-draft-store.ts · 125 lines

server/utils/run-draft-store.ts125 lines · TypeScript

⋯ 26 lines hidden (lines 1–26)1/**
* The run-draft store — where an IN-PROGRESS run is parked so a refresh or a crash
* can't lose it (#152). POST /api/run-draft upserts the draft here keyed by the run
* id; GET /api/run-draft reads back the subject's latest in-progress draft to resume;
* DELETE /api/run-draft clears it (also cleared on terminal save). The terminal,
* immutable record lives in the separate run-snapshot store — a draft is the live,
* overwritten mirror, never the saved run.
*
* Two adapters behind one port, chosen by config — the repo's env-degradation idiom
* (cf. runSnapshotStore, runStore):
*   - in-memory (default): no external dependency, so `npm run dev` and the unit tests
*     need nothing. Drafts don't outlive the process, but the round-trip (save -> read
*     latest -> delete) is real, which is what the resume path rests on.
*   - Supabase: used when SUPABASE_URL + SUPABASE_SECRET_KEY are configured. Upserts
*     the `run_drafts` row via the service (secret) key, which bypasses RLS — the table
*     has no public policy, so it is server-only.
*
* Ownership is by SUBJECT (the Supabase user id, falling back to the device id) — the
* same string balances/runs/snapshots key on. Reads filter by it, so a player only
* ever resumes their OWN run; an anonymous draft carries over to the account for free
* on a magic-link sign-in (same subject id).
*/
23import { createClient, type SupabaseClient } from '@supabase/supabase-js'
24import { supabaseConfig } from './supabase'
25import type { RunDraft } from '~/utils/run-snapshot'
26 
27export interface RunDraftStore {
  /** Persist (or overwrite) the in-progress draft, owned by `subject`, keyed by run id. */
  saveDraft(subject: string, draft: RunDraft): Promise<void>
  /** The subject's most-recently-updated draft, or null when they have none. A
   *  player has a single active run (starting one spends a credit), so "latest"
   *  is the one to resume. */
  getLatestDraft(subject: string): Promise<RunDraft | null>
  /** Drop a draft the subject owns. Idempotent; a no-op when absent / not theirs. */
  deleteDraft(subject: string, runId: string): Promise<void>
36}
37 
⋯ 47 lines hidden (lines 38–84)38/** Dev/test default — keeps the round-trip real without any external dependency. A
*  monotonic tick orders "latest" deterministically (clock ties can't reorder it). */
40export class InMemoryRunDraftStore implements RunDraftStore {
  private tick = 0
  private readonly drafts: Array<{ subject: string; runId: string; draft: RunDraft; updatedAt: number }> = []
43 
  async saveDraft(subject: string, draft: RunDraft): Promise<void> {
      const updatedAt = ++this.tick
      const existing = this.drafts.find((d) => d.runId === draft.runId)
      if (existing) {
          existing.subject = subject
          existing.draft = draft
          existing.updatedAt = updatedAt
          return
      }
      this.drafts.push({ subject, runId: draft.runId, draft, updatedAt })
  }
55 
  async getLatestDraft(subject: string): Promise<RunDraft | null> {
      const owned = this.drafts.filter((d) => d.subject === subject)
      if (!owned.length) return null
      return owned.reduce((a, b) => (b.updatedAt > a.updatedAt ? b : a)).draft
  }
61 
  async deleteDraft(subject: string, runId: string): Promise<void> {
      const i = this.drafts.findIndex((d) => d.runId === runId && d.subject === subject)
      if (i >= 0) this.drafts.splice(i, 1)
  }
66}
67 
68/** Records each draft as a `run_drafts` row via the service (secret) key, which
*  bypasses RLS — the table has no public policy, so it is server-only. */
70export class SupabaseRunDraftStore implements RunDraftStore {
  constructor(private readonly client: SupabaseClient) {}
72 
  async saveDraft(subject: string, draft: RunDraft): Promise<void> {
      // Upsert on the run-id PK so each turn's autosave overwrites the prior one
      // rather than erroring. `updated_at` is stamped explicitly (a column default
      // fires only on insert, not on the update half of an upsert) so "latest" stays
      // accurate across the run.
      const { error } = await this.client.from('run_drafts').upsert({
          run_id: draft.runId,
          user_id: subject,
          version: draft.version,
          data: draft,
          updated_at: new Date().toISOString()
      })
      if (error) throw new Error(`run_drafts upsert failed: ${error.message}`)
  }
87 
  async getLatestDraft(subject: string): Promise<RunDraft | null> {
      const { data, error } = await this.client
          .from('run_drafts')
          .select('data')
          .eq('user_id', subject)
          .order('updated_at', { ascending: false })
          .limit(1)
          .maybeSingle()
      if (error) throw new Error(`run_drafts get failed: ${error.message}`)
      return (data?.data as RunDraft | undefined) ?? null
  }
99 
⋯ 26 lines hidden (lines 100–125)100    async deleteDraft(subject: string, runId: string): Promise<void> {
      const { error } = await this.client
          .from('run_drafts')
          .delete()
          .eq('run_id', runId)
          .eq('user_id', subject)
      if (error) throw new Error(`run_drafts delete failed: ${error.message}`)
  }
108}
109 
110let cached: RunDraftStore | null = null
111 
112/** The configured run-draft store (memoized — reuses one Supabase client). */
113export function runDraftStore(): RunDraftStore {
  if (cached) return cached
  const cfg = supabaseConfig()
  cached = cfg
      ? new SupabaseRunDraftStore(createClient(cfg.url, cfg.secretKey, { auth: { persistSession: false } }))
      : new InMemoryRunDraftStore()
  return cached
120}
121 
122/** Test seam: clear the memoized store so the next call re-reads config. */
123export function resetRunDraftStore(): void {
  cached = null
125}

Autosave, clear, and resume — woven into the store

Three new actions sit beside saveRunSnapshot. **saveRunDraft** mirrors it for a still-playing run, serializing Date stamps to ISO strings. **clearRunDraft** drops the draft (it takes an explicit run id so resetGame can clear the run it is tearing down). **resumeDraft** reads the latest draft and rehydrates the store.

The wiring lives in the sendMessage tail. The terminal branch (victory/defeat) gains a clearRunDraft() next to the snapshot save; a new still-playing branch autosaves — an immediate write (in case the chronicle refresh hangs) plus a re-save once the fresh Chronicle lands, the same two-beat shape the terminal save already uses.

resumeDraft is the subtle one. It reuses the draft's runId (so no second credit is charged), revives the ISO stamps to real Dates, then re-grounds the active figure and restores the saved contact year over the mid-lifetime default that grounding would otherwise pick. Read the two guards on it closely — they are covered in the callout.

The turn-tail wiring, saveRunDraft's serialize, all of resumeDraft, and resetGame's clear.

stores/game.ts · 1651 lines

stores/game.ts1651 lines · TypeScript

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

Resume on load, and the finished-run safety net

The page kicks off resume from onMounted, after the balance load and any magic-link return settle, and only when the board is empty. It is auto-resume: the player lands back on the in-progress board, and the header's existing ↻ "new timeline" control is the abandon path (it clears the draft through resetGame).

One guarded call at the end of the mount sequence.

pages/play.vue · 625 lines

pages/play.vue625 lines · Vue

⋯ 461 lines hidden (lines 1–461)1<template>
2  <div class="min-h-screen lg:h-screen ew-bg flex flex-col lg:overflow-hidden">
3    <!-- HUD: wordmark · objective mission-strip · gauge · status · dark · new-timeline -->
4    <header class="border-b ew-line">
5      <!-- On phones the bar wraps: controls stay on the top line, and the objective
6           (with its foldable brief) drops to its own full-width line so the brief
7           reads at full width instead of a thin column. Single row from sm up. -->
8      <div class="px-3 sm:px-5 py-2.5 flex flex-wrap items-center gap-x-2 gap-y-1.5 sm:flex-nowrap sm:gap-4">
9        <GameTitle />
10 
11        <div v-if="gameStore.currentObjective" class="order-last basis-full min-w-0 sm:order-none sm:basis-auto sm:flex-1">
12          <ObjectiveDisplay data-testid="objective-display" />
13        </div>
14        <div v-else class="flex-1" />
15 
16        <div v-if="gameStore.currentObjective" class="flex items-center gap-1.5 sm:gap-2 shrink-0 ml-auto sm:ml-0">
17          <MessagesCounter data-testid="messages-counter" />
18          <!-- One mis-tap must not erase five AI-resolved turns: with a run in
19               progress the reset arms a tiny inline confirm (auto-reverts); an
20               untouched run still resets in one tap. -->
21          <span v-if="resetArmed" class="flex items-center gap-1.5">
22            <span class="text-[11px] ew-warn">abandon this history?</span>
23            <button type="button" data-testid="reset-confirm" class="ew-tap ew-hover-fg text-sm leading-none ew-warn"
24              aria-label="Yes — abandon this history" @click="performReset">✓</button>
25            <button type="button" data-testid="reset-cancel" class="ew-tap ew-hover-fg text-sm leading-none"
26              aria-label="Keep playing" @click="disarmReset">✕</button>
27          </span>
28          <button v-else type="button" data-testid="reset-button" class="ew-tap ew-hover-fg text-base leading-none"
29            title="New timeline" aria-label="New timeline" @click="handleResetGame">↻</button>
30        </div>
31 
32        <!-- Runs gauge — always visible (briefing + board), and the entry to the
33             account popover / the run-packs modal. -->
34        <RunsBalance class="shrink-0" :class="gameStore.currentObjective ? '' : 'ml-auto'" />
35 
36        <!-- Sound on/off — beside the dark toggle, persisted the same way. The svg is
37             decorative (aria-hidden); the button carries the state-reflecting name. -->
38        <button type="button" data-testid="mute-toggle" class="ew-tap ew-hover-fg leading-none shrink-0"
39          :aria-label="audio.muted ? 'Unmute sound effects' : 'Mute sound effects'"
40          :title="audio.muted ? 'Sound off' : 'Sound on'" :aria-pressed="!audio.muted" @click="toggleMute">
41          <svg width="17" height="17" viewBox="0 0 24 24" fill="none" aria-hidden="true">
42            <path d="M4 9h3l5-4v14l-5-4H4z" fill="currentColor" stroke="currentColor"
43              stroke-width="1.6" stroke-linejoin="round" />
44            <template v-if="!audio.muted">
45              <path d="M16.5 8.5a5 5 0 0 1 0 7" stroke="currentColor" stroke-width="1.8"
46                stroke-linecap="round" />
47              <path d="M19 6a8.5 8.5 0 0 1 0 12" stroke="currentColor" stroke-width="1.8"
48                stroke-linecap="round" />
49            </template>
50            <template v-else>
51              <path d="M16.5 9.5l5 5m0-5l-5 5" stroke="currentColor" stroke-width="1.8"
52                stroke-linecap="round" />
53            </template>
54          </svg>
55        </button>
56 
57        <button type="button" class="ew-tap ew-hover-fg text-base leading-none shrink-0"
58          :aria-label="isDark ? 'Switch to light mode' : 'Switch to dark mode'" @click="toggleDark">◐</button>
59      </div>
60    </header>
61 
62    <!-- Post-checkout banner: the missing feedback after returning from Stripe — a
63         credited confirmation, or a gentle "no charge" on cancel. Self-dismisses. -->
64    <div v-if="gameStore.purchaseNotice" data-testid="purchase-notice" role="status" aria-live="polite"
65      class="border-b ew-line px-5 py-2.5 text-sm flex items-center gap-2"
66      :class="gameStore.purchaseNotice === 'success' ? 'ew-tint' : ''">
67      <span aria-hidden="true">{{ gameStore.purchaseNotice === 'success' ? '✓' : '○' }}</span>
68      <span class="ew-fg">
69        <template v-if="gameStore.purchaseNotice === 'success'">
70          Payment received — your runs have been added to your balance.
71        </template>
72        <template v-else>Checkout canceled — you weren't charged.</template>
73      </span>
74      <button type="button" data-testid="purchase-notice-close" class="ew-tap ew-hover-fg ml-auto shrink-0"
75        aria-label="Dismiss" @click="gameStore.clearPurchaseNotice()">✕</button>
76    </div>
77 
78    <!-- Waiting mode: a thin indeterminate sweep while a turn resolves — the whole
79         board reads as "history is being rewritten," in concert with the shaking die. -->
80    <div v-if="gameStore.isLoading" class="ew-loading-bar" role="status">
81      <span class="sr-only">Resolving your move — history is being rewritten…</span>
82    </div>
83 
84    <!-- At lg the board owns the viewport and scrolls inside its own panes, so main is
85         clipped (lg:overflow-hidden). The mission briefing has no such inner scroll, so
86         on a short viewport that clipping hid the Begin button under the footer — give
87         the briefing a scrollable main instead. -->
88    <main class="px-5 py-6 pb-24 md:pb-6 flex-1"
89      :class="gameStore.currentObjective ? 'lg:min-h-0 lg:py-0 lg:overflow-hidden' : 'lg:overflow-y-auto'">
90      <!-- Briefing: choose (or compose) an objective before the run begins -->
91      <MissionSelect v-if="!gameStore.currentObjective" />
92 
93      <template v-else>
94        <!-- The board, only while the run is live — once it ends, the end-screen
95             takeover fully replaces it (no board bleeding under the verdict).
96             On phones the three zones become one-at-a-time panels driven by the
97             bottom tab bar; from md up every zone is shown together as before. -->
98        <template v-if="gameStore.gameStatus === 'playing'">
99        <!-- THE WORKSPACE — at lg the board splits into two panes that fit the viewport:
100             a scrolling read-model (roll · shift · Spine · Chronicle · Thread) on the
101             left, and the act-model (the compose dock) pinned on the right, so the move
102             is never buried below the read. Below lg this wrapper is inert and the zones
103             fall back to the stacked page (md) / phone tab panels (sm). -->
104        <div class="ew-fade-in lg:h-full lg:grid lg:grid-cols-[minmax(0,1fr)_minmax(360px,440px)] lg:grid-rows-1">
105        <!-- LEFT pane — the read-model. At lg it's a flex column the height of the
106             pane: the board/Spine on top at its natural height, then the story zone
107             flexes to fill the rest, so the Chronicle & Thread are full-height panels
108             (each scrolls inside itself) rather than a single scrolling stack. -->
109        <div class="lg:min-h-0 lg:min-w-0 lg:flex lg:flex-col lg:overflow-hidden lg:pr-6 lg:py-6">
110        <!-- ZONE 1 — the board state: the roll + the shift, then the Spine -->
111        <section class="ew-panel space-y-4 lg:space-y-6 lg:flex-none" :class="[{ 'ew-dim': isFirstTurn }, mobileTab === 'board' ? '' : 'hidden', 'md:block']">
112          <div class="grid sm:grid-cols-2 gap-4">
113            <div class="sm:border-r ew-line sm:pr-6 py-1">
114              <span class="ew-label mb-2 block">Dice of fate</span>
115              <DiceRoller />
116              <!-- The bands, disclosed: the player can always see how fate maps to
117                   swing — the same table the Timeline Engine is instructed with. -->
118              <details data-testid="roll-legend" class="mt-2 text-[11px]">
119                <summary class="ew-faint cursor-pointer select-none hover:underline">how fate is weighed</summary>
120                <ul class="mt-1.5 space-y-0.5 ew-mono ew-muted">
121                  <li v-for="row in rollLegend" :key="row.label" class="flex justify-between gap-3">
122                    <span>{{ row.range }} · {{ row.label }}</span><span :class="row.cls">{{ row.swing }}</span>
123                  </li>
124                </ul>
125                <p class="ew-faint mt-1.5 leading-snug">✒ craft tilts the roll (±2) · ⚡ anachronism widens the result — gains gently, losses hard · ⚑ a staked final dispatch doubles everything</p>
126              </details>
127            </div>
128            <div class="sm:pl-2 flex flex-col justify-center gap-3">
129              <ProgressTracker />
130              <MomentumMeter />
131            </div>
132          </div>
133          <TimelineLedger />
134        </section>
135 
136        <!-- ZONE 2 — the story: the living chronicle · the conversation thread. At lg
137             this flexes to fill the rest of the pane and lays the two out side by side
138             as equal full-height columns (md keeps the two-up grid in the page flow). -->
139        <section class="ew-panel mt-9 lg:mt-10 gap-x-8 gap-y-2" :class="[{ 'ew-dim': isFirstTurn }, mobileTab === 'story' ? 'grid' : 'hidden', 'md:grid md:grid-cols-2', 'lg:grid-rows-1 lg:flex-1 lg:min-h-0']">
140          <Chronicle :force-open="isMd" />
141          <!-- Thread: a <div> from md up (see Chronicle for why a <details> can't fill the
142               column height), a collapsible <details> on phones. -->
143          <component :is="isMd ? 'div' : 'details'" class="ew-rail lg:h-full lg:min-h-0 lg:flex lg:flex-col" :open="isMd ? null : threadOpen" @toggle="onThreadToggle">
144            <summary class="ew-summary" :class="{ 'ew-summary--static': isMd }">
145              <span class="ew-label">Thread<span class="normal-case tracking-normal ew-faint font-normal"> · your messages<span v-if="gameStore.activeFigureName"> · {{ gameStore.activeFigureName }}</span></span></span>
146            </summary>
147            <div class="pt-2 lg:flex-1 lg:min-h-0 lg:overflow-y-auto">
148              <MessageHistory data-testid="message-history" />
149            </div>
150          </component>
151        </section>
152        </div><!-- /LEFT pane -->
153 
154        <!-- RIGHT pane — the act-model, pinned beside the read column at lg -->
155        <div class="lg:min-h-0 lg:overflow-y-auto lg:border-l ew-line lg:pl-6 lg:py-6">
156        <!-- ZONE 3 — your turn: the compose dock (the page-stack divider is dropped at
157             lg, where it's a column of its own, not a section below the read). -->
158        <section class="ew-panel mt-9 border-t ew-line pt-5 lg:mt-0 lg:border-t-0 lg:pt-0" :class="[mobileTab === 'compose' ? '' : 'hidden', 'md:block']">
159          <div class="flex items-center justify-between gap-3 mb-4 flex-wrap">
160            <span class="ew-label">Send a message into the past</span>
161            <!-- The wager, read BEFORE the roll: when the Archive has stamped a
162                 known-since and a contact year is chosen, the chip translates the
163                 reach into the same ⚡ tiers the spine uses. Otherwise the general
164                 principle is stated — on the first turn too, where it teaches most. -->
165            <span v-if="wagerRead" data-testid="wager-chip" class="text-[11px]"
166              :class="wagerRead.tier === 'in-period' ? 'ew-muted' : 'ew-warn'">
167              <span aria-hidden="true">{{ wagerRead.pips }}</span> {{ wagerRead.text }}
168            </span>
169            <span v-else data-testid="wager-line" class="text-[11px] ew-warn"><span aria-hidden="true">⚡</span> the further your words reach beyond their era, the wider the timeline swings — gains gently, losses hard</span>
170            <!-- The chain, read BEFORE the roll: how far this moment lands from your
171                 nearest foothold (the objective's era or a change you've made). A
172                 lone leap into the deep past is diffuse (warned); landing on a
173                 foothold is at-hinge, full force (a positive read) — so good
174                 chaining is confirmed, not silent. -->
175            <span v-if="chainRead" data-testid="chain-chip" class="text-[11px]"
176              :class="chainRead.tier === 'at-hinge' ? 'ew-ok' : chainRead.tier === 'diffuse' ? 'ew-warn' : 'ew-muted'">
177              <span aria-hidden="true">⏳</span> {{ chainRead.text }}
178            </span>
179          </div>
180 
181          <p v-if="isFirstTurn" class="ew-accent text-sm mb-4">
182            Reach someone in history, write up to 160 characters, and send — one message can bend the whole timeline.
183          </p>
184 
185          <div class="grid md:grid-cols-2 lg:grid-cols-1 gap-x-8 gap-y-6">
186            <div>
187              <span class="ew-label block mb-2"><span class="ew-accent">1</span> · choose who &amp; when</span>
188              <FigurePicker v-model="figure" :disabled="!gameStore.canSendMessage" />
189            </div>
190 
191            <div class="space-y-3 ew-line lg:border-t lg:pt-6">
192              <span class="ew-label block mb-2"><span class="ew-accent">2</span> · write &amp; send</span>
193              <MessageInput ref="messageInputRef" />
194              <!-- The last stand: offered only when the final dispatch can no
195                   longer win inside the normal per-turn cap — a true last resort,
196                   never a free doubling from a winnable position. -->
197              <div v-if="gameStore.canStake" data-testid="stake-control"
198                class="border rounded-sm px-2.5 py-2 flex items-start gap-2"
199                :class="stakeArmed ? 'stake-armed' : 'ew-line'">
200                <input id="stake-toggle" v-model="stakeArmed" type="checkbox" class="mt-0.5"
201                  :style="{ accentColor: 'var(--ew-accent)' }" />
202                <label for="stake-toggle" class="text-[11px] leading-snug cursor-pointer">
203                  <span class="ew-warn font-semibold uppercase tracking-wide"><span aria-hidden="true">⚑</span> Stake the timeline</span>
204                  <span class="ew-muted block">Your final dispatch cuts twice as deep — both ways — and can move the whole meter. The last stand.</span>
205                </label>
206              </div>
207              <div class="flex items-center gap-3 flex-wrap">
208                <SendButton data-testid="send-button" :input-valid="canSend" @click="handleSendMessage" />
209                <div v-if="gameStore.error" data-testid="error-alert" role="status" aria-live="polite"
210                  class="flex items-center gap-2 text-xs flex-1 min-w-0 border-l-2 ew-line pl-2 py-0.5">
211                  <span class="ew-label shrink-0">notice</span>
212                  <span class="ew-muted truncate">{{ gameStore.error }}</span>
213                  <button type="button" data-testid="error-close" class="ew-tap ew-hover-fg shrink-0 ml-auto" aria-label="Dismiss notice" @click="gameStore.setError(null)">✕</button>
214                </div>
215                <div v-if="gameStore.moderationNotice" data-testid="moderation-alert" role="alert" aria-live="assertive"
216                  class="flex items-start gap-2 text-xs flex-1 min-w-0 border-l-2 border-red-500/70 bg-red-500/5 pl-2 py-1 text-red-300">
217                  <span class="shrink-0 font-semibold uppercase tracking-wide">⚠ blocked</span>
218                  <span class="min-w-0">{{ gameStore.moderationNotice }}</span>
219                  <button type="button" data-testid="moderation-close" class="ew-tap shrink-0 ml-auto hover:text-red-100" aria-label="Dismiss" @click="gameStore.clearModerationNotice()">✕</button>
220                </div>
221              </div>
222              <ArchiveLookup />
223            </div>
224          </div>
225        </section>
226        </div><!-- /RIGHT pane -->
227        </div><!-- /workspace -->
228        </template>
229      </template>
230    </main>
231 
232    <!-- Phone-only tab bar: the three zones as fixed panels you switch between, so the
233         board never becomes one infinite scroll and your next move is always one tap
234         away. Hidden from md up (where every zone is shown at once). -->
235    <!-- A labelled nav of view-switch buttons (NOT an ARIA tablist: there's no roving
236         tabindex / arrow-key tabset here, and the zones are simple show/hide regions).
237         The active view is conveyed with aria-current, the honest, complete pattern. -->
238    <nav v-if="gameStore.currentObjective && gameStore.gameStatus === 'playing'"
239      class="md:hidden fixed bottom-0 inset-x-0 z-30 border-t ew-line ew-bg grid grid-cols-3"
240      aria-label="Switch board view">
241      <button v-for="t in mobileTabs" :key="t.id" type="button" :aria-current="mobileTab === t.id ? 'true' : undefined"
242        class="mobile-tab ew-press" :class="{ 'is-active': mobileTab === t.id }" @click="mobileTab = t.id">
243        <span class="text-lg leading-none" aria-hidden="true">{{ t.glyph }}</span>
244        <span class="ew-label flex items-center gap-1">
245          {{ t.label }}
246          <span v-if="t.id === 'compose' && yourMove" class="ew-dot ew-dot--accent" aria-hidden="true" />
247        </span>
248      </button>
249    </nav>
250 
251    <!-- A ledger running-foot: header + footer frame the page as a document.
252         (Hidden on phones, where the tab bar is the foot.) -->
253    <footer class="border-t ew-line px-5 py-3 hidden md:block text-[11px] ew-faint">
254      <div class="flex items-center gap-2">
255        <span class="ew-mono uppercase tracking-wide">Everwhen</span>
256        <span class="ew-hair-c" aria-hidden="true">·</span>
257        <span class="ew-mono">a history you are writing</span>
258        <span class="ml-auto ew-serif italic">the past is not fixed</span>
259      </div>
260      <!-- Persistent compliance line (AI disclosure + fiction + adults-only). -->
261      <p data-testid="footer-disclosure" class="mt-1.5">
262        Figures are AI, not real people · replies are AI-generated fiction, not historical fact · for adults (18+)
263      </p>
264    </footer>
265 
266    <EndGameScreen @play-again="performReset" />
267 
268    <!-- The run-packs store: opened from the header/account or automatically when a
269         commit is refused for being out of runs. Mounted once, here. -->
270    <RunPacksModal />
271 
272    <!-- The guided first run (issue #60): a skippable, non-blocking coach-mark that
273         teaches a brand-new player the core loop in context, then gets out of the
274         way. Client-only — it reads localStorage and positions against live rects. -->
275    <ClientOnly><CoachMark /></ClientOnly>
276 
277    <!-- Developer mode (issue #105): a floating panel to traverse stages and force
278         outcomes through the real mechanics. Self-gates on import.meta.dev /
279         public.devMode — tree-shaken out of a normal production build. -->
280    <ClientOnly><DevPanel /></ClientOnly>
281  </div>
282</template>
283 
284<script setup lang="ts">
285/**
286 * Main game page — Everwhen, "The Spine Console" layout.
287 *
288 * A full-bleed board grouped into three super-zones — board-state (roll + shift +
289 * Spine), story (chronicle · thread), and your-turn (the compose dock) — separated
290 * by space, not chrome. State lives in the store; this only arranges it.
291 */
292import { ref, computed, watch, nextTick, onMounted, onUnmounted } from 'vue'
293import { useGameStore, formatContactYear } from '~/stores/game'
294import { useCoachingStore } from '~/stores/coaching'
295import { useAudioStore } from '~/stores/audio'
296import { useGameSoundscape } from '~/composables/useGameSoundscape'
297import { SWING_BANDS } from '~/utils/swing-bands'
298import { DiceOutcome, CRIT_FAIL_MAX, FAILURE_MAX, NEUTRAL_MAX, CRIT_SUCCESS_MIN } from '~/utils/dice'
299import { parseKnownSinceYear, wagerTier } from '~/utils/known-since'
300import { CHAIN_HINT } from '~/utils/causal-chain'
301import { ANACHRONISM_LABEL } from '~/server/utils/anachronism'
302import { readAuthReturnParams, hasAuthReturn, finalizeAuthReturn } from '~/utils/auth-return'
303 
304const gameStore = useGameStore()
305 
306// The soundscape (issue #92): this one call wires every game transition to its cue
307// (decoupled — the store stays sound-agnostic) and returns the engine handle for the
308// few UI-driven cues. The audio store holds the persisted mute/volume the header
309// control toggles. Both survive resetGame() untouched.
310const audio = useAudioStore()
311const soundscape = useGameSoundscape()
312 
313// The disclosed band table — rendered from the same constants the Timeline
314// Engine is instructed with, so the legend can't lie.
315const fmtSwing = (b: { min: number; max: number }) =>
316    `${b.min >= 0 ? '+' : ''}${b.min}…${b.max >= 0 ? '+' : ''}${b.max}%`
317const rollLegend = [
318    { range: `${CRIT_SUCCESS_MIN}–20`, label: 'Critical Success', swing: fmtSwing(SWING_BANDS[DiceOutcome.CRITICAL_SUCCESS]), cls: 'ew-ok' },
319    { range: `${NEUTRAL_MAX + 1}–${CRIT_SUCCESS_MIN - 1}`, label: 'Success', swing: fmtSwing(SWING_BANDS[DiceOutcome.SUCCESS]), cls: 'ew-ok' },
320    { range: `${FAILURE_MAX + 1}–${NEUTRAL_MAX}`, label: 'Neutral', swing: fmtSwing(SWING_BANDS[DiceOutcome.NEUTRAL]), cls: 'ew-muted' },
321    { range: `${CRIT_FAIL_MAX + 1}–${FAILURE_MAX}`, label: 'Failure', swing: fmtSwing(SWING_BANDS[DiceOutcome.FAILURE]), cls: 'ew-warn' },
322    { range: `1–${CRIT_FAIL_MAX}`, label: 'Critical Failure', swing: fmtSwing(SWING_BANDS[DiceOutcome.CRITICAL_FAILURE]), cls: 'ew-bad' }
323]
324 
325// The pre-send wager chip: Archive known-since × chosen contact year → ⚡ tier.
326const wagerRead = computed(() => {
327    const lookup = gameStore.archiveResult
328    const when = gameStore.contactWhen
329    if (!lookup?.knownSince || when == null) return null
330    const knownYear = parseKnownSinceYear(lookup.knownSince)
331    if (knownYear == null) return null
332    const tier = wagerTier(knownYear, when)
333    const pips = tier === 'impossible' ? '⚡⚡⚡' : tier === 'far-ahead' ? '⚡⚡' : tier === 'ahead' ? '⚡' : '✓'
334    // Hedged copy: this is a year-gap compass, not the engine's verdict.
335    const text = tier === 'in-period'
336        ? `${lookup.topic}: already known by ${formatContactYear(when)} — steady ground`
337        : `${lookup.topic}: reads ≈ ${ANACHRONISM_LABEL[tier].toLowerCase()} for ${formatContactYear(when)} — a wider swing, losses harder than gains`
338    return { tier, pips, text }
339})
340 
341// The pre-send chain chip: how far the chosen moment lands from the nearest
342// foothold (the objective's era or a prior change). Surfaced for every tier —
343// at-hinge reads as a win (full force), diffuse as a caution — so good chaining
344// gets the same confirmation a caution does, not silence. A null status now
345// means only "no chain to read" (anchorless objective / no footholds yet).
346const chainRead = computed(() => {
347    const s = gameStore.causalChainRead
348    if (!s) return null
349    return { tier: s.tier, text: CHAIN_HINT[s.tier] }
350})
351 
352// The last stand, armed by the player on their final dispatch. Arming it is the
353// wager committed — a tension swell marks the doubling.
354const stakeArmed = ref(false)
355watch(stakeArmed, (armed) => { if (armed) soundscape.play('stake') })
356 
357const figure = ref('')
358watch(figure, (name) => gameStore.setActiveFigure((name || '').trim()))
359 
360const messageInputRef = ref()
361const messageInputValid = computed(() => messageInputRef.value?.isValid ?? false)
362const canSend = computed(() => messageInputValid.value && figure.value.trim().length > 0 && gameStore.canContact)
363 
364// The very first turn: the read-model is empty, so quiet it and lead the eye to the dock.
365const isFirstTurn = computed(() => gameStore.timelineEvents.length === 0)
366 
367// Phone tab bar: the three zones as switchable panels (md+ shows them all at once, so
368// this state is inert there). The run opens on the move; the instant a turn is rolling
369// we flip to the Board so the die + shift + spine land as the payoff beat, then the
370// player taps back to Compose. A nudge dot marks Compose when it's their move.
371type MobileTab = 'board' | 'story' | 'compose'
372const mobileTabs = [
373    { id: 'board', glyph: '🎲', label: 'Board' },
374    { id: 'story', glyph: '📖', label: 'Story' },
375    { id: 'compose', glyph: '✎', label: 'Compose' }
376] as const
377const mobileTab = ref<MobileTab>('compose')
378const yourMove = computed(() => gameStore.canSendMessage && !gameStore.isLoading && mobileTab.value !== 'compose')
379watch(() => gameStore.isLoading, (loading) => { if (loading) mobileTab.value = 'board' })
380watch(() => gameStore.currentObjective, (obj) => { if (obj) mobileTab.value = 'compose' })
381 
382// Thread rail (below md): open by default (the figure's replies are the game's most
383// charming content — collapsed-by-default made them too easy to miss). A fold is the
384// player's explicit choice now, so nothing force-reopens it. From md up it's forced
385// open as a full panel beside the Chronicle (isMd), so its toggle is inert there —
386// guard the handler so the native toggle event can't flip our own state.
387const threadOpen = ref(true)
388function onThreadToggle(e: Event) { if (!isMd.value) threadOpen.value = (e.target as HTMLDetailsElement).open }
389 
390// When a run begins, drop the cursor straight into the "who" field.
391function focusFigure() {
392    nextTick(() => (document.querySelector('[data-testid="figure-input"]') as HTMLElement | null)?.focus())
393}
394watch(() => gameStore.currentObjective, (obj) => { if (obj) focusFigure() })
395 
396// Lock body scroll while the end-screen takeover is up (so the board can't peek).
397watch(() => gameStore.gameStatus, (s) => {
398    if (typeof document === 'undefined') return
399    document.body.style.overflow = (s === 'victory' || s === 'defeat') ? 'hidden' : ''
400})
401 
402// md+ breakpoint — from md up every zone is shown together, so the Chronicle is
403// forced open as the prose payoff rather than a tap-to-open rail (below md it stays
404// a collapsible rail in the Story tab); tracked reactively.
405const isMd = ref(false)
406let mdMql: MediaQueryList | null = null
407function syncMd() { isMd.value = mdMql?.matches ?? false }
408onMounted(() => {
409    mdMql = window.matchMedia('(min-width: 768px)')
410    syncMd()
411    mdMql.addEventListener('change', syncMd)
412})
413onUnmounted(() => { mdMql?.removeEventListener('change', syncMd) })
414 
415// Load the device's run balance for the header gauge, and handle the return from
416// Stripe Checkout: ?purchase=success|cancel drives the banner + a balance refresh,
417// then the query is stripped so a later refresh can't re-fire it.
418const route = useRoute()
419const router = useRouter()
420const supabase = useSupabaseClient()
421onMounted(async () => {
422    // A magic-link / email-change sign-in lands back here carrying an artifact to
423    // consume (?code= the Supabase client auto-exchanges; ?token_hash= we verify;
424    // ?error= means the link failed). On success the anonymous account upgrades in
425    // place — same id, runs carried over — so re-read the balance (the account view
426    // is server-derived) and strip the query so a reload can't re-fire a spent link.
427    const authReturn = readAuthReturnParams(route.query)
428    if (hasAuthReturn(authReturn)) {
429        const result = await finalizeAuthReturn(authReturn, {
430            settle: async () => {
431                const { data } = await supabase.auth.getSession()
432                return Boolean(data.session && !data.session.user.is_anonymous)
433            },
434            verifyOtp: (params) => supabase.auth.verifyOtp(params)
435        })
436        if (result.status === 'error') {
437            console.warn('[auth] sign-in link could not be finalized:', authReturn.error, authReturn.errorDescription)
438        }
439        await gameStore.loadBalance()
440        router.replace({ query: {} })
441    } else {
442        const purchase = route.query.purchase
443        if (purchase === 'success' || purchase === 'cancel') {
444            await gameStore.notePurchaseReturn(purchase)
445            router.replace({ query: {} })
446            // The webhook credits asynchronously and can lag Stripe's redirect, so the
447            // first read may predate the credit. Poll briefly so the header gauge
448            // converges to the credited total without a manual reload — stopping as soon
449            // as it changes, or after a few tries (the credit is guaranteed by the
450            // webhook + its retries regardless). The banner asserts no specific count.
451            if (purchase === 'success') {
452                const before = gameStore.runsRemaining
453                for (let i = 0; i < 4; i++) {
454                    await new Promise((r) => setTimeout(r, 1500))
455                    await gameStore.loadBalance()
456                    if (gameStore.runsRemaining !== before) break
457                }
458            }
459        } else {
460            await gameStore.loadBalance()
461        }
462    }
463 
464    // Resume an in-progress run (#152) — once the balance load + any magic-link return
465    // have settled (a magic-link sign-in carries an anonymous run over to the account),
466    // and only when nothing is already on the board. Auto-resume: the player drops back
467    // onto the in-progress board, with the header ↻ "new timeline" as the abandon path.
468    if (!gameStore.currentObjective) await gameStore.resumeDraft()
469})
⋯ 156 lines hidden (lines 470–625)470 
471// Dark-mode toggle via @nuxtjs/color-mode (bundled with @nuxt/ui): persists across
472// reloads, respects the OS preference, and ships a no-flash inline script — replacing
473// the old manual classList toggle that did none of those.
474const colorMode = useColorMode()
475const isDark = computed(() => colorMode.value === 'dark')
476function toggleDark() {
477    colorMode.preference = colorMode.value === 'dark' ? 'light' : 'dark'
478}
479 
480// Sound on/off (issue #92), persisted like the dark toggle. The click is itself a
481// user gesture, so unmuting unlocks the audio context here and chirps a tick to
482// confirm sound is live; muting falls silent (the cue would be inaudible anyway).
483function toggleMute() {
484    audio.toggleMute()
485    if (!audio.muted) {
486        soundscape.unlock()
487        soundscape.play('uiTick')
488    }
489}
490 
491const handleSendMessage = async () => {
492    if (!messageInputRef.value) return
493    const messageText = messageInputRef.value.message?.trim()
494    const target = figure.value.trim()
495    if (!messageText || !messageInputRef.value.isValid || !target) return
496 
497    // Clear the composer only when the turn actually resolved — a blocked or
498    // failed send keeps the player's crafted 160 characters for another try.
499    const resolved = await gameStore.sendMessage(messageText, target, { stake: stakeArmed.value })
500    if (resolved) {
501        stakeArmed.value = false
502        if (messageInputRef.value) messageInputRef.value.message = ''
503    }
504}
505 
506// The header reset arms a confirm when a run is in progress (and auto-disarms);
507// performReset is the single unified reset path — the end screen's Play Again
508// lands here too, so every reset clears the figure input and composer alike.
509const resetArmed = ref(false)
510let resetArmTimer: ReturnType<typeof setTimeout> | null = null
511 
512const handleResetGame = () => {
513    // One tap only when there is truly nothing to lose: no resolved turns AND no
514    // words or contact in progress (a typed first dispatch is work too).
515    const composerDirty = !!messageInputRef.value?.message?.trim() || !!figure.value.trim()
516    if (gameStore.timelineEvents.length === 0 && !composerDirty) {
517        performReset()
518        return
519    }
520    resetArmed.value = true
521    if (resetArmTimer) clearTimeout(resetArmTimer)
522    resetArmTimer = setTimeout(() => { resetArmed.value = false }, 3500)
523}
524 
525function disarmReset() {
526    resetArmed.value = false
527    if (resetArmTimer) clearTimeout(resetArmTimer)
528}
529 
530function performReset() {
531    disarmReset()
532    stakeArmed.value = false
533    gameStore.resetGame()
534    figure.value = ''
535    if (messageInputRef.value) messageInputRef.value.message = ''
536    focusFigure()
537}
538 
539onUnmounted(() => { if (resetArmTimer) clearTimeout(resetArmTimer) })
540 
541// ── Guided first run (issue #60) ──────────────────────────────────────────
542// A teaching layer for a brand-new player's first game. This page is the single
543// orchestration site: it reads the game and drives the coaching store one way,
544// so the store stays game-agnostic and survives resetGame() untouched. The board
545// never blocks — the coach-mark only points; the player plays through it.
546const coaching = useCoachingStore()
547const autoStartCtx = () => ({
548    hasObjective: !!gameStore.currentObjective,
549    isPlaying: gameStore.gameStatus === 'playing',
550    isFirstTurn: gameStore.timelineEvents.length === 0
551})
552onMounted(() => {
553    audio.hydrate()
554    coaching.hydrate()
555    coaching.maybeAutoStart(autoStartCtx())
556})
557// A run beginning cues a brand-new player's first beat; tearing the board down
558// (New timeline) ends a tour left running rather than stranding it over an empty board.
559watch(() => gameStore.currentObjective, (obj) => {
560    if (obj) coaching.maybeAutoStart(autoStartCtx())
561    else coaching.stop()
562})
563// Replays can begin mid-run, so the reveal + overstay beats key off turns resolved
564// SINCE the tour started, not absolute counts (a fresh first run baselines at 0).
565const tourBaseTurns = ref(0)
566watch(() => coaching.isRunning, (running) => {
567    if (running) tourBaseTurns.value = gameStore.timelineEvents.length
568})
569// Auto-advance on the real action. Picking who & when clears the first beat; the
570// reading beats (the dispatch, the wager) advance on the card's own Next; the
571// send beat waits for an actual resolved turn below.
572watch(
573    () => !!gameStore.figureGrounding?.resolved && gameStore.contactWhen != null,
574    (ready) => { if (ready) coaching.advanceFrom('who-when') }
575)
576// The first turn resolved since the tour began is the payoff beat; advanceTo is
577// monotonic, so it also fast-forwards a player who sent before pressing Next on the
578// readers. One turn further and the loop has plainly landed, so a tour still running
579// has overstayed — it bows out on its own (the engaged reader pressed Done already).
580watch(() => gameStore.timelineEvents.length, (n) => {
581    if (!coaching.isRunning) return
582    if (n >= tourBaseTurns.value + 2) coaching.complete()
583    else if (n > tourBaseTurns.value) coaching.advanceTo('roll-swing')
584})
585// On each new beat, bring its host control into view on phones (md+ shows every
586// zone at once, so this is inert there). Only on a real step change — never yanks
587// a player who tapped elsewhere mid-beat back.
588watch(() => coaching.activeStep?.hostTab, (tab) => {
589    if (tab && !isMd.value) mobileTab.value = tab
590})
591 
592useHead({
593    title: 'Everwhen — Rewrite History',
594    meta: [
595        { name: 'description', content: 'Send 160-character messages to anyone in history. A D20 and an AI decide how the timeline bends.' }
596    ]
597})
598</script>
599 
600<style scoped>
601/* Phone tab bar — letterpress, not chrome: a hairline-topped strip, the active tab
602   marked by the one accent and a terracotta top rule. ≥44px tall for the thumb. */
603.mobile-tab {
604    display: flex;
605    flex-direction: column;
606    align-items: center;
607    justify-content: center;
608    gap: 2px;
609    padding: 8px 0 9px;
610    color: var(--ew-faint);
611    border-top: 2px solid transparent;
612    transition: color var(--ew-dur-1) var(--ew-ease), border-color var(--ew-dur-1) var(--ew-ease);
613}
614.mobile-tab .ew-label { color: inherit; }
615.mobile-tab.is-active {
616    color: var(--ew-accent);
617    border-top-color: var(--ew-accent);
618}
619 
620/* The armed last stand — a quiet accent wash, not a flashing alarm. */
621.stake-armed {
622    border-color: var(--ew-accent);
623    background: color-mix(in srgb, var(--ew-accent) 7%, transparent);
624}
625</style>

The read endpoint adds a belt to the autosave's suspenders. Clearing a draft on terminal save is best-effort and fire-and-forget; should it ever miss, a finished run's draft could linger. So the GET refuses to hand back a draft whose run already saved a terminal snapshot — the snapshot store is the source of truth for "done".

Read the subject's latest draft, then refuse it if the run already finished.

server/api/run-draft.get.ts · 24 lines

server/api/run-draft.get.ts24 lines · TypeScript

1/**
* GET /api/run-draft — the current subject's latest in-progress draft, for resume
* on load (#152). Server-side only and read-safe: the subject (Supabase user id,
* else the device id) is derived from the request, never trusted from the client, so
* a player only ever resumes their OWN run. Mirrors runs/index.get's subject-scoped read.
*
* Returns `{ draft: null }` when there's nothing to resume.
*/
9import { currentSubject } from '~/server/utils/auth'
10import { runDraftStore } from '~/server/utils/run-draft-store'
11import { runSnapshotStore } from '~/server/utils/run-snapshot-store'
12 
13export default defineEventHandler(async (event) => {
  const subject = await currentSubject(event)
  const draft = await runDraftStore().getLatestDraft(subject)
  if (!draft) return { draft: null }
  // Safety net: a run that already saved a terminal snapshot is FINISHED — never
  // resume it, even if the draft's clear-on-terminal didn't land (it's a best-effort
  // fire-and-forget). The snapshot store is the source of truth for "done", so one
  // owner-scoped lookup makes resume robust against a missed clear.
  const finished = await runSnapshotStore().getRun(subject, draft.runId)
  if (finished) return { draft: null }
  return { draft }
24})

The table and the write/clear endpoints

The migration adds run_drafts: one row per run, run_id PK referencing runs(id), upserted per turn, RLS on with no policy (service-key only) like every other table. An index on (user_id, updated_at desc) serves the "latest draft" read.

supabase/migrations/0008_run_drafts.sql · 22 lines

supabase/migrations/0008_run_drafts.sql22 lines · Transact-SQL

1-- run_drafts: the in-progress run autosave (#152) — the live counterpart to the
2-- immutable run_snapshots record. A snapshot is written ONCE, at victory/defeat; a
3-- draft is overwritten after every still-playing turn so a refresh or a crash can't
4-- lose a half-played run (each turn is a model call, expensive to redo). One row per
5-- run, upserted on the run-id PK; cleared on terminal save and on abandon/reset.
6-- Versioned jsonb so a later shape change can't break an in-flight draft.
7-- RLS on with no policy: service-key-only, like runs / run_snapshots.
8 
9create table if not exists public.run_drafts (
10    run_id     uuid        primary key references public.runs(id) on delete cascade,
11    user_id    text        not null,
12    version    int         not null,
13    data       jsonb       not null,
14    updated_at timestamptz not null default now()
15);
16 
17alter table public.run_drafts enable row level security;
18 
19-- Resume reads the subject's latest in-progress draft (newest updated_at first); index
20-- that access path so it doesn't sequentially scan every draft.
21create index if not exists run_drafts_user_idx
22    on public.run_drafts (user_id, updated_at desc);

The write and clear routes are thin and mirror the existing run-save / run-share conventions: POST validates with sanitizeDraft, gates the run id to a real uuid (a degraded local id has no runs row to anchor the FK), and upserts under currentSubject; DELETE is uuid-gated, owner-scoped, and idempotent.

server/api/run-draft.post.ts · 38 lines

server/api/run-draft.post.ts38 lines · TypeScript

1/**
* POST /api/run-draft — autosave an in-progress run's draft, owned by the account
* subject (#152). The client fires this after each resolved-but-still-playing turn;
* the server validates + clamps it (it's client-trusted, same posture as send-message)
* and upserts it keyed by the run id, so a refresh or a crash can resume the run.
*
* Best-effort by design: the client fires it fire-and-forget, so a failure degrades
* resume, never the turn. A degraded run (a non-uuid local id, never recorded
* server-side) has no runs row for the FK — it's accepted as a no-op.
*/
11import { sanitizeDraft } from '~/server/utils/run-draft'
12import { runDraftStore } from '~/server/utils/run-draft-store'
13import { currentSubject } from '~/server/utils/auth'
14import { isUuid } from '~/server/utils/uuid'
15 
16export default defineEventHandler(async (event) => {
  if (getMethod(event) !== 'POST') {
      throw createError({ statusCode: 405, statusMessage: 'Method Not Allowed' })
  }
  const body = await readBody(event)
  const draft = sanitizeDraft(body)
  if (!draft) {
      throw createError({ statusCode: 400, statusMessage: 'Bad Request: invalid run draft' })
  }
  // A degraded (non-uuid local) run was never recorded server-side — there is no
  // runs row to anchor the FK, so nothing to draft against.
  if (!isUuid(draft.runId)) {
      return { saved: false, degraded: true }
  }
  const subject = await currentSubject(event)
  try {
      await runDraftStore().saveDraft(subject, draft)
  } catch (error) {
      console.error('Failed to save run draft:', error)
      throw createError({ statusCode: 500, statusMessage: 'Internal Server Error' })
  }
  return { saved: true }
38})

server/api/run-draft.delete.ts · 21 lines

server/api/run-draft.delete.ts21 lines · TypeScript

1/**
2 * DELETE /api/run-draft?runId=… — clear one of the current subject's in-progress
3 * drafts (#152): fired on terminal save (the run is finished) and on abandon/reset
4 * (the player started over). Idempotent and privacy-quiet — clearing a draft that
5 * isn't there (or isn't the subject's) is a no-op that still answers ok, so it never
6 * reveals whether the run existed or who owned it. The id is uuid-shape-gated before
7 * any query so a malformed value never hits the DB.
8 */
9import { runDraftStore } from '~/server/utils/run-draft-store'
10import { currentSubject } from '~/server/utils/auth'
11import { isUuid } from '~/server/utils/uuid'
12 
13export default defineEventHandler(async (event) => {
14    const runId = String(getQuery(event).runId ?? '')
15    if (!isUuid(runId)) {
16        throw createError({ statusCode: 404, statusMessage: 'Not Found' })
17    }
18    const subject = await currentSubject(event)
19    await runDraftStore().deleteDraft(subject, runId)
20    return { ok: true }
21})

Verification

The full suite is green: 979 unit tests pass and nuxt typecheck is clean. Four new specs carry the feature — the validator's clamps and coercion, both store adapters plus their Supabase query shapes, the three store actions (autosave / clear / resume, including the replay-seed guard), and the endpoint contract.

Beyond the suite, an adversarial multi-agent review read the branch across security, resume correctness, lifecycle, and contract-consistency lenses, then verified each finding independently. It surfaced one real cross-feature bug — the replay-seed clobber in the section above — which is now fixed and pinned by a test.