Disclose the swing multipliers — a code-level reading (PR #192)

What changed, and why

The reveal equation showed which levers bent a turn's swing but not by how much. It named the anachronism wager (⚡) and the causal chain (⏳), yet the two biggest scalers — craft and momentum — were off-screen entirely. A vague-graded Success quietly shrank to about 40% of the swing it earned (×0.4) with nothing on screen to account for it, so "+22 → +9%" read as random and a sharp-looking move could pay almost nothing for no visible reason (issue #184).

This change writes the numeric multiplier onto each scaler token, so the printed equation now reconciles: a reader multiplies the base by the shown factors and lands on the final. The bug case reads "+22 ✒ vague ×0.4 → +9%" — the 60% cut is right there. Three small moves carry it: a factor on each scaler in the one shared token builder; momentum plumbed the last mile so the ledger and codex leaf can show it too; and the ledger detail strip folded onto that same builder, retiring its own parallel badges. The blast radius is the reveal surfaces only — no scoring math moves.

The single source: a factor on each scaler token

equationTokens is the one place every surface — the thread, the codex reveal leaf, the ledger — turns a turn's record into the labeled glyphs between base and final. The change appends the multiplier to the three SCALER tokens. Craft reads its two-sided factor (the gain table on a win, the inverted loss table on a miss, so a masterful loss shows the ×0.6 shield). Momentum shows the factor its level applies via momentumFactor, not the bare level — that's the number the equation multiplies by, and the level moves to the hover hint. Chain shows its exact carried decay factor. A short formatFactor trims each to at most two decimals so "×0.4" and "×1.45" read clean.

Each scaler appends ×factor; formatFactor trims it. Anachronism is untouched.

utils/swing-equation.ts · 95 lines

utils/swing-equation.ts95 lines · TypeScript

⋯ 51 lines hidden (lines 1–51)1/**
* The swing equation's amplifier tokens — the labeled glyphs that disclose WHY a
* turn's base swing became its final one: anachronism widened it (⚡), the causal
* chain decayed it (⏳), craft scaled it (✒), momentum lifted it (✦), the stake
* doubled it (⚑). Named ONCE here so every surface that prints the base → final
* equation renders the SAME breakdown from the SAME source — the thread
* (MessageHistory), the codex reveal leaf (LeafRipple), and the ledger detail
* (TimelineLedger) — so a lever can never explain a swing in one place and vanish
* in another (the gap behind "+22 → +9%, how?").
*
* The SCALER levers carry their numeric multiplier so the equation reconciles to
* the result (issue #184): `✒ vague ×0.4`, `✦ momentum ×1.3`, `⏳ diffuse ×0.41`.
* Without it a craft- or chain-shrunk swing showed a grade word but no magnitude,
* so "+22 → +9%" still read as random. Anachronism stays the lone QUALITATIVE
* token — its ⚡-pip count already encodes the tier and its factor is "qualitative
* on purpose" (server/utils/anachronism.ts), the dramatic wager kept off the math.
*/
18import { ANACHRONISM_HINT, ANACHRONISM_LABEL, type Anachronism } from '~/server/utils/anachronism'
19import { CHAIN_HINT, CHAIN_LABEL, type ChainStatus } from '~/utils/causal-chain'
20import { CRAFT_GAIN_FACTOR, CRAFT_LABEL, CRAFT_LOSS_FACTOR, type Craft } from '~/utils/craft'
21import { MOMENTUM_MAX, momentumFactor } from '~/utils/momentum'
22import { STAKE_HINT } from '~/utils/swing-bands'
23 
24/**
* The fields a swing's breakdown reads — all optional, so `Message`, `TimelineEvent`,
* and the ripple payload all satisfy it structurally (each carries the same turn-level
* record, `momentumAtSwing` included, so the breakdown renders identically on every
* surface). A lever that stayed idle this turn (in-period reach, at-hinge chain, sound
* craft, zero momentum) simply renders no token.
*/
31export interface SwingBreakdown {
  progressChange?: number
  anachronism?: Anachronism
  causalChain?: ChainStatus
  craft?: Craft
  momentumAtSwing?: number
  staked?: boolean
38}
39 
40export interface EquationToken {
  kind: 'anachronism' | 'chain' | 'craft' | 'momentum' | 'staked'
  label: string
  hint: string
44}
45 
46/**
* The amplifier tokens between the base and final swing, each a labeled glyph carrying
* its own hover hint for what it did. Emitted in the order the server applies them
* (anachronism → chain → craft → momentum → stake), so the printed equation reads
* left-to-right as the math ran; absent levers drop their token.
*/
52export function equationTokens(m: SwingBreakdown): EquationToken[] {
  const tokens: EquationToken[] = []
  if (m.anachronism && m.anachronism !== 'in-period') {
      const pips = m.anachronism === 'impossible' ? '⚡⚡⚡' : m.anachronism === 'far-ahead' ? '⚡⚡' : '⚡'
      tokens.push({ kind: 'anachronism', label: `${pips} ${ANACHRONISM_LABEL[m.anachronism].toLowerCase()}`, hint: ANACHRONISM_HINT[m.anachronism] })
  }
  if (m.causalChain && m.causalChain.tier !== 'at-hinge') {
      tokens.push({ kind: 'chain', label: `⏳ ${CHAIN_LABEL[m.causalChain.tier].toLowerCase()} ${formatFactor(m.causalChain.factor)}`, hint: CHAIN_HINT[m.causalChain.tier] })
  }
  // Craft drives the magnitude on BOTH signs (issue #166): on a gain it banks more
  // (or less) of the band the roll earned; on a loss it works INVERTED — good craft
  // shields the blow, poor craft deepens it. Skip the neutral 'sound' (no tilt) and a
  // zero swing (nothing to attribute).
  if (m.progressChange !== undefined && m.progressChange !== 0 && m.craft && m.craft !== 'sound') {
      const grade = CRAFT_LABEL[m.craft].toLowerCase()
      // The factor mirrors the server's two-sided craft amplifier: a gain banks
      // CRAFT_GAIN_FACTOR of the band, a loss is bent by CRAFT_LOSS_FACTOR. Sign of
      // the final swing == sign at the craft step (every later factor is positive).
      const factor = m.progressChange > 0 ? CRAFT_GAIN_FACTOR[m.craft] : CRAFT_LOSS_FACTOR[m.craft]
      tokens.push({
          kind: 'craft',
          label: `✒ ${grade} ${formatFactor(factor)}`,
          hint: m.progressChange > 0
              ? `a ${grade} dispatch scales the gain it earned — craft drives the swing`
              : `a ${grade} dispatch bends the loss it took — good craft shields it, poor craft deepens it`
      })
  }
  // Momentum is the other gains-only amplifier (the arc meter): show it whenever it
  // lifted this turn, so the printed equation reconciles to the result (issue #62).
  // The label is the MULTIPLIER it applied (momentumFactor of the level), not the bare
  // level — that's the number the equation multiplies by; the level rides in the hint.
  if (m.progressChange !== undefined && m.progressChange > 0 && m.momentumAtSwing && m.momentumAtSwing >= 1) {
      tokens.push({ kind: 'momentum', label: `✦ momentum ${formatFactor(momentumFactor(m.momentumAtSwing))}`, hint: `momentum ${m.momentumAtSwing} of ${MOMENTUM_MAX} — a coherent arc amplifies every gain` })
  }
  if (m.staked) tokens.push({ kind: 'staked', label: '⚑ staked', hint: STAKE_HINT })
  return tokens
88}
89 
90/** A swing multiplier as the player reads it in the equation — `×` then the factor
*  trimmed to at most two decimals with trailing zeros dropped (×0.4, ×1.2, ×0.41),
*  so `base × factor` reads clean and reconciles to the shown final. */
93function formatFactor(factor: number): string {
  return `×${Number(factor.toFixed(2))}`
95}

Momentum, carried the last mile to the ledger

Momentum already rode the thread's Message, which is why the thread could show it. The ledger event and the ripple payload never carried it, so the Spine and the codex leaf showed nothing. This adds momentumAtSwing to TimelineEvent and threads it through every carrier: the ripple frame that lands a resolved turn onto the ledger node, both addTimelineEvent sites, the snapshot and draft builders, and the two saved-run contracts. So live, end-screen, and reloaded runs disclose the same breakdown.

The new TimelineEvent field, and the ripple frame copying it onto the ledger payload.

stores/game.ts · 2354 lines

stores/game.ts2354 lines · TypeScript

⋯ 52 lines hidden (lines 1–52)1import { defineStore } from 'pinia'
2import type { GameObjective, ObjectiveSteer } from '~/server/utils/objectives'
3import type { Pack } from '~/server/utils/packs'
4import type { GroundedFigure } from '~/server/utils/figure-grounding'
5import { formatContactMoment, type ContactMoment } from '~/utils/contact-moment'
6import type { FigureSuggestion } from '~/server/utils/figure-suggester'
7import type { ChronicleEntry } from '~/server/utils/openai'
8import type { FigureStudy, ArchiveLookup } from '~/server/utils/prompt-builder'
9import type { Anachronism } from '~/server/utils/anachronism'
10import { chainStatus, type ChainStatus } from '~/utils/causal-chain'
11import type { Craft } from '~/utils/craft'
12import type { Continuity } from '~/utils/continuity'
13import type { DiceOutcome } from '~/utils/dice'
14import { generateGameSummary, rateEfficiency, type GameSummary } from '~/utils/game-summary'
15import { TOTAL_MESSAGES, MAX_PROGRESS_SWING, MAX_PROGRESS } from '~/utils/game-config'
16import { RUN_SNAPSHOT_VERSION, RUN_DRAFT_VERSION, type RunSnapshot, type RunDraft } from '~/utils/run-snapshot'
17 
18export type Valence = 'positive' | 'negative' | 'neutral'
19 
20/**
* A historical figure the player has reached out to. Figures are freeform — the
* player can write to anyone, in any era. The AI infers each figure's era and a
* short descriptor on first contact, which we cache here for the UI.
*/
25export interface HistoricalFigure {
  name: string
  era: string
  descriptor: string
29}
30 
31/**
* Timeline Ledger entry — a single recorded change to history.
*
* The ledger is the heart of the game: every resolved turn appends one entry
* describing how the world bent, so the player literally watches the timeline
* rewrite itself as they play.
*/
38export interface TimelineEvent {
  id: string
  figureName: string
  era: string
  headline: string
  detail: string
  diceRoll: number
  diceOutcome: DiceOutcome
  progressChange: number
  /** The engine's swing BEFORE the anachronism amplifier — shown so the player
   *  can see exactly what their wager did ("+8 ⚡ far-ahead → +11%"). */
  baseProgressChange?: number
  valence: Valence
  /** How anachronistic the player's nudge was — it widened this swing. */
  anachronism?: Anachronism
  /** How far this landed from the nearest foothold — it decayed this swing. */
  causalChain?: ChainStatus
  /** The Judge's grade of the dispatch that caused this change. */
  craft?: Craft
  /** The PRE-turn momentum that amplified this swing — the Spine reads it to show
   *  the ✦ momentum factor in the reveal equation, the same as the thread. */
  momentumAtSwing?: number
  /** Signed year of the intervention, when the contact was grounded. */
  whenSigned?: number
  /** True when this was the run's staked last stand (doubled swing). */
⋯ 1482 lines hidden (lines 63–1544)63    staked?: boolean
  timestamp: Date
65}
66 
67/**
* 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.
*/
72export interface Message {
  text: string
  sender: 'user' | 'ai' | 'system'
  timestamp: Date
  figureName?: string
  /** The figure's Wikipedia portrait (the picture shown at selection), snapshotted
   *  at send time so the reply leaf can show it. Absent when the figure has no
   *  Wikipedia image — the reply leaf then falls back to the monogram. */
  figureThumbnail?: 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
105}
106 
107export type GameStatus = 'playing' | 'victory' | 'defeat'
108 
109/** The two deferred turn writes, as the exact payloads their store actions take. */
110type AIMessagePayload = Partial<Message> & { text: string; sender: 'ai' }
111type RipplePayload = Omit<TimelineEvent, 'id' | 'timestamp' | 'valence'> & { valence?: Valence; timestamp?: Date }
112 
113/**
* A resolved-but-not-yet-revealed turn — held between `resolveTurn` (the network
* round-trip, the Sending leaf) and the conductor's per-leaf commits
* (`commitReveal` on the Dice leaf, `commitRipple` on the Ripple leaf). It decouples
* DATA-presence from the timing of the animation/SFX-bearing writes, so the
* page-by-page reveal can fire each store write at its own leaf — preserving the
* soundscape's "write == beat" lockstep (and every component's animate-on-change)
* for free. Holds plain payloads, never the response type: the deferred writes are
* exactly the ones `sendMessage` makes inline today.
*/
123export interface PendingTurn {
  epoch: number
  target: string
  sentWhen: number | null
  ledgerBefore: number
  aiMessage: AIMessagePayload
  ripple: RipplePayload | null
  progressChange: number | undefined
  momentum: number
  /** Precomputed at resolve (from the shared win/lose rule) so the conductor can
   *  route the Ripple leaf straight to the End screen on a terminal turn — the same
   *  verdict the live commit will set, so the two can never diverge. */
  terminal: boolean
  /** The Chronicle/suggestion re-narration, fired EARLY (at resolve, leaf II) on the
   *  animated path so it composes during the III→VI reading and is ready by VII —
   *  stashed here so commitRipple's two-beat persistence can re-save once it lands.
   *  Null on the inline (!animate) path, where commitRipple fires it against live state. */
  refresh?: Promise<void> | null
  /** Streaming: resolves once the WHOLE turn (reply + ripple + final) has landed in
   *  this pending turn — or it was blocked/errored. The conductor's commits await it,
   *  so the reveal can START on the early `dice` frame while the slow Character +
   *  Timeline calls finish; reaching a commit before its data arrived simply waits
   *  here (a graceful micro-state), never an empty leaf. */
  ready: Promise<void>
  /** True once the whole turn has landed (the `final` frame). The commits skip the
   *  `await ready` when this is set, so they run SYNCHRONOUSLY in the common case (and
   *  in tests / the inline path) — an async fn with no await runs its body in the same
   *  tick, preserving the "state present the moment the commit is called" contract. */
  resolved: boolean
  /** Set by a moderation block / failure mid-stream (after the early reveal): the
   *  store has already refunded + bannered, so the commits must NOT write and the
   *  conductor halts the reveal back to the dispatch. */
  blocked: boolean
156}
157 
158/**
* 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.
*/
165type 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
      }
  }
