Saved runs render the Spine — a code-level reading (PR #115)

What changed, and why

A saved run at /runs/:id used to show its timeline as a plain text list: headline, "era · figure", a bare signed %. The live end screen, meanwhile, renders the real Spine — a horizontal era-axis with valence dots, ⚡/⚑ badges, the roll, and the Δ (base → final) equation. So a finished run read more flatly in the archive than it did the moment it ended.

That gap was left over from #84, which moved EndGameScreen onto the shared Spine but left RunView on the old hand-rolled <ol>. #84 even anticipated the fix: a reusable read-only Spine the saved-run view could share.

The change is small and has two halves. First, the Spine learns to render from a passed list of events, not just the live store, so RunView can feed it a saved snapshot. Second, the saved snapshot is widened to carry the two fields the Spine renders that it wasn't yet storing — baseProgressChange (the Δ equation) and staked (the ⚑ badge). Live play is untouched, and older saved runs still load.

The Spine learns a second source

TimelineLedger (the Spine) sourced its events straight from the Pinia store. This adds an optional events prop and falls back to the store only when it's absent. In live play nothing is passed, so the computed resolves to exactly what it did before; the read-only run view passes a snapshot's ledger instead.

The new prop, and the one-line change to where events comes from.

components/TimelineLedger.vue · 209 lines

components/TimelineLedger.vue209 lines · Vue

⋯ 105 lines hidden (lines 1–105)1<template>
<!-- THE SPINE: history as a horizontal era-axis you travel left→right. -->
<div data-testid="timeline-ledger">
  <div class="border-b rv-line pb-1.5 mb-3">
    <div class="flex items-center justify-between gap-3">
      <span class="rv-label">The Spine</span>
      <span class="rv-mono rv-faint text-[11px] normal-case tracking-normal">
        {{ events.length }} {{ events.length === 1 ? 'change' : 'changes' }}<template v-if="anachCount"> · ⚡{{ anachCount }}</template><span v-if="events.length" class="ml-2">scroll →</span>
      </span>
    </div>
    <p class="rv-faint text-[11px] mt-0.5">{{ props.readonly ? 'the history you wrote' : "the timeline you're rewriting" }} — every change, in the order you made it<template v-if="events.length"> · <span class="rv-accent">tap any node to inspect</span></template></p>
  </div>
13 
  <!-- Empty state — but the instant a first move is resolving, it leans in rather
       than still reading "unwritten" (the board never contradicts the act). -->
  <div v-if="events.length === 0" data-testid="timeline-empty" class="text-center py-12">
    <template v-if="!props.readonly && gameStore.isLoading">
      <div class="text-4xl mb-3 opacity-50 rv-accent" aria-hidden="true">✒</div>
      <p class="rv-serif rv-fg text-lg">The timeline trembles…</p>
      <p class="rv-faint text-xs mt-1">Your message ripples into the past.</p>
    </template>
    <template v-else>
      <div class="text-4xl mb-3 opacity-40" aria-hidden="true">📜</div>
      <p class="rv-serif rv-fg text-lg">History is still unwritten.</p>
      <p class="rv-faint text-xs mt-1">Send your first message to bend the timeline.</p>
    </template>
  </div>
28 
  <!-- The axis -->
  <div v-else class="spine-scroll overflow-x-auto px-1 pb-2">
    <TransitionGroup name="timeline" tag="ol" class="flex items-start min-w-full" aria-label="Timeline of changes">
      <li v-for="event in events" :key="event.id" data-testid="timeline-event"
        class="spine-node rv-press" :class="{ 'is-selected': event.id === selectedId }"
        role="button" tabindex="0" @click="select(event.id)" @keydown.enter="select(event.id)" @keydown.space.prevent="select(event.id)">
        <span class="sr-only">{{ event.headline }} — {{ event.detail }} ({{ signed(event.progressChange) }})</span>
        <span class="block text-center rv-mono text-[11px] rv-faint">{{ event.era || '—' }}</span>
        <span class="dot-wrap" aria-hidden="true">
          <span class="connector" />
          <span class="rv-dot" :class="event.id === selectedId ? 'rv-dot--accent' : dotClass(event.valence)" />
        </span>
        <span class="block text-center rv-mono text-xs rv-fg truncate px-1">{{ event.figureName }}</span>
        <span class="block text-center rv-mono text-[11px] mt-0.5 tabular-nums">
          <span class="rv-faint">🎲</span>{{ event.diceRoll }}
          <span class="delta-cell" :class="deltaClass(event.progressChange)">{{ signed(event.progressChange) }}</span><span
            v-if="isAnachronistic(event.anachronism)" class="rv-warn ml-0.5" :aria-label="anachronismLabel(event.anachronism)" :title="anachronismHint(event.anachronism)">{{ anachPips(event.anachronism) }}</span><span
            v-if="event.staked" class="rv-warn ml-0.5" aria-label="Staked — the last stand" :title="STAKE_HINT">⚑</span>
        </span>
      </li>
49 
      <!-- the live present — only while the run is live; the verdict has no next move -->
      <li v-if="!props.readonly" key="now" class="spine-now" aria-hidden="true">
        <span class="block text-center rv-mono text-[11px] rv-accent font-semibold">▷ now</span>
        <span class="dot-wrap"><span class="connector connector--half" /></span>
        <span class="block text-center rv-faint text-[11px]">your move</span>
      </li>
    </TransitionGroup>
  </div>
58 
  <!-- Node-detail strip: the selected change in full (defaults to the newest).
       The consequence headline leads — the second of the board's two focal peaks. -->
  <div v-if="selected" data-testid="node-detail" class="border-t rv-line pt-2.5 mt-2">
    <p class="rv-serif rv-fg text-lg lg:text-xl font-semibold leading-snug">{{ selected.headline }}</p>
    <p class="rv-muted text-xs lg:text-sm mt-1 leading-relaxed max-w-2xl">{{ selected.detail }}</p>
    <div class="flex items-center gap-x-2 gap-y-1 flex-wrap text-[11px] rv-mono mt-1.5 tabular-nums">
      <span class="inline-flex items-center gap-1.5">
        <span class="rv-dot" :class="dotClass(selected.valence)" aria-hidden="true" />
        <span class="rv-faint">{{ selected.era || '—' }} · {{ selected.figureName }}</span>
      </span>
      <span class="rv-hair-c">·</span>
      <span class="rv-muted">🎲 {{ selected.diceRoll }} · {{ selected.diceOutcome }}</span>
      <span v-if="selected.craft && selected.craft !== 'sound'" class="rv-hair-c">·</span>
      <SymbolHint v-if="selected.craft && selected.craft !== 'sound'" :text="CRAFT_HINT[selected.craft]">
        <span data-testid="craft-badge"
          class="font-semibold" :class="selected.craft === 'masterful' || selected.craft === 'sharp' ? 'rv-ok' : 'rv-warn'">✒ {{ CRAFT_LABEL[selected.craft] }}</span>
      </SymbolHint>
      <span class="rv-hair-c">·</span>
      <span class="font-bold" :class="deltaClass(selected.progressChange)">{{ signed(selected.progressChange) }}%</span>
      <!-- The wager's arithmetic, in the open: base → amplified/staked final. -->
      <span v-if="selected.baseProgressChange !== undefined && selected.baseProgressChange !== selected.progressChange"
        data-testid="swing-equation" class="rv-faint">({{ signed(selected.baseProgressChange) }} → {{ signed(selected.progressChange) }})</span>
      <SymbolHint v-if="isAnachronistic(selected.anachronism)" :text="anachronismHint(selected.anachronism)">
        <span data-testid="anachronism-badge" class="rv-warn font-semibold ml-1">⚡ {{ anachronismLabel(selected.anachronism) }}</span>
      </SymbolHint>
      <SymbolHint v-if="selected.staked" :text="STAKE_HINT">
        <span data-testid="staked-badge" class="rv-warn font-semibold ml-1">⚑ staked</span>
      </SymbolHint>
    </div>
  </div>
</div>
90</template>
91 
92<script setup lang="ts">
93/**
* TimelineLedger — the Spine. Each resolved turn is a node on a horizontal era-axis
* (valence dot + mono year/figure/roll/Δ + ⚡), newest on the right with a ▷now marker;
* clicking a node snaps its full payload into the node-detail strip, which defaults to
* the newest change so the latest turn is always visible. Pure glyphs on the axis; the
* only prose lives in the strip. (Re-skin only — the store data is unchanged.)
*/
100import { computed, ref, watch } from 'vue'
101import { useGameStore } from '~/stores/game'
102import type { Valence } from '~/stores/game'
103import { ANACHRONISM_HINT, ANACHRONISM_LABEL, type Anachronism } from '~/server/utils/anachronism'
104import { CRAFT_HINT, CRAFT_LABEL } from '~/utils/craft'
105import { STAKE_HINT } from '~/utils/swing-bands'
106import type { RunLedgerEntry } from '~/utils/run-snapshot'
107 
108const gameStore = useGameStore()
109const props = defineProps<{
  /** Verdict / past-run view (the end screen): drop the live "▷ now" present
   *  marker and the "the timeline trembles…" loading empty state, and frame the
   *  lead in past tense. In-game usage passes nothing, so its behavior is
   *  unchanged — the Spine the player scrolled and tapped renders the same. */
  readonly?: boolean
  /** Events to render. Omitted in live play, where the Spine reads the live store.
   *  The saved-run view (RunView) passes a snapshot's ledger so a past run renders
   *  the same Spine from the saved record, not the (empty/irrelevant) live store.
   *  `RunLedgerEntry` is the view-facing projection of the store's `TimelineEvent`,
   *  so the live events satisfy it too — the fallback stays byte-identical. */
  events?: RunLedgerEntry[]
121}>()
122const events = computed<RunLedgerEntry[]>(() => props.events ?? gameStore.timelineEvents)
⋯ 87 lines hidden (lines 123–209)123 
124const selectedId = ref<string | null>(null)
125// Default the detail strip to the newest change, and snap to it whenever one lands.
126watch(() => events.value.length, () => {
  const last = events.value[events.value.length - 1]
  if (last) selectedId.value = last.id
129}, { immediate: true })
130 
131const selected = computed(() =>
  events.value.find(e => e.id === selectedId.value) ?? events.value[events.value.length - 1] ?? null
133)
134const anachCount = computed(() => events.value.filter(e => isAnachronistic(e.anachronism)).length)
135 
136function select(id: string) { selectedId.value = id }
137function signed(n: number) { return `${n > 0 ? '+' : ''}${n}` }
138function isAnachronistic(a?: Anachronism) { return !!a && a !== 'in-period' }
139function anachronismLabel(a?: Anachronism) { return a ? ANACHRONISM_LABEL[a] : '' }
140function anachronismHint(a?: Anachronism) { return a ? ANACHRONISM_HINT[a] : '' }
141/** A quantified, glanceable anachronism tier on the spine node: 1–3 amber pips. */
142function anachPips(a?: Anachronism) {
  return a === 'impossible' ? '⚡⚡⚡' : a === 'far-ahead' ? '⚡⚡' : a === 'ahead' ? '⚡' : ''
144}
145 
146function dotClass(v: Valence) {
  return v === 'positive' ? 'rv-dot--ok' : v === 'negative' ? 'rv-dot--bad' : 'rv-dot--mut'
148}
149function deltaClass(change: number) {
  if (change > 0) return 'rv-ok'
  if (change < 0) return 'rv-bad'
  return 'rv-muted'
153}
154</script>
155 
156<style scoped>
spine-node,
spine-now {
  flex: 0 0 auto;
  min-width: 92px;
  padding: 2px 4px;
  cursor: pointer;
  border: none;
  background: transparent;
  scroll-snap-align: center;
166}
spine-scroll { scroll-snap-type: x proximity; -webkit-overflow-scrolling: touch; }
168/* Reserve a stable sign slot so a column of +/− deltas stacks rule-straight. */
delta-cell { display: inline-block; min-width: 1.9em; text-align: left; }
spine-now { cursor: default; }
spine-node:focus-visible { outline: 2px solid var(--rv-accent); outline-offset: 2px; border-radius: 3px; }
172 
173/* The axis line is drawn by a full-width connector behind each node's dot. */
dot-wrap {
  position: relative;
  display: flex;
  justify-content: center;
  align-items: center;
  height: 16px;
  margin: 3px 0;
181}
connector {
  position: absolute;
  top: 50%;
  left: 0;
  right: 0;
  height: 1px;
  background: var(--rv-line);
  transform: translateY(-50%);
190}
connector--half { right: 50%; }
dot-wrap > .rv-dot { position: relative; z-index: 1; }
spine-node.is-selected .dot-wrap > .rv-dot {
  width: 12px;
  height: 12px;
  box-shadow: 0 0 0 3px var(--rv-bg), 0 0 0 4px var(--rv-accent);
197}
spine-node:hover .dot-wrap > .rv-dot { transform: translateY(-1px); }
199 
200/* Preserved entry/move animation (now driving the right-edge node arrival). */
timeline-enter-active { transition: opacity var(--rv-dur-3) var(--rv-ease), transform var(--rv-dur-3) var(--rv-ease); }
timeline-enter-from { opacity: 0; transform: translateY(-10px); }
timeline-move { transition: transform var(--rv-dur-3) var(--rv-ease); }
204 
205@media (prefers-reduced-motion: reduce) {
  .timeline-enter-active, .timeline-move { transition: none; }
  .spine-node:hover .dot-wrap > .rv-dot { transform: none; }
208}
209</style>

RunView drops the flat list for the Spine

With the prop in place, the retrospective view swaps its <ol> for the shared component, read-only, fed the snapshot's ledger. It mirrors EndGameScreen exactly: no separate section label (the Spine's own header carries it), the same mt-6 wrapper, the same readonly. The only difference from the end screen is the source — a saved snapshot instead of the live store.

The whole timeline section is now one line of Spine.

components/RunView.vue · 102 lines

components/RunView.vue102 lines · Vue

⋯ 68 lines hidden (lines 1–68)1<template>
<!-- A finished run, read-only — the same verdict / epilogue / ledger the end screen
     shows, but rendered from a saved snapshot rather than the live store, so a past
     run reads identically to the moment it ended. Verdict strings, glyphs, and the
     rv-* tokens are deliberately the same as EndGameScreen's. -->
<div data-testid="run-view" class="run-view" :class="isVictory ? 'run--win' : 'run--loss'">
  <!-- Verdict masthead -->
  <div class="text-center border-b rv-line pb-6">
    <div class="verdict-seal" :class="isVictory ? 'is-win' : 'is-loss'" aria-hidden="true">{{ isVictory ? '✦' : '⊘' }}</div>
    <h2 v-if="isVictory" data-testid="run-verdict" class="rv-serif text-3xl sm:text-4xl font-bold rv-fg mt-3">History Rewritten</h2>
    <h2 v-else data-testid="run-verdict" class="rv-serif text-3xl sm:text-4xl font-bold rv-muted mt-3">The Timeline Held</h2>
    <p class="text-sm mt-2.5 flex items-center justify-center gap-2 flex-wrap">
      <span class="rv-muted inline-flex items-center gap-1.5">
        <span aria-hidden="true">{{ snapshot.objective.icon }}</span>
        <strong data-testid="run-objective-title" class="font-semibold">{{ snapshot.objective.title || 'Historical Mission' }}</strong>
      </span>
      <span class="rv-hair-c" aria-hidden="true">·</span>
      <span class="rv-mono font-bold" :class="isVictory ? 'rv-ok' : 'rv-bad'">
        <span data-testid="run-progress">{{ snapshot.objectiveProgress }}%</span> rewritten
      </span>
    </p>
22 
    <div v-if="snapshot.efficiency" data-testid="run-efficiency" class="mt-3 rv-mono text-sm">
      <span class="rv-ok font-semibold">{{ victoryPhrase }}</span>
      <span class="rv-muted"> · {{ snapshot.efficiency.messagesUsed }}/{{ snapshot.totalMessages }} used<span v-if="snapshot.efficiency.messagesSaved > 0"> · {{ snapshot.efficiency.messagesSaved }} saved</span></span>
      <span v-if="snapshot.efficiency.isEarlyVictory" class="rv-ok"> · 🌟 to spare</span>
    </div>
  </div>
29 
  <!-- The Chronicle's final telling — the epilogue -->
  <div v-if="snapshot.chronicle" data-testid="run-chronicle" class="mt-6">
    <span class="rv-label rv-label--rule"><span aria-hidden="true">📖</span> The Chronicle</span>
    <article class="max-w-[62ch]">
      <h4 data-testid="run-chronicle-title" class="rv-serif text-xl font-semibold rv-fg mb-2.5 leading-tight">{{ snapshot.chronicle.title }}</h4>
      <p v-for="(para, i) in snapshot.chronicle.paragraphs" :key="i" class="rv-serif rv-muted text-[15px] leading-relaxed mb-2.5 last:mb-0">{{ para }}</p>
    </article>
  </div>
38 
  <!-- The words you sent — the keepsake -->
  <div v-if="snapshot.dispatches.length" data-testid="run-dispatches" class="mt-7">
    <span class="rv-label rv-label--rule">The words you sent</span>
    <ul class="space-y-3.5">
      <li v-for="(d, i) in snapshot.dispatches" :key="i">
        <p class="rv-label">to {{ d.figure }}<span v-if="d.era"> · {{ d.era }}</span></p>
        <blockquote class="rv-serif rv-fg text-base leading-relaxed border-l-2 rv-line pl-3 mt-1">"{{ d.text }}"</blockquote>
      </li>
    </ul>
  </div>
49 
  <!-- Stats -->
  <div data-testid="run-summary" class="mt-7">
    <span class="rv-label rv-label--rule">How it played out</span>
    <div class="flex flex-wrap gap-10">
      <div data-testid="run-message-efficiency">
        <div class="rv-mono text-3xl font-extrabold rv-fg leading-none">{{ snapshot.messagesUsed }}</div>
        <div class="rv-label mt-1">{{ snapshot.messagesUsed === 1 ? 'message' : 'messages' }} sent</div>
      </div>
      <div v-if="snapshot.bestRoll" data-testid="run-best-roll">
        <div class="rv-mono text-3xl font-extrabold rv-ok leading-none">{{ snapshot.bestRoll.diceRoll }}</div>
        <div class="rv-label mt-1">{{ snapshot.messagesUsed >= 2 ? 'best roll' : 'the roll that did it' }} · {{ snapshot.bestRoll.diceOutcome }}</div>
      </div>
      <div v-if="snapshot.worstRoll && snapshot.messagesUsed >= 2" data-testid="run-worst-roll">
        <div class="rv-mono text-3xl font-extrabold rv-bad leading-none">{{ snapshot.worstRoll.diceRoll }}</div>
        <div class="rv-label mt-1">worst roll · {{ snapshot.worstRoll.diceOutcome }}</div>
      </div>
    </div>
  </div>
68 
  <!-- The history you wrote — the Spine itself, read-only, rendered from the saved
       snapshot rather than the live store, so a past run reads exactly as it did
       when it ended: valence dots, ⚡/⚑ badges, the roll, and the Δ equation all
       carry over, identical to EndGameScreen (which renders the same component). -->
  <div v-if="snapshot.timeline.length > 0" data-testid="run-timeline" class="mt-6">
    <TimelineLedger readonly :events="snapshot.timeline" />
  </div>
⋯ 27 lines hidden (lines 76–102)76  </div>
77</template>
78 
79<script setup lang="ts">
80/**
* RunView — a read-only render of a saved run (a RunSnapshot). It mirrors
* EndGameScreen's verdict / epilogue / ledger, reading everything from the passed
* snapshot rather than the live store, so it can replay a past run (and later, a
* shared one). The timeline renders through the shared Spine (TimelineLedger), fed
* the snapshot's ledger via :events — the same component the end screen uses, so the
* two read identically. RunView itself stays store-free: no AI, no controls.
*/
88import { computed } from 'vue'
89import type { RunSnapshot } from '~/utils/run-snapshot'
90 
91const props = defineProps<{ snapshot: RunSnapshot }>()
92 
93const isVictory = computed(() => props.snapshot.status === 'victory')
94 
95// The verdict never deflates: a full-message win reads "Hard-won," not "Standard"
96// (matches EndGameScreen's phrasing exactly).
97const victoryPhrase = computed(() => {
  const rating = props.snapshot.efficiency?.efficiencyRating
  if (!rating) return 'Victory'
  return rating === 'Standard' ? 'Hard-won victory' : `${rating} victory`
101})
102</script>

The old block (a <v-for> over <li> rows, plus a local deltaClass helper) is gone, and so is the helper — the Spine owns all that rendering now.

The two fields the Spine renders, that the snapshot lacked

The Spine reads two fields off each event that the saved RunLedgerEntry didn't carry yet. The Δ equation only shows when the pre-amplifier swing differs from the final one, and the ⚑ badge only when the turn was the staked last stand:

baseProgressChange drives the swing equation; staked the ⚑ badge.

components/TimelineLedger.vue · 209 lines

components/TimelineLedger.vue209 lines · Vue

⋯ 77 lines hidden (lines 1–77)1<template>
<!-- THE SPINE: history as a horizontal era-axis you travel left→right. -->
<div data-testid="timeline-ledger">
  <div class="border-b rv-line pb-1.5 mb-3">
    <div class="flex items-center justify-between gap-3">
      <span class="rv-label">The Spine</span>
      <span class="rv-mono rv-faint text-[11px] normal-case tracking-normal">
        {{ events.length }} {{ events.length === 1 ? 'change' : 'changes' }}<template v-if="anachCount"> · ⚡{{ anachCount }}</template><span v-if="events.length" class="ml-2">scroll →</span>
      </span>
    </div>
    <p class="rv-faint text-[11px] mt-0.5">{{ props.readonly ? 'the history you wrote' : "the timeline you're rewriting" }} — every change, in the order you made it<template v-if="events.length"> · <span class="rv-accent">tap any node to inspect</span></template></p>
  </div>