213 
214const RATE_LIMIT_MS = 1000 // message cooldown window, in ms
215 
216// Turn-reveal pacing. A resolved turn releases its beats one at a time — a beat of
217// suspense, then the die lands and the figure's reply writes itself in, then the
218// timeline shift, then the ledger node — so the resolution reads as one conducted
219// moment instead of everything firing in the same tick. Each component already
220// animates when its own slice of state changes; sequencing the WRITES sequences the
221// animations, with no component coordination. Tuned so the swing lands with the
222// reply's own "ripple" line (~0.55s into its staged reveal).
223export const REVEAL = { suspense: 450, swing: 550, node: 250 } as const
224const wait = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms))
225/** 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. */
228function canAnimateReveal(): boolean {
  return typeof window !== 'undefined'
      && typeof window.matchMedia === 'function'
      && !window.matchMedia('(prefers-reduced-motion: reduce)').matches
232}
233 
234function valenceOf(progressChange: number): Valence {
  if (progressChange > 0) return 'positive'
  if (progressChange < 0) return 'negative'
  return 'neutral'
238}
239 
240/** The single win/lose rule. Shared by `resolveGameStatus` (the live flip at
*  commitRipple) and the resolve-time `terminal` precompute, so a turn's verdict
*  and any epilogue framing derived from it can never diverge. Mirrors the original
*  resolveGameStatus exactly: victory at/over the cap, else defeat once the messages
*  are spent, else still playing. */
245function deriveStatus(progress: number, remaining: number): GameStatus {
  if (progress >= MAX_PROGRESS) return 'victory'
  if (remaining <= 0) return 'defeat'
  return 'playing'
249}
250 
251/** Formats a signed timeline year (AD positive, BCE negative) for display. */
252export function formatContactYear(signed: number): string {
  return signed < 0 ? `${-signed} BC` : `${signed}`
254}
255 
256/** The landed ledger as {era, headline} for the suggester's altered-timeline brief
*  (issue #131) — the server bounds + caps it. Drops changes without a headline. */
258function ledgerForSuggester(events: TimelineEvent[]): { era: string; headline: string }[] {
  return events.filter(e => e.headline).map(e => ({ era: e.era, headline: e.headline }))
260}
261 
262/** Human lifespan line for a grounded figure, e.g. "69 BC – 30 BC" or "1942 – present". */
263function 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
267}
268 
269/** 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. */
271function 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
274}
275 
276/** True when a $fetch error is a 503 / at-capacity — the spend cap paused new
*  runs (distinct from the per-device 402 paywall). */
278function 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
281}
282 
283export type ContactLiveness = 'ok' | 'before-birth' | 'after-death' | 'living' | 'unresolved' | 'unknown'
284 
285/**
* A replay seed (issue #89) — when a player starts a run from a shared run's captured
* objective. It carries the objective to seed (verbatim, no generation), the SOURCE run's
* public share token (rides along to /api/run-save to stamp the lineage pointer), and the
* source's display name at seed time (for the "remixed from" credit shown before/after the
* run; the public page re-derives the credit live, honoring the source's current opt-in).
*/
292export interface ReplaySeed {
  objective: GameObjective
  sourceToken: string
  sourceAttribution: string | null
296}
297 
298/**
* Game Store — core state for a session of freeform timeline editing.
*/
301export 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,
      suggestionsSeq: 0,
      groundingSeq: 0,
      // The current run's id — lazily minted on the run's first server call and
      // cleared by resetGame so each run gets a fresh one. Tags every AI call
      // (via the x-run-id header) so the gateway's cost telemetry groups per
      // run: the GTM cost instrument.
      runId: null as string | null,
      // The in-flight begin-run, so concurrent first-calls of a run share one
      // mint (one POST /api/run, one runs row) instead of racing two. Cleared
      // by resetGame. (Vue leaves a Promise unproxied, so awaiting it is safe.)
      runIdInflight: null as Promise<string> | null,
      // True once this run's snapshot is durably saved (POST /api/run-save returned
      // saved). Gates the end-screen Share affordance (issue #88) so it appears only for
      // a run that actually exists server-side to share — never for a degraded local id.
      // Reset per run.
      runSnapshotSaved: false,
      // outOfRuns gates the mission screen's paywall (set when a commit is
      // refused with 402). The run packs offered there are loaded into `packs`.
      outOfRuns: false,
      // atCapacity gates the "at capacity" notice (set when a commit is refused
      // with 503 because the global spend cap paused new runs).
      atCapacity: false,
      packs: [] as Pack[],
      // The device's run balance, for the header gauge + account popover. null
      // until first loaded (GET /api/balance); the run-commit response also
      // refreshes it so the gauge stays live without a second round-trip.
      runsRemaining: null as number | null,
      freeRuns: 1,
      deviceRef: '' as string,
      // Account state (from /api/balance): the signed-in email, and whether the
      // current user is anonymous (→ must sign in before buying). Drives the
      // account UI + the sign-in-to-buy gate. false/null in device-fallback mode.
      accountEmail: null as string | null,
      accountAnonymous: false,
      // Referral credits earned from sharing (issue #96), from /api/balance — the
      // passive "+N from sharing" tally in the account popover. Pull-based, never a ping.
      referralCredits: 0,
      referralCount: 0,
      // The account's generated, reroll-only username (#117), from /api/profile. null
      // until first loaded; lazily minted server-side on that first read. Reroll is the
      // only way to change it — there is no typed-name path anywhere.
      username: null as string | null,
      // The run-packs sales modal — opened on demand (header) or automatically
      // when a commit is refused for being out of runs.
      buyModalOpen: false,
      // A one-shot notice after returning from Stripe Checkout ('success' shows a
      // credited confirmation; 'cancel' a gentle "no charge" note). Cleared by the UI.
      purchaseNotice: null as 'success' | 'cancel' | null,
      currentObjective: null as GameObjective | null,
      // Set when this run is a REPLAY of a shared run's objective (issue #89): seeded
      // verbatim from the public projection, no generation. Survives chooseObjective so
      // it can stamp the lineage pointer at save time and credit the source on the end
      // screen; cleared by resetGame (a fresh "new timeline" carries no lineage).
      replayState: null as ReplaySeed | null,
      objectiveProgress: 0,
      // The run's high-water mark (0..MAX_PROGRESS): the highest objectiveProgress ever
      // reached this run. Tracked so the end screen can show "peaked at X%" when a run
      // loses ground from its peak — classically a staked final dispatch that crit-fails
      // to 0% — instead of the floored final % erasing the player's real effort (#129).
      peakProgress: 0,
      // The run-level momentum meter (0..MOMENTUM_MAX): a coherent arc compounds its
      // gains amplifier; a reset or catastrophe shatters it back to 0 (issue #62).
      momentum: 0,
      timelineEvents: [] as TimelineEvent[],
      figures: [] as HistoricalFigure[],
      activeFigureName: '' as string,
      // Grounding for the active contact: real facts + the chosen year to reach them.
      figureGrounding: null as GroundedFigure | null,
      groundingLoading: false,
      contactWhen: null as number | null,
      /** Optional sub-year refinement of contactWhen — display/prompt flavor
       *  only; every mechanic keeps doing arithmetic on the YEAR (issue #32). */
      contactMoment: null as ContactMoment | null,
      // Era-relevant figure suggestions for the current objective (the on-ramp).
      figureSuggestions: [] as FigureSuggestion[],
      suggestionsLoading: false,
      suggestionsFor: '' as string,
      // The objective title an initial load is in flight FOR (''=idle). Set the moment
      // loadSuggestions begins so the prefetch fired at chooseObjective and the later
      // FigurePicker onMounted call can't both hit the suggester for one objective.
      suggestionsLoadingFor: '' 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 committed-ledger length the current `chronicle` was generated for. The
      // Chronicle PAGE shows a loader (not the stale prior telling) until this
      // matches the live ledger — under the explicit-Continue model a fast player can
      // reach the page before the ~10s compose finishes, and a one-turn-stale telling
      // on a focused page reads as disjointed.
      chronicleForLedgerLen: 0,
      // Live streaming buffer: the telling as it's being WRITTEN, delta by delta,
      // so the Chronicle page (and the End screen) can show the prose appearing in
      // realtime instead of a static loader. `chronicleStreamLen` is the ledger
      // length the active stream narrates — a render only shows the live buffer
      // when it matches the live ledger (never a stale prior turn's stream).
      chronicleStream: '',
      chronicleStreaming: false,
      chronicleStreamLen: 0,
      // The run's epilogue — the TERMINAL telling carrying the verdict — is being
      // written. Set when the final turn fires its refresh and cleared when that
      // telling lands or the refresh fails. Distinct from chronicleLoading (any
      // refresh): it lets the end screen show "the final account…" instead of
      // presenting the prior turn's stale, pre-ending telling as the epilogue.
      epiloguePending: false,
      // A turn resolved by `resolveTurn` but not yet revealed leaf-by-leaf by the
      // conductor — its deferred writes wait here for commitReveal/commitRipple.
      // Null except mid-reveal; the legacy `sendMessage` path never touches it.
      pendingTurn: null as PendingTurn | null,
      // 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
  }),
445 
  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
      },
457 
      /**
       * 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'
          )
      },
468 
      /** Total progress, net of setbacks, the player has clawed back. */
      gameSummary(): GameSummary {
          return generateGameSummary(this)
      },