13 
  <!-- Empty state — but the instant a first move is resolving, it leans in rather
       than still reading "unwritten" (the board never contradicts the act). -->
  <div v-if="events.length === 0" data-testid="timeline-empty" class="text-center py-12">
    <template v-if="!props.readonly && gameStore.isLoading">
      <div class="text-4xl mb-3 opacity-50 rv-accent" aria-hidden="true">✒</div>
      <p class="rv-serif rv-fg text-lg">The timeline trembles…</p>
      <p class="rv-faint text-xs mt-1">Your message ripples into the past.</p>
    </template>
    <template v-else>
      <div class="text-4xl mb-3 opacity-40" aria-hidden="true">📜</div>
      <p class="rv-serif rv-fg text-lg">History is still unwritten.</p>
      <p class="rv-faint text-xs mt-1">Send your first message to bend the timeline.</p>
    </template>
  </div>
28 
  <!-- The axis -->
  <div v-else class="spine-scroll overflow-x-auto px-1 pb-2">
    <TransitionGroup name="timeline" tag="ol" class="flex items-start min-w-full" aria-label="Timeline of changes">
      <li v-for="event in events" :key="event.id" data-testid="timeline-event"
        class="spine-node rv-press" :class="{ 'is-selected': event.id === selectedId }"
        role="button" tabindex="0" @click="select(event.id)" @keydown.enter="select(event.id)" @keydown.space.prevent="select(event.id)">
        <span class="sr-only">{{ event.headline }} — {{ event.detail }} ({{ signed(event.progressChange) }})</span>
        <span class="block text-center rv-mono text-[11px] rv-faint">{{ event.era || '—' }}</span>
        <span class="dot-wrap" aria-hidden="true">
          <span class="connector" />
          <span class="rv-dot" :class="event.id === selectedId ? 'rv-dot--accent' : dotClass(event.valence)" />
        </span>
        <span class="block text-center rv-mono text-xs rv-fg truncate px-1">{{ event.figureName }}</span>
        <span class="block text-center rv-mono text-[11px] mt-0.5 tabular-nums">
          <span class="rv-faint">🎲</span>{{ event.diceRoll }}
          <span class="delta-cell" :class="deltaClass(event.progressChange)">{{ signed(event.progressChange) }}</span><span
            v-if="isAnachronistic(event.anachronism)" class="rv-warn ml-0.5" :aria-label="anachronismLabel(event.anachronism)" :title="anachronismHint(event.anachronism)">{{ anachPips(event.anachronism) }}</span><span
            v-if="event.staked" class="rv-warn ml-0.5" aria-label="Staked — the last stand" :title="STAKE_HINT">⚑</span>
        </span>
      </li>
49 
      <!-- the live present — only while the run is live; the verdict has no next move -->
      <li v-if="!props.readonly" key="now" class="spine-now" aria-hidden="true">
        <span class="block text-center rv-mono text-[11px] rv-accent font-semibold">▷ now</span>
        <span class="dot-wrap"><span class="connector connector--half" /></span>
        <span class="block text-center rv-faint text-[11px]">your move</span>
      </li>
    </TransitionGroup>
  </div>
58 
  <!-- Node-detail strip: the selected change in full (defaults to the newest).
       The consequence headline leads — the second of the board's two focal peaks. -->
  <div v-if="selected" data-testid="node-detail" class="border-t rv-line pt-2.5 mt-2">
    <p class="rv-serif rv-fg text-lg lg:text-xl font-semibold leading-snug">{{ selected.headline }}</p>
    <p class="rv-muted text-xs lg:text-sm mt-1 leading-relaxed max-w-2xl">{{ selected.detail }}</p>
    <div class="flex items-center gap-x-2 gap-y-1 flex-wrap text-[11px] rv-mono mt-1.5 tabular-nums">
      <span class="inline-flex items-center gap-1.5">
        <span class="rv-dot" :class="dotClass(selected.valence)" aria-hidden="true" />
        <span class="rv-faint">{{ selected.era || '—' }} · {{ selected.figureName }}</span>
      </span>
      <span class="rv-hair-c">·</span>
      <span class="rv-muted">🎲 {{ selected.diceRoll }} · {{ selected.diceOutcome }}</span>
      <span v-if="selected.craft && selected.craft !== 'sound'" class="rv-hair-c">·</span>
      <SymbolHint v-if="selected.craft && selected.craft !== 'sound'" :text="CRAFT_HINT[selected.craft]">
        <span data-testid="craft-badge"
          class="font-semibold" :class="selected.craft === 'masterful' || selected.craft === 'sharp' ? 'rv-ok' : 'rv-warn'">✒ {{ CRAFT_LABEL[selected.craft] }}</span>
      </SymbolHint>
      <span class="rv-hair-c">·</span>
      <span class="font-bold" :class="deltaClass(selected.progressChange)">{{ signed(selected.progressChange) }}%</span>
      <!-- The wager's arithmetic, in the open: base → amplified/staked final. -->
      <span v-if="selected.baseProgressChange !== undefined && selected.baseProgressChange !== selected.progressChange"
        data-testid="swing-equation" class="rv-faint">({{ signed(selected.baseProgressChange) }} → {{ signed(selected.progressChange) }})</span>
      <SymbolHint v-if="isAnachronistic(selected.anachronism)" :text="anachronismHint(selected.anachronism)">
        <span data-testid="anachronism-badge" class="rv-warn font-semibold ml-1">⚡ {{ anachronismLabel(selected.anachronism) }}</span>
      </SymbolHint>
      <SymbolHint v-if="selected.staked" :text="STAKE_HINT">
        <span data-testid="staked-badge" class="rv-warn font-semibold ml-1">⚑ staked</span>
      </SymbolHint>
⋯ 123 lines hidden (lines 87–209)87      </div>
  </div>
</div>
90</template>
91 
92<script setup lang="ts">
93/**
* TimelineLedger — the Spine. Each resolved turn is a node on a horizontal era-axis
* (valence dot + mono year/figure/roll/Δ + ⚡), newest on the right with a ▷now marker;
* clicking a node snaps its full payload into the node-detail strip, which defaults to
* the newest change so the latest turn is always visible. Pure glyphs on the axis; the
* only prose lives in the strip. (Re-skin only — the store data is unchanged.)
*/
100import { computed, ref, watch } from 'vue'
101import { useGameStore } from '~/stores/game'
102import type { Valence } from '~/stores/game'
103import { ANACHRONISM_HINT, ANACHRONISM_LABEL, type Anachronism } from '~/server/utils/anachronism'
104import { CRAFT_HINT, CRAFT_LABEL } from '~/utils/craft'
105import { STAKE_HINT } from '~/utils/swing-bands'
106import type { RunLedgerEntry } from '~/utils/run-snapshot'
107 
108const gameStore = useGameStore()
109const props = defineProps<{
  /** Verdict / past-run view (the end screen): drop the live "▷ now" present
   *  marker and the "the timeline trembles…" loading empty state, and frame the
   *  lead in past tense. In-game usage passes nothing, so its behavior is
   *  unchanged — the Spine the player scrolled and tapped renders the same. */
  readonly?: boolean
  /** Events to render. Omitted in live play, where the Spine reads the live store.
   *  The saved-run view (RunView) passes a snapshot's ledger so a past run renders
   *  the same Spine from the saved record, not the (empty/irrelevant) live store.
   *  `RunLedgerEntry` is the view-facing projection of the store's `TimelineEvent`,
   *  so the live events satisfy it too — the fallback stays byte-identical. */
  events?: RunLedgerEntry[]
121}>()
122const events = computed<RunLedgerEntry[]>(() => props.events ?? gameStore.timelineEvents)
123 
124const selectedId = ref<string | null>(null)
125// Default the detail strip to the newest change, and snap to it whenever one lands.
126watch(() => events.value.length, () => {
  const last = events.value[events.value.length - 1]
  if (last) selectedId.value = last.id
129}, { immediate: true })
130 
131const selected = computed(() =>
  events.value.find(e => e.id === selectedId.value) ?? events.value[events.value.length - 1] ?? null
133)
134const anachCount = computed(() => events.value.filter(e => isAnachronistic(e.anachronism)).length)
135 
136function select(id: string) { selectedId.value = id }
137function signed(n: number) { return `${n > 0 ? '+' : ''}${n}` }
138function isAnachronistic(a?: Anachronism) { return !!a && a !== 'in-period' }
139function anachronismLabel(a?: Anachronism) { return a ? ANACHRONISM_LABEL[a] : '' }
140function anachronismHint(a?: Anachronism) { return a ? ANACHRONISM_HINT[a] : '' }
141/** A quantified, glanceable anachronism tier on the spine node: 1–3 amber pips. */
142function anachPips(a?: Anachronism) {
  return a === 'impossible' ? '⚡⚡⚡' : a === 'far-ahead' ? '⚡⚡' : a === 'ahead' ? '⚡' : ''
144}
145 
146function dotClass(v: Valence) {
  return v === 'positive' ? 'rv-dot--ok' : v === 'negative' ? 'rv-dot--bad' : 'rv-dot--mut'
148}
149function deltaClass(change: number) {
  if (change > 0) return 'rv-ok'
  if (change < 0) return 'rv-bad'
  return 'rv-muted'
153}
154</script>
155 
156<style scoped>
spine-node,
spine-now {
  flex: 0 0 auto;
  min-width: 92px;
  padding: 2px 4px;
  cursor: pointer;
  border: none;
  background: transparent;
  scroll-snap-align: center;
166}
spine-scroll { scroll-snap-type: x proximity; -webkit-overflow-scrolling: touch; }
168/* Reserve a stable sign slot so a column of +/− deltas stacks rule-straight. */
delta-cell { display: inline-block; min-width: 1.9em; text-align: left; }
spine-now { cursor: default; }
spine-node:focus-visible { outline: 2px solid var(--rv-accent); outline-offset: 2px; border-radius: 3px; }
172 
173/* The axis line is drawn by a full-width connector behind each node's dot. */
dot-wrap {
  position: relative;
  display: flex;
  justify-content: center;
  align-items: center;
  height: 16px;
  margin: 3px 0;
181}
connector {
  position: absolute;
  top: 50%;
  left: 0;
  right: 0;
  height: 1px;
  background: var(--rv-line);
  transform: translateY(-50%);
190}
connector--half { right: 50%; }
dot-wrap > .rv-dot { position: relative; z-index: 1; }
spine-node.is-selected .dot-wrap > .rv-dot {
  width: 12px;
  height: 12px;
  box-shadow: 0 0 0 3px var(--rv-bg), 0 0 0 4px var(--rv-accent);
197}
spine-node:hover .dot-wrap > .rv-dot { transform: translateY(-1px); }
199 
200/* Preserved entry/move animation (now driving the right-edge node arrival). */
timeline-enter-active { transition: opacity var(--rv-dur-3) var(--rv-ease), transform var(--rv-dur-3) var(--rv-ease); }
timeline-enter-from { opacity: 0; transform: translateY(-10px); }
timeline-move { transition: transform var(--rv-dur-3) var(--rv-ease); }
204 
205@media (prefers-reduced-motion: reduce) {
  .timeline-enter-active, .timeline-move { transition: none; }
  .spine-node:hover .dot-wrap > .rv-dot { transform: none; }
208}
209</style>