473 
      /**
       * 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'
      },
495 
      /** Can the chosen contact + when actually be reached? */
      canContact(): boolean {
          return this.contactLiveness === 'ok' || this.contactLiveness === 'unknown'
      },
500 
      /**
       * 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
      },
512 
      /**
       * 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
      },
528 
      /**
       * 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)
      }
  },
544 
  actions: {
      // ---------- message helpers ----------
      addUserMessage(text: string, figureName?: string) {
          if (this.gameStatus !== 'playing') return
          this.messageHistory.push({
              text,
              sender: 'user',
              timestamp: new Date(),
              figureName
          })
      },
556 
      addAIMessage(text: string, figureName?: string) {
          this.messageHistory.push({
              text,
              sender: 'ai',
              timestamp: new Date(),
              figureName
          })
      },
565 
      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,
              figureThumbnail: messageData.figureThumbnail,
              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
          })
      },
590 
      // ---------- 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 })
          }
      },
601 
      setActiveFigure(name: string) {
          this.activeFigureName = name
      },
605 
      /**
       * 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
      },
623 
      /**
       * 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
          }
      },
671 
      /** 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
      },
700 
      /** 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() }
      },
706 
      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
      },
712 
      setContactMoment(moment: ContactMoment | null) {
          this.contactMoment = moment
      },
716 
      /**
       * 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
733 
          // 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
          }
      },
770 
      /**
       * 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. The result stays put
       * across figure changes while you compose one dispatch, then clears the moment
       * that dispatch is sent (`clearArchive`) — each turn starts from fresh research.
       */
      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
          }
      },
805 
      /**
       * 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
          // Prefetch already running for this objective (chooseObjective started it;
          // FigurePicker's onMounted is calling again) — let the one in flight finish.
          if (this.suggestionsLoadingFor === objective.title) return
822 
          const epoch = this.runEpoch
          const seq = ++this.suggestionsSeq
          this.suggestionsLoadingFor = objective.title
          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
                      },
                      // Usually empty here (the initial load fires at run start), but a
                      // mid-run remount carries the ledger so even the first paint is
                      // timeline-aware. refreshSuggestions re-sends it after each change.
                      ledger: ledgerForSuggester(this.timelineEvents)
                  }
              }) as { success?: boolean; suggestions?: FigureSuggestion[]; blocked?: boolean; reason?: string }
              if (epoch !== this.runEpoch || seq !== this.suggestionsSeq) 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 || seq !== this.suggestionsSeq) 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 && seq === this.suggestionsSeq) this.suggestionsLoading = false
              // Always release the in-flight marker for this load, even if a refresh
              // superseded it — otherwise a future load for this objective is blocked.
              if (this.suggestionsLoadingFor === objective.title) this.suggestionsLoadingFor = ''
          }
      },
864 
      /**
       * Re-narrate the figure-suggestion blurbs against the altered timeline (issue
       * #131). The suggester is re-run with the landed ledger so a blurb stops
       * asserting a fate the player has already overturned. Fired non-blocking after
       * a landed change, like refreshChronicle — the turn reveal waits on neither.
       * A failed, blocked, or curated-fallback refresh KEEPS the prior list: a
       * populated panel never blanks, and a model outage never regresses good
       * era-specific picks to the generic fallback.
       *
       * loadSuggestions and refreshSuggestions share `suggestionsSeq` so the newest
       * call of EITHER wins. Whichever holds the latest seq therefore owns settling
       * `suggestionsLoading` + `suggestionsFor` (in the finally), so a refresh fired
       * while the initial load is still in flight can never strand the skeletons.
       */
      async refreshSuggestions(ledgerOverride?: TimelineEvent[]): Promise<void> {
          const objective = this.currentObjective
          if (!objective) return
          const epoch = this.runEpoch
          const seq = ++this.suggestionsSeq
          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
                      },
                      ledger: ledgerForSuggester(ledgerOverride ?? this.timelineEvents)
                  }
              }) as { success?: boolean; suggestions?: FigureSuggestion[]; fallback?: boolean; blocked?: boolean }
              if (epoch !== this.runEpoch || seq !== this.suggestionsSeq) return
              // Only a genuine, model-built list may overwrite the panel — a curated
              // fallback (model unavailable) or an empty/blocked result keeps the
              // better existing suggestions rather than regressing to generic names.
              if (res?.success && res.suggestions?.length && !res.fallback) {
                  this.figureSuggestions = res.suggestions
              }
              this.suggestionsFor = objective.title
          } catch (error) {
              if (epoch !== this.runEpoch || seq !== this.suggestionsSeq) return
              console.error('Failed to refresh figure suggestions:', error)
              // Keep the prior list — a failed refresh never blanks the panel.
          } finally {
              // This refresh bumped the shared seq; if it's still the latest, it owns
              // the resolution — clear a loading flag an invalidated in-flight load
              // can no longer clear itself (the stuck-skeletons race).
              if (epoch === this.runEpoch && seq === this.suggestionsSeq) this.suggestionsLoading = false
          }
      },
916 
      // ---------- 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,
              momentumAtSwing: evt.momentumAtSwing,
              whenSigned: evt.whenSigned,
              staked: evt.staked,
              timestamp: evt.timestamp ?? new Date()
          })
      },
941 
      // ---------- the living chronicle (Layer 3) ----------
      /**
       * Re-narrates the Chronicle from the freshly-bent timeline. Fired
       * non-blocking after a resolved turn (and at game end): the dice/progress
       * reveal never waits on prose. The WHOLE account is rewritten each turn —
       * a later change can re-frame how earlier events read.
       * Graceful: a failed refresh keeps the prior telling, so the panel never
       * blanks; an empty timeline clears it (nothing to chronicle yet).
       */
      async refreshChronicle(override?: { ledger: TimelineEvent[]; progress: number; status: GameStatus }): Promise<void> {
          // The conductor can fire this at resolve with the resolved-but-not-yet-committed
          // snapshot (ledger/progress/status) so the telling narrates the very turn it
          // is about; the legacy tail passes nothing and reads the live, just-committed
          // state. Byte-identical when no override is given.
          const ledger = override?.ledger ?? this.timelineEvents
          const progress = override?.progress ?? this.objectiveProgress
          const status = override?.status ?? this.gameStatus
          if (!ledger.length) {
              this.chronicle = null
              this.chronicleForLedgerLen = 0
              this.chronicleStream = ''
              this.chronicleStreaming = false
              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
          // True only while THIS issued refresh is still the newest (and same run).
          const current = () => epoch === this.runEpoch && seq === this.chronicleSeq
          this.chronicleLoading = true
          try {
              const res = await $fetch('/api/chronicle', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  // The real endpoint streams the prose as SSE; ask for the raw body
                  // so we can render it being written. A non-streaming mock ignores
                  // this and returns a plain { success, chronicle } object — handled
                  // below — so tests and the e2e suite need no streaming machinery.
                  responseType: 'stream',
                  body: {
                      objective: this.currentObjective,
                      status,
                      progress,
                      timeline: ledger.map(e => ({
                          era: e.era,
                          figureName: e.figureName,
                          headline: e.headline,
                          detail: e.detail,
                          progressChange: e.progressChange
                      }))
                  }
              }) as unknown
997 
              const isStream = !!res && typeof (res as ReadableStream<Uint8Array>).getReader === 'function'
              if (isStream) {
                  // SSE path: accumulate prose deltas into the live buffer (so the
                  // page shows it being written), then settle on the terminal frame.
                  if (!current()) { try { await (res as ReadableStream).cancel() } catch { /* already gone */ } return }
                  this.chronicleStream = ''
                  this.chronicleStreaming = true
                  this.chronicleStreamLen = ledger.length
                  const reader = (res as ReadableStream<Uint8Array>).getReader()
                  const decoder = new TextDecoder()
                  let buf = ''
                  let final: ChronicleEntry | null = null
                  while (true) {
                      const { done, value } = await reader.read()
                      if (done) break
                      // A newer refresh superseded this one — stop, drop, free the
                      // connection. The newest stream owns the buffer now.
                      if (!current()) { try { await reader.cancel() } catch { /* noop */ } return }
                      buf += decoder.decode(value, { stream: true })
                      let nl: number
                      while ((nl = buf.indexOf('\n\n')) >= 0) {
                          const frame = buf.slice(0, nl); buf = buf.slice(nl + 2)
                          const dataLine = frame.split('\n').map(l => l.trim()).find(l => l.startsWith('data:'))
                          if (!dataLine) continue
                          let msg: { t?: string; x?: string; chronicle?: ChronicleEntry } | null = null
                          try { msg = JSON.parse(dataLine.slice(5).trim()) } catch { continue }
                          if (msg?.t === 'd' && typeof msg.x === 'string') {
                              if (current() && this.chronicleStreamLen === ledger.length) this.chronicleStream += msg.x
                          } else if (msg?.t === 'final' && msg.chronicle) {
                              final = msg.chronicle
                          } // t:'error' → leave final null; the prior telling is kept
                      }
                  }
                  if (!current()) return
                  if (!final) {
                      // No SSE `final` frame — tolerate a plain { success, chronicle }
                      // body that arrived as a stream (a non-streaming mock or proxy:
                      // responseType:'stream' returns the raw body for ANY response).
                      // The leftover buffer holds the whole un-framed body.
                      try {
                          const j = JSON.parse(buf.trim()) as { success?: boolean; chronicle?: ChronicleEntry }
                          if (j?.chronicle && Array.isArray(j.chronicle.paragraphs)) final = j.chronicle
                      } catch { /* not JSON either — keep the prior telling */ }
                  }
                  if (final && Array.isArray(final.paragraphs) && final.paragraphs.length) {
                      this.chronicle = final
                      this.chronicleForLedgerLen = ledger.length
                  }
              } else {
                  // Plain JSON path (the test/e2e mock, or any non-streamed response).
                  const json = res as { success?: boolean; chronicle?: ChronicleEntry }
                  if (!current()) return
                  if (json?.success && json.chronicle) {
                      this.chronicle = json.chronicle
                      // Stamp the ledger length this telling narrates, so the Chronicle
                      // page can tell a current telling from a stale prior one.
                      this.chronicleForLedgerLen = ledger.length
                  }
              }
          } catch (error) {
              if (!current()) return
              console.error('Failed to refresh the chronicle:', error)
              // Keep the prior chronicle — a failed refresh never blanks the panel.
          } finally {
              if (current()) {
                  this.chronicleLoading = false
                  this.chronicleStreaming = false
              }
          }
      },
1068 
      // ---------- simple setters ----------
      setLoading(loading: boolean) { this.isLoading = loading },
      setError(error: string | null) { this.error = error },
      clearModerationNotice() { this.moderationNotice = null },
      clearArchiveNotice() { this.archiveNotice = null },
      // Reset the Archive lookup panel — both the last result and any block banner.
      // Fired on each dispatch so a new turn starts from fresh research, not the
      // previous turn's stale lookup.
      clearArchive() { this.archiveResult = null; this.archiveNotice = null },
1078 
      // ---------- rate limiting ----------
      checkRateLimit(): boolean {
          const now = Date.now()
          if (this.lastMessageTime && (now - this.lastMessageTime) < RATE_LIMIT_MS) return false
          return true
      },
1085 
      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)
      },
1093 
      // ---------- counter & status ----------
      decrementMessages() {
          if (this.remainingMessages > 0) this.remainingMessages--
      },