So the contract gains both, optional. Optional is the point: a turn that didn't amplify has no equation to show, and most turns aren't staked — and an older saved run that predates these fields simply renders without them.

The two additions to the saved-run ledger contract.

utils/run-snapshot.ts · 113 lines

utils/run-snapshot.ts113 lines · TypeScript

⋯ 66 lines hidden (lines 1–66)1/**
2 * The saved-run contract — the immutable, versioned record of a finished run.
3 *
4 * A run is otherwise client-only: the objective, the dispatches, the timeline
5 * ledger, the Chronicle epilogue, and the verdict all live in the Pinia store and
6 * evaporate on reload. This is the persisted form of that end-state: the store builds
7 * it on game end, the server stores it keyed by the run id, and a read-only "your
8 * runs" view replays it. It is a SNAPSHOT, not a live record — in-progress
9 * save/resume is out of scope; a run is short (five messages) and persists at the end.
10 *
11 * Naming: "run" is overloaded. The header gauge's balance ("runs remaining") is a
12 * purchasable CREDIT (the `balances` table); this is a PLAYED run (the game record,
13 * the `run_snapshots` table). Same noun, two states — kept distinct in the schema.
14 *
15 * The shape is VERSIONED (`version`) so a later change can't silently break runs
16 * saved under an older shape: a reader can branch on `version` and migrate. It is a
17 * flat, fully JSON-native projection of the store state — the `Date` timestamps on
18 * the in-memory ledger/thread are dropped (a snapshot needs none of the duration
19 * math), so the stored blob round-trips through jsonb cleanly.
20 *
21 * This module is the SHARED contract (types + version), client-safe by design: it
22 * carries no runtime imports, only type-only ones, so the client store can import the
23 * version + types without pulling any server-only code. The server-side boundary
24 * validator lives separately in `server/utils/run-snapshot.ts`.
25 */
26import type { DiceOutcome } from '~/utils/dice'
27import type { Craft } from '~/utils/craft'
28import type { Anachronism } from '~/server/utils/anachronism'
29import type { GameObjective } from '~/server/utils/objectives'
30import type { ChronicleEntry } from '~/server/utils/openai'
31 
32/** The current saved-run shape. Bump when the shape changes incompatibly; a reader
33 *  branches on it to migrate older snapshots rather than mis-reading them. */
34export const RUN_SNAPSHOT_VERSION = 1
35 
36/** Only a finished run is ever saved — the two terminal verdicts. */
37export type RunOutcome = 'victory' | 'defeat'
38 
39/** The valence of a ledger swing (mirrors the store's `Valence`). */
40export type RunValence = 'positive' | 'negative' | 'neutral'
41 
42/** The five efficiency tiers a victory can earn (mirrors the store's rating). */
43export type EfficiencyRating = 'Legendary' | 'Excellent' | 'Great' | 'Good' | 'Standard'
44 
45/** The bit of a roll the read-only view shows: the number and its named outcome. */
46export interface RollMark {
47    diceRoll: number
48    diceOutcome: DiceOutcome
49}
50 
51/** A dispatch keepsake — the player's verbatim message and whom/when it reached. */
52export interface RunDispatch {
53    text: string
54    figure: string
55    era: string
56}
57 
58/** The victory efficiency block (null on defeat) — the same data the end screen shows. */
59export interface RunEfficiency {
60    messagesSaved: number
61    messagesUsed: number
62    efficiencyPercentage: number
63    efficiencyRating: EfficiencyRating
64    isEarlyVictory: boolean
65}
66 
67/** One ledger entry, trimmed to the fields a read-only run view renders (the live
68 *  `TimelineEvent` minus its `Date` timestamp and the internals the view ignores). */
69export interface RunLedgerEntry {
70    id: string
71    figureName: string
72    era: string
73    headline: string
74    detail: string
75    diceRoll: number
76    diceOutcome: DiceOutcome
77    progressChange: number
78    /** The pre-amplifier swing — the Spine reads it to show the Δ equation
79     *  (`base → final`). Absent on turns that didn't amplify (none to disclose). */
80    baseProgressChange?: number
81    valence: RunValence
82    craft?: Craft
83    anachronism?: Anachronism
84    /** True when this was the run's staked last stand — the Spine's ⚑ badge. */
85    staked?: boolean
86}
⋯ 27 lines hidden (lines 87–113)87 
88/** The full saved run — everything a read-only view needs to replay the end screen. */
89export interface RunSnapshot {
90    version: number
91    runId: string
92    status: RunOutcome
93    objective: GameObjective
94    objectiveProgress: number
95    messagesUsed: number
96    totalMessages: number
97    bestRoll: RollMark | null
98    worstRoll: RollMark | null
99    efficiency: RunEfficiency | null
100    dispatches: RunDispatch[]
101    timeline: RunLedgerEntry[]
102    chronicle: ChronicleEntry | null
103}
104 
105/** The list projection — what the "your runs" list shows per run, without pulling
106 *  the full snapshot blob for every row. */
107export interface RunSummary {
108    runId: string
109    status: RunOutcome
110    title: string
111    progress: number
112    createdAt: string
113}

Plumbing the fields through the save and the boundary

Two consumers of the contract follow. The store's snapshot builder copies the fields off the live ledger when it persists a finished run:

baseProgressChange and staked join the persisted ledger entry.

stores/game.ts · 1382 lines

stores/game.ts1382 lines · TypeScript

⋯ 1306 lines hidden (lines 1–1306)1import { defineStore } from 'pinia'
2import type { GameObjective, ObjectiveSteer } from '~/server/utils/objectives'
3import type { Pack } from '~/server/utils/packs'
4import type { GroundedFigure } from '~/server/utils/figure-grounding'
5import { formatContactMoment, type ContactMoment } from '~/utils/contact-moment'
6import type { FigureSuggestion } from '~/server/utils/figure-suggester'
7import type { ChronicleEntry } from '~/server/utils/openai'
8import type { FigureStudy, ArchiveLookup } from '~/server/utils/prompt-builder'
9import type { Anachronism } from '~/server/utils/anachronism'
10import { chainStatus, type ChainStatus } from '~/utils/causal-chain'
11import type { Craft } from '~/utils/craft'
12import type { Continuity } from '~/utils/continuity'
13import type { DiceOutcome } from '~/utils/dice'
14import { generateGameSummary, rateEfficiency, type GameSummary } from '~/utils/game-summary'
15import { TOTAL_MESSAGES, MAX_PROGRESS_SWING, MAX_PROGRESS } from '~/utils/game-config'
16import { RUN_SNAPSHOT_VERSION, type RunSnapshot } from '~/utils/run-snapshot'
17 
18export type Valence = 'positive' | 'negative' | 'neutral'
19 
20/**
* A historical figure the player has reached out to. Figures are freeform — the
* player can write to anyone, in any era. The AI infers each figure's era and a
* short descriptor on first contact, which we cache here for the UI.
*/
25export interface HistoricalFigure {
  name: string
  era: string
  descriptor: string
29}
30 
31/**
* Timeline Ledger entry — a single recorded change to history.
*
* The ledger is the heart of the game: every resolved turn appends one entry
* describing how the world bent, so the player literally watches the timeline
* rewrite itself as they play.
*/
38export interface TimelineEvent {
  id: string
  figureName: string
  era: string
  headline: string
  detail: string
  diceRoll: number
  diceOutcome: DiceOutcome
  progressChange: number
  /** The engine's swing BEFORE the anachronism amplifier — shown so the player
   *  can see exactly what their wager did ("+8 ⚡ far-ahead → +11%"). */
  baseProgressChange?: number
  valence: Valence
  /** How anachronistic the player's nudge was — it widened this swing. */
  anachronism?: Anachronism
  /** How far this landed from the nearest foothold — it decayed this swing. */
  causalChain?: ChainStatus
  /** The Judge's grade of the dispatch that caused this change. */
  craft?: Craft
  /** Signed year of the intervention, when the contact was grounded. */
  whenSigned?: number
  /** True when this was the run's staked last stand (doubled swing). */
  staked?: boolean
  timestamp: Date
62}
63 
64/**
* Message Interface — one line in the conversation with a figure.
* Dice / outcome / action / impact / progress are recorded on the AI (figure)
* turn, since that is the resolved result of the roll.
*/
69export interface Message {
  text: string
  sender: 'user' | 'ai' | 'system'
  timestamp: Date
  figureName?: string
  /** The effective (craft-tilted) roll — what the bands judged. */
  diceRoll?: number
  diceOutcome?: DiceOutcome
  /** The die as it actually landed, before the craft modifier. */
  naturalRoll?: number
  /** The Judge's tilt on the roll (±2..0), and the grade + reason behind it. */
  rollModifier?: number
  craft?: Craft
  craftReason?: string
  /** Whether the dispatch built on the run's thread (issue #62) — drives the
   *  momentum meter and the 'builds' badge in the reveal. */
  continuity?: Continuity
  characterAction?: string
  timelineImpact?: string
  progressChange?: number
  /** The pre-amplifier swing + the wager level, for the reveal's equation. */
  baseProgressChange?: number
  /** The PRE-turn momentum that amplified this swing — for the reveal's equation. */
  momentumAtSwing?: number
  anachronism?: Anachronism
  /** The causal-chain decay applied to this swing (for the reveal's equation). */
  causalChain?: ChainStatus
  /** True when this turn was the staked last stand. */
  staked?: boolean
98}
99 
100export type GameStatus = 'playing' | 'victory' | 'defeat'
101 
102/**
* Shape returned by `POST /api/send-message` (see `server/api/send-message.post.ts`).
* Discriminated by `success`: when `true`, all fields downstream of the dice roll are
* guaranteed; when `false`, only `userMessage` + `error` are guaranteed (and the
* Character-AI-failure path doesn't even surface a dice roll). The discriminant lets
* the consumer destructure without optional chaining or null gymnastics.
*/
109type SendMessageApiResponse =
  | {
      success: true
      message: string
      data: {
          userMessage: string
          figure: { name: string; era: string; descriptor: string }
          diceRoll: number
          diceOutcome: DiceOutcome
          // Judge-of-craft fields (optional so older mocks/fixtures stay valid;
          // the live server always sends them).
          naturalRoll?: number
          rollModifier?: number
          craft?: Craft
          craftReason?: string
          continuity?: Continuity
          momentum?: number
          staked?: boolean
          characterResponse: { message: string; action: string }
          timeline: {
              headline: string
              detail: string
              era: string
              progressChange: number
              baseProgressChange?: number
              momentumAtSwing?: number
              valence: Valence
              anachronism?: Anachronism
              causalChain?: ChainStatus
          }
          error: null
      }
  }
  | {
      success: false
      message: string
      data: {
          userMessage: string
          diceRoll?: number
          diceOutcome?: DiceOutcome
          characterResponse?: { message: string; action: string }
          error: string
          /** A content-moderation block (not an infra failure): the dispatch was
           *  refused by the detector, the Sentinel, or the model itself. */
          blocked?: boolean
          moderationReason?: string
      }
  }