1098 
      /**
       * 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
              }
          }
      },
1115 
      applyProgress(progressChange: number) {
          this.objectiveProgress = Math.max(0, Math.min(MAX_PROGRESS, this.objectiveProgress + progressChange))
          this.peakProgress = Math.max(this.peakProgress, this.objectiveProgress)
      },
1120 
      /**
       * 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() {
          // The single win/lose rule lives in `deriveStatus` (shared with the
          // resolve-time precompute). Only ever flips TO a terminal status —
          // never back to playing — so an already-resolved run stays resolved.
          const status = deriveStatus(this.objectiveProgress, this.remainingMessages)
          if (status !== 'playing') this.gameStatus = status
      },
1136 
      /** The player-facing reason a contact is currently blocked (unresolved /
       *  before-birth / living / after-death) — pure derivation, lifted out of
       *  sendMessage's guard so the action reads as flow, not message copy. */
      contactBlockedMessage(target: string): string {
          const who = this.figureGrounding?.name || target
          return this.contactLiveness === 'unresolved'
              ? (this.figureGrounding?.transient
                  ? `Couldn't reach the record to verify "${target}" — try again in a moment.`
                  : `No historical record found for "${target}" — reach for a real figure (pick a match as you type).`)
              : this.contactLiveness === 'before-birth'
                  ? `${who} isn't born yet in that year — choose a later moment to reach them.`
                  : this.contactLiveness === 'living'
                      ? (this.figureGrounding?.born
                          ? `${who} is still living — Everwhen only reaches figures from history.`
                          : `${who} couldn't be dated — Everwhen can only reach figures it can place in history.`)
                      : `${who} has died by that year — choose an earlier moment to reach them.`
      },
1154 
      /** Shape the /api/send-message request body — pure field assembly, lifted out
       *  of sendMessage so the action's flow isn't buried under plumbing. `sentWhen`/
       *  `sentMoment` are captured at send time (the slider can move mid-request). */
      buildSendBody(text: string, target: string, sentWhen: number | null, sentMoment: ContactMoment | null, stake: boolean) {
          return {
              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)
          }
      },
1190 
      // ---------- 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
1208 
          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) {
              this.setError(this.contactBlockedMessage(target))
              return false
          }
1223 
          this.setError(null)
          this.moderationNotice = null
          this.clearArchive()
          this.setActiveFigure(target)
          this.addUserMessage(text, target)
          this.decrementMessages()
          this.setLoading(true)
          this.lastMessageTime = Date.now()
1232 
          // 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
          // The figure's Wikipedia portrait shown at selection (if any) — see resolveTurn.
          const sentThumbnail = this.figureGrounding?.thumbnail
          let resolved = false
          // Decide once whether to stagger the reveal (browser + motion allowed).
          const animate = canAnimateReveal()
1247 
          try {
              const response = await $fetch<SendMessageApiResponse>('/api/send-message', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: this.buildSendBody(text, target, sentWhen, sentMoment, stake)
              })
1254 
              if (epoch !== this.runEpoch) return false
1256 
              if (response?.success && response.data?.characterResponse) {
                  const { figure, characterResponse, diceRoll, diceOutcome, timeline } = response.data
1259 
                  if (figure?.name) {
                      this.registerFigure({
                          name: figure.name,
                          era: figure.era || '',
                          descriptor: figure.descriptor || ''
                      })
                  }
1267 
                  // ---- 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
                  }
1275 
                  // 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,
                      figureThumbnail: sentThumbnail,
                      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)
1303 
                  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
1320 
                      // 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,
                          momentumAtSwing: timeline.momentumAtSwing,
                          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()
              }
          }
1372 
          // 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 on-ramp blurbs re-narrate against the altered timeline (issue
              // #131), non-blocking like the chronicle — neither holds the reveal.
              void this.refreshSuggestions()
          }
          // The run just ended: persist it (best-effort) so it survives reload, then
          // re-save once the epilogue's telling lands — the immediate save guards
          // against that refresh failing, the second captures the final Chronicle.
          if (this.gameStatus === 'victory' || this.gameStatus === 'defeat') {
              // This turn's refresh writes the EPILOGUE — the terminal telling that
              // carries the verdict. Mark it pending so the end screen shows "the
              // final account…" instead of the prior turn's stale telling. Cleared
              // when the telling lands OR the refresh fails (refreshChronicle keeps
              // the prior telling on failure) — so the panel reveals or falls back,
              // never hanging on the loading state.
              if (refresh) {
                  this.epiloguePending = true
                  void refresh.finally(() => { if (epoch === this.runEpoch) this.epiloguePending = false })
              }
              void this.saveRunSnapshot()
              if (refresh) void refresh.finally(() => { void this.saveRunSnapshot() })
              // The terminal snapshot is the record now — drop the in-progress draft
              // so a reload can't resume a finished run (#152).
              void this.clearRunDraft()
          } else if (resolved) {
              // Still playing: autosave the live state (best-effort, fire-and-forget)
              // so a refresh or crash resumes exactly here (#152). The immediate save
              // guards against the chronicle refresh hanging; the post-refresh re-save
              // captures this turn's freshly-narrated Chronicle — same two-beat shape
              // as the terminal saveRunSnapshot above.
              void this.saveRunDraft()
              if (refresh) void refresh.finally(() => { void this.saveRunDraft() })
          }
          return resolved
      },
1415 
      /**
       * The conducted turn — the two-phase twin of `sendMessage`. It runs the SAME
       * gates + network round-trip, but instead of staggering the reveal itself with
       * `await wait()`, it holds the resolved turn in `pendingTurn` and lets the
       * client leaf conductor fire the animation/SFX-bearing writes leaf by leaf
       * (`commitReveal` on the Dice leaf, `commitRipple` on the Ripple leaf). So the
       * page-by-page reveal paces on the player's reading, never artificial waits,
       * while the soundscape's "write == beat" lockstep is preserved untouched.
       *
       * Returns `true` once a turn is RESOLVED and ready to reveal (animated path),
       * OR — under SSR / tests / reduced-motion (`!canAnimateReveal`) — once it has
       * committed atomically inline, exactly like `sendMessage`'s instant path, so
       * the store's "all turn state present the moment the promise resolves" contract
       * is unchanged. A blocked / failed send returns `false` (composer keeps words).
       */
      async resolveTurn(text: string, figureName?: string, opts?: { stake?: boolean }): Promise<boolean> {
          const target = (figureName ?? this.activeFigureName ?? '').trim()
          const stake = opts?.stake === true && this.canStake
1434 
          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) {
              this.setError(this.contactBlockedMessage(target))
              return false
          }
1449 
          this.setError(null)
          this.moderationNotice = null
          this.clearArchive()
          this.setActiveFigure(target)
          // Enqueue the player's line while the run is still 'playing' — addUserMessage
          // no-ops on a terminal status, and refundUnresolvedTurn would then splice the
          // wrong entry. No status flip happens before here (#Fix9).
          this.addUserMessage(text, target)
          this.decrementMessages()
          this.setLoading(true)
          this.lastMessageTime = Date.now()
1461 
          // Same staleness contract as sendMessage: a reset mid-flight bumps runEpoch,
          // so every write below finds no purchase (the response is dropped whole).
          const epoch = this.runEpoch
          const ledgerBefore = this.timelineEvents.length
          // Capture the contact year NOW (the slider can move while the request is in
          // flight) — the ledger must record the year this turn was SENT to.
          const sentWhen = this.contactWhen
          const sentMoment = this.contactMoment
          // The figure's Wikipedia portrait shown at selection (if any), captured NOW
          // so the reply leaf shows it even after the active figure changes mid-reveal.
          const sentThumbnail = this.figureGrounding?.thumbnail
          const animate = canAnimateReveal()
1474 
          // Streaming reveal (see PendingTurn.ready). The server emits the turn as SSE
          // frames (dice → reply → ripple → final), so the reveal STARTS on the early
          // `dice` frame while the slow Character + Timeline calls finish behind the
          // player reading the Judgment/Dice beats. resolveTurn resolves on the dice
          // frame (the conductor's data-ready); the rest streams into pendingTurn, and
          // the commits await `ready`. A non-streaming mock returns the old plain JSON,
          // converted to the same frames by applyPlain — so tests need no streaming.
          let releaseDice: () => void = () => {}
          let releaseReady: () => void = () => {}
          const diceReady = new Promise<void>((r) => { releaseDice = r })
          const ready = new Promise<void>((r) => { releaseReady = r })
          let dicedReleased = false
          let readyReleased = false
          const settleDice = () => { if (!dicedReleased) { dicedReleased = true; releaseDice() } }
          const settleReady = () => { if (!readyReleased) { readyReleased = true; pending.resolved = true; releaseReady() } }
1490 
          const pending: PendingTurn = {
              epoch, target, sentWhen, ledgerBefore,
              aiMessage: { text: '', sender: 'ai', figureName: target, figureThumbnail: sentThumbnail, timestamp: new Date() } as AIMessagePayload,
              ripple: null, progressChange: undefined, momentum: this.momentum, terminal: false,
              ready, resolved: false, blocked: false
          }
1497 
          // Refund + banner mid-stream, mirroring the old graceful-failure / thrown paths.
          const fail = (o: { blocked?: boolean; reason?: string; error?: string }) => {
              if (epoch !== this.runEpoch) { settleDice(); settleReady(); return }
              if (o.blocked) {
                  pending.blocked = true
                  this.moderationNotice = o.reason || 'That dispatch was blocked by content moderation and cannot be sent.'
              } else {
                  this.setError(o.error || 'History did not answer. Try again.')
              }
              this.refundUnresolvedTurn()
              this.setLoading(false)
              this.pendingTurn = null
              settleDice(); settleReady()
          }