157 
158const RATE_LIMIT_MS = 1000 // message cooldown window, in ms
159 
160// Turn-reveal pacing. A resolved turn releases its beats one at a time — a beat of
161// suspense, then the die lands and the figure's reply writes itself in, then the
162// timeline shift, then the ledger node — so the resolution reads as one conducted
163// moment instead of everything firing in the same tick. Each component already
164// animates when its own slice of state changes; sequencing the WRITES sequences the
165// animations, with no component coordination. Tuned so the swing lands with the
166// reply's own "ripple" line (~0.55s into its staged reveal).
167export const REVEAL = { suspense: 450, swing: 550, node: 250 } as const
168const wait = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms))
169/** Stagger the reveal only in a real browser with motion allowed. SSR and the test
*  env (no `matchMedia`) collapse to an instant, atomic apply — so the store's
*  contract (state present the moment sendMessage resolves) is unchanged for tests. */
172function canAnimateReveal(): boolean {
  return typeof window !== 'undefined'
      && typeof window.matchMedia === 'function'
      && !window.matchMedia('(prefers-reduced-motion: reduce)').matches
176}
177 
178function valenceOf(progressChange: number): Valence {
  if (progressChange > 0) return 'positive'
  if (progressChange < 0) return 'negative'
  return 'neutral'
182}
183 
184/** Formats a signed timeline year (AD positive, BCE negative) for display. */
185export function formatContactYear(signed: number): string {
  return signed < 0 ? `${-signed} BC` : `${signed}`
187}
188 
189/** Human lifespan line for a grounded figure, e.g. "69 BC – 30 BC" or "1942 – present". */
190function lifespanText(g: GroundedFigure): string | undefined {
  if (!g.born) return undefined
  if (g.died) return `${g.born.display} – ${g.died.display}`
  return g.living ? `${g.born.display} – present` : g.born.display
194}
195 
196/** True when a $fetch error is a 402 (out of runs) — the paywall signal. ofetch
*  surfaces the status as statusCode and on the response, so check both. */
198function isPaymentRequired(error: unknown): boolean {
  const e = error as { statusCode?: number; status?: number; response?: { status?: number } }
  return e?.statusCode === 402 || e?.status === 402 || e?.response?.status === 402
201}
202 
203/** True when a $fetch error is a 503 / at-capacity — the spend cap paused new
*  runs (distinct from the per-device 402 paywall). */
205function isAtCapacity(error: unknown): boolean {
  const e = error as { statusCode?: number; status?: number; response?: { status?: number }; data?: { atCapacity?: boolean } }
  return e?.statusCode === 503 || e?.status === 503 || e?.response?.status === 503 || e?.data?.atCapacity === true
208}
209 
210export type ContactLiveness = 'ok' | 'before-birth' | 'after-death' | 'living' | 'unresolved' | 'unknown'
211 
212/**
* Game Store — core state for a session of freeform timeline editing.
*/
215export const useGameStore = defineStore('game', {
  state: () => ({
      remainingMessages: TOTAL_MESSAGES,
      messageHistory: [] as Message[],
      gameStatus: 'playing' as GameStatus,
      isLoading: false,
      error: null as string | null,
      lastMessageTime: null as number | null,
      isRateLimited: false,
      // Staleness plumbing, not run state. runEpoch increments on every reset so an
      // async result from a dead run can never write into a fresh one; the seq
      // counters order overlapping requests of the same kind so only the latest
      // lands (an earlier chronicle rewrite must not overwrite a later one).
      // Deliberately NOT restored by resetGame — they must survive it to work.
      runEpoch: 0,
      chronicleSeq: 0,
      groundingSeq: 0,
      // The current run's id — lazily minted on the run's first server call and
      // cleared by resetGame so each run gets a fresh one. Tags every AI call
      // (via the x-run-id header) so the gateway's cost telemetry groups per
      // run: the GTM cost instrument.
      runId: null as string | null,
      // The in-flight begin-run, so concurrent first-calls of a run share one
      // mint (one POST /api/run, one runs row) instead of racing two. Cleared
      // by resetGame. (Vue leaves a Promise unproxied, so awaiting it is safe.)
      runIdInflight: null as Promise<string> | null,
      // outOfRuns gates the mission screen's paywall (set when a commit is
      // refused with 402). The run packs offered there are loaded into `packs`.
      outOfRuns: false,
      // atCapacity gates the "at capacity" notice (set when a commit is refused
      // with 503 because the global spend cap paused new runs).
      atCapacity: false,
      packs: [] as Pack[],
      // The device's run balance, for the header gauge + account popover. null
      // until first loaded (GET /api/balance); the run-commit response also
      // refreshes it so the gauge stays live without a second round-trip.
      runsRemaining: null as number | null,
      freeRuns: 1,
      deviceRef: '' as string,
      // Account state (from /api/balance): the signed-in email, and whether the
      // current user is anonymous (→ must sign in before buying). Drives the
      // account UI + the sign-in-to-buy gate. false/null in device-fallback mode.
      accountEmail: null as string | null,
      accountAnonymous: false,
      // The run-packs sales modal — opened on demand (header) or automatically
      // when a commit is refused for being out of runs.
      buyModalOpen: false,
      // A one-shot notice after returning from Stripe Checkout ('success' shows a
      // credited confirmation; 'cancel' a gentle "no charge" note). Cleared by the UI.
      purchaseNotice: null as 'success' | 'cancel' | null,
      currentObjective: null as GameObjective | null,
      objectiveProgress: 0,
      // The run-level momentum meter (0..MOMENTUM_MAX): a coherent arc compounds its
      // gains amplifier; a reset or catastrophe shatters it back to 0 (issue #62).
      momentum: 0,
      timelineEvents: [] as TimelineEvent[],
      figures: [] as HistoricalFigure[],
      activeFigureName: '' as string,
      // Grounding for the active contact: real facts + the chosen year to reach them.
      figureGrounding: null as GroundedFigure | null,
      groundingLoading: false,
      contactWhen: null as number | null,
      /** Optional sub-year refinement of contactWhen — display/prompt flavor
       *  only; every mechanic keeps doing arithmetic on the YEAR (issue #32). */
      contactMoment: null as ContactMoment | null,
      // Era-relevant figure suggestions for the current objective (the on-ramp).
      figureSuggestions: [] as FigureSuggestion[],
      suggestionsLoading: false,
      suggestionsFor: '' as string,
      // The living Chronicle (Layer 3): a prose telling of the altered timeline,
      // rewritten each turn. Non-blocking — see refreshChronicle.
      chronicle: null as ChronicleEntry | null,
      chronicleLoading: false,
      // The 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
  }),
307 
  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
      },
319 
      /**
       * 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'
          )
      },
330 
      /** Total progress, net of setbacks, the player has clawed back. */
      gameSummary(): GameSummary {
          return generateGameSummary(this)
      },
335 
      /**
       * 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'
      },
357 
      /** Can the chosen contact + when actually be reached? */
      canContact(): boolean {
          return this.contactLiveness === 'ok' || this.contactLiveness === 'unknown'
      },
362 
      /**
       * 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
      },
374 
      /**
       * 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
      },
390 
      /**
       * 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)
      }
  },
406 
  actions: {
      // ---------- message helpers ----------
      addUserMessage(text: string, figureName?: string) {
          if (this.gameStatus !== 'playing') return
          this.messageHistory.push({
              text,
              sender: 'user',
              timestamp: new Date(),
              figureName
          })
      },
418 
      addAIMessage(text: string, figureName?: string) {
          this.messageHistory.push({
              text,
              sender: 'ai',
              timestamp: new Date(),
              figureName
          })
      },
427 
      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
          })
      },
451 
      // ---------- 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 })
          }
      },
462 
      setActiveFigure(name: string) {
          this.activeFigureName = name
      },
466 
      /**
       * 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
      },
484 
      /**
       * 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
          }
      },
532 
      /** 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
      },
561 
      /** 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() }
      },
567 
      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
      },
573 
      setContactMoment(moment: ContactMoment | null) {
          this.contactMoment = moment
      },
577 
      /**
       * 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
594 
          // 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
          }
      },
631 
      /**
       * 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
          }
      },
665 
      /**
       * 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
679 
          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
          }
      },
712 
      // ---------- 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()
          })
      },
736 
      // ---------- the living chronicle (Layer 3) ----------
      /**
       * Re-narrates the Chronicle from the freshly-bent timeline. Fired
       * non-blocking after a resolved turn (and at game end): the dice/progress
       * reveal never waits on prose. True to the game's name, the WHOLE account is
       * rewritten each turn — a later change can re-frame how earlier events read.
       * Graceful: a failed refresh keeps the prior telling, so the panel never
       * blanks; an empty timeline clears it (nothing to chronicle yet).
       */
      async refreshChronicle(): Promise<void> {
          if (!this.timelineEvents.length) {
              this.chronicle = null
              return
          }
          // Sequencing: rewrites overlap (each turn fires one, never awaited), so
          // only the LATEST issued refresh may land — an earlier telling arriving
          // late must not regress the account (or worse, the epilogue). The epoch
          // guard keeps a dead run's telling out of a fresh run entirely.
          const epoch = this.runEpoch
          const seq = ++this.chronicleSeq
          this.chronicleLoading = true
          try {
              const res = await $fetch('/api/chronicle', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: {
                      objective: this.currentObjective,
                      status: this.gameStatus,
                      progress: this.objectiveProgress,
                      timeline: this.timelineEvents.map(e => ({
                          era: e.era,
                          figureName: e.figureName,
                          headline: e.headline,
                          detail: e.detail,
                          progressChange: e.progressChange
                      }))
                  }
              }) as { success?: boolean; chronicle?: ChronicleEntry }
              if (epoch !== this.runEpoch || seq !== this.chronicleSeq) return
              if (res?.success && res.chronicle) this.chronicle = res.chronicle
          } catch (error) {
              if (epoch !== this.runEpoch || seq !== this.chronicleSeq) return
              console.error('Failed to refresh the chronicle:', error)
              // Keep the prior chronicle — a failed refresh never blanks the panel.
          } finally {
              if (epoch === this.runEpoch && seq === this.chronicleSeq) this.chronicleLoading = false
          }
      },
785 
      // ---------- simple setters ----------
      setLoading(loading: boolean) { this.isLoading = loading },
      setError(error: string | null) { this.error = error },
      clearModerationNotice() { this.moderationNotice = null },
      clearArchiveNotice() { this.archiveNotice = null },
791 
      // ---------- rate limiting ----------
      checkRateLimit(): boolean {
          const now = Date.now()
          if (this.lastMessageTime && (now - this.lastMessageTime) < RATE_LIMIT_MS) return false
          return true
      },
798 
      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)
      },
806 
      // ---------- counter & status ----------
      decrementMessages() {
          if (this.remainingMessages > 0) this.remainingMessages--
      },