1512 
          // Apply one parsed frame onto the pending turn (mutating the REACTIVE copy after
          // the dice frame publishes it, so the leaves fill live as data lands).
          const onFrame = (msg: Record<string, unknown> | null) => {
              if (!msg || epoch !== this.runEpoch) return
              const t = msg.t
              if (t === 'dice') {
                  Object.assign(pending.aiMessage, {
                      diceRoll: msg.diceRoll, diceOutcome: msg.diceOutcome,
                      naturalRoll: (msg.naturalRoll as number) ?? (msg.diceRoll as number),
                      rollModifier: (msg.rollModifier as number) ?? 0,
                      craft: msg.craft, craftReason: msg.craftReason, continuity: msg.continuity
                  })
                  this.pendingTurn = pending // the Judgment + Dice leaves can read now (early reveal)
                  settleDice()
                  return
              }
              const pt = this.pendingTurn
              if (!pt || pt.epoch !== epoch) return
              switch (t) {
                  case 'reply': {
                      pt.aiMessage.text = (msg.message as string) ?? ''
                      pt.aiMessage.characterAction = msg.action as string
                      break
                  }
                  case 'ripple': {
                      const pc = typeof msg.progressChange === 'number' ? (msg.progressChange as number) : 0
                      Object.assign(pt.aiMessage, {
                          timelineImpact: msg.detail, progressChange: msg.progressChange,
                          baseProgressChange: msg.baseProgressChange, momentumAtSwing: msg.momentumAtSwing,
                          anachronism: msg.anachronism, causalChain: msg.causalChain
                      })
                      pt.ripple = {
                          figureName: target,
                          era: (msg.era as string) || (this.currentObjective?.era ?? ''),
                          headline: msg.headline as string,
                          detail: msg.detail as string,
                          diceRoll: pt.aiMessage.diceRoll!,
                          diceOutcome: pt.aiMessage.diceOutcome!,
                          progressChange: pc,
                          baseProgressChange: msg.baseProgressChange as number | undefined,
                          valence: msg.valence as Valence,
                          anachronism: msg.anachronism as Anachronism | undefined,
                          causalChain: msg.causalChain as ChainStatus | undefined,
                          craft: pt.aiMessage.craft,
                          momentumAtSwing: msg.momentumAtSwing as number | undefined,
                          whenSigned: sentWhen ?? undefined,
                          staked: pt.aiMessage.staked
⋯ 795 lines hidden (lines 1560–2354)1560                        }
                      pt.progressChange = msg.progressChange !== undefined ? (msg.progressChange as number) : undefined
                      const newProgress = pt.progressChange !== undefined
                          ? Math.max(0, Math.min(MAX_PROGRESS, this.objectiveProgress + pt.progressChange))
                          : this.objectiveProgress
                      pt.terminal = deriveStatus(newProgress, this.remainingMessages) !== 'playing'
                      // Fire the Chronicle/suggestion re-narration from the resolved SNAPSHOT
                      // (the not-yet-committed node) so it composes during the reveal reading
                      // — animated path only (the inline path fires from commitRipple).
                      if (animate && pt.ripple) {
                          const node: TimelineEvent = {
                              ...pt.ripple,
                              id: `evt-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
                              valence: pt.ripple.valence ?? valenceOf(pt.ripple.progressChange),
                              timestamp: new Date()
                          }
                          const snapshot = {
                              ledger: [...this.timelineEvents, node],
                              progress: newProgress,
                              status: deriveStatus(newProgress, this.remainingMessages)
                          }
                          const refresh = this.refreshChronicle(snapshot)
                          void refresh
                          void this.refreshSuggestions(snapshot.ledger)
                          pt.refresh = refresh
                          if (pt.terminal) {
                              this.epiloguePending = true
                              void refresh.finally(() => { if (epoch === this.runEpoch) this.epiloguePending = false })
                          }
                      }
                      break
                  }
                  case 'final': {
                      pt.momentum = typeof msg.momentum === 'number' ? (msg.momentum as number) : this.momentum
                      pt.aiMessage.staked = msg.staked as boolean | undefined
                      if (pt.ripple) pt.ripple.staked = msg.staked as boolean | undefined
                      const fig = msg.figure as { name?: string; era?: string; descriptor?: string } | undefined
                      if (fig?.name) this.registerFigure({ name: fig.name, era: fig.era || '', descriptor: fig.descriptor || '' })
                      settleReady()
                      break
                  }
                  case 'blocked': fail({ blocked: true, reason: msg.reason as string }); break
                  case 'error': fail({ error: msg.error as string }); break
              }
          }
1605 
          // Convert the old plain `{ success, data }` JSON (a non-streaming mock) into the
          // same frame sequence, so unit/e2e mocks that return JSON keep working.
          const applyPlain = (res: SendMessageApiResponse | null) => {
              if (res?.success && res.data?.characterResponse) {
                  const d = res.data
                  onFrame({ t: 'dice', diceRoll: d.diceRoll, diceOutcome: d.diceOutcome, naturalRoll: d.naturalRoll, rollModifier: d.rollModifier, craft: d.craft, craftReason: d.craftReason, continuity: d.continuity })
                  onFrame({ t: 'reply', message: d.characterResponse.message, action: d.characterResponse.action })
                  if (d.timeline) onFrame({ t: 'ripple', headline: d.timeline.headline, detail: d.timeline.detail, era: d.timeline.era, progressChange: d.timeline.progressChange, baseProgressChange: d.timeline.baseProgressChange, momentumAtSwing: d.timeline.momentumAtSwing, valence: d.timeline.valence, anachronism: d.timeline.anachronism, causalChain: d.timeline.causalChain })
                  onFrame({ t: 'final', momentum: d.momentum, staked: d.staked, figure: d.figure })
              } else {
                  const failed = res && !res.success ? res.data : undefined
                  if (failed?.blocked) fail({ blocked: true, reason: failed.moderationReason })
                  else fail({ error: failed?.error })
              }
          }
1621 
          const consume = async (): Promise<void> => {
              try {
                  const res = await $fetch('/api/send-message', {
                      method: 'POST',
                      headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                      responseType: 'stream',
                      body: this.buildSendBody(text, target, sentWhen, sentMoment, stake)
                  }) as unknown
                  if (epoch !== this.runEpoch) { settleDice(); settleReady(); return }
                  const isStream = !!res && typeof (res as ReadableStream<Uint8Array>).getReader === 'function'
                  if (!isStream) { applyPlain(res as SendMessageApiResponse); return }
                  const reader = (res as ReadableStream<Uint8Array>).getReader()
                  const decoder = new TextDecoder()
                  let buf = ''
                  while (true) {
                      const { done, value } = await reader.read()
                      if (done) break
                      if (epoch !== this.runEpoch) { try { await reader.cancel() } catch { /* gone */ } settleDice(); settleReady(); return }
                      buf += decoder.decode(value, { stream: true })
                      let nl: number
                      while ((nl = buf.indexOf('\n\n')) >= 0) {
                          const frame = buf.slice(0, nl); buf = buf.slice(nl + 2)
                          const dataLine = frame.split('\n').map(l => l.trim()).find(l => l.startsWith('data:'))
                          if (!dataLine) continue
                          try { onFrame(JSON.parse(dataLine.slice(5).trim())) } catch { /* skip a partial/garbled frame */ }
                      }
                  }
                  // Stream ended. Normal completion / handled block → done. No frames at all
                  // → a plain-JSON body delivered as a stream. Some frames but no terminal
                  // (a dropped connection mid-turn) → refund, like the thrown path.
                  if (readyReleased || pending.blocked) return
                  if (!this.pendingTurn) {
                      try { applyPlain(JSON.parse(buf.trim())) } catch { fail({ error: 'History did not answer. Try again.' }) }
                  } else {
                      fail({ error: 'The timeline resisted your message. Please try again.' })
                  }
              } catch (error) {
                  if (epoch !== this.runEpoch) { settleDice(); settleReady(); return }
                  console.error('Error sending message:', error)
                  fail({ error: 'The timeline resisted your message. Please try again.' })
              }
          }
1664 
          if (!animate) {
              // SSR / tests / reduced-motion: drain the whole stream, then commit
              // atomically — the "all state present the moment resolveTurn resolves"
              // contract is unchanged.
              await consume()
              if (epoch !== this.runEpoch) return false
              if (pending.blocked || !this.pendingTurn) return false
              await this.commitReveal()
              await this.commitRipple()
              return pending.ripple != null
          }
1676 
          // Animated path: consume in the background; resolve on the `dice` frame so the
          // conductor reveals immediately while reply/ripple/final keep streaming in.
          void consume()
          await diceReady
          if (epoch !== this.runEpoch) return false
          if (pending.blocked || !this.pendingTurn) return false
          return true
      },
1685 
      /**
       * Reveal beat — the figure's reply writes itself in and the die lands
       * (`setLoading(false)` is the falling edge DiceRoller + the soundscape watch).
       * Fired by the conductor on the Dice leaf. A no-op once the run has moved on
       * (epoch guard), so a stale turn never lands in a fresh run.
       */
      async commitReveal(): Promise<boolean> {
          const p = this.pendingTurn
          if (!p || p.epoch !== this.runEpoch) return true // nothing to commit — benign
          // Wait for the reply (and the rest of the turn) to stream in — a graceful
          // micro-wait if the player outran the Character/Timeline calls, usually already
          // landed by here (skipped once resolved, so this stays synchronous in tests).
          if (!p.resolved && !p.blocked) await p.ready
          if (p.blocked) return false // a real moderation block — the conductor halts the reveal
          const cur = this.pendingTurn
          if (!cur || cur !== p || cur.epoch !== this.runEpoch) return true // reset/cleared — benign
          // addAIMessageWithData BEFORE setLoading(false): the soundscape's diceLand fires
          // on the loading falling edge and reads the new message's roll/outcome/craft.
          this.addAIMessageWithData(cur.aiMessage)
          this.setLoading(false)
          return true
      },
1708 
      /**
       * Ripple beat — the % gauge flies its delta, momentum advances, and the change
       * drops onto the Spine ledger; then win/lose resolves and (reading the now-live,
       * just-committed state) the run persists and the Chronicle/suggestions re-narrate
       * non-blocking. Fired by the conductor on the Ripple leaf, AFTER commitReveal, so
       * the writes land in exactly the order sendMessage makes them. No-op under a
       * bumped epoch. This is the mirror of sendMessage's beats 2-3 + its tail.
       */
      async commitRipple(): Promise<boolean> {
          const p = this.pendingTurn
          if (!p || p.epoch !== this.runEpoch) return true // nothing to commit — benign
          if (!p.resolved && !p.blocked) await p.ready
          if (p.blocked) return false // a real moderation block — the conductor halts the reveal
          const cur = this.pendingTurn
          if (!cur || cur !== p || cur.epoch !== this.runEpoch) return true // reset/cleared — benign
          const { epoch, ledgerBefore } = p
          if (p.progressChange !== undefined) this.applyProgress(p.progressChange)
          // The arc meter is server-authoritative for the result; advance it WITH the
          // swing it amplified (only past the epoch guard above).
          this.momentum = p.momentum
          if (p.ripple) this.addTimelineEvent(p.ripple)
          this.resolveGameStatus()
          const resolved = p.ripple != null
          // The re-narration fired EARLY (animate path, at resolve) is carried on the
          // pending turn; capture it before we clear the slot. Persistence reads LIVE
          // (now-committed) state, so it stays here regardless.
          const earlyRefresh = p.refresh ?? null
          this.pendingTurn = null
1737 
          // Reuse the early-fired telling if there is one; otherwise (the inline path)
          // fire it now — never awaited (the reveal waits on neither), reading the
          // just-committed live state. By here the status is resolved, so a final turn's
          // chronicle carries the verdict (the epilogue).
          let refresh: Promise<void> | null = earlyRefresh
          if (!earlyRefresh && resolved && this.timelineEvents.length > ledgerBefore) {
              refresh = this.refreshChronicle()
              void refresh
              void this.refreshSuggestions()
          }
          // Persist AFTER the commit (the draft/snapshot serialize the now-committed
          // ledger/progress/momentum/history). Two beats: the immediate save guards a
          // hanging refresh; the post-refresh re-save captures the fresh telling.
          if (this.gameStatus === 'victory' || this.gameStatus === 'defeat') {
              // The animate path already marked epiloguePending at resolve; the inline
              // path marks it here (only when it fired the telling itself).
              if (refresh && !earlyRefresh) {
                  this.epiloguePending = true
                  void refresh.finally(() => { if (epoch === this.runEpoch) this.epiloguePending = false })
              }
              void this.saveRunSnapshot()
              if (refresh) void refresh.finally(() => { void this.saveRunSnapshot() })
              // The terminal snapshot is the record now — drop the in-progress draft.
              void this.clearRunDraft()
          } else if (resolved) {
              void this.saveRunDraft()
              if (refresh) void refresh.finally(() => { void this.saveRunDraft() })
          }
          return true
      },
1768 
      /**
       * Seed a replay (issue #89): start a fresh run on a shared run's captured
       * objective. Resets first (the share page may follow an abandoned run in the
       * same tab) so the run starts clean, THEN records the seed — so the mission
       * briefing opens focused on this objective, and the lineage + credit ride
       * through to the end. No generation: the objective is reused verbatim, and the
       * player still commits (and is charged) by pressing Begin.
       */
      preseedReplay(objective: GameObjective, sourceToken: string, sourceAttribution: string | null): void {
          this.resetGame()
          this.replayState = { objective, sourceToken, sourceAttribution }
      },
1781 
      /** Drop the replay seed — the player chose to start from scratch instead, so this
       *  run is an original (no "remixed from" lineage). */
      clearReplayState(): void {
          this.replayState = null
      },
1787 
      /**
       * Commits a chosen objective and starts the run from a clean slate of
       * progress. Used by the mission-select screen for both curated picks and
       * freshly composed ones.
       */
      async chooseObjective(objective: GameObjective): Promise<boolean> {
          // Commit = the run is charged here. Mint the run id server-side, then
          // spend one run from the device's balance. Fails CLOSED: out of runs →
          // raise the paywall; begin-run or commit failing → surface an error and
          // do NOT start. A run that isn't a charged, server-backed run would be
          // rejected by the gameplay gate anyway, so starting it only strands the
          // player mid-run. The spend cap (not free play) is the outage backstop.
          let runId: string
          try {
              runId = await this.ensureRunId()
          } catch (error) {
              console.error('Could not begin the run:', error)
              this.error = 'Could not start the run. Please try again.'
              return false
          }
          try {
              const res = await $fetch('/api/run-commit', {
                  method: 'POST',
                  headers: { 'Content-Type': 'application/json' },
                  body: { runId }
              }) as { runsRemaining?: number }
              this.outOfRuns = false
              // Keep the header gauge live: the commit returns the post-charge
              // balance (−1 marks a degraded, ungated run — leave the gauge as is).
              if (typeof res?.runsRemaining === 'number' && res.runsRemaining >= 0) {
                  this.runsRemaining = res.runsRemaining
              }
          } catch (error) {
              if (isPaymentRequired(error)) {
                  this.outOfRuns = true
                  this.openBuyModal()
                  return false
              }
              if (isAtCapacity(error)) {
                  this.atCapacity = true
                  return false
              }
              console.error('Could not charge the run:', error)
              this.error = 'Could not start the run. Please try again.'
              return false
          }
          this.currentObjective = objective
          this.objectiveProgress = 0
          this.peakProgress = 0
          this.momentum = 0
          this.error = null
          // Prefetch the era-relevant figures the instant the objective commits, so
          // they're already in flight (often landed) by the time the player reaches
          // the dispatch page — not a cold wait as their first impression. The
          // FigurePicker onMounted call no-ops while this is in flight (see the
          // suggestionsLoadingFor guard in loadSuggestions).
          void this.loadSuggestions()
          return true
      },
1847 
      /**
       * 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 the objective (or null, never throwing, so the UI can quietly fall
       * back to the curated pool) alongside `fellBackToCurated` (#127): true only
       * when the player steered and the server still returned a curated objective —
       * the signal the caller surfaces so a dropped steer doesn't read as a bug.
       */
      async fetchAIObjective(steer: ObjectiveSteer = {}, avoid: string[] = []): Promise<{ objective: GameObjective | null; fellBackToCurated: boolean }> {
          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
                  fellBackToCurated?: boolean
              }
              const objective = res?.success && res.objective ? res.objective : null
              // Only report a dropped steer when we actually have an objective; a hard
              // failure (null) is the louder compose-error path, not this quiet notice.
              return { objective, fellBackToCurated: objective ? res.fellBackToCurated === true : false }
          } catch (error) {
              console.error('Failed to compose a fresh objective:', error)
              return { objective: null, fellBackToCurated: false }
          }
      },
1883 
      /**
       * 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; referralCredits?: number; referralCount?: number }
              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
              if (typeof res?.referralCredits === 'number') this.referralCredits = res.referralCredits
              if (typeof res?.referralCount === 'number') this.referralCount = res.referralCount
          } catch (error) {
              console.error('Failed to load balance:', error)
          }
      },
1903 
      /**
       * Claims a pending referral after an email signup (issue #96). Best-effort and
       * fire-and-forget by design: the credit lands on the SHARER, not this player, so
       * there's nothing here to surface — the server decides idempotently whether it
       * qualifies. Never throws into the sign-in flow.
       */
      async claimReferral(): Promise<void> {
          try {
              await $fetch('/api/referral/claim', { method: 'POST' })
          } catch (error) {
              console.error('Failed to claim referral:', error)
          }
      },
1917 
      /**
       * Loads the account's generated username (#117) for the profile / settings pages
       * and the share affordance, minting one server-side on first need. Cached: skips
       * the round-trip once loaded (a reroll keeps it current). Graceful on failure —
       * leaves the prior value.
       */
      async loadUsername(force = false): Promise<void> {
          if (this.username && !force) return
          try {
              const res = await $fetch('/api/profile') as { username?: string }
              if (typeof res?.username === 'string') this.username = res.username
          } catch (error) {
              console.error('Failed to load username:', error)
          }
      },
1933 
      /**
       * Rerolls the account username to a fresh generated one (#117) — the only way to
       * change it. The server re-stamps it onto the player's attributed shares too, so
       * the handle stays consistent everywhere it appears. Returns the new name on
       * success, or null on failure so the caller can surface a notice.
       */
      async rerollUsername(): Promise<string | null> {
          try {
              const res = await $fetch('/api/profile/reroll', { method: 'POST' }) as { username?: string }
              if (typeof res?.username === 'string') {
                  this.username = res.username
                  return res.username
              }
              return null
          } catch (error) {
              console.error('Failed to reroll username:', error)
              return null
          }
      },
1953 
      /** Opens the run-packs sales modal, loading the catalog first. */
      async openBuyModal(): Promise<void> {
          this.buyModalOpen = true
          await this.loadPacks()
      },
1959 
      /** Closes the sales modal. */
      closeBuyModal(): void {
          this.buyModalOpen = false
      },
1964 
      /** 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()
          }
      },
1975 
      /** Dismisses the post-purchase notice. */
      clearPurchaseNotice(): void {
          this.purchaseNotice = null
      },
1980 
      /** 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)
          }
      },
1994 
      /** 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
          }
      },
2010 
      getVictoryEfficiency() {
          if (this.gameStatus === 'victory') {
              const messagesSaved = this.remainingMessages
              const messagesUsed = TOTAL_MESSAGES - this.remainingMessages
              const efficiencyPercentage = Math.round((messagesSaved / TOTAL_MESSAGES) * 100)
2016 
              const efficiencyRating = rateEfficiency(messagesSaved)
2018 
              return {
                  messagesSaved,
                  messagesUsed,
                  efficiencyPercentage,
                  efficiencyRating,
                  isEarlyVictory: messagesSaved > 0
              }
          }
          return null
      },
2029 
      /**
       * 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
2046 
          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
2062 
          const snapshot: RunSnapshot = {
              version: RUN_SNAPSHOT_VERSION,
              runId,
              status,
              objective,
              objectiveProgress: this.objectiveProgress,
              // The high-water mark, so a snapshot-backed view can show "Peaked at X%"
              // (the live store zeroes it on reset, so it's only meaningful here at end).
              peakProgress: this.peakProgress,
              messagesUsed: TOTAL_MESSAGES - this.remainingMessages,
              totalMessages: TOTAL_MESSAGES,
              bestRoll: mark(summary.bestRoll),
              worstRoll: mark(summary.worstRoll),
              efficiency: this.getVictoryEfficiency(),
              dispatches,
              timeline: events.map((e) => ({
                  id: e.id,
                  figureName: e.figureName,
                  era: e.era,
                  headline: e.headline,
                  detail: e.detail,
                  diceRoll: e.diceRoll,
                  diceOutcome: e.diceOutcome,
                  progressChange: e.progressChange,
                  baseProgressChange: e.baseProgressChange,
                  valence: e.valence,
                  craft: e.craft,
                  momentumAtSwing: e.momentumAtSwing,
                  anachronism: e.anachronism,
                  causalChain: e.causalChain,
                  staked: e.staked
              })),
              chronicle: this.chronicle
          }
2097 
          // A replay (issue #89) rides its source's share token alongside the snapshot
          // (a sibling field, not part of the immutable blob); the server resolves it to
          // the parent run id and stamps the lineage pointer. replayState set ⟺ this run
          // committed the seeded objective (the briefing clears it on any other choice).
          const body = this.replayState
              ? { ...snapshot, remixedFromToken: this.replayState.sourceToken }
              : snapshot
2105 
          try {
              const res = (await $fetch('/api/run-save', {
                  method: 'POST',
                  headers: { 'Content-Type': 'application/json' },
                  body
              })) as { saved?: boolean }
              // Mark saved (for the share affordance) only if this run is still current
              // and the server actually persisted it (a degraded run returns saved:false).
              if (epoch === this.runEpoch && res?.saved) this.runSnapshotSaved = true
          } catch (error) {
              // Saving the run is a nicety; a failure must not break the end screen.
              if (epoch === this.runEpoch) console.error('Could not save the run:', error)
          }
      },
2120 
      /**
       * Autosave the in-progress run's draft, best-effort (#152). The live mirror of
       * saveRunSnapshot: it serializes the DURABLE live state — totals, the full
       * thread (both sides), the un-trimmed ledger (with whenSigned + causalChain),
       * the contacted figures, the active contact, the Chronicle, and any replay
       * lineage — keyed by the run id, so a refresh or a crash resumes exactly here.
       * Fires and forgets: only an in-progress, server-backed (uuid) run is saved;
       * the server drops a degraded local id, and any failure is swallowed.
       */
      async saveRunDraft(): Promise<void> {
          if (this.gameStatus !== 'playing') return
          const runId = this.runId
          const objective = this.currentObjective
          if (!runId || !objective) return
2135 
          const draft: RunDraft = {
              version: RUN_DRAFT_VERSION,
              runId,
              currentObjective: objective,
              objectiveProgress: this.objectiveProgress,
              peakProgress: this.peakProgress,
              momentum: this.momentum,
              remainingMessages: this.remainingMessages,
              // The full thread, both sides — the in-memory Date stamp serialized for
              // jsonb (revived on resume). The AI replies cost a model call to redo.
              messageHistory: this.messageHistory.map((m) => ({
                  text: m.text,
                  sender: m.sender,
                  timestamp: m.timestamp.toISOString(),
                  figureName: m.figureName,
                  diceRoll: m.diceRoll,
                  diceOutcome: m.diceOutcome,
                  naturalRoll: m.naturalRoll,
                  rollModifier: m.rollModifier,
                  craft: m.craft,
                  craftReason: m.craftReason,
                  continuity: m.continuity,
                  characterAction: m.characterAction,
                  timelineImpact: m.timelineImpact,
                  progressChange: m.progressChange,
                  baseProgressChange: m.baseProgressChange,
                  momentumAtSwing: m.momentumAtSwing,
                  anachronism: m.anachronism,
                  causalChain: m.causalChain,
                  staked: m.staked
              })),
              // The UN-trimmed ledger: keeps whenSigned + causalChain (the footholds
              // the next turn's causal chain and the world-brief read back).
              timelineEvents: this.timelineEvents.map((e) => ({
                  id: e.id,
                  figureName: e.figureName,
                  era: e.era,
                  headline: e.headline,
                  detail: e.detail,
                  diceRoll: e.diceRoll,
                  diceOutcome: e.diceOutcome,
                  progressChange: e.progressChange,
                  baseProgressChange: e.baseProgressChange,
                  valence: e.valence,
                  anachronism: e.anachronism,
                  causalChain: e.causalChain,
                  craft: e.craft,
                  momentumAtSwing: e.momentumAtSwing,
                  whenSigned: e.whenSigned,
                  staked: e.staked,
                  timestamp: e.timestamp.toISOString()
              })),
              figures: this.figures.map((f) => ({ name: f.name, era: f.era, descriptor: f.descriptor })),
              activeFigureName: this.activeFigureName,
              contactWhen: this.contactWhen,
              contactMoment: this.contactMoment,
              chronicle: this.chronicle,
              replayState: this.replayState
          }
2195 
          try {
              await $fetch('/api/run-draft', {
                  method: 'POST',
                  headers: { 'Content-Type': 'application/json' },
                  body: draft
              })
          } catch (error) {
              // Autosave is a safety net; a failure must never disturb the turn.
              console.error('Could not save the run draft:', error)
          }
      },
2207 
      /**
       * Clear the run's server-side draft (#152) — fired on terminal save and on
       * resetGame (abandon). Takes an explicit run id so resetGame can clear the
       * run it is tearing down (runId is nulled there). Idempotent + best-effort.
       */
      async clearRunDraft(runId?: string): Promise<void> {
          const id = runId ?? this.runId
          if (!id) return
          try {
              await $fetch('/api/run-draft', { method: 'DELETE', query: { runId: id } })
          } catch (error) {
              console.error('Could not clear the run draft:', error)
          }
      },
2222 
      /**
       * Resume an in-progress run from its server-side draft (#152) — the counterpart
       * to saveRunDraft, called on page load when the board is empty. Reads the
       * subject's latest draft and, when there is one, rehydrates the store so the
       * player drops straight back onto the in-progress board: the SAME run id (no new
       * credit charged), the totals, the full thread, the ledger, and the figures.
       *
       * The active figure is RE-grounded from the live record (the draft carries no
       * dossier), then the saved contact year/moment are re-applied — groundActiveFigure
       * defaults contactWhen to mid-lifetime, which would otherwise clobber the player's
       * chosen year. Best-effort: any failure simply leaves the mission briefing.
       */
      async resumeDraft(): Promise<boolean> {
          // currentObjective set ⟹ a run is already on the board. A replayState seed
          // (preseedReplay, from a /r/<token> share link) is an intent to start a FRESH
          // charged run — never let a pre-existing server draft clobber it (#152/#89).
          if (this.currentObjective || this.replayState) return false
          let draft: RunDraft | null
          try {
              const res = (await $fetch('/api/run-draft')) as { draft?: RunDraft | null }
              draft = res?.draft ?? null
          } catch (error) {
              console.error('Could not load the run draft:', error)
              return false
          }
          if (!draft || !draft.currentObjective || !draft.runId) return false
          // A reset, a fresh run, or a replay seed may have begun while the draft was
          // loading — never drop a stale run onto a board the player has moved on from.
          if (this.currentObjective || this.replayState) return false
2252 
          // jsonb is dateless: revive the serialized ISO stamps, falling back to now()
          // for any unparseable value rather than minting an Invalid Date.
          const revive = (ts: string): Date => {
              const d = new Date(ts)
              return Number.isNaN(d.getTime()) ? new Date() : d
          }
2259 
          // Guard the async tail like every other state-writing action: the board (and
          // its ↻ reset) appears the instant we rehydrate, so a reset can fire during
          // the re-ground below — its stale contact must not land on the fresh run.
          const epoch = this.runEpoch
          this.runId = draft.runId
          this.gameStatus = 'playing'
          this.currentObjective = draft.currentObjective
          this.objectiveProgress = draft.objectiveProgress
          this.peakProgress = draft.peakProgress
          this.momentum = draft.momentum
          this.remainingMessages = draft.remainingMessages
          this.messageHistory = draft.messageHistory.map((m) => ({ ...m, timestamp: revive(m.timestamp) }))
          this.timelineEvents = draft.timelineEvents.map((e) => ({ ...e, timestamp: revive(e.timestamp) }))
          this.figures = draft.figures.map((f) => ({ ...f }))
          this.activeFigureName = draft.activeFigureName
          this.chronicle = draft.chronicle
          this.replayState = draft.replayState
2277 
          // Re-ground the active figure (the draft carries no dossier), then restore the
          // saved year/moment OVER the mid-lifetime default grounding picks — unless a
          // reset tore the board mid-ground, in which case abort without touching it.
          if (this.activeFigureName) {
              await this.groundActiveFigure(this.activeFigureName)
              if (epoch !== this.runEpoch) return false
          }
          this.contactWhen = draft.contactWhen
          this.contactMoment = draft.contactMoment
          return true
      },
2289 
      resetGame() {
          // Clear the abandoned run's server draft so a reload can't resume it (#152).
          // Capture the id before the epoch tear nulls runId below; fire-and-forget.
          const abandonedRunId = this.runId
          // Tear the epoch first: anything still in flight belongs to the old run
          // and must find no purchase here. (The seq counters deliberately survive.)
          this.runEpoch++
          this.remainingMessages = TOTAL_MESSAGES
          this.messageHistory = []
          this.gameStatus = 'playing'
          this.isLoading = false
          this.error = null
          this.lastMessageTime = null
          this.isRateLimited = false
          // A new run gets a fresh id on its next server call; abandon any
          // in-flight mint so a dead run's id can't land in the new run.
          this.runId = null
          this.runIdInflight = null
          this.runSnapshotSaved = false
          // The paywall / capacity notices re-check on the next commit.
          this.outOfRuns = false
          this.atCapacity = false
          this.currentObjective = null
          // A fresh run carries no replay lineage (preseedReplay re-sets it after).
          this.replayState = null
          this.objectiveProgress = 0
          this.peakProgress = 0
          this.momentum = 0
          this.timelineEvents = []
          this.figures = []
          this.activeFigureName = ''
          this.figureGrounding = null
          this.groundingLoading = false
          this.contactWhen = null
          this.contactMoment = null
          this.figureSuggestions = []
          this.suggestionsLoading = false
          this.suggestionsFor = ''
          this.chronicle = null
          this.chronicleForLedgerLen = 0
          this.chronicleLoading = false
          this.chronicleStream = ''
          this.chronicleStreaming = false
          this.chronicleStreamLen = 0
          this.epiloguePending = false
          // Drop any half-revealed turn — a reset mid-reveal must leave nothing
          // for commitReveal/commitRipple to land in the fresh run (the epoch guard
          // also catches it, this is the belt-and-suspenders clear).
          this.pendingTurn = null
          this.figureStudy = null
          this.studyLoading = false
          this.studyFor = ''
          this.studyWhen = null
          this.archiveResult = null
          this.lookupLoading = false
          this.moderationNotice = null
          this.archiveNotice = null
          this.studyNotice = null
          this.suggestionsNotice = null
          // Drop the abandoned run's draft last, off the fresh (already-torn) epoch —
          // a no-op when there was no run yet (#152).
          if (abandonedRunId) void this.clearRunDraft(abandonedRunId)
      }
  }
2354})

The server validator that rebuilds a posted snapshot gets the matching guard. A direct POST can send anything, so momentum is coerced to a clamped integer in [0, MOMENTUM_MAX] — the same shape every other ledger field is bounded to.

Untrusted momentum clamped to the meter's range before it reaches a saved run.

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

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

⋯ 148 lines hidden (lines 1–148)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 { MOMENTUM_MAX } from '~/utils/momentum'
37import { CHAIN_TIERS, type ChainStatus, type ChainTier } from '~/utils/causal-chain'
38import type { Anachronism } from '~/server/utils/anachronism'
39import type { GameObjective } from '~/server/utils/objectives'
40import type { ChronicleEntry } from '~/server/utils/openai'
41 
42// Caps specific to a snapshot's own fields (the shared input caps live in validate.ts).
43const MAX_DISPATCH_CHARS = 320
44const MAX_HEADLINE_CHARS = 200
45const MAX_ICON_CHARS = 16
46const MAX_OUTCOME_CHARS = 24
47const MAX_RATING_CHARS = 24
48const MAX_HINT_CHARS = 24
49const MAX_ID_CHARS = 64
50const MAX_TOTAL_MESSAGES = 20
51const MAX_DICE = 40
52 
53const VALENCES: RunValence[] = ['positive', 'negative', 'neutral']
54const coerceValence = (v: unknown): RunValence =>
  VALENCES.includes(v as RunValence) ? (v as RunValence) : 'neutral'
56 
57// The causal-chain status rides a ledger entry as a nested object — validate the tier
58// against the known set and keep gap/factor only if finite; a malformed blob drops to
59// null (no ⏳ badge), never throws.
60const cleanChainStatus = (v: unknown): ChainStatus | null => {
  if (!v || typeof v !== 'object') return null
  const c = v as Record<string, unknown>
  if (!CHAIN_TIERS.includes(c.tier as ChainTier)) return null
  if (typeof c.gap !== 'number' || !Number.isFinite(c.gap)) return null
  if (typeof c.factor !== 'number' || !Number.isFinite(c.factor)) return null
  return { gap: c.gap, factor: c.factor, tier: c.tier as ChainTier }
67}
68 
69const clampNonNeg = (n: number): number => Math.max(0, n)
70 
71const 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 }
77}
78 
79/**
* 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.
*/
85export function sanitizeSnapshot(raw: unknown): RunSnapshot | null {
  if (!raw || typeof raw !== 'object') return null
  const r = raw as Record<string, unknown>
88 
  const status: RunOutcome | null =
      r.status === 'victory' || r.status === 'defeat' ? r.status : null
  if (!status) return null
92 
  const runId = sanitizeRunId(r.runId)
  if (!runId) return null
95 
  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)
  }
107 
  const totalMessages = clampNonNeg(clampInt(r.totalMessages, MAX_TOTAL_MESSAGES)) || TOTAL_MESSAGES
  const messagesUsed = Math.min(totalMessages, clampNonNeg(clampInt(r.messagesUsed, MAX_TOTAL_MESSAGES)))
110 
  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
      }
  }
122 
  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)
      }
  })
131 
  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
      // The pre-turn momentum that amplified the swing (0..MOMENTUM_MAX) — the detail
      // strip reads it for the ✦ factor, so a saved run discloses momentum too.
      if (typeof t.momentumAtSwing === 'number') {
          entry.momentumAtSwing = clampNonNeg(clampInt(t.momentumAtSwing, MOMENTUM_MAX))
      }
⋯ 43 lines hidden (lines 157–199)157        const anachronism = cleanString(t.anachronism, MAX_HINT_CHARS)
      if (anachronism) entry.anachronism = anachronism as Anachronism
      if (t.staked === true) entry.staked = true
      const causalChain = cleanChainStatus(t.causalChain)
      if (causalChain) entry.causalChain = causalChain
      return entry
  })
164 
  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)
      }
  }
175 
  const objectiveProgress = clampNonNeg(clampInt(r.objectiveProgress, 100))
  // The high-water mark is a peak, so it can't sit below the final progress — floor it
  // there. That both defaults an absent peak (an old client / a direct POST) to the
  // final % (peak == final → no "Peaked at X%") and rejects a malformed peak < final.
  const peakProgress = Math.max(objectiveProgress, clampNonNeg(clampInt(r.peakProgress, 100)))
181 
  return {
      // The server owns the version stamp — never trust the client's.
      version: RUN_SNAPSHOT_VERSION,
      runId,
      status,
      objective,
      objectiveProgress,
      peakProgress,
      messagesUsed,
      totalMessages,
      bestRoll: cleanRoll(r.bestRoll),
      worstRoll: cleanRoll(r.worstRoll),
      efficiency,
      dispatches,
      timeline,
      chronicle
  }
199}

One equation everywhere: the ledger folds onto the shared tokens

The ledger detail strip used to disclose levers its own way: a bare "(base → final)" plus standalone craft, anachronism, chain, and staked badges beside it. So the factors, even once added to equationTokens, would not have reached it. This replaces that whole row's tail with the same token-bearing equation the thread and leaf render, and retires the four standalone badges — every lever now rides inside the one equation.

The detail strip now renders equationTokens inline; the parallel badges are gone.

components/TimelineLedger.vue · 212 lines

components/TimelineLedger.vue212 lines · Vue

⋯ 63 lines hidden (lines 1–63)1<template>
<!-- THE SPINE: history as a horizontal era-axis you travel left→right. -->
<div data-testid="timeline-ledger">
  <div v-if="!props.bare" class="border-b ew-line pb-1.5 mb-3">
    <div class="flex items-center justify-between gap-3">
      <span class="ew-label">The Spine</span>
      <span class="ew-mono ew-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="ew-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="ew-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 ew-accent" aria-hidden="true">✒</div>
      <p class="ew-serif ew-fg text-lg">The timeline trembles…</p>
      <p class="ew-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="ew-serif ew-fg text-lg">History is still unwritten.</p>
      <p class="ew-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 ew-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 ew-mono text-[11px] ew-faint">{{ event.era || '—' }}</span>
        <span class="dot-wrap" aria-hidden="true">
          <span class="connector" />
          <span class="ew-dot" :class="event.id === selectedId ? 'ew-dot--accent' : dotClass(event.valence)" />
        </span>
        <span class="block text-center ew-mono text-xs ew-fg truncate px-1">{{ event.figureName }}</span>
        <span class="block text-center ew-mono text-[11px] mt-0.5 tabular-nums">
          <span class="ew-faint">🎲</span>{{ event.diceRoll }}
          <span class="delta-cell" :class="deltaClass(event.progressChange)">{{ signed(event.progressChange) }}</span><span
            v-if="isAnachronistic(event.anachronism)" class="ew-warn ml-0.5" :aria-label="anachronismLabel(event.anachronism)" :title="anachronismHint(event.anachronism)">{{ anachPips(event.anachronism) }}</span><span
            v-if="event.staked" class="ew-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 ew-mono text-[11px] ew-accent font-semibold">▷ now</span>
        <span class="dot-wrap"><span class="connector connector--half" /></span>
        <span class="block text-center ew-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 ew-line pt-2.5 mt-2">
    <p class="ew-serif ew-fg text-lg lg:text-xl font-semibold leading-snug">{{ selected.headline }}</p>
    <p class="ew-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] ew-mono mt-1.5 tabular-nums">
      <span class="inline-flex items-center gap-1.5">
        <span class="ew-dot" :class="dotClass(selected.valence)" aria-hidden="true" />
        <span class="ew-faint">{{ selected.era || '—' }} · {{ selected.figureName }}</span>
      </span>
      <span class="ew-hair-c">·</span>
      <span class="ew-muted">🎲 {{ selected.diceRoll }} · {{ selected.diceOutcome }}</span>
      <span class="ew-hair-c">·</span>
      <span class="font-bold" :class="deltaClass(selected.progressChange)">{{ signed(selected.progressChange) }}%</span>
      <!-- The full base → final breakdown, in the open on every turn (issue #135), with
           each scaler disclosing its multiplier so the Δ reconciles (issue #184): ⚡
           wager, ⏳ chain ×f, ✒ craft ×f, ✦ momentum ×f, ⚑ stake. Rendered from the SAME
           equationTokens as the thread + codex leaf, so a lever can't explain a swing in
           one place and vanish here; collapses to (+22 → +22) when nothing moved it. -->
      <span v-if="selected.baseProgressChange !== undefined" data-testid="swing-equation"
        class="ew-faint inline-flex items-center flex-wrap gap-x-1">
        <span>({{ signed(selected.baseProgressChange) }}</span>
        <SymbolHint v-for="tok in equationTokens(selected)" :key="tok.kind" :text="tok.hint">
          <span :data-testid="`equation-${tok.kind}`">{{ tok.label }}</span>
        </SymbolHint>
        <span>→ {{ signed(selected.progressChange) }})</span>
      </span>
⋯ 127 lines hidden (lines 86–212)86      </div>
  </div>
</div>
89</template>
90 
91<script setup lang="ts">
92/**
* 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.)
*/
99import { computed, ref, watch } from 'vue'
100import { useGameStore } from '~/stores/game'
101import type { Valence } from '~/stores/game'
102import { ANACHRONISM_HINT, ANACHRONISM_LABEL, type Anachronism } from '~/server/utils/anachronism'
103import { STAKE_HINT } from '~/utils/swing-bands'
104import { equationTokens } from '~/utils/swing-equation'
105import type { RunLedgerEntry } from '~/utils/run-snapshot'
106 
107const gameStore = useGameStore()
108const 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[]
  /** Drop the "The Spine" header block for inline use where an outer surface (the
   *  record pane) already labels it. Off by default, so the end-screen and
   *  saved-run views keep their own header. */
  bare?: boolean
124}>()
125const events = computed<RunLedgerEntry[]>(() => props.events ?? gameStore.timelineEvents)
126 
127const selectedId = ref<string | null>(null)
128// Default the detail strip to the newest change, and snap to it whenever one lands.
129watch(() => events.value.length, () => {
  const last = events.value[events.value.length - 1]
  if (last) selectedId.value = last.id
132}, { immediate: true })
133 
134const selected = computed(() =>
  events.value.find(e => e.id === selectedId.value) ?? events.value[events.value.length - 1] ?? null
136)
137const anachCount = computed(() => events.value.filter(e => isAnachronistic(e.anachronism)).length)
138 
139function select(id: string) { selectedId.value = id }
140function signed(n: number) { return `${n > 0 ? '+' : ''}${n}` }
141function isAnachronistic(a?: Anachronism) { return !!a && a !== 'in-period' }
142function anachronismLabel(a?: Anachronism) { return a ? ANACHRONISM_LABEL[a] : '' }
143function anachronismHint(a?: Anachronism) { return a ? ANACHRONISM_HINT[a] : '' }
144/** A quantified, glanceable anachronism tier on the spine node: 1–3 amber pips. */
145function anachPips(a?: Anachronism) {
  return a === 'impossible' ? '⚡⚡⚡' : a === 'far-ahead' ? '⚡⚡' : a === 'ahead' ? '⚡' : ''
147}
148 
149function dotClass(v: Valence) {
  return v === 'positive' ? 'ew-dot--ok' : v === 'negative' ? 'ew-dot--bad' : 'ew-dot--mut'
151}
152function deltaClass(change: number) {
  if (change > 0) return 'ew-ok'
  if (change < 0) return 'ew-bad'
  return 'ew-muted'
156}
157</script>
158 
159<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;
169}
spine-scroll { scroll-snap-type: x proximity; -webkit-overflow-scrolling: touch; }
171/* 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(--ew-accent); outline-offset: 2px; border-radius: 3px; }
175 
176/* 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;
184}
connector {
  position: absolute;
  top: 50%;
  left: 0;
  right: 0;
  height: 1px;
  background: var(--ew-line);
  transform: translateY(-50%);
193}
connector--half { right: 50%; }
dot-wrap > .ew-dot { position: relative; z-index: 1; }
spine-node.is-selected .dot-wrap > .ew-dot {
  width: 12px;
  height: 12px;
  box-shadow: 0 0 0 3px var(--ew-bg), 0 0 0 4px var(--ew-accent);
200}
spine-node:hover .dot-wrap > .ew-dot { transform: translateY(-1px); }
202 
203/* Preserved entry/move animation (now driving the right-edge node arrival). */
timeline-enter-active { transition: opacity var(--ew-dur-3) var(--ew-ease), transform var(--ew-dur-3) var(--ew-ease); }
timeline-enter-from { opacity: 0; transform: translateY(-10px); }
timeline-move { transition: transform var(--ew-dur-3) var(--ew-ease); }
207 
208@media (prefers-reduced-motion: reduce) {
  .timeline-enter-active, .timeline-move { transition: none; }
  .spine-node:hover .dot-wrap > .ew-dot { transform: none; }
211}
212</style>

The tests reconcile the math

The unit spec pins the behavior that matters: each scaler token carries its factor, anachronism carries none, and the factors multiply out. The second test below is the issue in miniature — a chain-decayed, vague gain shows both factors, so 22 × 0.41 × 0.4 reads straight off to the result. The component specs assert the same strings render on the thread, the codex leaf, and the ledger, with data that reconciles (20 × 1.45 = 29, 10 × 1.4 = 14, −10 × 0.8 = −8).

Anachronism stays pip-only; every scaler factor is present and multiplies out.

tests/unit/utils/swing-equation.spec.ts · 95 lines

tests/unit/utils/swing-equation.spec.ts95 lines · TypeScript

⋯ 79 lines hidden (lines 1–79)1import { describe, it, expect } from 'vitest'
2import { equationTokens, type SwingBreakdown } from '~/utils/swing-equation'
3import type { ChainStatus } from '~/utils/causal-chain'
4 
5// The shared source of truth behind the base → final equation on every surface
6// (thread, codex reveal leaf, ledger). The behavior that matters: a lever that moved
7// the swing earns exactly one token, an idle lever earns none, and the order matches
8// the server's apply order — so the printed equation reconciles to the result and the
9// "+22 → +9%, how?" gap can never reappear.
10 
11const chain = (tier: ChainStatus['tier']): ChainStatus => ({ gap: 600, factor: 0.41, tier })
12const kinds = (b: SwingBreakdown) => equationTokens(b).map(t => t.kind)
13 
14describe('equationTokens', () => {
  it('collapses to no tokens on a plain in-period, sound, full-power gain', () => {
      expect(equationTokens({ progressChange: 12, anachronism: 'in-period', craft: 'sound' })).toEqual([])
  })
18 
  it('emits a ⏳ chain token, with its decay factor, when a far reach shrank the swing', () => {
      const toks = equationTokens({ progressChange: 9, causalChain: chain('reaching') })
      expect(toks).toHaveLength(1)
      expect(toks[0].kind).toBe('chain')
      expect(toks[0].label).toContain('⏳')
      expect(toks[0].label).toContain('reaching')
      expect(toks[0].label).toContain('×0.41') // the multiplier, so base → final reconciles
  })
27 
  it('stays silent when the reach landed at the hinge (nothing to explain)', () => {
      expect(equationTokens({ progressChange: 22, causalChain: chain('at-hinge') })).toEqual([])
  })
31 
  it('emits a ✒ craft token with its gain factor — the +22 → +9 culprit, now disclosed', () => {
      const toks = equationTokens({ progressChange: 9, craft: 'vague' })
      expect(toks).toHaveLength(1)
      expect(toks[0].kind).toBe('craft')
      expect(toks[0].label).toContain('vague')
      expect(toks[0].label).toContain('×0.4') // CRAFT_GAIN_FACTOR.vague — 22 × 0.4 ≈ 9
      expect(toks[0].hint).toContain('scales the gain') // gain-side wording
  })
40 
  it('shows the INVERTED loss factor on a loss — craft shields rather than scales', () => {
      const [tok] = equationTokens({ progressChange: -8, craft: 'masterful' })
      expect(tok.kind).toBe('craft')
      expect(tok.label).toContain('×0.6') // CRAFT_LOSS_FACTOR.masterful — a softened blow
      expect(tok.hint).toContain('shields')
  })
47 
  it('skips the craft token on a neutral sound grade and on a zero swing', () => {
      expect(equationTokens({ progressChange: 9, craft: 'sound' })).toEqual([])
      expect(equationTokens({ progressChange: 0, craft: 'vague' })).toEqual([])
  })
52 
  it('scales the ⚡ pips with the anachronism tier', () => {
      expect(equationTokens({ progressChange: 9, anachronism: 'ahead' })[0].label).toContain('⚡ ')
      expect(equationTokens({ progressChange: 9, anachronism: 'far-ahead' })[0].label).toContain('⚡⚡')
      expect(equationTokens({ progressChange: 9, anachronism: 'impossible' })[0].label).toContain('⚡⚡⚡')
  })
58 
  it('shows momentum only on a positive swing it actually lifted', () => {
      expect(kinds({ progressChange: 9, momentumAtSwing: 3 })).toContain('momentum')
      expect(kinds({ progressChange: -9, momentumAtSwing: 3 })).not.toContain('momentum')
      expect(kinds({ progressChange: 9, momentumAtSwing: 0 })).not.toContain('momentum')
  })
64 
  it('labels momentum with its MULTIPLIER, not the raw level — that is what the equation multiplies by', () => {
      const [tok] = equationTokens({ progressChange: 9, momentumAtSwing: 3 })
      expect(tok.kind).toBe('momentum')
      expect(tok.label).toContain('×1.3') // momentumFactor(3) = 1 + 0.1·3
      expect(tok.hint).toContain('3 of') // the level still rides in the hint
  })
71 
  it('orders the tokens the way the server applied them: anachronism → chain → craft → momentum → staked', () => {
      const toks = kinds({
          progressChange: 14, anachronism: 'far-ahead', causalChain: chain('reaching'),
          craft: 'sharp', momentumAtSwing: 2, staked: true
      })
      expect(toks).toEqual(['anachronism', 'chain', 'craft', 'momentum', 'staked'])
  })
79 
  it('keeps anachronism QUALITATIVE — pips, no ×factor (the wager stays off the math)', () => {
      const [tok] = equationTokens({ progressChange: 9, anachronism: 'far-ahead' })
      expect(tok.kind).toBe('anachronism')
      expect(tok.label).not.toContain('×') // its factor is "qualitative on purpose"
  })
85 
  it('discloses every scaler factor so base × factors reconciles to the shown final (issue #184)', () => {
      // The vague Success the issue filed on: base 22, in-period, chain 1.0 → +9.
      // The single craft token now shows ×0.4, and 22 × 0.4 ≈ 9 reads straight off.
      const [craftTok] = equationTokens({ progressChange: 9, craft: 'vague' })
      expect(craftTok.label).toMatch(/✒ vague ×0\.4/)
      // A chain-decayed, vague gain: both scalers show their factor (22 × 0.41 × 0.4 ≈ 4).
      const toks = equationTokens({ progressChange: 4, causalChain: chain('reaching'), craft: 'vague' })
      expect(toks.map(t => t.label)).toEqual(['⏳ reaching ×0.41', '✒ vague ×0.4'])
  })
95})