811 
      /**
       * 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
              }
          }
      },
828 
      applyProgress(progressChange: number) {
          this.objectiveProgress = Math.max(0, Math.min(MAX_PROGRESS, this.objectiveProgress + progressChange))
      },
832 
      /**
       * 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'
          }
      },
848 
      // ---------- 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
866 
          if (!this.canSendMessage) return false
          if (!target) {
              this.setError('Choose who in history to send your message to first.')
              return false
          }
          if (!this.checkRateLimit()) {
              this.setRateLimit()
              this.setError('The timeline needs a moment — wait before sending again.')
              return false
          }
          if (!this.canContact) {
              const who = this.figureGrounding?.name || target
              this.setError(
                  this.contactLiveness === 'unresolved'
                      ? (this.figureGrounding?.transient
                          ? `Couldn't reach the record to verify "${target}" — try again in a moment.`
                          : `No historical record found for "${target}" — reach for a real figure (pick a match as you type).`)
                      : this.contactLiveness === 'before-birth'
                          ? `${who} isn't born yet in that year — choose a later moment to reach them.`
                          : this.contactLiveness === 'living'
                              ? (this.figureGrounding?.born
                                  ? `${who} is still living — Revisionist only reaches figures from history.`
                                  : `${who} couldn't be dated — Revisionist can only reach figures it can place in history.`)
                              : `${who} has died by that year — choose an earlier moment to reach them.`
              )
              return false
          }
894 
          this.setError(null)
          this.moderationNotice = null
          this.setActiveFigure(target)
          this.addUserMessage(text, target)
          this.decrementMessages()
          this.setLoading(true)
          this.lastMessageTime = Date.now()
902 
          // 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()
915 
          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)
                  }
              })
951 
              if (epoch !== this.runEpoch) return false
953 
              if (response?.success && response.data?.characterResponse) {
                  const { figure, characterResponse, diceRoll, diceOutcome, timeline } = response.data
956 
                  if (figure?.name) {
                      this.registerFigure({
                          name: figure.name,
                          era: figure.era || '',
                          descriptor: figure.descriptor || ''
                      })
                  }
964 
                  // ---- 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
                  }
972 
                  // 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)
999 
                  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
1016 
                      // 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()
              }
          }
1067 
          // 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') {
              void this.saveRunSnapshot()
              if (refresh) void refresh.finally(() => { void this.saveRunSnapshot() })
          }
          return resolved
      },
1086 
      /**
       * Commits a chosen objective and starts the run from a clean slate of
       * progress. Used by the mission-select screen for both curated picks and
       * freshly composed ones.
       */
      async chooseObjective(objective: GameObjective): Promise<boolean> {
          // Commit = the run is charged here. Mint the run id server-side, then
          // spend one run from the device's balance. Fails CLOSED: out of runs →
          // raise the paywall; begin-run or commit failing → surface an error and
          // do NOT start. A run that isn't a charged, server-backed run would be
          // rejected by the gameplay gate anyway, so starting it only strands the
          // player mid-run. The spend cap (not free play) is the outage backstop.
          let runId: string
          try {
              runId = await this.ensureRunId()
          } catch (error) {
              console.error('Could not begin the run:', error)
              this.error = 'Could not start the run. Please try again.'
              return false
          }
          try {
              const res = await $fetch('/api/run-commit', {
                  method: 'POST',
                  headers: { 'Content-Type': 'application/json' },
                  body: { runId }
              }) as { runsRemaining?: number }
              this.outOfRuns = false
              // Keep the header gauge live: the commit returns the post-charge
              // balance (−1 marks a degraded, ungated run — leave the gauge as is).
              if (typeof res?.runsRemaining === 'number' && res.runsRemaining >= 0) {
                  this.runsRemaining = res.runsRemaining
              }
          } catch (error) {
              if (isPaymentRequired(error)) {
                  this.outOfRuns = true
                  this.openBuyModal()
                  return false
              }
              if (isAtCapacity(error)) {
                  this.atCapacity = true
                  return false
              }
              console.error('Could not charge the run:', error)
              this.error = 'Could not start the run. Please try again.'
              return false
          }
          this.currentObjective = objective
          this.objectiveProgress = 0
          this.momentum = 0
          this.error = null
          return true
      },
1139 
      /**
       * 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
          }
      },
1167 
      /**
       * 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)
          }
      },
1185 
      /** Opens the run-packs sales modal, loading the catalog first. */
      async openBuyModal(): Promise<void> {
          this.buyModalOpen = true
          await this.loadPacks()
      },
1191 
      /** Closes the sales modal. */
      closeBuyModal(): void {
          this.buyModalOpen = false
      },
1196 
      /** 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()
          }
      },
1207 
      /** Dismisses the post-purchase notice. */
      clearPurchaseNotice(): void {
          this.purchaseNotice = null
      },
1212 
      /** 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)
          }
      },
1226 
      /** 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
          }
      },
1242 
      getVictoryEfficiency() {
          if (this.gameStatus === 'victory') {
              const messagesSaved = this.remainingMessages
              const messagesUsed = TOTAL_MESSAGES - this.remainingMessages
              const efficiencyPercentage = Math.round((messagesSaved / TOTAL_MESSAGES) * 100)
1248 
              const efficiencyRating = rateEfficiency(messagesSaved)
1250 
              return {
                  messagesSaved,
                  messagesUsed,
                  efficiencyPercentage,
                  efficiencyRating,
                  isEarlyVictory: messagesSaved > 0
              }
          }
          return null
      },
1261 
      /**
       * 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
1278 
          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
1294 
          const snapshot: RunSnapshot = {
              version: RUN_SNAPSHOT_VERSION,
              runId,
              status,
              objective,
              objectiveProgress: this.objectiveProgress,
              messagesUsed: TOTAL_MESSAGES - this.remainingMessages,
              totalMessages: TOTAL_MESSAGES,
              bestRoll: mark(summary.bestRoll),
              worstRoll: mark(summary.worstRoll),
              efficiency: this.getVictoryEfficiency(),
              dispatches,
              timeline: events.map((e) => ({
                  id: e.id,
                  figureName: e.figureName,
                  era: e.era,
                  headline: e.headline,
                  detail: e.detail,
                  diceRoll: e.diceRoll,
                  diceOutcome: e.diceOutcome,
                  progressChange: e.progressChange,
                  baseProgressChange: e.baseProgressChange,
                  valence: e.valence,
                  craft: e.craft,
                  anachronism: e.anachronism,
                  staked: e.staked
              })),
⋯ 61 lines hidden (lines 1322–1382)1322                chronicle: this.chronicle
          }
1324 
          try {
              await $fetch('/api/run-save', {
                  method: 'POST',
                  headers: { 'Content-Type': 'application/json' },
                  body: snapshot
              })
          } catch (error) {
              // Saving the run is a nicety; a failure must not break the end screen.
              if (epoch === this.runEpoch) console.error('Could not save the run:', error)
          }
      },
1336 
      resetGame() {
          // Tear the epoch first: anything still in flight belongs to the old run
          // and must find no purchase here. (The seq counters deliberately survive.)
          this.runEpoch++
          this.remainingMessages = TOTAL_MESSAGES
          this.messageHistory = []
          this.gameStatus = 'playing'
          this.isLoading = false
          this.error = null
          this.lastMessageTime = null
          this.isRateLimited = false
          // A new run gets a fresh id on its next server call; abandon any
          // in-flight mint so a dead run's id can't land in the new run.
          this.runId = null
          this.runIdInflight = null
          // The paywall / capacity notices re-check on the next commit.
          this.outOfRuns = false
          this.atCapacity = false
          this.currentObjective = null
          this.objectiveProgress = 0
          this.momentum = 0
          this.timelineEvents = []
          this.figures = []
          this.activeFigureName = ''
          this.figureGrounding = null
          this.groundingLoading = false
          this.contactWhen = null
          this.contactMoment = null
          this.figureSuggestions = []
          this.suggestionsLoading = false
          this.suggestionsFor = ''
          this.chronicle = null
          this.chronicleLoading = false
          this.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
      }
  }
1382})

And the server's boundary validator — a saved run can be POSTed directly, so every field is coerced — bounds the two new ones. The pre-amplifier swing is signed-clamped like its sibling progressChange; staked is a strict-boolean flag, so only a real true survives.

The two new coercion branches sit beside craft/anachronism.

server/utils/run-snapshot.ts · 171 lines

server/utils/run-snapshot.ts171 lines · TypeScript

⋯ 117 lines hidden (lines 1–117)1/**
* Server-side boundary validation for a saved run snapshot.
*
* The shared CONTRACT (types + version) lives in `~/utils/run-snapshot` so both the
* client store and the server can import it without pulling server-only code into the
* client bundle. This module is the server-only half: it coerces an untrusted POST
* body into a valid RunSnapshot (a direct POST can send anything), bounding every
* field with the same cleanString/cleanArray/clampInt helpers the other routes use.
*/
10import { cleanString, cleanArray, clampInt } from './validate'
11import {
  MAX_OBJECTIVE_TITLE_CHARS,
  MAX_OBJECTIVE_DESC_CHARS,
  MAX_ERA_CHARS,
  MAX_FIGURE_NAME_CHARS,
  MAX_LEDGER_DETAIL_CHARS,
  MAX_TIMELINE_ENTRIES,
  MAX_HISTORY_ENTRIES,
  MAX_LEDGER_SWING
20} from './validate'
21import { sanitizeRunId } from './run-context'
22import { TOTAL_MESSAGES } from '~/utils/game-config'
23import {
  RUN_SNAPSHOT_VERSION,
  type RunSnapshot,
  type RunOutcome,
  type RunValence,
  type RunEfficiency,
  type RunDispatch,
  type RunLedgerEntry,
  type RollMark,
  type EfficiencyRating
33} from '~/utils/run-snapshot'
34import type { DiceOutcome } from '~/utils/dice'
35import type { Craft } from '~/utils/craft'
36import type { Anachronism } from '~/server/utils/anachronism'
37import type { GameObjective } from '~/server/utils/objectives'
38import type { ChronicleEntry } from '~/server/utils/openai'
39 
40// Caps specific to a snapshot's own fields (the shared input caps live in validate.ts).
41const MAX_DISPATCH_CHARS = 320
42const MAX_HEADLINE_CHARS = 200
43const MAX_ICON_CHARS = 16
44const MAX_OUTCOME_CHARS = 24
45const MAX_RATING_CHARS = 24
46const MAX_HINT_CHARS = 24
47const MAX_ID_CHARS = 64
48const MAX_TOTAL_MESSAGES = 20
49const MAX_DICE = 40
50 
51const VALENCES: RunValence[] = ['positive', 'negative', 'neutral']
52const coerceValence = (v: unknown): RunValence =>
  VALENCES.includes(v as RunValence) ? (v as RunValence) : 'neutral'
54 
55const clampNonNeg = (n: number): number => Math.max(0, n)
56 
57const cleanRoll = (v: unknown): RollMark | null => {
  if (!v || typeof v !== 'object') return null
  const m = v as Record<string, unknown>
  const diceOutcome = cleanString(m.diceOutcome, MAX_OUTCOME_CHARS)
  if (!diceOutcome) return null
  return { diceRoll: clampNonNeg(clampInt(m.diceRoll, MAX_DICE)), diceOutcome: diceOutcome as DiceOutcome }
63}
64 
65/**
* Coerce an untrusted body into a valid RunSnapshot, or null when it isn't a
* completed run we can save. Bounds every field, and stamps the server's own
* `version` rather than trusting the client's. Returns null when the run isn't
* terminal or has no objective / run id — there is nothing meaningful to persist then.
*/
71export function sanitizeSnapshot(raw: unknown): RunSnapshot | null {
  if (!raw || typeof raw !== 'object') return null
  const r = raw as Record<string, unknown>
74 
  const status: RunOutcome | null =
      r.status === 'victory' || r.status === 'defeat' ? r.status : null
  if (!status) return null
78 
  const runId = sanitizeRunId(r.runId)
  if (!runId) return null
81 
  if (!r.objective || typeof r.objective !== 'object') return null
  const o = r.objective as Record<string, unknown>
  const objective: GameObjective = {
      title: cleanString(o.title, MAX_OBJECTIVE_TITLE_CHARS),
      description: cleanString(o.description, MAX_OBJECTIVE_DESC_CHARS),
      era: cleanString(o.era, MAX_ERA_CHARS),
      icon: cleanString(o.icon, MAX_ICON_CHARS)
  }
  if (typeof o.anchorYear === 'number' && Number.isFinite(o.anchorYear)) {
      objective.anchorYear = Math.round(o.anchorYear)
  }
93 
  const totalMessages = clampNonNeg(clampInt(r.totalMessages, MAX_TOTAL_MESSAGES)) || TOTAL_MESSAGES
  const messagesUsed = Math.min(totalMessages, clampNonNeg(clampInt(r.messagesUsed, MAX_TOTAL_MESSAGES)))
96 
  let efficiency: RunEfficiency | null = null
  if (r.efficiency && typeof r.efficiency === 'object') {
      const e = r.efficiency as Record<string, unknown>
      efficiency = {
          messagesSaved: clampNonNeg(clampInt(e.messagesSaved, MAX_TOTAL_MESSAGES)),
          messagesUsed: clampNonNeg(clampInt(e.messagesUsed, MAX_TOTAL_MESSAGES)),
          efficiencyPercentage: clampNonNeg(clampInt(e.efficiencyPercentage, 100)),
          efficiencyRating: (cleanString(e.efficiencyRating, MAX_RATING_CHARS) || 'Standard') as EfficiencyRating,
          isEarlyVictory: e.isEarlyVictory === true
      }
  }
108 
  const dispatches: RunDispatch[] = cleanArray(r.dispatches, MAX_HISTORY_ENTRIES).map((raw) => {
      const d = (raw ?? {}) as Record<string, unknown>
      return {
          text: cleanString(d.text, MAX_DISPATCH_CHARS),
          figure: cleanString(d.figure, MAX_FIGURE_NAME_CHARS),
          era: cleanString(d.era, MAX_ERA_CHARS)
      }
  })
117 
  const timeline: RunLedgerEntry[] = cleanArray(r.timeline, MAX_TIMELINE_ENTRIES).map((raw) => {
      const t = (raw ?? {}) as Record<string, unknown>
      const entry: RunLedgerEntry = {
          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: cleanString(t.diceOutcome, MAX_OUTCOME_CHARS) as DiceOutcome,
          progressChange: clampInt(t.progressChange, MAX_LEDGER_SWING),
          valence: coerceValence(t.valence)
      }
      // The pre-amplifier swing is signed and only present when it amplified; keep
      // "absent" distinct from a real 0 so the Spine shows the Δ equation faithfully.
      if (typeof t.baseProgressChange === 'number') {
          entry.baseProgressChange = clampInt(t.baseProgressChange, MAX_LEDGER_SWING)
      }
      const craft = cleanString(t.craft, MAX_HINT_CHARS)
      if (craft) entry.craft = craft as Craft
      const anachronism = cleanString(t.anachronism, MAX_HINT_CHARS)
      if (anachronism) entry.anachronism = anachronism as Anachronism
      if (t.staked === true) entry.staked = true
      return entry
⋯ 30 lines hidden (lines 142–171)142    })
143 
  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)
      }
  }
154 
  return {
      // The server owns the version stamp — never trust the client's.
      version: RUN_SNAPSHOT_VERSION,
      runId,
      status,
      objective,
      objectiveProgress: clampNonNeg(clampInt(r.objectiveProgress, 100)),
      messagesUsed,
      totalMessages,
      bestRoll: cleanRoll(r.bestRoll),
      worstRoll: cleanRoll(r.worstRoll),
      efficiency,
      dispatches,
      timeline,
      chronicle
  }
171}

Tests: both sources, and plumbing that can't silently rot

A new spec drives the Spine from both sources. The passed-events path proves a saved run renders the full graphic — nodes, the Δ equation, both badges — and that it ignores the live store entirely; the no-prop path proves live play is unchanged, down to the ▷ now present marker. (SymbolHint wraps each badge in a tooltip that needs a provider the bare mount lacks, so it's stubbed to a slot passthrough — the same idiom MessageHistory.spec uses.)

Two describes: from a passed prop, and the store fallback.

tests/unit/components/TimelineLedger.spec.ts · 81 lines

tests/unit/components/TimelineLedger.spec.ts81 lines · TypeScript

⋯ 20 lines hidden (lines 1–20)1import { mount } from '@vue/test-utils'
2import { describe, it, expect, beforeEach } from 'vitest'
3import { setActivePinia, createPinia } from 'pinia'
4import TimelineLedger from '../../../components/TimelineLedger.vue'
5import { useGameStore, type TimelineEvent } from '../../../stores/game'
6import { DiceOutcome } from '../../../utils/dice'
7import type { RunLedgerEntry } from '../../../utils/run-snapshot'
8 
9/**
10 * TimelineLedger — the Spine. In live play it reads the store; the saved-run view
11 * (RunView) feeds it a snapshot's ledger via the `events` prop. These cover both
12 * sources: the passed-prop path (a past run renders the full Spine from the saved
13 * record) and the store-fallback path (live play, unchanged).
14 */
15 
16// SymbolHint wraps each badge in a reka-ui tooltip that needs a TooltipProvider
17// ancestor the bare mount lacks; stub it to a slot passthrough (the badge + its
18// testid still render), matching MessageHistory.spec's idiom.
19const withHint = { global: { stubs: { SymbolHint: { template: '<span><slot/></span>' } } } }
20 
21function savedLedger(): RunLedgerEntry[] {
22    return [
23        { id: 'e1', figureName: 'Archimedes', era: 'Antiquity', headline: 'The lever turns', detail: 'A first nudge to the past.', diceRoll: 12, diceOutcome: DiceOutcome.SUCCESS, progressChange: 8, valence: 'positive' },
24        // The newest change — amplified and staked, so it exercises the Δ equation
25        // and both ⚡/⚑ badges the Spine renders (the parity #110 restores).
26        { id: 'e2', figureName: 'Hypatia', era: 'Antiquity', headline: 'The scrolls endure', detail: 'A copy survives the fire.', diceRoll: 19, diceOutcome: DiceOutcome.CRITICAL_SUCCESS, progressChange: 60, baseProgressChange: 40, valence: 'positive', anachronism: 'far-ahead', staked: true }
27    ]
28}
29 
30const mountSaved = () => mount(TimelineLedger, { props: { readonly: true, events: savedLedger() }, ...withHint })
⋯ 4 lines hidden (lines 31–34)31 
32describe('TimelineLedger', () => {
33    beforeEach(() => setActivePinia(createPinia()))
34 
35    describe('from a passed events prop (the saved-run view)', () => {
36        it('renders the Spine from the prop — a node per event, newest leading the detail strip', () => {
37            const w = mountSaved()
38            expect(w.find('[data-testid="timeline-ledger"]').exists()).toBe(true)
39            expect(w.findAll('[data-testid="timeline-event"]')).toHaveLength(2)
40            expect(w.find('[data-testid="node-detail"]').text()).toContain('The scrolls endure')
41        })
42 
43        it('surfaces the snapshot\'s Spine fields: the Δ equation and the ⚡/⚑ badges', () => {
44            const w = mountSaved()
45            const eq = w.find('[data-testid="swing-equation"]')
46            expect(eq.exists()).toBe(true)
⋯ 21 lines hidden (lines 47–67)47            expect(eq.text()).toContain('+40')
48            expect(eq.text()).toContain('+60')
49            expect(w.find('[data-testid="anachronism-badge"]').exists()).toBe(true)
50            expect(w.find('[data-testid="staked-badge"]').exists()).toBe(true)
51        })
52 
53        it('is read-only: no live "▷ now" present marker', () => {
54            expect(mountSaved().find('.spine-now').exists()).toBe(false)
55        })
56 
57        it('ignores the live store entirely when events are passed', () => {
58            const store = useGameStore()
59            store.timelineEvents = [
60                { id: 'ghost', figureName: 'Nobody', era: 'Nowhen', headline: 'A live ghost', detail: 'Should never render.', diceRoll: 1, diceOutcome: DiceOutcome.CRITICAL_FAILURE, progressChange: -5, valence: 'negative', timestamp: new Date() }
61            ] as TimelineEvent[]
62            const w = mountSaved()
63            expect(w.text()).not.toContain('A live ghost')
64            expect(w.findAll('[data-testid="timeline-event"]')).toHaveLength(2)
65        })
66    })
67 
68    describe('without an events prop (live play, unchanged)', () => {
69        it('falls back to the store and shows the live present marker', () => {
70            const store = useGameStore()
71            store.timelineEvents = [
72                { id: 's1', figureName: 'Tesla', era: '19th c.', headline: 'A spark leaps', detail: 'Current flows early.', diceRoll: 15, diceOutcome: DiceOutcome.SUCCESS, progressChange: 10, valence: 'positive', timestamp: new Date() }
73            ] as TimelineEvent[]
⋯ 8 lines hidden (lines 74–81)74            const w = mount(TimelineLedger, withHint)
75            expect(w.findAll('[data-testid="timeline-event"]')).toHaveLength(1)
76            expect(w.find('[data-testid="node-detail"]').text()).toContain('A spark leaps')
77            // Live (not read-only): the "▷ now" present marker is shown.
78            expect(w.find('.spine-now').exists()).toBe(true)
79        })
80    })
81})

The render tests hand-build fixtures with both fields present, so on their own they wouldn't catch the plumbing breaking. Two more assertions close that: one proves the store builder actually copies the fields into the saved snapshot, the other that the boundary validator preserves and bounds them. Drop either plumbing line and one of these goes red.

The save path carries the two fields into the POST body.

tests/unit/stores/game-save-run.spec.ts · 109 lines

tests/unit/stores/game-save-run.spec.ts109 lines · TypeScript

⋯ 80 lines hidden (lines 1–80)1import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
2import { setActivePinia, createPinia } from 'pinia'
3import { useGameStore } from '../../../stores/game'
4import { DiceOutcome } from '../../../utils/dice'
5import { RUN_SNAPSHOT_VERSION } from '../../../utils/run-snapshot'
6 
7/**
* saveRunSnapshot persists the finished run's end-state to the player's account. It
* captures exactly what the end screen shows (objective, verdict, ledger, dispatches,
* rolls, epilogue), keyed by the run id, and only fires for a completed, server-backed
* run — best-effort, so a failure never disturbs the end screen.
*/
13const RUN_ID = '11111111-1111-4111-8111-111111111111'
14 
15function seedFinishedVictory(store: ReturnType<typeof useGameStore>) {
  store.runId = RUN_ID
  store.gameStatus = 'victory'
  store.currentObjective = { title: 'Save the Library', description: 'Keep the scrolls.', era: 'Antiquity', icon: '📜' }
  store.objectiveProgress = 100
  store.remainingMessages = 2 // messagesUsed = 3
  store.messageHistory = [
      { text: 'Hide the scrolls.', sender: 'user', timestamp: new Date(), figureName: 'Hypatia' },
      { text: 'It is done.', sender: 'ai', timestamp: new Date(), diceRoll: 19, diceOutcome: DiceOutcome.CRITICAL_SUCCESS, progressChange: 60 }
  ] as never
  store.timelineEvents = [
      { id: 'evt-1', figureName: 'Hypatia', era: 'Antiquity', headline: 'The scrolls are hidden', detail: 'A copy survives.', diceRoll: 19, diceOutcome: DiceOutcome.CRITICAL_SUCCESS, progressChange: 60, baseProgressChange: 40, valence: 'positive', staked: true, timestamp: new Date() }
  ] as never
  store.chronicle = { title: 'The Library Stands', paragraphs: ['It did not burn.'] }
29}
30 
31describe('game store · saveRunSnapshot', () => {
  let store: ReturnType<typeof useGameStore>
  let fetchMock: ReturnType<typeof vi.fn>
34 
  beforeEach(() => {
      setActivePinia(createPinia())
      store = useGameStore()
      fetchMock = vi.fn().mockResolvedValue({ saved: true })
      vi.stubGlobal('$fetch', fetchMock)
  })
41 
  afterEach(() => {
      vi.unstubAllGlobals()
      vi.restoreAllMocks()
  })
46 
  it('POSTs the finished run snapshot to /api/run-save', async () => {
      seedFinishedVictory(store)
      await store.saveRunSnapshot()
50 
      expect(fetchMock).toHaveBeenCalledTimes(1)
      const [url, opts] = fetchMock.mock.calls[0]
      expect(url).toBe('/api/run-save')
      expect(opts.method).toBe('POST')
55 
      const body = opts.body
      expect(body).toMatchObject({
          version: RUN_SNAPSHOT_VERSION,
          runId: RUN_ID,
          status: 'victory',
          objective: { title: 'Save the Library', era: 'Antiquity', icon: '📜' },
          objectiveProgress: 100,
          messagesUsed: 3,
          totalMessages: 5,
          bestRoll: { diceRoll: 19, diceOutcome: 'Critical Success' },
          dispatches: [{ text: 'Hide the scrolls.', figure: 'Hypatia', era: 'Antiquity' }],
          chronicle: { title: 'The Library Stands', paragraphs: ['It did not burn.'] }
      })
      // The victory efficiency block is derived and carried.
      expect(body.efficiency).toMatchObject({ messagesUsed: 3, efficiencyRating: expect.any(String) })
  })
72 
  it('serializes the ledger without the in-memory Date timestamp', async () => {
      seedFinishedVictory(store)
      await store.saveRunSnapshot()
      const entry = fetchMock.mock.calls[0][1].body.timeline[0]
      expect(entry).not.toHaveProperty('timestamp')
      expect(entry).toMatchObject({ id: 'evt-1', headline: 'The scrolls are hidden', progressChange: 60, valence: 'positive' })
  })
80 
  it('carries the Spine fields the retro run view renders — baseProgressChange (the Δ equation) and staked (the ⚑)', async () => {
      // The builder must copy these from the ledger into the snapshot, or a saved run
      // loses the Δ equation and the ⚑ badge on /runs/:id (the #110 regression).
      seedFinishedVictory(store)
      await store.saveRunSnapshot()
      const entry = fetchMock.mock.calls[0][1].body.timeline[0]
      expect(entry).toMatchObject({ baseProgressChange: 40, staked: true })
  })
⋯ 21 lines hidden (lines 89–109)89 
  it('does nothing while the run is still playing', async () => {
      seedFinishedVictory(store)
      store.gameStatus = 'playing'
      await store.saveRunSnapshot()
      expect(fetchMock).not.toHaveBeenCalled()
  })
96 
  it('does nothing without a server-backed run id', async () => {
      seedFinishedVictory(store)
      store.runId = null
      await store.saveRunSnapshot()
      expect(fetchMock).not.toHaveBeenCalled()
  })
103 
  it('swallows a save failure (never throws into the end screen)', async () => {
      seedFinishedVictory(store)
      fetchMock.mockRejectedValueOnce(new Error('network'))
      await expect(store.saveRunSnapshot()).resolves.toBeUndefined()
  })
109})

Preserve, signed-clamp, and the strict-boolean guard at the boundary.

tests/unit/server/utils/run-snapshot.spec.ts · 100 lines

tests/unit/server/utils/run-snapshot.spec.ts100 lines · TypeScript

⋯ 42 lines hidden (lines 1–42)1import { describe, it, expect } from 'vitest'
2import { sanitizeSnapshot } from '../../../../server/utils/run-snapshot'
3import { RUN_SNAPSHOT_VERSION } from '../../../../utils/run-snapshot'
4 
5/**
* sanitizeSnapshot is the API-boundary gate for a saved run: a direct POST can send
* anything, so it must coerce-and-bound every field, reject a non-completed run, and
* stamp the server's own version rather than trusting the client's.
*/
10const RUN_ID = '11111111-1111-4111-8111-111111111111'
11 
12function validRaw(overrides: Record<string, unknown> = {}) {
  return {
      version: 99, // client-supplied — must be ignored
      runId: RUN_ID,
      status: 'victory',
      objective: { title: 'Save the Library', description: 'Keep the scrolls.', era: 'Antiquity', icon: '📜', anchorYear: -300 },
      objectiveProgress: 100,
      messagesUsed: 3,
      totalMessages: 5,
      bestRoll: { diceRoll: 19, diceOutcome: 'Critical Success' },
      worstRoll: { diceRoll: 4, diceOutcome: 'Failure' },
      efficiency: { messagesSaved: 2, messagesUsed: 3, efficiencyPercentage: 40, efficiencyRating: 'Great', isEarlyVictory: true },
      dispatches: [{ text: 'Hide the scrolls.', figure: 'Hypatia', era: 'Antiquity' }],
      timeline: [{ id: 'evt-1', figureName: 'Hypatia', era: 'Antiquity', headline: 'Hidden', detail: 'A copy survives.', diceRoll: 19, diceOutcome: 'Critical Success', progressChange: 60, valence: 'positive', craft: 'sharp', anachronism: 'in-period' }],
      chronicle: { title: 'The Library Stands', paragraphs: ['It did not burn.', 'The knowledge endured.'] },
      ...overrides
  }
29}
30 
31describe('sanitizeSnapshot', () => {
  it('accepts a valid completed run and stamps the server version', () => {
      const snap = sanitizeSnapshot(validRaw())
      expect(snap).not.toBeNull()
      expect(snap!.version).toBe(RUN_SNAPSHOT_VERSION)
      expect(snap!.runId).toBe(RUN_ID)
      expect(snap!.status).toBe('victory')
      expect(snap!.objective).toEqual({ title: 'Save the Library', description: 'Keep the scrolls.', era: 'Antiquity', icon: '📜', anchorYear: -300 })
      expect(snap!.timeline[0]).toMatchObject({ headline: 'Hidden', craft: 'sharp', anachronism: 'in-period', valence: 'positive' })
      expect(snap!.bestRoll).toEqual({ diceRoll: 19, diceOutcome: 'Critical Success' })
  })
42 
  it('preserves the Spine fields baseProgressChange + staked, clamping/guarding them at the boundary', () => {
      const base = { id: 'evt-1', figureName: 'Hypatia', era: 'Antiquity', headline: 'Hidden', detail: 'A copy survives.', diceRoll: 19, diceOutcome: 'Critical Success', progressChange: 60, valence: 'positive' }
      // Present + in range: carried through to the read-only run view's Spine.
      expect(sanitizeSnapshot(validRaw({ timeline: [{ ...base, baseProgressChange: 40, staked: true }] }))!.timeline[0])
          .toMatchObject({ baseProgressChange: 40, staked: true })
      // The pre-amplifier swing is signed-clamped (MAX_LEDGER_SWING = ±100).
      expect(sanitizeSnapshot(validRaw({ timeline: [{ ...base, baseProgressChange: 9999 }] }))!.timeline[0].baseProgressChange).toBe(100)
      expect(sanitizeSnapshot(validRaw({ timeline: [{ ...base, baseProgressChange: -9999 }] }))!.timeline[0].baseProgressChange).toBe(-100)
      // staked is a strict-boolean flag: a truthy non-boolean is dropped, not coerced.
      expect(sanitizeSnapshot(validRaw({ timeline: [{ ...base, staked: 'yes' }] }))!.timeline[0].staked).toBeUndefined()
      // Absent stays absent — an older snapshot (no Δ/⚑) loads cleanly.
      const bare = sanitizeSnapshot(validRaw())!.timeline[0]
      expect(bare.baseProgressChange).toBeUndefined()
      expect(bare.staked).toBeUndefined()
  })
⋯ 43 lines hidden (lines 58–100)58 
  it('rejects a non-terminal status', () => {
      expect(sanitizeSnapshot(validRaw({ status: 'playing' }))).toBeNull()
      expect(sanitizeSnapshot(validRaw({ status: undefined }))).toBeNull()
  })
63 
  it('rejects a missing run id or objective', () => {
      expect(sanitizeSnapshot(validRaw({ runId: '' }))).toBeNull()
      expect(sanitizeSnapshot(validRaw({ objective: null }))).toBeNull()
  })
68 
  it('rejects a non-object body', () => {
      expect(sanitizeSnapshot(null)).toBeNull()
      expect(sanitizeSnapshot('nope')).toBeNull()
  })
73 
  it('clamps progress into 0..100', () => {
      expect(sanitizeSnapshot(validRaw({ objectiveProgress: 9999 }))!.objectiveProgress).toBe(100)
      expect(sanitizeSnapshot(validRaw({ objectiveProgress: -50 }))!.objectiveProgress).toBe(0)
  })
78 
  it('truncates an over-long objective title', () => {
      const long = 'x'.repeat(500)
      const snap = sanitizeSnapshot(validRaw({ objective: { title: long, description: '', era: '', icon: '' } }))
      expect(snap!.objective.title.length).toBe(120)
  })
84 
  it('caps the timeline length and coerces a bad valence to neutral', () => {
      const many = Array.from({ length: 80 }, (_, i) => ({ id: `e${i}`, valence: 'sideways' }))
      const snap = sanitizeSnapshot(validRaw({ timeline: many }))
      expect(snap!.timeline.length).toBe(50)
      expect(snap!.timeline[0].valence).toBe('neutral')
  })
91 
  it('drops a roll with no named outcome', () => {
      expect(sanitizeSnapshot(validRaw({ bestRoll: { diceRoll: 12 } }))!.bestRoll).toBeNull()
  })
95 
  it('filters non-string chronicle paragraphs', () => {
      const snap = sanitizeSnapshot(validRaw({ chronicle: { title: 'T', paragraphs: ['ok', 123, '', 'fine'] } }))
      expect(snap!.chronicle).toEqual({ title: 'T', paragraphs: ['ok', 'fine'] })
  })
100})