Replay a shared objective, tracing lineage (#121)

What changed, and why

A shared run (#88) already carries its objective in the public projection. This PR lets a viewer play that objective, not just read it: a "Play this objective" button on /r/:token starts a fresh run seeded with the shared run's captured GameObjective, reused verbatim — no model call, no reroll cost, no re-running #71's bounds (the objective was bounded when first composed). That closes a viral loop: play → share → someone replays → shares their run.

The replayed run also records its lineage and shows a one-hop "remixed from" credit. The whole design turns on one decision: lineage is a pointer, not a copy. We store a stable pointer to the parent run and walk it at read time to the parent's current title and opt-in name — so attribution always reflects the source's current privacy choice (un-share → the credit goes anonymous), and no identity is ever copied into the child.

Read the contract first, then the one column it rests on, then the two store methods that write and walk it, then the seam and the UI.

Layer	File	What it does
Contract	`utils/run-snapshot.ts`	`RemixCredit` + `PublicRun.remixedFrom`
Schema	`supabase/migrations/0007_run_lineage.sql`	`derived_from_run_id` pointer column
Store	`server/utils/run-snapshot-store.ts`	stamp the pointer · walk one hop
Seam	`server/api/run-save.post.ts` · `stores/game.ts`	carry the source token · replay state
UI	`MissionSelect` · `RunView` · `EndGameScreen` · `RemixCreditLine` · `pages/r/[token].vue`	seed + render the credit

The contract: a credit that's resolved, not stored

RemixCredit is the one-hop lineage of a replayed run. It is deliberately small: the source's opt-in display name (null when they shared anonymously), the source's objective title, and the source's live share token (for an optional backlink, null once un-shared). It carries no parent run id, no owner, no device. It hangs off PublicRun as an optional remixedFrom — a projection field, exactly like attribution already is, never part of the stored snapshot blob.

RemixCredit + the optional remixedFrom on the public projection.

utils/run-snapshot.ts · 161 lines

utils/run-snapshot.ts161 lines · TypeScript

⋯ 114 lines hidden (lines 1–114)1/**
2 * The saved-run contract — the immutable, versioned record of a finished run.
3 *
4 * A run is otherwise client-only: the objective, the dispatches, the timeline
5 * ledger, the Chronicle epilogue, and the verdict all live in the Pinia store and
6 * evaporate on reload. This is the persisted form of that end-state: the store builds
7 * it on game end, the server stores it keyed by the run id, and a read-only "your
8 * runs" view replays it. It is a SNAPSHOT, not a live record — in-progress
9 * save/resume is out of scope; a run is short (five messages) and persists at the end.
10 *
11 * Naming: "run" is overloaded. The header gauge's balance ("runs remaining") is a
12 * purchasable CREDIT (the `balances` table); this is a PLAYED run (the game record,
13 * the `run_snapshots` table). Same noun, two states — kept distinct in the schema.
14 *
15 * The shape is VERSIONED (`version`) so a later change can't silently break runs
16 * saved under an older shape: a reader can branch on `version` and migrate. It is a
17 * flat, fully JSON-native projection of the store state — the `Date` timestamps on
18 * the in-memory ledger/thread are dropped (a snapshot needs none of the duration
19 * math), so the stored blob round-trips through jsonb cleanly.
20 *
21 * This module is the SHARED contract (types + version), client-safe by design: it
22 * carries no runtime imports, only type-only ones, so the client store can import the
23 * version + types without pulling any server-only code. The server-side boundary
24 * validator lives separately in `server/utils/run-snapshot.ts`.
25 */
26import type { DiceOutcome } from '~/utils/dice'
27import type { Craft } from '~/utils/craft'
28import type { Anachronism } from '~/server/utils/anachronism'
29import type { GameObjective } from '~/server/utils/objectives'
30import type { ChronicleEntry } from '~/server/utils/openai'
31 
32/** The current saved-run shape. Bump when the shape changes incompatibly; a reader
33 *  branches on it to migrate older snapshots rather than mis-reading them. */
34export const RUN_SNAPSHOT_VERSION = 1
35 
36/** Only a finished run is ever saved — the two terminal verdicts. */
37export type RunOutcome = 'victory' | 'defeat'
38 
39/** The valence of a ledger swing (mirrors the store's `Valence`). */
40export type RunValence = 'positive' | 'negative' | 'neutral'
41 
42/** The five efficiency tiers a victory can earn (mirrors the store's rating). */
43export type EfficiencyRating = 'Legendary' | 'Excellent' | 'Great' | 'Good' | 'Standard'
44 
45/** The bit of a roll the read-only view shows: the number and its named outcome. */
46export interface RollMark {
47    diceRoll: number
48    diceOutcome: DiceOutcome
49}
50 
51/** A dispatch keepsake — the player's verbatim message and whom/when it reached. */
52export interface RunDispatch {
53    text: string
54    figure: string
55    era: string
56}
57 
58/** The victory efficiency block (null on defeat) — the same data the end screen shows. */
59export interface RunEfficiency {
60    messagesSaved: number
61    messagesUsed: number
62    efficiencyPercentage: number
63    efficiencyRating: EfficiencyRating
64    isEarlyVictory: boolean
65}
66 
67/** One ledger entry, trimmed to the fields a read-only run view renders (the live
68 *  `TimelineEvent` minus its `Date` timestamp and the internals the view ignores). */
69export interface RunLedgerEntry {
70    id: string
71    figureName: string
72    era: string
73    headline: string
74    detail: string
75    diceRoll: number
76    diceOutcome: DiceOutcome
77    progressChange: number
78    /** The pre-amplifier swing — the Spine reads it to show the Δ equation
79     *  (`base → final`). Absent on turns that didn't amplify (none to disclose). */
80    baseProgressChange?: number
81    valence: RunValence
82    craft?: Craft
83    anachronism?: Anachronism
84    /** True when this was the run's staked last stand — the Spine's ⚑ badge. */
85    staked?: boolean
86}
87 
88/** The full saved run — everything a read-only view needs to replay the end screen. */
89export interface RunSnapshot {
90    version: number
91    runId: string
92    status: RunOutcome
93    objective: GameObjective
94    objectiveProgress: number
95    messagesUsed: number
96    totalMessages: number
97    bestRoll: RollMark | null
98    worstRoll: RollMark | null
99    efficiency: RunEfficiency | null
100    dispatches: RunDispatch[]
101    timeline: RunLedgerEntry[]
102    chronicle: ChronicleEntry | null
103}
104 
105/** The list projection — what the "your runs" list shows per run, without pulling
106 *  the full snapshot blob for every row. */
107export interface RunSummary {
108    runId: string
109    status: RunOutcome
110    title: string
111    progress: number
112    createdAt: string
113}
114 
115/**
116 * "Remixed from" credit (issue #89) — the one-hop lineage of a replayed run: the run it
117 * was seeded from. It is a POINTER WALKED at render time (never a copy stamped into the
118 * child), so it always reflects the source's CURRENT privacy choice — a later un-share
119 * drops `attribution` back to anonymous and `sourceToken` to null. It carries only public
120 * game data + the opt-in display name: never the parent's run id, owner, or device.
121 */
122export interface RemixCredit {
123    /** The source sharer's opt-in display name, or null when they shared anonymously. */
124    attribution: string | null
125    /** The source run's objective title — the objective this run is a replay of. */
126    objectiveTitle: string
127    /** The source's live share token for an optional backlink, or null when un-shared. */
128    sourceToken: string | null
129}
130 
131/**
132 * The PUBLIC, shareable projection of a saved run (issue #88) — the sanitized form
133 * served at an unguessable share URL to anyone, no login. It carries the GAME RECORD
134 * (verdict, ledger, dispatches, Chronicle epilogue) and an optional self-chosen display
135 * name, and DELIBERATELY nothing that identifies the player: no user id, no device id,
136 * no email — and not even the run id (the share token is the only handle). `run.runId`
137 * is blanked for that reason; the read-only view never renders it.
138 */
139export interface PublicRun {
140    run: RunSnapshot
141    /** The sharer's opt-in display name, or null when shared anonymously. */
142    attribution: string | null
143    /** When this run is itself a replay (issue #89), the one-hop "remixed from" credit;
144     *  null/absent for an original run. Walked from the parent's live snapshot, so it
145     *  honors the source's current privacy opt-in. */
146    remixedFrom?: RemixCredit | null
147}
148 
⋯ 13 lines hidden (lines 149–161)149/** What the OWNER sees about a run's share status: the live token (null = not shared)
150 *  and the current display name. Owner-only — never part of the public projection. */
151export interface ShareState {
152    token: string | null
153    name: string | null
154}
155 
156/** The brag line a share prefills (the X intent + the native sheet) — one source so the
157 *  end screen, the saved-run page, and the public page never drift (issue #88). */
158export function buildShareText(objectiveTitle: string, status: RunOutcome, progress: number): string {
159    const verb = status === 'victory' ? 'I rewrote history' : 'I tried to rewrite history'
160    return `${verb} in Revisionist: ${objectiveTitle || 'a historical mission'} — ${progress}% rewritten.`
161}

One nullable column carries the lineage

The pointer is a single nullable column on run_snapshots: derived_from_run_id, a foreign key to runs(id). It points at the parent run (null = an original, not a replay). ON DELETE SET NULL means a child outlives a deleted parent — the link just goes quiet, never a dangling reference — and the index serves the later "every run remixed from X" spread query.

Why the pointer is a stable run id, not the revocable share token.

supabase/migrations/0007_run_lineage.sql · 20 lines

supabase/migrations/0007_run_lineage.sql20 lines · Transact-SQL

1-- Run lineage / replay (issue #89): a replayed run is a fresh run seeded with a shared
2-- run's captured objective — same objective, new player, new dispatches. Stamp the child
3-- with a pointer back to the run it was remixed from, so a "remixed from" credit can be
4-- shown (walking ONE hop to the parent's current title + opt-in share name) and the
5-- spread of a custom objective can be traced later.
6--
7--   derived_from_run_id — the PARENT run this one was remixed from (null = an original,
8--                         not a replay). A STABLE pointer to runs.id, not the parent's
9--                         share token (tokens can be revoked / re-minted): the credit is
10--                         walked at render time from the parent's live snapshot row, so a
11--                         later un-share correctly drops the name back to anonymous.
12--                         ON DELETE SET NULL — a child outlives a deleted parent (the
13--                         lineage link simply goes quiet), never a dangling reference.
14alter table public.run_snapshots
15    add column if not exists derived_from_run_id uuid references public.runs(id) on delete set null;
16 
17-- Index the pointer so "every run remixed from X" (the spread / viral-tree query, a
18-- later nicety) doesn't sequentially scan every saved run.
19create index if not exists run_snapshots_derived_from_idx
20    on public.run_snapshots (derived_from_run_id);

Writing the pointer — stamped once, never nulled

Lineage is stamped at save time. The client only ever holds the public share token, so saveRun resolves it server-side to the parent's stable run id and writes that. Two safeguards make this robust: it guards self-derivation (parentId !== snapshot.runId), and — the key fix — it sets the column only on a successful resolve and never writes null. So a replay whose source un-shares mid-run keeps the pointer an earlier save stamped, and an ordinary run's upsert is byte-identical to before (the column is simply absent).

Supabase saveRun: resolve the token to a stable id; stamp on success, never null.

server/utils/run-snapshot-store.ts · 382 lines

server/utils/run-snapshot-store.ts382 lines · TypeScript

⋯ 217 lines hidden (lines 1–217)1/**
* The run-snapshot store — where a finished run becomes a durable, owned record.
* POST /api/run-save writes the snapshot here keyed by the run id; the "your runs"
* routes (GET /api/runs, GET /api/runs/:id) read it back, scoped to the account
* subject so a player only ever sees their own runs.
*
* Two adapters behind one port, chosen by config — the repo's env-degradation idiom
* (cf. runStore, balanceStore):
*   - in-memory (default): no external dependency, so `npm run dev` and the unit
*     tests need nothing. History doesn't outlive the process, but the round-trip is
*     real, which is what the save -> list -> load test exercises.
*   - Supabase: used when SUPABASE_URL + SUPABASE_SECRET_KEY are configured. Writes
*     the `run_snapshots` row (and stamps the owner onto the billing `runs` row) via
*     the service (secret) key, which bypasses RLS — the table has no public policy,
*     so it is server-only.
*
* Ownership is by SUBJECT (the Supabase user id, falling back to the device id) — the
* same string balances/runs key on. Reads filter by it, so a non-owned run id reads
* as absent (the route turns that into a 404, never leaking another subject's run).
*/
21import { randomUUID } from 'node:crypto'
22import { createClient, type SupabaseClient } from '@supabase/supabase-js'
23import { supabaseConfig } from './supabase'
24import type { RunSnapshot, RunSummary, PublicRun, ShareState, RemixCredit } from '~/utils/run-snapshot'
25 
26/** Save-time extras the snapshot blob itself doesn't carry. */
27export interface SaveRunOptions {
  /** When this run is a replay (issue #89), the SOURCE run's share token — resolved
   *  server-side to the parent's stable run id and stamped as the lineage pointer. The
   *  client only ever holds the public token (the run id is never exposed to it). */
  derivedFromToken?: string | null
32}
33 
34export interface RunSnapshotStore {
  /** Persist (or overwrite) the finished run's snapshot, owned by `subject`. */
  saveRun(subject: string, snapshot: RunSnapshot, opts?: SaveRunOptions): Promise<void>
  /** A subject's saved runs, newest first (the list projection). */
  listRuns(subject: string): Promise<RunSummary[]>
  /** One saved run by id, only if `subject` owns it; null otherwise. */
  getRun(subject: string, runId: string): Promise<RunSnapshot | null>
  /**
   * Make an owned run public (issue #88): mint a share token if it has none (reuse it
   * if already shared, so the URL is stable), set the opt-in display name, and return
   * the live share state. Null when `subject` doesn't own the run (reads as absent).
   */
  shareRun(subject: string, runId: string, name: string | null): Promise<ShareState | null>
  /** Revoke an owned run's share (clear token + name). Idempotent; a no-op otherwise. */
  unshareRun(subject: string, runId: string): Promise<void>
  /** The owner's view of a run's share status; null when `subject` doesn't own it. */
  getShareState(subject: string, runId: string): Promise<ShareState | null>
  /** Resolve a public share token to its sanitized projection; null when unknown. */
  getPublicRun(token: string): Promise<PublicRun | null>
53}
54 
55/** Project a snapshot down to the list row. */
56function toSummary(snapshot: RunSnapshot, createdAt: string): RunSummary {
  return {
      runId: snapshot.runId,
      status: snapshot.status,
      title: snapshot.objective.title,
      progress: snapshot.objectiveProgress,
      createdAt
  }
64}
65 
66/**
* Project a stored snapshot down to its PUBLIC, shareable form. The snapshot blob is
* already identity-free (the owner lives only in the row's `user_id` column, never in
* the data), so the sanitization here is deliberate-and-explicit: blank the run id (the
* share token is the only handle a public viewer gets) and surface only the opt-in
* display name. This is the boundary the public endpoint serves — never the raw row.
*/
73export function toPublicRun(snapshot: RunSnapshot, name: string | null, remixedFrom: RemixCredit | null = null): PublicRun {
  const trimmed = name?.trim()
  return {
      run: { ...snapshot, runId: '' },
      attribution: trimmed ? trimmed : null,
      remixedFrom
  }
80}
81 
82/**
* Build the one-hop "remixed from" credit (issue #89) from the PARENT run's live fields.
* Only public, opt-in data crosses: the parent's display name (anonymous if blank/unset),
* its objective title, and its current share token (for an optional backlink, null when
* the parent is no longer shared). Never the parent's run id, owner, or device.
*/
88function toRemixCredit(
  parent: { title: string; shareName: string | null; shareToken: string | null } | null
90): RemixCredit | null {
  if (!parent) return null
  const name = parent.shareName?.trim()
  return {
      attribution: name ? name : null,
      objectiveTitle: parent.title,
      sourceToken: parent.shareToken ?? null
  }
98}
99 
100/** Dev/test default — keeps the round-trip real (save -> list -> load) without any
*  external dependency. Not durable across process restarts; the Supabase adapter is
*  the one that actually preserves history. */
103export class InMemoryRunSnapshotStore implements RunSnapshotStore {
  private readonly runs: Array<{
      subject: string
      snapshot: RunSnapshot
      createdAt: string
      shareToken: string | null
      shareName: string | null
      derivedFromRunId: string | null
  }> = []
112 
  /** Resolve a source share token to the parent's stable run id (issue #89), guarding
   *  self-derivation. Returns null for an unknown token or no token. */
  private resolveDerivedRunId(token: string | null | undefined, selfRunId: string): string | null {
      if (!token) return null
      const parent = this.runs.find((r) => r.shareToken === token)
      return parent && parent.snapshot.runId !== selfRunId ? parent.snapshot.runId : null
  }
120 
  async saveRun(subject: string, snapshot: RunSnapshot, opts?: SaveRunOptions): Promise<void> {
      const createdAt = new Date().toISOString()
      const existing = this.runs.find((r) => r.snapshot.runId === snapshot.runId)
      if (existing) {
          // Snapshots are immutable, but the save fires again once the epilogue
          // lands — overwrite in place (keep the original position/createdAt, and any
          // share already minted for this run).
          existing.subject = subject
          existing.snapshot = snapshot
          // Stamp the pointer only on a SUCCESSFUL resolve, and never overwrite one
          // already set with null: it's stable once stamped, so a later un-share (the
          // token stops resolving) leaves the lineage intact — only the walked credit
          // goes anonymous (see getPublicRun).
          const resolved = this.resolveDerivedRunId(opts?.derivedFromToken, snapshot.runId)
          if (resolved) existing.derivedFromRunId = resolved
          return
      }
      this.runs.push({
          subject,
          snapshot,
          createdAt,
          shareToken: null,
          shareName: null,
          derivedFromRunId: this.resolveDerivedRunId(opts?.derivedFromToken, snapshot.runId)
      })
  }
147 
  async listRuns(subject: string): Promise<RunSummary[]> {
      return this.runs
          .filter((r) => r.subject === subject)
          .map((r) => toSummary(r.snapshot, r.createdAt))
          .reverse()
  }
154 
  async getRun(subject: string, runId: string): Promise<RunSnapshot | null> {
      const found = this.runs.find((r) => r.snapshot.runId === runId && r.subject === subject)
      return found ? found.snapshot : null
  }
159 
  async shareRun(subject: string, runId: string, name: string | null): Promise<ShareState | null> {
      const found = this.runs.find((r) => r.snapshot.runId === runId && r.subject === subject)
      if (!found) return null
      found.shareToken = found.shareToken ?? randomUUID()
      found.shareName = name
      return { token: found.shareToken, name: found.shareName }
  }
167 
  async unshareRun(subject: string, runId: string): Promise<void> {
      const found = this.runs.find((r) => r.snapshot.runId === runId && r.subject === subject)
      if (!found) return
      found.shareToken = null
      found.shareName = null
  }
174 
  async getShareState(subject: string, runId: string): Promise<ShareState | null> {
      const found = this.runs.find((r) => r.snapshot.runId === runId && r.subject === subject)
      return found ? { token: found.shareToken, name: found.shareName } : null
  }
179 
  async getPublicRun(token: string): Promise<PublicRun | null> {
      const found = this.runs.find((r) => r.shareToken === token)
      if (!found) return null
      // Walk one hop to the parent's LIVE row for the "remixed from" credit (issue #89),
      // so the source's current opt-in (name / still-shared) is what surfaces.
      const parent = found.derivedFromRunId
          ? this.runs.find((r) => r.snapshot.runId === found.derivedFromRunId) ?? null
          : null
      const remixedFrom = toRemixCredit(
          parent
              ? { title: parent.snapshot.objective.title, shareName: parent.shareName, shareToken: parent.shareToken }
              : null
      )
      return toPublicRun(found.snapshot, found.shareName, remixedFrom)
  }
195}
196 
197/** Records each saved run as a `run_snapshots` row via the service (secret) key,
*  which bypasses RLS — the table has no public policy, so it is server-only. */
199export class SupabaseRunSnapshotStore implements RunSnapshotStore {
  constructor(private readonly client: SupabaseClient) {}
201 
  async saveRun(subject: string, snapshot: RunSnapshot, opts?: SaveRunOptions): Promise<void> {
      // Stamp the owner onto the billing run row too (it carries only device_id
      // today) so a run's ownership is legible from either table.
      const owned = await this.client.from('runs').update({ user_id: subject }).eq('id', snapshot.runId)
      if (owned.error) throw new Error(`runs owner update failed: ${owned.error.message}`)
207 
      const row: Record<string, unknown> = {
          run_id: snapshot.runId,
          user_id: subject,
          version: snapshot.version,
          status: snapshot.status,
          title: snapshot.objective.title,
          progress: snapshot.objectiveProgress,
          data: snapshot
      }
      // Stamp the lineage pointer ONLY for a replay (issue #89): resolve the source's
      // public share token to the parent's STABLE run id (a token can be revoked / re-
      // minted; the id can't), guarding self-derivation. The column is set only on a
      // SUCCESSFUL resolve and is NEVER written as null — so an ordinary run's upsert is
      // byte-identical to before, and a replay whose source un-shares before the run ends
      // keeps the pointer an earlier save stamped (the credit then walks to an anonymized
      // parent). It's a stable pointer, never overwritten with null.
      if (opts?.derivedFromToken) {
          const parentId = await this.resolveDerivedRunId(opts.derivedFromToken)
          if (parentId && parentId !== snapshot.runId) row.derived_from_run_id = parentId
      }
228 
      // Upsert on the run-id PK so the second (post-epilogue) save overwrites the
      // first rather than erroring — the snapshot is immutable, the write is not.
      const { error } = await this.client.from('run_snapshots').upsert(row)
      if (error) throw new Error(`run_snapshots upsert failed: ${error.message}`)
  }
234 
  /** Resolve a source share token to the parent's stable run id (issue #89); null when
   *  the token is unknown / revoked. */
  private async resolveDerivedRunId(token: string): Promise<string | null> {
      const { data, error } = await this.client
          .from('run_snapshots')
          .select('run_id')
          .eq('share_token', token)
          .maybeSingle()
      if (error) throw new Error(`run_snapshots lineage resolve failed: ${error.message}`)
      return (data?.run_id as string | null) ?? null
  }
246 
  /** Walk one hop to the parent's LIVE row for the "remixed from" credit (issue #89) —
⋯ 135 lines hidden (lines 248–382)248     *  its current title, opt-in name, and share token. Null when there's no parent (not
   *  a replay) or the parent has since been deleted. */
  private async resolveRemixCredit(parentRunId: string | null): Promise<RemixCredit | null> {
      if (!parentRunId) return null
      const { data, error } = await this.client
          .from('run_snapshots')
          .select('title, share_name, share_token')
          .eq('run_id', parentRunId)
          .maybeSingle()
      if (error) throw new Error(`run_snapshots remix credit failed: ${error.message}`)
      if (!data) return null
      return toRemixCredit({
          title: data.title as string,
          shareName: (data.share_name as string | null) ?? null,
          shareToken: (data.share_token as string | null) ?? null
      })
  }
265 
  async listRuns(subject: string): Promise<RunSummary[]> {
      const { data, error } = await this.client
          .from('run_snapshots')
          .select('run_id, status, title, progress, created_at')
          .eq('user_id', subject)
          .order('created_at', { ascending: false })
      if (error) throw new Error(`run_snapshots list failed: ${error.message}`)
      return ((data ?? []) as Array<{
          run_id: string
          status: RunSnapshot['status']
          title: string
          progress: number
          created_at: string
      }>).map((row) => ({
          runId: row.run_id,
          status: row.status,
          title: row.title,
          progress: row.progress,
          createdAt: row.created_at
      }))
  }
287 
  async getRun(subject: string, runId: string): Promise<RunSnapshot | null> {
      const { data, error } = await this.client
          .from('run_snapshots')
          .select('data')
          .eq('run_id', runId)
          .eq('user_id', subject)
          .maybeSingle()
      if (error) throw new Error(`run_snapshots get failed: ${error.message}`)
      return (data?.data ?? null) as RunSnapshot | null
  }
298 
  async shareRun(subject: string, runId: string, name: string | null): Promise<ShareState | null> {
      // Mint a token ONLY if the owned run has none yet, in one row-atomic UPDATE (the
      // `share_token IS NULL` guard). Two concurrent shares can't both mint — the second
      // sees the first's token and matches no row — so re-sharing keeps one stable URL
      // and never trips the unique constraint. (A wasted uuid when already shared is
      // harmless: the guard excludes the row, so it's never written.)
      const minted = await this.client
          .from('run_snapshots')
          .update({ share_token: randomUUID() })
          .eq('run_id', runId)
          .eq('user_id', subject)
          .is('share_token', null)
      if (minted.error) throw new Error(`run_snapshots share mint failed: ${minted.error.message}`)
312 
      // Set the name and read back the live token (the freshly-minted one, or a token
      // from a prior share). Scoped to the owner, so a run the subject doesn't own
      // matches no row and reads as absent (null) — never shared on their behalf.
      const { data, error } = await this.client
          .from('run_snapshots')
          .update({ share_name: name })
          .eq('run_id', runId)
          .eq('user_id', subject)
          .select('share_token, share_name')
          .maybeSingle()
      if (error) throw new Error(`run_snapshots share failed: ${error.message}`)
      if (!data) return null
      return { token: data.share_token as string, name: (data.share_name as string | null) ?? null }
  }
327 
  async unshareRun(subject: string, runId: string): Promise<void> {
      const { error } = await this.client
          .from('run_snapshots')
          .update({ share_token: null, share_name: null })
          .eq('run_id', runId)
          .eq('user_id', subject)
      if (error) throw new Error(`run_snapshots unshare failed: ${error.message}`)
  }
336 
  async getShareState(subject: string, runId: string): Promise<ShareState | null> {
      const { data, error } = await this.client
          .from('run_snapshots')
          .select('share_token, share_name')
          .eq('run_id', runId)
          .eq('user_id', subject)
          .maybeSingle()
      if (error) throw new Error(`run_snapshots share state failed: ${error.message}`)
      if (!data) return null
      return {
          token: (data.share_token as string | null) ?? null,
          name: (data.share_name as string | null) ?? null
      }
  }
351 
  async getPublicRun(token: string): Promise<PublicRun | null> {
      // Looked up by the share token ALONE — no owner filter — because the public page
      // has no subject. The token is the capability; an unknown/revoked token misses.
      const { data, error } = await this.client
          .from('run_snapshots')
          .select('data, share_name, derived_from_run_id')
          .eq('share_token', token)
          .maybeSingle()
      if (error) throw new Error(`run_snapshots public get failed: ${error.message}`)
      if (!data) return null
      const remixedFrom = await this.resolveRemixCredit((data.derived_from_run_id as string | null) ?? null)
      return toPublicRun(data.data as RunSnapshot, (data.share_name as string | null) ?? null, remixedFrom)
  }
365}
366 
367let cached: RunSnapshotStore | null = null
368 
369/** The configured run-snapshot store (memoized — reuses one Supabase client). */
370export function runSnapshotStore(): RunSnapshotStore {
  if (cached) return cached
  const cfg = supabaseConfig()
  cached = cfg
      ? new SupabaseRunSnapshotStore(createClient(cfg.url, cfg.secretKey, { auth: { persistSession: false } }))
      : new InMemoryRunSnapshotStore()
  return cached
377}
378 
379/** Test seam: clear the memoized store so the next call re-reads config. */
380export function resetRunSnapshotStore(): void {
  cached = null
382}

Reading the credit — walk exactly one hop

getPublicRun reads the run by token (as before), then walks the pointer one hop: fetch the parent's row by run_id and project its current title, share name, and share token into a RemixCredit. toRemixCredit is the single place that decides anonymity — a blank/absent name becomes null ("an anonymous run" in the UI), and the token is carried only for the backlink. The owner-scoped reads (getRun, listRuns) never select the column, so the pointer stays server-side.

toRemixCredit (the anonymity rule) · resolveRemixCredit (the hop) · getPublicRun wiring.

server/utils/run-snapshot-store.ts · 382 lines

server/utils/run-snapshot-store.ts382 lines · TypeScript

⋯ 81 lines hidden (lines 1–81)1/**
* The run-snapshot store — where a finished run becomes a durable, owned record.
* POST /api/run-save writes the snapshot here keyed by the run id; the "your runs"
* routes (GET /api/runs, GET /api/runs/:id) read it back, scoped to the account
* subject so a player only ever sees their own runs.
*
* Two adapters behind one port, chosen by config — the repo's env-degradation idiom
* (cf. runStore, balanceStore):
*   - in-memory (default): no external dependency, so `npm run dev` and the unit
*     tests need nothing. History doesn't outlive the process, but the round-trip is
*     real, which is what the save -> list -> load test exercises.
*   - Supabase: used when SUPABASE_URL + SUPABASE_SECRET_KEY are configured. Writes
*     the `run_snapshots` row (and stamps the owner onto the billing `runs` row) via
*     the service (secret) key, which bypasses RLS — the table has no public policy,
*     so it is server-only.
*
* Ownership is by SUBJECT (the Supabase user id, falling back to the device id) — the
* same string balances/runs key on. Reads filter by it, so a non-owned run id reads
* as absent (the route turns that into a 404, never leaking another subject's run).
*/
21import { randomUUID } from 'node:crypto'
22import { createClient, type SupabaseClient } from '@supabase/supabase-js'
23import { supabaseConfig } from './supabase'
24import type { RunSnapshot, RunSummary, PublicRun, ShareState, RemixCredit } from '~/utils/run-snapshot'
25 
26/** Save-time extras the snapshot blob itself doesn't carry. */
27export interface SaveRunOptions {
  /** When this run is a replay (issue #89), the SOURCE run's share token — resolved
   *  server-side to the parent's stable run id and stamped as the lineage pointer. The
   *  client only ever holds the public token (the run id is never exposed to it). */
  derivedFromToken?: string | null
32}
33 
34export interface RunSnapshotStore {
  /** Persist (or overwrite) the finished run's snapshot, owned by `subject`. */
  saveRun(subject: string, snapshot: RunSnapshot, opts?: SaveRunOptions): Promise<void>
  /** A subject's saved runs, newest first (the list projection). */
  listRuns(subject: string): Promise<RunSummary[]>
  /** One saved run by id, only if `subject` owns it; null otherwise. */
  getRun(subject: string, runId: string): Promise<RunSnapshot | null>
  /**
   * Make an owned run public (issue #88): mint a share token if it has none (reuse it
   * if already shared, so the URL is stable), set the opt-in display name, and return
   * the live share state. Null when `subject` doesn't own the run (reads as absent).
   */
  shareRun(subject: string, runId: string, name: string | null): Promise<ShareState | null>
  /** Revoke an owned run's share (clear token + name). Idempotent; a no-op otherwise. */
  unshareRun(subject: string, runId: string): Promise<void>
  /** The owner's view of a run's share status; null when `subject` doesn't own it. */
  getShareState(subject: string, runId: string): Promise<ShareState | null>
  /** Resolve a public share token to its sanitized projection; null when unknown. */
  getPublicRun(token: string): Promise<PublicRun | null>
53}
54 
55/** Project a snapshot down to the list row. */
56function toSummary(snapshot: RunSnapshot, createdAt: string): RunSummary {
  return {
      runId: snapshot.runId,
      status: snapshot.status,
      title: snapshot.objective.title,
      progress: snapshot.objectiveProgress,
      createdAt
  }
64}
65 
66/**
* Project a stored snapshot down to its PUBLIC, shareable form. The snapshot blob is
* already identity-free (the owner lives only in the row's `user_id` column, never in
* the data), so the sanitization here is deliberate-and-explicit: blank the run id (the
* share token is the only handle a public viewer gets) and surface only the opt-in
* display name. This is the boundary the public endpoint serves — never the raw row.
*/
73export function toPublicRun(snapshot: RunSnapshot, name: string | null, remixedFrom: RemixCredit | null = null): PublicRun {
  const trimmed = name?.trim()
  return {
      run: { ...snapshot, runId: '' },
      attribution: trimmed ? trimmed : null,
      remixedFrom
  }
80}
81 
82/**
* Build the one-hop "remixed from" credit (issue #89) from the PARENT run's live fields.
* Only public, opt-in data crosses: the parent's display name (anonymous if blank/unset),
* its objective title, and its current share token (for an optional backlink, null when
* the parent is no longer shared). Never the parent's run id, owner, or device.
*/
88function toRemixCredit(
  parent: { title: string; shareName: string | null; shareToken: string | null } | null
90): RemixCredit | null {
  if (!parent) return null
  const name = parent.shareName?.trim()
  return {
      attribution: name ? name : null,
      objectiveTitle: parent.title,
      sourceToken: parent.shareToken ?? null
  }
98}
99 
100/** Dev/test default — keeps the round-trip real (save -> list -> load) without any
*  external dependency. Not durable across process restarts; the Supabase adapter is
⋯ 148 lines hidden (lines 102–249)102 *  the one that actually preserves history. */
103export class InMemoryRunSnapshotStore implements RunSnapshotStore {
  private readonly runs: Array<{
      subject: string
      snapshot: RunSnapshot
      createdAt: string
      shareToken: string | null
      shareName: string | null
      derivedFromRunId: string | null
  }> = []
112 
  /** Resolve a source share token to the parent's stable run id (issue #89), guarding
   *  self-derivation. Returns null for an unknown token or no token. */
  private resolveDerivedRunId(token: string | null | undefined, selfRunId: string): string | null {
      if (!token) return null
      const parent = this.runs.find((r) => r.shareToken === token)
      return parent && parent.snapshot.runId !== selfRunId ? parent.snapshot.runId : null
  }
120 
  async saveRun(subject: string, snapshot: RunSnapshot, opts?: SaveRunOptions): Promise<void> {
      const createdAt = new Date().toISOString()
      const existing = this.runs.find((r) => r.snapshot.runId === snapshot.runId)
      if (existing) {
          // Snapshots are immutable, but the save fires again once the epilogue
          // lands — overwrite in place (keep the original position/createdAt, and any
          // share already minted for this run).
          existing.subject = subject
          existing.snapshot = snapshot
          // Stamp the pointer only on a SUCCESSFUL resolve, and never overwrite one
          // already set with null: it's stable once stamped, so a later un-share (the
          // token stops resolving) leaves the lineage intact — only the walked credit
          // goes anonymous (see getPublicRun).
          const resolved = this.resolveDerivedRunId(opts?.derivedFromToken, snapshot.runId)
          if (resolved) existing.derivedFromRunId = resolved
          return
      }
      this.runs.push({
          subject,
          snapshot,
          createdAt,
          shareToken: null,
          shareName: null,
          derivedFromRunId: this.resolveDerivedRunId(opts?.derivedFromToken, snapshot.runId)
      })
  }
147 
  async listRuns(subject: string): Promise<RunSummary[]> {
      return this.runs
          .filter((r) => r.subject === subject)
          .map((r) => toSummary(r.snapshot, r.createdAt))
          .reverse()
  }
154 
  async getRun(subject: string, runId: string): Promise<RunSnapshot | null> {
      const found = this.runs.find((r) => r.snapshot.runId === runId && r.subject === subject)
      return found ? found.snapshot : null
  }
159 
  async shareRun(subject: string, runId: string, name: string | null): Promise<ShareState | null> {
      const found = this.runs.find((r) => r.snapshot.runId === runId && r.subject === subject)
      if (!found) return null
      found.shareToken = found.shareToken ?? randomUUID()
      found.shareName = name
      return { token: found.shareToken, name: found.shareName }
  }
167 
  async unshareRun(subject: string, runId: string): Promise<void> {
      const found = this.runs.find((r) => r.snapshot.runId === runId && r.subject === subject)
      if (!found) return
      found.shareToken = null
      found.shareName = null
  }
174 
  async getShareState(subject: string, runId: string): Promise<ShareState | null> {
      const found = this.runs.find((r) => r.snapshot.runId === runId && r.subject === subject)
      return found ? { token: found.shareToken, name: found.shareName } : null
  }
179 
  async getPublicRun(token: string): Promise<PublicRun | null> {
      const found = this.runs.find((r) => r.shareToken === token)
      if (!found) return null
      // Walk one hop to the parent's LIVE row for the "remixed from" credit (issue #89),
      // so the source's current opt-in (name / still-shared) is what surfaces.
      const parent = found.derivedFromRunId
          ? this.runs.find((r) => r.snapshot.runId === found.derivedFromRunId) ?? null
          : null
      const remixedFrom = toRemixCredit(
          parent
              ? { title: parent.snapshot.objective.title, shareName: parent.shareName, shareToken: parent.shareToken }
              : null
      )
      return toPublicRun(found.snapshot, found.shareName, remixedFrom)
  }
195}
196 
197/** Records each saved run as a `run_snapshots` row via the service (secret) key,
*  which bypasses RLS — the table has no public policy, so it is server-only. */
199export class SupabaseRunSnapshotStore implements RunSnapshotStore {
  constructor(private readonly client: SupabaseClient) {}
201 
  async saveRun(subject: string, snapshot: RunSnapshot, opts?: SaveRunOptions): Promise<void> {
      // Stamp the owner onto the billing run row too (it carries only device_id
      // today) so a run's ownership is legible from either table.
      const owned = await this.client.from('runs').update({ user_id: subject }).eq('id', snapshot.runId)
      if (owned.error) throw new Error(`runs owner update failed: ${owned.error.message}`)
207 
      const row: Record<string, unknown> = {
          run_id: snapshot.runId,
          user_id: subject,
          version: snapshot.version,
          status: snapshot.status,
          title: snapshot.objective.title,
          progress: snapshot.objectiveProgress,
          data: snapshot
      }
      // Stamp the lineage pointer ONLY for a replay (issue #89): resolve the source's
      // public share token to the parent's STABLE run id (a token can be revoked / re-
      // minted; the id can't), guarding self-derivation. The column is set only on a
      // SUCCESSFUL resolve and is NEVER written as null — so an ordinary run's upsert is
      // byte-identical to before, and a replay whose source un-shares before the run ends
      // keeps the pointer an earlier save stamped (the credit then walks to an anonymized
      // parent). It's a stable pointer, never overwritten with null.
      if (opts?.derivedFromToken) {
          const parentId = await this.resolveDerivedRunId(opts.derivedFromToken)
          if (parentId && parentId !== snapshot.runId) row.derived_from_run_id = parentId
      }
228 
      // Upsert on the run-id PK so the second (post-epilogue) save overwrites the
      // first rather than erroring — the snapshot is immutable, the write is not.
      const { error } = await this.client.from('run_snapshots').upsert(row)
      if (error) throw new Error(`run_snapshots upsert failed: ${error.message}`)
  }
234 
  /** Resolve a source share token to the parent's stable run id (issue #89); null when
   *  the token is unknown / revoked. */
  private async resolveDerivedRunId(token: string): Promise<string | null> {
      const { data, error } = await this.client
          .from('run_snapshots')
          .select('run_id')
          .eq('share_token', token)
          .maybeSingle()
      if (error) throw new Error(`run_snapshots lineage resolve failed: ${error.message}`)
      return (data?.run_id as string | null) ?? null
  }
246 
  /** Walk one hop to the parent's LIVE row for the "remixed from" credit (issue #89) —
   *  its current title, opt-in name, and share token. Null when there's no parent (not
   *  a replay) or the parent has since been deleted. */
  private async resolveRemixCredit(parentRunId: string | null): Promise<RemixCredit | null> {
      if (!parentRunId) return null
      const { data, error } = await this.client
          .from('run_snapshots')
          .select('title, share_name, share_token')
          .eq('run_id', parentRunId)
          .maybeSingle()
      if (error) throw new Error(`run_snapshots remix credit failed: ${error.message}`)
      if (!data) return null
      return toRemixCredit({
          title: data.title as string,
          shareName: (data.share_name as string | null) ?? null,
          shareToken: (data.share_token as string | null) ?? null
      })
  }
265 
⋯ 86 lines hidden (lines 266–351)266    async listRuns(subject: string): Promise<RunSummary[]> {
      const { data, error } = await this.client
          .from('run_snapshots')
          .select('run_id, status, title, progress, created_at')
          .eq('user_id', subject)
          .order('created_at', { ascending: false })
      if (error) throw new Error(`run_snapshots list failed: ${error.message}`)
      return ((data ?? []) as Array<{
          run_id: string
          status: RunSnapshot['status']
          title: string
          progress: number
          created_at: string
      }>).map((row) => ({
          runId: row.run_id,
          status: row.status,
          title: row.title,
          progress: row.progress,
          createdAt: row.created_at
      }))
  }
287 
  async getRun(subject: string, runId: string): Promise<RunSnapshot | null> {
      const { data, error } = await this.client
          .from('run_snapshots')
          .select('data')
          .eq('run_id', runId)
          .eq('user_id', subject)
          .maybeSingle()
      if (error) throw new Error(`run_snapshots get failed: ${error.message}`)
      return (data?.data ?? null) as RunSnapshot | null
  }
298 
  async shareRun(subject: string, runId: string, name: string | null): Promise<ShareState | null> {
      // Mint a token ONLY if the owned run has none yet, in one row-atomic UPDATE (the
      // `share_token IS NULL` guard). Two concurrent shares can't both mint — the second
      // sees the first's token and matches no row — so re-sharing keeps one stable URL
      // and never trips the unique constraint. (A wasted uuid when already shared is
      // harmless: the guard excludes the row, so it's never written.)
      const minted = await this.client
          .from('run_snapshots')
          .update({ share_token: randomUUID() })
          .eq('run_id', runId)
          .eq('user_id', subject)
          .is('share_token', null)
      if (minted.error) throw new Error(`run_snapshots share mint failed: ${minted.error.message}`)
312 
      // Set the name and read back the live token (the freshly-minted one, or a token
      // from a prior share). Scoped to the owner, so a run the subject doesn't own
      // matches no row and reads as absent (null) — never shared on their behalf.
      const { data, error } = await this.client
          .from('run_snapshots')
          .update({ share_name: name })
          .eq('run_id', runId)
          .eq('user_id', subject)
          .select('share_token, share_name')
          .maybeSingle()
      if (error) throw new Error(`run_snapshots share failed: ${error.message}`)
      if (!data) return null
      return { token: data.share_token as string, name: (data.share_name as string | null) ?? null }
  }
327 
  async unshareRun(subject: string, runId: string): Promise<void> {
      const { error } = await this.client
          .from('run_snapshots')
          .update({ share_token: null, share_name: null })
          .eq('run_id', runId)
          .eq('user_id', subject)
      if (error) throw new Error(`run_snapshots unshare failed: ${error.message}`)
  }
336 
  async getShareState(subject: string, runId: string): Promise<ShareState | null> {
      const { data, error } = await this.client
          .from('run_snapshots')
          .select('share_token, share_name')
          .eq('run_id', runId)
          .eq('user_id', subject)
          .maybeSingle()
      if (error) throw new Error(`run_snapshots share state failed: ${error.message}`)
      if (!data) return null
      return {
          token: (data.share_token as string | null) ?? null,
          name: (data.share_name as string | null) ?? null
      }
  }
351 
  async getPublicRun(token: string): Promise<PublicRun | null> {
      // Looked up by the share token ALONE — no owner filter — because the public page
      // has no subject. The token is the capability; an unknown/revoked token misses.
      const { data, error } = await this.client
          .from('run_snapshots')
          .select('data, share_name, derived_from_run_id')
          .eq('share_token', token)
          .maybeSingle()
      if (error) throw new Error(`run_snapshots public get failed: ${error.message}`)
      if (!data) return null
      const remixedFrom = await this.resolveRemixCredit((data.derived_from_run_id as string | null) ?? null)
      return toPublicRun(data.data as RunSnapshot, (data.share_name as string | null) ?? null, remixedFrom)
⋯ 19 lines hidden (lines 364–382)364    }
365}
366 
367let cached: RunSnapshotStore | null = null
368 
369/** The configured run-snapshot store (memoized — reuses one Supabase client). */
370export function runSnapshotStore(): RunSnapshotStore {
  if (cached) return cached
  const cfg = supabaseConfig()
  cached = cfg
      ? new SupabaseRunSnapshotStore(createClient(cfg.url, cfg.secretKey, { auth: { persistSession: false } }))
      : new InMemoryRunSnapshotStore()
  return cached
377}
378 
379/** Test seam: clear the memoized store so the next call re-reads config. */
380export function resetRunSnapshotStore(): void {
  cached = null
382}

The seam: carrying the source token through a run

The token rides from the shared page to the save as a sibling of the snapshot, never inside the immutable blob. On the client, a replay is held in replayState — the seed objective, the source token, and the source's name at seed time. preseedReplay resets first (the share page may follow an abandoned run in the same tab) then records the seed; it survives chooseObjective so it can stamp lineage at save, and is cleared by resetGame so a fresh run carries none of it.

ReplaySeed + preseedReplay / clearReplayState.

stores/game.ts · 1455 lines

stores/game.ts1455 lines · TypeScript

⋯ 211 lines hidden (lines 1–211)1import { defineStore } from 'pinia'
2import type { GameObjective, ObjectiveSteer } from '~/server/utils/objectives'
3import type { Pack } from '~/server/utils/packs'
4import type { GroundedFigure } from '~/server/utils/figure-grounding'
5import { formatContactMoment, type ContactMoment } from '~/utils/contact-moment'
6import type { FigureSuggestion } from '~/server/utils/figure-suggester'
7import type { ChronicleEntry } from '~/server/utils/openai'
8import type { FigureStudy, ArchiveLookup } from '~/server/utils/prompt-builder'
9import type { Anachronism } from '~/server/utils/anachronism'
10import { chainStatus, type ChainStatus } from '~/utils/causal-chain'
11import type { Craft } from '~/utils/craft'
12import type { Continuity } from '~/utils/continuity'
13import type { DiceOutcome } from '~/utils/dice'
14import { generateGameSummary, rateEfficiency, type GameSummary } from '~/utils/game-summary'
15import { TOTAL_MESSAGES, MAX_PROGRESS_SWING, MAX_PROGRESS } from '~/utils/game-config'
16import { RUN_SNAPSHOT_VERSION, type RunSnapshot } from '~/utils/run-snapshot'
17 
18export type Valence = 'positive' | 'negative' | 'neutral'
19 
20/**
* A historical figure the player has reached out to. Figures are freeform — the
* player can write to anyone, in any era. The AI infers each figure's era and a
* short descriptor on first contact, which we cache here for the UI.
*/
25export interface HistoricalFigure {
  name: string
  era: string
  descriptor: string
29}
30 
31/**
* Timeline Ledger entry — a single recorded change to history.
*
* The ledger is the heart of the game: every resolved turn appends one entry
* describing how the world bent, so the player literally watches the timeline
* rewrite itself as they play.
*/
38export interface TimelineEvent {
  id: string
  figureName: string
  era: string
  headline: string
  detail: string
  diceRoll: number
  diceOutcome: DiceOutcome
  progressChange: number
  /** The engine's swing BEFORE the anachronism amplifier — shown so the player
   *  can see exactly what their wager did ("+8 ⚡ far-ahead → +11%"). */
  baseProgressChange?: number
  valence: Valence
  /** How anachronistic the player's nudge was — it widened this swing. */
  anachronism?: Anachronism
  /** How far this landed from the nearest foothold — it decayed this swing. */
  causalChain?: ChainStatus
  /** The Judge's grade of the dispatch that caused this change. */
  craft?: Craft
  /** Signed year of the intervention, when the contact was grounded. */
  whenSigned?: number
  /** True when this was the run's staked last stand (doubled swing). */
  staked?: boolean
  timestamp: Date
62}
63 
64/**
* Message Interface — one line in the conversation with a figure.
* Dice / outcome / action / impact / progress are recorded on the AI (figure)
* turn, since that is the resolved result of the roll.
*/
69export interface Message {
  text: string
  sender: 'user' | 'ai' | 'system'
  timestamp: Date
  figureName?: string
  /** The effective (craft-tilted) roll — what the bands judged. */
  diceRoll?: number
  diceOutcome?: DiceOutcome
  /** The die as it actually landed, before the craft modifier. */
  naturalRoll?: number
  /** The Judge's tilt on the roll (±2..0), and the grade + reason behind it. */
  rollModifier?: number
  craft?: Craft
  craftReason?: string
  /** Whether the dispatch built on the run's thread (issue #62) — drives the
   *  momentum meter and the 'builds' badge in the reveal. */
  continuity?: Continuity
  characterAction?: string
  timelineImpact?: string
  progressChange?: number
  /** The pre-amplifier swing + the wager level, for the reveal's equation. */
  baseProgressChange?: number
  /** The PRE-turn momentum that amplified this swing — for the reveal's equation. */
  momentumAtSwing?: number
  anachronism?: Anachronism
  /** The causal-chain decay applied to this swing (for the reveal's equation). */
  causalChain?: ChainStatus
  /** True when this turn was the staked last stand. */
  staked?: boolean
98}
99 
100export type GameStatus = 'playing' | 'victory' | 'defeat'
101 
102/**
* Shape returned by `POST /api/send-message` (see `server/api/send-message.post.ts`).
* Discriminated by `success`: when `true`, all fields downstream of the dice roll are
* guaranteed; when `false`, only `userMessage` + `error` are guaranteed (and the
* Character-AI-failure path doesn't even surface a dice roll). The discriminant lets
* the consumer destructure without optional chaining or null gymnastics.
*/
109type SendMessageApiResponse =
  | {
      success: true
      message: string
      data: {
          userMessage: string
          figure: { name: string; era: string; descriptor: string }
          diceRoll: number
          diceOutcome: DiceOutcome
          // Judge-of-craft fields (optional so older mocks/fixtures stay valid;
          // the live server always sends them).
          naturalRoll?: number
          rollModifier?: number
          craft?: Craft
          craftReason?: string
          continuity?: Continuity
          momentum?: number
          staked?: boolean
          characterResponse: { message: string; action: string }
          timeline: {
              headline: string
              detail: string
              era: string
              progressChange: number
              baseProgressChange?: number
              momentumAtSwing?: number
              valence: Valence
              anachronism?: Anachronism
              causalChain?: ChainStatus
          }
          error: null
      }
  }
  | {
      success: false
      message: string
      data: {
          userMessage: string
          diceRoll?: number
          diceOutcome?: DiceOutcome
          characterResponse?: { message: string; action: string }
          error: string
          /** A content-moderation block (not an infra failure): the dispatch was
           *  refused by the detector, the Sentinel, or the model itself. */
          blocked?: boolean
          moderationReason?: string
      }
  }
157 
158const RATE_LIMIT_MS = 1000 // message cooldown window, in ms
159 
160// Turn-reveal pacing. A resolved turn releases its beats one at a time — a beat of
161// suspense, then the die lands and the figure's reply writes itself in, then the
162// timeline shift, then the ledger node — so the resolution reads as one conducted
163// moment instead of everything firing in the same tick. Each component already
164// animates when its own slice of state changes; sequencing the WRITES sequences the
165// animations, with no component coordination. Tuned so the swing lands with the
166// reply's own "ripple" line (~0.55s into its staged reveal).
167export const REVEAL = { suspense: 450, swing: 550, node: 250 } as const
168const wait = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms))
169/** Stagger the reveal only in a real browser with motion allowed. SSR and the test
*  env (no `matchMedia`) collapse to an instant, atomic apply — so the store's
*  contract (state present the moment sendMessage resolves) is unchanged for tests. */
172function canAnimateReveal(): boolean {
  return typeof window !== 'undefined'
      && typeof window.matchMedia === 'function'
      && !window.matchMedia('(prefers-reduced-motion: reduce)').matches
176}
177 
178function valenceOf(progressChange: number): Valence {
  if (progressChange > 0) return 'positive'
  if (progressChange < 0) return 'negative'
  return 'neutral'
182}
183 
184/** Formats a signed timeline year (AD positive, BCE negative) for display. */
185export function formatContactYear(signed: number): string {
  return signed < 0 ? `${-signed} BC` : `${signed}`
187}
188 
189/** Human lifespan line for a grounded figure, e.g. "69 BC – 30 BC" or "1942 – present". */
190function lifespanText(g: GroundedFigure): string | undefined {
  if (!g.born) return undefined
  if (g.died) return `${g.born.display} – ${g.died.display}`
  return g.living ? `${g.born.display} – present` : g.born.display
194}
195 
196/** True when a $fetch error is a 402 (out of runs) — the paywall signal. ofetch
*  surfaces the status as statusCode and on the response, so check both. */
198function isPaymentRequired(error: unknown): boolean {
  const e = error as { statusCode?: number; status?: number; response?: { status?: number } }
  return e?.statusCode === 402 || e?.status === 402 || e?.response?.status === 402
201}
202 
203/** True when a $fetch error is a 503 / at-capacity — the spend cap paused new
*  runs (distinct from the per-device 402 paywall). */
205function isAtCapacity(error: unknown): boolean {
  const e = error as { statusCode?: number; status?: number; response?: { status?: number }; data?: { atCapacity?: boolean } }
  return e?.statusCode === 503 || e?.status === 503 || e?.response?.status === 503 || e?.data?.atCapacity === true
208}
209 
210export type ContactLiveness = 'ok' | 'before-birth' | 'after-death' | 'living' | 'unresolved' | 'unknown'
211 
212/**
* A replay seed (issue #89) — when a player starts a run from a shared run's captured
* objective. It carries the objective to seed (verbatim, no generation), the SOURCE run's
* public share token (rides along to /api/run-save to stamp the lineage pointer), and the
* source's display name at seed time (for the "remixed from" credit shown before/after the
* run; the public page re-derives the credit live, honoring the source's current opt-in).
*/
219export interface ReplaySeed {
  objective: GameObjective
  sourceToken: string
  sourceAttribution: string | null
223}
224 
225/**
* Game Store — core state for a session of freeform timeline editing.
*/
228export const useGameStore = defineStore('game', {
  state: () => ({
      remainingMessages: TOTAL_MESSAGES,
⋯ 895 lines hidden (lines 231–1125)231        messageHistory: [] as Message[],
      gameStatus: 'playing' as GameStatus,
      isLoading: false,
      error: null as string | null,
      lastMessageTime: null as number | null,
      isRateLimited: false,
      // Staleness plumbing, not run state. runEpoch increments on every reset so an
      // async result from a dead run can never write into a fresh one; the seq
      // counters order overlapping requests of the same kind so only the latest
      // lands (an earlier chronicle rewrite must not overwrite a later one).
      // Deliberately NOT restored by resetGame — they must survive it to work.
      runEpoch: 0,
      chronicleSeq: 0,
      groundingSeq: 0,
      // The current run's id — lazily minted on the run's first server call and
      // cleared by resetGame so each run gets a fresh one. Tags every AI call
      // (via the x-run-id header) so the gateway's cost telemetry groups per
      // run: the GTM cost instrument.
      runId: null as string | null,
      // The in-flight begin-run, so concurrent first-calls of a run share one
      // mint (one POST /api/run, one runs row) instead of racing two. Cleared
      // by resetGame. (Vue leaves a Promise unproxied, so awaiting it is safe.)
      runIdInflight: null as Promise<string> | null,
      // True once this run's snapshot is durably saved (POST /api/run-save returned
      // saved). Gates the end-screen Share affordance (issue #88) so it appears only for
      // a run that actually exists server-side to share — never for a degraded local id.
      // Reset per run.
      runSnapshotSaved: false,
      // outOfRuns gates the mission screen's paywall (set when a commit is
      // refused with 402). The run packs offered there are loaded into `packs`.
      outOfRuns: false,
      // atCapacity gates the "at capacity" notice (set when a commit is refused
      // with 503 because the global spend cap paused new runs).
      atCapacity: false,
      packs: [] as Pack[],
      // The device's run balance, for the header gauge + account popover. null
      // until first loaded (GET /api/balance); the run-commit response also
      // refreshes it so the gauge stays live without a second round-trip.
      runsRemaining: null as number | null,
      freeRuns: 1,
      deviceRef: '' as string,
      // Account state (from /api/balance): the signed-in email, and whether the
      // current user is anonymous (→ must sign in before buying). Drives the
      // account UI + the sign-in-to-buy gate. false/null in device-fallback mode.
      accountEmail: null as string | null,
      accountAnonymous: false,
      // The run-packs sales modal — opened on demand (header) or automatically
      // when a commit is refused for being out of runs.
      buyModalOpen: false,
      // A one-shot notice after returning from Stripe Checkout ('success' shows a
      // credited confirmation; 'cancel' a gentle "no charge" note). Cleared by the UI.
      purchaseNotice: null as 'success' | 'cancel' | null,
      currentObjective: null as GameObjective | null,
      // Set when this run is a REPLAY of a shared run's objective (issue #89): seeded
      // verbatim from the public projection, no generation. Survives chooseObjective so
      // it can stamp the lineage pointer at save time and credit the source on the end
      // screen; cleared by resetGame (a fresh "new timeline" carries no lineage).
      replayState: null as ReplaySeed | null,
      objectiveProgress: 0,
      // The run-level momentum meter (0..MOMENTUM_MAX): a coherent arc compounds its
      // gains amplifier; a reset or catastrophe shatters it back to 0 (issue #62).
      momentum: 0,
      timelineEvents: [] as TimelineEvent[],
      figures: [] as HistoricalFigure[],
      activeFigureName: '' as string,
      // Grounding for the active contact: real facts + the chosen year to reach them.
      figureGrounding: null as GroundedFigure | null,
      groundingLoading: false,
      contactWhen: null as number | null,
      /** Optional sub-year refinement of contactWhen — display/prompt flavor
       *  only; every mechanic keeps doing arithmetic on the YEAR (issue #32). */
      contactMoment: null as ContactMoment | null,
      // Era-relevant figure suggestions for the current objective (the on-ramp).
      figureSuggestions: [] as FigureSuggestion[],
      suggestionsLoading: false,
      suggestionsFor: '' as string,
      // The living Chronicle (Layer 3): a prose telling of the altered timeline,
      // rewritten each turn. Non-blocking — see refreshChronicle.
      chronicle: null as ChronicleEntry | null,
      chronicleLoading: false,
      // The run's epilogue — the TERMINAL telling carrying the verdict — is being
      // written. Set when the final turn fires its refresh and cleared when that
      // telling lands or the refresh fails. Distinct from chronicleLoading (any
      // refresh): it lets the end screen show "the final account…" instead of
      // presenting the prior turn's stale, pre-ending telling as the epilogue.
      epiloguePending: false,
      // The Archive (prototype): an objective-blind brief on the active figure, so
      // the player can research who they're reaching without leaving the game. The
      // brief is moment-specific, so it's cached against the figure AND the year.
      figureStudy: null as FigureStudy | null,
      studyLoading: false,
      studyFor: '' as string,
      studyWhen: null as number | null,
      // Archive topic lookup (the "yellow" layer): concrete domain facts on demand.
      archiveResult: null as ArchiveLookup | null,
      lookupLoading: false,
      // A content-moderation block — distinct from `error` (an infra hiccup) so
      // the UI shows an honest, visibly different banner. One per surface that
      // takes untrusted input into a model: the dispatch/turn, the Archive lookup,
      // the Archivist study, and the figure-suggestions step.
      moderationNotice: null as string | null,
      archiveNotice: null as string | null,
      studyNotice: null as string | null,
      suggestionsNotice: null as string | null
  }),
336 
  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
      },
348 
      /**
       * 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'
          )
      },
359 
      /** Total progress, net of setbacks, the player has clawed back. */
      gameSummary(): GameSummary {
          return generateGameSummary(this)
      },
364 
      /**
       * 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'
      },
386 
      /** Can the chosen contact + when actually be reached? */
      canContact(): boolean {
          return this.contactLiveness === 'ok' || this.contactLiveness === 'unknown'
      },
391 
      /**
       * 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
      },
403 
      /**
       * 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
      },
419 
      /**
       * 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)
      }
  },
435 
  actions: {
      // ---------- message helpers ----------
      addUserMessage(text: string, figureName?: string) {
          if (this.gameStatus !== 'playing') return
          this.messageHistory.push({
              text,
              sender: 'user',
              timestamp: new Date(),
              figureName
          })
      },
447 
      addAIMessage(text: string, figureName?: string) {
          this.messageHistory.push({
              text,
              sender: 'ai',
              timestamp: new Date(),
              figureName
          })
      },
456 
      addAIMessageWithData(messageData: Partial<Message> & { text: string, sender: 'ai' }) {
          this.messageHistory.push({
              text: messageData.text,
              sender: messageData.sender,
              timestamp: messageData.timestamp || new Date(),
              figureName: messageData.figureName,
              diceRoll: messageData.diceRoll,
              diceOutcome: messageData.diceOutcome,
              naturalRoll: messageData.naturalRoll,
              rollModifier: messageData.rollModifier,
              craft: messageData.craft,
              craftReason: messageData.craftReason,
              continuity: messageData.continuity,
              characterAction: messageData.characterAction,
              timelineImpact: messageData.timelineImpact,
              progressChange: messageData.progressChange,
              baseProgressChange: messageData.baseProgressChange,
              momentumAtSwing: messageData.momentumAtSwing,
              anachronism: messageData.anachronism,
              causalChain: messageData.causalChain,
              staked: messageData.staked
          })
      },
480 
      // ---------- 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 })
          }
      },
491 
      setActiveFigure(name: string) {
          this.activeFigureName = name
      },
495 
      /**
       * 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
      },
513 
      /**
       * 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
          }
      },
561 
      /** 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
      },
590 
      /** 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() }
      },
596 
      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
      },
602 
      setContactMoment(moment: ContactMoment | null) {
          this.contactMoment = moment
      },
606 
      /**
       * 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
623 
          // 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
          }
      },
660 
      /**
       * Asks the Archive about a freeform topic (the "yellow" layer) — concrete
       * domain facts: what it is, what it takes, and when it first became known
       * (the player's anachronism read). Graceful on failure. Topic-scoped, so it
       * persists across figure changes within a run.
       */
      async askArchive(query: string): Promise<void> {
          const q = (query || '').trim()
          if (!q) return
          const epoch = this.runEpoch
          this.lookupLoading = true
          this.archiveNotice = null
          try {
              const res = await $fetch('/api/lookup', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: { query: q }
              }) as { success?: boolean; lookup?: ArchiveLookup; blocked?: boolean; error?: string }
              if (epoch !== this.runEpoch) return
              if (res?.blocked) {
                  // The Archive is the sharpest elicitation vector — a block here is
                  // honest and visible, not a silent empty result.
                  this.archiveNotice = res.error || 'That lookup was blocked by content moderation.'
              } else if (res?.success && res.lookup) {
                  this.archiveResult = res.lookup
              }
          } catch (error) {
              if (epoch !== this.runEpoch) return
              console.error('Archive lookup failed:', error)
          } finally {
              if (epoch === this.runEpoch) this.lookupLoading = false
          }
      },
694 
      /**
       * 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
708 
          const epoch = this.runEpoch
          this.suggestionsLoading = true
          this.suggestionsNotice = null
          try {
              const res = await $fetch('/api/suggestions', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: {
                      objective: {
                          title: objective.title,
                          description: objective.description,
                          era: objective.era
                      }
                  }
              }) as { success?: boolean; suggestions?: FigureSuggestion[]; blocked?: boolean; reason?: string }
              if (epoch !== this.runEpoch) return
              // A blocked objective must not masquerade as an empty result — surface it.
              if (res?.blocked) this.suggestionsNotice = res.reason || 'That objective was blocked by content moderation.'
              this.figureSuggestions = res?.suggestions ?? []
              this.suggestionsFor = objective.title
          } catch (error) {
              if (epoch !== this.runEpoch) return
              console.error('Failed to load figure suggestions:', error)
              this.figureSuggestions = []
              // Record that this objective WAS asked, even though it failed — the
              // picker uses suggestionsFor to tell "not yet asked" (skeletons)
              // from "asked and came up empty" (the honest famous-names fallback).
              this.suggestionsFor = objective.title
          } finally {
              if (epoch === this.runEpoch) this.suggestionsLoading = false
          }
      },
741 
      // ---------- timeline ledger ----------
      addTimelineEvent(
          evt: Omit<TimelineEvent, 'id' | 'timestamp' | 'valence'> & { valence?: Valence; timestamp?: Date }
      ) {
          this.timelineEvents.push({
              id: `evt-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
              figureName: evt.figureName,
              era: evt.era,
              headline: evt.headline,
              detail: evt.detail,
              diceRoll: evt.diceRoll,
              diceOutcome: evt.diceOutcome,
              progressChange: evt.progressChange,
              baseProgressChange: evt.baseProgressChange,
              valence: evt.valence ?? valenceOf(evt.progressChange),
              anachronism: evt.anachronism,
              causalChain: evt.causalChain,
              craft: evt.craft,
              whenSigned: evt.whenSigned,
              staked: evt.staked,
              timestamp: evt.timestamp ?? new Date()
          })
      },
765 
      // ---------- the living chronicle (Layer 3) ----------
      /**
       * Re-narrates the Chronicle from the freshly-bent timeline. Fired
       * non-blocking after a resolved turn (and at game end): the dice/progress
       * reveal never waits on prose. True to the game's name, the WHOLE account is
       * rewritten each turn — a later change can re-frame how earlier events read.
       * Graceful: a failed refresh keeps the prior telling, so the panel never
       * blanks; an empty timeline clears it (nothing to chronicle yet).
       */
      async refreshChronicle(): Promise<void> {
          if (!this.timelineEvents.length) {
              this.chronicle = null
              return
          }
          // Sequencing: rewrites overlap (each turn fires one, never awaited), so
          // only the LATEST issued refresh may land — an earlier telling arriving
          // late must not regress the account (or worse, the epilogue). The epoch
          // guard keeps a dead run's telling out of a fresh run entirely.
          const epoch = this.runEpoch
          const seq = ++this.chronicleSeq
          this.chronicleLoading = true
          try {
              const res = await $fetch('/api/chronicle', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: {
                      objective: this.currentObjective,
                      status: this.gameStatus,
                      progress: this.objectiveProgress,
                      timeline: this.timelineEvents.map(e => ({
                          era: e.era,
                          figureName: e.figureName,
                          headline: e.headline,
                          detail: e.detail,
                          progressChange: e.progressChange
                      }))
                  }
              }) as { success?: boolean; chronicle?: ChronicleEntry }
              if (epoch !== this.runEpoch || seq !== this.chronicleSeq) return
              if (res?.success && res.chronicle) this.chronicle = res.chronicle
          } catch (error) {
              if (epoch !== this.runEpoch || seq !== this.chronicleSeq) return
              console.error('Failed to refresh the chronicle:', error)
              // Keep the prior chronicle — a failed refresh never blanks the panel.
          } finally {
              if (epoch === this.runEpoch && seq === this.chronicleSeq) this.chronicleLoading = false
          }
      },
814 
      // ---------- simple setters ----------
      setLoading(loading: boolean) { this.isLoading = loading },
      setError(error: string | null) { this.error = error },
      clearModerationNotice() { this.moderationNotice = null },
      clearArchiveNotice() { this.archiveNotice = null },
820 
      // ---------- rate limiting ----------
      checkRateLimit(): boolean {
          const now = Date.now()
          if (this.lastMessageTime && (now - this.lastMessageTime) < RATE_LIMIT_MS) return false
          return true
      },
827 
      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)
      },
835 
      // ---------- counter & status ----------
      decrementMessages() {
          if (this.remainingMessages > 0) this.remainingMessages--
      },
840 
      /**
       * 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
              }
          }
      },
857 
      applyProgress(progressChange: number) {
          this.objectiveProgress = Math.max(0, Math.min(MAX_PROGRESS, this.objectiveProgress + progressChange))
      },
861 
      /**
       * Resolves win/lose AFTER a turn's progress has been applied.
       *
       * Victory the instant the objective hits 100%; defeat only once the
       * final message is spent without reaching it. This fixes the old
       * premature-defeat bug, where status flipped on the last decrement
       * BEFORE that turn's progress had a chance to land.
       */
      resolveGameStatus() {
          if (this.objectiveProgress >= MAX_PROGRESS) {
              this.gameStatus = 'victory'
          } else if (this.remainingMessages <= 0) {
              this.gameStatus = 'defeat'
          }
      },
877 
      // ---------- 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
895 
          if (!this.canSendMessage) return false
          if (!target) {
              this.setError('Choose who in history to send your message to first.')
              return false
          }
          if (!this.checkRateLimit()) {
              this.setRateLimit()
              this.setError('The timeline needs a moment — wait before sending again.')
              return false
          }
          if (!this.canContact) {
              const who = this.figureGrounding?.name || target
              this.setError(
                  this.contactLiveness === 'unresolved'
                      ? (this.figureGrounding?.transient
                          ? `Couldn't reach the record to verify "${target}" — try again in a moment.`
                          : `No historical record found for "${target}" — reach for a real figure (pick a match as you type).`)
                      : this.contactLiveness === 'before-birth'
                          ? `${who} isn't born yet in that year — choose a later moment to reach them.`
                          : this.contactLiveness === 'living'
                              ? (this.figureGrounding?.born
                                  ? `${who} is still living — Revisionist only reaches figures from history.`
                                  : `${who} couldn't be dated — Revisionist can only reach figures it can place in history.`)
                              : `${who} has died by that year — choose an earlier moment to reach them.`
              )
              return false
          }
923 
          this.setError(null)
          this.moderationNotice = null
          this.setActiveFigure(target)
          this.addUserMessage(text, target)
          this.decrementMessages()
          this.setLoading(true)
          this.lastMessageTime = Date.now()
931 
          // If the run is reset while this request is in flight, every write below
          // would land in a world that no longer exists — the epoch guard drops the
          // response (no fold-in, no refund: the new run's counter is not ours).
          const epoch = this.runEpoch
          const ledgerBefore = this.timelineEvents.length
          // Capture the contact year NOW: the slider can move while the request is
          // in flight, and the ledger must record the year this turn was SENT to.
          const sentWhen = this.contactWhen
          const sentMoment = this.contactMoment
          let resolved = false
          // Decide once whether to stagger the reveal (browser + motion allowed).
          const animate = canAnimateReveal()
944 
          try {
              const response = await $fetch<SendMessageApiResponse>('/api/send-message', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: {
                      message: text,
                      figureName: target,
                      when: sentWhen != null ? formatContactMoment(sentWhen, sentMoment) : undefined,
                      whenSigned: sentWhen ?? undefined,
                      // The pinned moment travels as validated integers; the server
                      // re-derives the display string rather than trusting ours.
                      whenMonth: sentWhen != null ? sentMoment?.month : undefined,
                      whenDay: sentWhen != null ? sentMoment?.day : undefined,
                      stake,
                      // The pre-turn momentum the server amplifies the swing by, and
                      // returns advanced (the client stays the system of record).
                      momentum: this.momentum,
                      figureContext: this.figureGrounding?.resolved
                          ? {
                              description: this.figureGrounding.description,
                              lifespan: lifespanText(this.figureGrounding)
                          }
                          : undefined,
                      objective: this.currentObjective,
                      timeline: this.timelineEvents.map(e => ({
                          era: e.era,
                          figureName: e.figureName,
                          headline: e.headline,
                          detail: e.detail,
                          progressChange: e.progressChange,
                          whenSigned: e.whenSigned
                      })),
                      conversationHistory: this.conversationWith(target)
                  }
              })
980 
              if (epoch !== this.runEpoch) return false
982 
              if (response?.success && response.data?.characterResponse) {
                  const { figure, characterResponse, diceRoll, diceOutcome, timeline } = response.data
985 
                  if (figure?.name) {
                      this.registerFigure({
                          name: figure.name,
                          era: figure.era || '',
                          descriptor: figure.descriptor || ''
                      })
                  }
993 
                  // ---- 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
                  }
1001 
                  // Beat 1 — the die lands and the figure's reply writes itself in
                  // (its parts stage over ~0.55s via CSS). Flipping loading here
                  // (mid-sequence) is what lands the die now; the finally's flip
                  // becomes a no-op.
                  this.addAIMessageWithData({
                      text: characterResponse.message,
                      sender: 'ai',
                      figureName: target,
                      timestamp: new Date(),
                      diceRoll,
                      diceOutcome,
                      naturalRoll: response.data.naturalRoll ?? diceRoll,
                      rollModifier: response.data.rollModifier ?? 0,
                      craft: response.data.craft,
                      craftReason: response.data.craftReason,
                      continuity: response.data.continuity,
                      characterAction: characterResponse.action,
                      timelineImpact: timeline?.detail,
                      progressChange: timeline?.progressChange,
                      baseProgressChange: timeline?.baseProgressChange,
                      momentumAtSwing: timeline?.momentumAtSwing,
                      anachronism: timeline?.anachronism,
                      causalChain: timeline?.causalChain,
                      staked: response.data.staked
                  })
                  if (animate) this.setLoading(false)
1028 
                  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
1045 
                      // Beat 3 — the change drops onto the Spine ledger.
                      if (animate) {
                          await wait(REVEAL.node)
                          if (epoch !== this.runEpoch) return false
                      }
                      this.addTimelineEvent({
                          figureName: target,
                          era: timeline.era || figure?.era || (this.currentObjective?.era ?? ''),
                          headline: timeline.headline,
                          detail: timeline.detail,
                          diceRoll,
                          diceOutcome,
                          progressChange: timeline.progressChange ?? 0,
                          baseProgressChange: timeline.baseProgressChange,
                          valence: timeline.valence,
                          anachronism: timeline.anachronism,
                          causalChain: timeline.causalChain,
                          craft: response.data.craft,
                          whenSigned: sentWhen ?? undefined,
                          staked: response.data.staked
                      })
                      resolved = true
                  }
              } else {
                  // A graceful failure (HTTP 200, success:false): an AI layer gave
                  // out mid-turn. No ripple landed, so the dispatch is refunded —
                  // exactly like the thrown path below.
                  // Narrow to the failure variant (its data carries `blocked`).
                  const failed = response && !response.success ? response.data : undefined
                  if (failed?.blocked) {
                      // A content-moderation block, not an infra hiccup — show an
                      // honest, distinct banner (not "try again"). The composer
                      // keeps the player's words (sendMessage returns false).
                      this.moderationNotice = failed.moderationReason || 'That dispatch was blocked by content moderation and cannot be sent.'
                  } else {
                      this.setError(failed?.error || 'History did not answer. Try again.')
                  }
                  this.refundUnresolvedTurn()
              }
          } catch (error) {
              if (epoch !== this.runEpoch) return false
              console.error('Error sending message:', error)
              this.setError('The timeline resisted your message. Please try again.')
              this.refundUnresolvedTurn()
          } finally {
              if (epoch === this.runEpoch) {
                  this.setLoading(false)
                  this.resolveGameStatus()
              }
          }
1096 
          // The living chronicle re-narrates the world from the new timeline — but
          // only when this turn actually added a change, and never awaited: the turn
          // reveal must not wait on prose. By here the status is resolved, so the
          // final turn's chronicle carries the victory/defeat framing (the epilogue).
          let refresh: Promise<void> | null = null
          if (resolved && this.timelineEvents.length > ledgerBefore) {
              refresh = this.refreshChronicle()
              void refresh
          }
          // The run just ended: persist it (best-effort) so it survives reload, then
          // re-save once the epilogue's telling lands — the immediate save guards
          // against that refresh failing, the second captures the final Chronicle.
          if (this.gameStatus === 'victory' || this.gameStatus === 'defeat') {
              // This turn's refresh writes the EPILOGUE — the terminal telling that
              // carries the verdict. Mark it pending so the end screen shows "the
              // final account…" instead of the prior turn's stale telling. Cleared
              // when the telling lands OR the refresh fails (refreshChronicle keeps
              // the prior telling on failure) — so the panel reveals or falls back,
              // never hanging on the loading state.
              if (refresh) {
                  this.epiloguePending = true
                  void refresh.finally(() => { if (epoch === this.runEpoch) this.epiloguePending = false })
              }
              void this.saveRunSnapshot()
              if (refresh) void refresh.finally(() => { void this.saveRunSnapshot() })
          }
          return resolved
      },
1125 
      /**
       * 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 }
      },
1138 
      /** 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
      },
⋯ 312 lines hidden (lines 1144–1455)1144 
      /**
       * Commits a chosen objective and starts the run from a clean slate of
       * progress. Used by the mission-select screen for both curated picks and
       * freshly composed ones.
       */
      async chooseObjective(objective: GameObjective): Promise<boolean> {
          // Commit = the run is charged here. Mint the run id server-side, then
          // spend one run from the device's balance. Fails CLOSED: out of runs →
          // raise the paywall; begin-run or commit failing → surface an error and
          // do NOT start. A run that isn't a charged, server-backed run would be
          // rejected by the gameplay gate anyway, so starting it only strands the
          // player mid-run. The spend cap (not free play) is the outage backstop.
          let runId: string
          try {
              runId = await this.ensureRunId()
          } catch (error) {
              console.error('Could not begin the run:', error)
              this.error = 'Could not start the run. Please try again.'
              return false
          }
          try {
              const res = await $fetch('/api/run-commit', {
                  method: 'POST',
                  headers: { 'Content-Type': 'application/json' },
                  body: { runId }
              }) as { runsRemaining?: number }
              this.outOfRuns = false
              // Keep the header gauge live: the commit returns the post-charge
              // balance (−1 marks a degraded, ungated run — leave the gauge as is).
              if (typeof res?.runsRemaining === 'number' && res.runsRemaining >= 0) {
                  this.runsRemaining = res.runsRemaining
              }
          } catch (error) {
              if (isPaymentRequired(error)) {
                  this.outOfRuns = true
                  this.openBuyModal()
                  return false
              }
              if (isAtCapacity(error)) {
                  this.atCapacity = true
                  return false
              }
              console.error('Could not charge the run:', error)
              this.error = 'Could not start the run. Please try again.'
              return false
          }
          this.currentObjective = objective
          this.objectiveProgress = 0
          this.momentum = 0
          this.error = null
          return true
      },
1197 
      /**
       * Asks the server to compose a fresh objective with the model, WITHOUT
       * committing it — the caller previews it, then commits via chooseObjective.
       * Generation lives server-side because it needs the OpenAI key (the client
       * has no access to it). An optional steer (era + theme, closed enums) biases
       * the composition; the server re-validates it against the enums, so a bad
       * value is harmless. `avoid` is the titles already composed this session, so
       * a reroll lands somewhere new (#95) — the stateless server only knows what
       * the client supplies. Returns null rather than throwing if composing fails,
       * so the UI can quietly fall back to the curated pool.
       */
      async fetchAIObjective(steer: ObjectiveSteer = {}, avoid: string[] = []): Promise<GameObjective | null> {
          try {
              const query: Record<string, string | string[]> = {}
              if (steer.era) query.era = steer.era
              if (steer.theme) query.theme = steer.theme
              if (avoid.length) query.avoid = avoid
              const res = await $fetch('/api/objective', { method: 'GET', query, headers: await this.aiHeaders() }) as {
                  success?: boolean
                  objective?: GameObjective
              }
              return res?.success && res.objective ? res.objective : null
          } catch (error) {
              console.error('Failed to compose a fresh objective:', error)
              return null
          }
      },
1225 
      /**
       * Loads the device's run balance for the header gauge + account popover.
       * Grants the free trial on a brand-new device (server-side). Graceful: on
       * failure it leaves the prior value (the gauge simply doesn't update).
       */
      async loadBalance(): Promise<void> {
          try {
              const res = await $fetch('/api/balance') as { runsRemaining?: number; freeRuns?: number; deviceRef?: string; email?: string | null; isAnonymous?: boolean }
              if (typeof res?.runsRemaining === 'number') this.runsRemaining = res.runsRemaining
              if (typeof res?.freeRuns === 'number') this.freeRuns = res.freeRuns
              if (typeof res?.deviceRef === 'string') this.deviceRef = res.deviceRef
              this.accountEmail = res?.email ?? null
              this.accountAnonymous = res?.isAnonymous === true
          } catch (error) {
              console.error('Failed to load balance:', error)
          }
      },
1243 
      /** Opens the run-packs sales modal, loading the catalog first. */
      async openBuyModal(): Promise<void> {
          this.buyModalOpen = true
          await this.loadPacks()
      },
1249 
      /** Closes the sales modal. */
      closeBuyModal(): void {
          this.buyModalOpen = false
      },
1254 
      /** 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()
          }
      },
1265 
      /** Dismisses the post-purchase notice. */
      clearPurchaseNotice(): void {
          this.purchaseNotice = null
      },
1270 
      /** 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)
          }
      },
1284 
      /** 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
          }
      },
1300 
      getVictoryEfficiency() {
          if (this.gameStatus === 'victory') {
              const messagesSaved = this.remainingMessages
              const messagesUsed = TOTAL_MESSAGES - this.remainingMessages
              const efficiencyPercentage = Math.round((messagesSaved / TOTAL_MESSAGES) * 100)
1306 
              const efficiencyRating = rateEfficiency(messagesSaved)
1308 
              return {
                  messagesSaved,
                  messagesUsed,
                  efficiencyPercentage,
                  efficiencyRating,
                  isEarlyVictory: messagesSaved > 0
              }
          }
          return null
      },
1319 
      /**
       * 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
1336 
          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
1352 
          const snapshot: RunSnapshot = {
              version: RUN_SNAPSHOT_VERSION,
              runId,
              status,
              objective,
              objectiveProgress: this.objectiveProgress,
              messagesUsed: TOTAL_MESSAGES - this.remainingMessages,
              totalMessages: TOTAL_MESSAGES,
              bestRoll: mark(summary.bestRoll),
              worstRoll: mark(summary.worstRoll),
              efficiency: this.getVictoryEfficiency(),
              dispatches,
              timeline: events.map((e) => ({
                  id: e.id,
                  figureName: e.figureName,
                  era: e.era,
                  headline: e.headline,
                  detail: e.detail,
                  diceRoll: e.diceRoll,
                  diceOutcome: e.diceOutcome,
                  progressChange: e.progressChange,
                  baseProgressChange: e.baseProgressChange,
                  valence: e.valence,
                  craft: e.craft,
                  anachronism: e.anachronism,
                  staked: e.staked
              })),
              chronicle: this.chronicle
          }
1382 
          // 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
1390 
          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)
          }
      },
1405 
      resetGame() {
          // Tear the epoch first: anything still in flight belongs to the old run
          // and must find no purchase here. (The seq counters deliberately survive.)
          this.runEpoch++
          this.remainingMessages = TOTAL_MESSAGES
          this.messageHistory = []
          this.gameStatus = 'playing'
          this.isLoading = false
          this.error = null
          this.lastMessageTime = null
          this.isRateLimited = false
          // A new run gets a fresh id on its next server call; abandon any
          // in-flight mint so a dead run's id can't land in the new run.
          this.runId = null
          this.runIdInflight = null
          this.runSnapshotSaved = false
          // The paywall / capacity notices re-check on the next commit.
          this.outOfRuns = false
          this.atCapacity = false
          this.currentObjective = null
          // A fresh run carries no replay lineage (preseedReplay re-sets it after).
          this.replayState = null
          this.objectiveProgress = 0
          this.momentum = 0
          this.timelineEvents = []
          this.figures = []
          this.activeFigureName = ''
          this.figureGrounding = null
          this.groundingLoading = false
          this.contactWhen = null
          this.contactMoment = null
          this.figureSuggestions = []
          this.suggestionsLoading = false
          this.suggestionsFor = ''
          this.chronicle = null
          this.chronicleLoading = false
          this.epiloguePending = false
          this.figureStudy = null
          this.studyLoading = false
          this.studyFor = ''
          this.studyWhen = null
          this.archiveResult = null
          this.lookupLoading = false
          this.moderationNotice = null
          this.archiveNotice = null
          this.studyNotice = null
          this.suggestionsNotice = null
      }
  }
1455})

At save time the store appends remixedFromToken only when replayState is set, and the route uuid-gates it before handing it to saveRun. Best-effort throughout: a malformed or unresolved token is simply ignored.

saveRunSnapshot: the token rides alongside the snapshot, not within it.

stores/game.ts · 1455 lines

stores/game.ts1455 lines · TypeScript

⋯ 1382 lines hidden (lines 1–1382)1import { defineStore } from 'pinia'
2import type { GameObjective, ObjectiveSteer } from '~/server/utils/objectives'
3import type { Pack } from '~/server/utils/packs'
4import type { GroundedFigure } from '~/server/utils/figure-grounding'
5import { formatContactMoment, type ContactMoment } from '~/utils/contact-moment'
6import type { FigureSuggestion } from '~/server/utils/figure-suggester'
7import type { ChronicleEntry } from '~/server/utils/openai'
8import type { FigureStudy, ArchiveLookup } from '~/server/utils/prompt-builder'
9import type { Anachronism } from '~/server/utils/anachronism'
10import { chainStatus, type ChainStatus } from '~/utils/causal-chain'
11import type { Craft } from '~/utils/craft'
12import type { Continuity } from '~/utils/continuity'
13import type { DiceOutcome } from '~/utils/dice'
14import { generateGameSummary, rateEfficiency, type GameSummary } from '~/utils/game-summary'
15import { TOTAL_MESSAGES, MAX_PROGRESS_SWING, MAX_PROGRESS } from '~/utils/game-config'
16import { RUN_SNAPSHOT_VERSION, type RunSnapshot } from '~/utils/run-snapshot'
17 
18export type Valence = 'positive' | 'negative' | 'neutral'
19 
20/**
* A historical figure the player has reached out to. Figures are freeform — the
* player can write to anyone, in any era. The AI infers each figure's era and a
* short descriptor on first contact, which we cache here for the UI.
*/
25export interface HistoricalFigure {
  name: string
  era: string
  descriptor: string
29}
30 
31/**
* Timeline Ledger entry — a single recorded change to history.
*
* The ledger is the heart of the game: every resolved turn appends one entry
* describing how the world bent, so the player literally watches the timeline
* rewrite itself as they play.
*/
38export interface TimelineEvent {
  id: string
  figureName: string
  era: string
  headline: string
  detail: string
  diceRoll: number
  diceOutcome: DiceOutcome
  progressChange: number
  /** The engine's swing BEFORE the anachronism amplifier — shown so the player
   *  can see exactly what their wager did ("+8 ⚡ far-ahead → +11%"). */
  baseProgressChange?: number
  valence: Valence
  /** How anachronistic the player's nudge was — it widened this swing. */
  anachronism?: Anachronism
  /** How far this landed from the nearest foothold — it decayed this swing. */
  causalChain?: ChainStatus
  /** The Judge's grade of the dispatch that caused this change. */
  craft?: Craft
  /** Signed year of the intervention, when the contact was grounded. */
  whenSigned?: number
  /** True when this was the run's staked last stand (doubled swing). */
  staked?: boolean
  timestamp: Date
62}
63 
64/**
* Message Interface — one line in the conversation with a figure.
* Dice / outcome / action / impact / progress are recorded on the AI (figure)
* turn, since that is the resolved result of the roll.
*/
69export interface Message {
  text: string
  sender: 'user' | 'ai' | 'system'
  timestamp: Date
  figureName?: string
  /** The effective (craft-tilted) roll — what the bands judged. */
  diceRoll?: number
  diceOutcome?: DiceOutcome
  /** The die as it actually landed, before the craft modifier. */
  naturalRoll?: number
  /** The Judge's tilt on the roll (±2..0), and the grade + reason behind it. */
  rollModifier?: number
  craft?: Craft
  craftReason?: string
  /** Whether the dispatch built on the run's thread (issue #62) — drives the
   *  momentum meter and the 'builds' badge in the reveal. */
  continuity?: Continuity
  characterAction?: string
  timelineImpact?: string
  progressChange?: number
  /** The pre-amplifier swing + the wager level, for the reveal's equation. */
  baseProgressChange?: number
  /** The PRE-turn momentum that amplified this swing — for the reveal's equation. */
  momentumAtSwing?: number
  anachronism?: Anachronism
  /** The causal-chain decay applied to this swing (for the reveal's equation). */
  causalChain?: ChainStatus
  /** True when this turn was the staked last stand. */
  staked?: boolean
98}
99 
100export type GameStatus = 'playing' | 'victory' | 'defeat'
101 
102/**
* Shape returned by `POST /api/send-message` (see `server/api/send-message.post.ts`).
* Discriminated by `success`: when `true`, all fields downstream of the dice roll are
* guaranteed; when `false`, only `userMessage` + `error` are guaranteed (and the
* Character-AI-failure path doesn't even surface a dice roll). The discriminant lets
* the consumer destructure without optional chaining or null gymnastics.
*/
109type SendMessageApiResponse =
  | {
      success: true
      message: string
      data: {
          userMessage: string
          figure: { name: string; era: string; descriptor: string }
          diceRoll: number
          diceOutcome: DiceOutcome
          // Judge-of-craft fields (optional so older mocks/fixtures stay valid;
          // the live server always sends them).
          naturalRoll?: number
          rollModifier?: number
          craft?: Craft
          craftReason?: string
          continuity?: Continuity
          momentum?: number
          staked?: boolean
          characterResponse: { message: string; action: string }
          timeline: {
              headline: string
              detail: string
              era: string
              progressChange: number
              baseProgressChange?: number
              momentumAtSwing?: number
              valence: Valence
              anachronism?: Anachronism
              causalChain?: ChainStatus
          }
          error: null
      }
  }
  | {
      success: false
      message: string
      data: {
          userMessage: string
          diceRoll?: number
          diceOutcome?: DiceOutcome
          characterResponse?: { message: string; action: string }
          error: string
          /** A content-moderation block (not an infra failure): the dispatch was
           *  refused by the detector, the Sentinel, or the model itself. */
          blocked?: boolean
          moderationReason?: string
      }
  }
157 
158const RATE_LIMIT_MS = 1000 // message cooldown window, in ms
159 
160// Turn-reveal pacing. A resolved turn releases its beats one at a time — a beat of
161// suspense, then the die lands and the figure's reply writes itself in, then the
162// timeline shift, then the ledger node — so the resolution reads as one conducted
163// moment instead of everything firing in the same tick. Each component already
164// animates when its own slice of state changes; sequencing the WRITES sequences the
165// animations, with no component coordination. Tuned so the swing lands with the
166// reply's own "ripple" line (~0.55s into its staged reveal).
167export const REVEAL = { suspense: 450, swing: 550, node: 250 } as const
168const wait = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms))
169/** Stagger the reveal only in a real browser with motion allowed. SSR and the test
*  env (no `matchMedia`) collapse to an instant, atomic apply — so the store's
*  contract (state present the moment sendMessage resolves) is unchanged for tests. */
172function canAnimateReveal(): boolean {
  return typeof window !== 'undefined'
      && typeof window.matchMedia === 'function'
      && !window.matchMedia('(prefers-reduced-motion: reduce)').matches
176}
177 
178function valenceOf(progressChange: number): Valence {
  if (progressChange > 0) return 'positive'
  if (progressChange < 0) return 'negative'
  return 'neutral'
182}
183 
184/** Formats a signed timeline year (AD positive, BCE negative) for display. */
185export function formatContactYear(signed: number): string {
  return signed < 0 ? `${-signed} BC` : `${signed}`
187}
188 
189/** Human lifespan line for a grounded figure, e.g. "69 BC – 30 BC" or "1942 – present". */
190function lifespanText(g: GroundedFigure): string | undefined {
  if (!g.born) return undefined
  if (g.died) return `${g.born.display} – ${g.died.display}`
  return g.living ? `${g.born.display} – present` : g.born.display
194}
195 
196/** True when a $fetch error is a 402 (out of runs) — the paywall signal. ofetch
*  surfaces the status as statusCode and on the response, so check both. */
198function isPaymentRequired(error: unknown): boolean {
  const e = error as { statusCode?: number; status?: number; response?: { status?: number } }
  return e?.statusCode === 402 || e?.status === 402 || e?.response?.status === 402
201}
202 
203/** True when a $fetch error is a 503 / at-capacity — the spend cap paused new
*  runs (distinct from the per-device 402 paywall). */
205function isAtCapacity(error: unknown): boolean {
  const e = error as { statusCode?: number; status?: number; response?: { status?: number }; data?: { atCapacity?: boolean } }
  return e?.statusCode === 503 || e?.status === 503 || e?.response?.status === 503 || e?.data?.atCapacity === true
208}
209 
210export type ContactLiveness = 'ok' | 'before-birth' | 'after-death' | 'living' | 'unresolved' | 'unknown'
211 
212/**
* A replay seed (issue #89) — when a player starts a run from a shared run's captured
* objective. It carries the objective to seed (verbatim, no generation), the SOURCE run's
* public share token (rides along to /api/run-save to stamp the lineage pointer), and the
* source's display name at seed time (for the "remixed from" credit shown before/after the
* run; the public page re-derives the credit live, honoring the source's current opt-in).
*/
219export interface ReplaySeed {
  objective: GameObjective
  sourceToken: string
  sourceAttribution: string | null
223}
224 
225/**
* Game Store — core state for a session of freeform timeline editing.
*/
228export const useGameStore = defineStore('game', {
  state: () => ({
      remainingMessages: TOTAL_MESSAGES,
      messageHistory: [] as Message[],
      gameStatus: 'playing' as GameStatus,
      isLoading: false,
      error: null as string | null,
      lastMessageTime: null as number | null,
      isRateLimited: false,
      // Staleness plumbing, not run state. runEpoch increments on every reset so an
      // async result from a dead run can never write into a fresh one; the seq
      // counters order overlapping requests of the same kind so only the latest
      // lands (an earlier chronicle rewrite must not overwrite a later one).
      // Deliberately NOT restored by resetGame — they must survive it to work.
      runEpoch: 0,
      chronicleSeq: 0,
      groundingSeq: 0,
      // The current run's id — lazily minted on the run's first server call and
      // cleared by resetGame so each run gets a fresh one. Tags every AI call
      // (via the x-run-id header) so the gateway's cost telemetry groups per
      // run: the GTM cost instrument.
      runId: null as string | null,
      // The in-flight begin-run, so concurrent first-calls of a run share one
      // mint (one POST /api/run, one runs row) instead of racing two. Cleared
      // by resetGame. (Vue leaves a Promise unproxied, so awaiting it is safe.)
      runIdInflight: null as Promise<string> | null,
      // True once this run's snapshot is durably saved (POST /api/run-save returned
      // saved). Gates the end-screen Share affordance (issue #88) so it appears only for
      // a run that actually exists server-side to share — never for a degraded local id.
      // Reset per run.
      runSnapshotSaved: false,
      // outOfRuns gates the mission screen's paywall (set when a commit is
      // refused with 402). The run packs offered there are loaded into `packs`.
      outOfRuns: false,
      // atCapacity gates the "at capacity" notice (set when a commit is refused
      // with 503 because the global spend cap paused new runs).
      atCapacity: false,
      packs: [] as Pack[],
      // The device's run balance, for the header gauge + account popover. null
      // until first loaded (GET /api/balance); the run-commit response also
      // refreshes it so the gauge stays live without a second round-trip.
      runsRemaining: null as number | null,
      freeRuns: 1,
      deviceRef: '' as string,
      // Account state (from /api/balance): the signed-in email, and whether the
      // current user is anonymous (→ must sign in before buying). Drives the
      // account UI + the sign-in-to-buy gate. false/null in device-fallback mode.
      accountEmail: null as string | null,
      accountAnonymous: false,
      // The run-packs sales modal — opened on demand (header) or automatically
      // when a commit is refused for being out of runs.
      buyModalOpen: false,
      // A one-shot notice after returning from Stripe Checkout ('success' shows a
      // credited confirmation; 'cancel' a gentle "no charge" note). Cleared by the UI.
      purchaseNotice: null as 'success' | 'cancel' | null,
      currentObjective: null as GameObjective | null,
      // Set when this run is a REPLAY of a shared run's objective (issue #89): seeded
      // verbatim from the public projection, no generation. Survives chooseObjective so
      // it can stamp the lineage pointer at save time and credit the source on the end
      // screen; cleared by resetGame (a fresh "new timeline" carries no lineage).
      replayState: null as ReplaySeed | null,
      objectiveProgress: 0,
      // The run-level momentum meter (0..MOMENTUM_MAX): a coherent arc compounds its
      // gains amplifier; a reset or catastrophe shatters it back to 0 (issue #62).
      momentum: 0,
      timelineEvents: [] as TimelineEvent[],
      figures: [] as HistoricalFigure[],
      activeFigureName: '' as string,
      // Grounding for the active contact: real facts + the chosen year to reach them.
      figureGrounding: null as GroundedFigure | null,
      groundingLoading: false,
      contactWhen: null as number | null,
      /** Optional sub-year refinement of contactWhen — display/prompt flavor
       *  only; every mechanic keeps doing arithmetic on the YEAR (issue #32). */
      contactMoment: null as ContactMoment | null,
      // Era-relevant figure suggestions for the current objective (the on-ramp).
      figureSuggestions: [] as FigureSuggestion[],
      suggestionsLoading: false,
      suggestionsFor: '' as string,
      // The living Chronicle (Layer 3): a prose telling of the altered timeline,
      // rewritten each turn. Non-blocking — see refreshChronicle.
      chronicle: null as ChronicleEntry | null,
      chronicleLoading: false,
      // The run's epilogue — the TERMINAL telling carrying the verdict — is being
      // written. Set when the final turn fires its refresh and cleared when that
      // telling lands or the refresh fails. Distinct from chronicleLoading (any
      // refresh): it lets the end screen show "the final account…" instead of
      // presenting the prior turn's stale, pre-ending telling as the epilogue.
      epiloguePending: false,
      // The Archive (prototype): an objective-blind brief on the active figure, so
      // the player can research who they're reaching without leaving the game. The
      // brief is moment-specific, so it's cached against the figure AND the year.
      figureStudy: null as FigureStudy | null,
      studyLoading: false,
      studyFor: '' as string,
      studyWhen: null as number | null,
      // Archive topic lookup (the "yellow" layer): concrete domain facts on demand.
      archiveResult: null as ArchiveLookup | null,
      lookupLoading: false,
      // A content-moderation block — distinct from `error` (an infra hiccup) so
      // the UI shows an honest, visibly different banner. One per surface that
      // takes untrusted input into a model: the dispatch/turn, the Archive lookup,
      // the Archivist study, and the figure-suggestions step.
      moderationNotice: null as string | null,
      archiveNotice: null as string | null,
      studyNotice: null as string | null,
      suggestionsNotice: null as string | null
  }),
336 
  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
      },
348 
      /**
       * 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'
          )
      },
359 
      /** Total progress, net of setbacks, the player has clawed back. */
      gameSummary(): GameSummary {
          return generateGameSummary(this)
      },
364 
      /**
       * 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'
      },
386 
      /** Can the chosen contact + when actually be reached? */
      canContact(): boolean {
          return this.contactLiveness === 'ok' || this.contactLiveness === 'unknown'
      },
391 
      /**
       * 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
      },
403 
      /**
       * 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
      },
419 
      /**
       * 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)
      }
  },
435 
  actions: {
      // ---------- message helpers ----------
      addUserMessage(text: string, figureName?: string) {
          if (this.gameStatus !== 'playing') return
          this.messageHistory.push({
              text,
              sender: 'user',
              timestamp: new Date(),
              figureName
          })
      },
447 
      addAIMessage(text: string, figureName?: string) {
          this.messageHistory.push({
              text,
              sender: 'ai',
              timestamp: new Date(),
              figureName
          })
      },
456 
      addAIMessageWithData(messageData: Partial<Message> & { text: string, sender: 'ai' }) {
          this.messageHistory.push({
              text: messageData.text,
              sender: messageData.sender,
              timestamp: messageData.timestamp || new Date(),
              figureName: messageData.figureName,
              diceRoll: messageData.diceRoll,
              diceOutcome: messageData.diceOutcome,
              naturalRoll: messageData.naturalRoll,
              rollModifier: messageData.rollModifier,
              craft: messageData.craft,
              craftReason: messageData.craftReason,
              continuity: messageData.continuity,
              characterAction: messageData.characterAction,
              timelineImpact: messageData.timelineImpact,
              progressChange: messageData.progressChange,
              baseProgressChange: messageData.baseProgressChange,
              momentumAtSwing: messageData.momentumAtSwing,
              anachronism: messageData.anachronism,
              causalChain: messageData.causalChain,
              staked: messageData.staked
          })
      },
480 
      // ---------- 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 })
          }
      },
491 
      setActiveFigure(name: string) {
          this.activeFigureName = name
      },
495 
      /**
       * 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
      },
513 
      /**
       * 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
          }
      },
561 
      /** 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
      },
590 
      /** 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() }
      },
596 
      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
      },
602 
      setContactMoment(moment: ContactMoment | null) {
          this.contactMoment = moment
      },
606 
      /**
       * 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
623 
          // 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
          }
      },
660 
      /**
       * Asks the Archive about a freeform topic (the "yellow" layer) — concrete
       * domain facts: what it is, what it takes, and when it first became known
       * (the player's anachronism read). Graceful on failure. Topic-scoped, so it
       * persists across figure changes within a run.
       */
      async askArchive(query: string): Promise<void> {
          const q = (query || '').trim()
          if (!q) return
          const epoch = this.runEpoch
          this.lookupLoading = true
          this.archiveNotice = null
          try {
              const res = await $fetch('/api/lookup', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: { query: q }
              }) as { success?: boolean; lookup?: ArchiveLookup; blocked?: boolean; error?: string }
              if (epoch !== this.runEpoch) return
              if (res?.blocked) {
                  // The Archive is the sharpest elicitation vector — a block here is
                  // honest and visible, not a silent empty result.
                  this.archiveNotice = res.error || 'That lookup was blocked by content moderation.'
              } else if (res?.success && res.lookup) {
                  this.archiveResult = res.lookup
              }
          } catch (error) {
              if (epoch !== this.runEpoch) return
              console.error('Archive lookup failed:', error)
          } finally {
              if (epoch === this.runEpoch) this.lookupLoading = false
          }
      },
694 
      /**
       * 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
708 
          const epoch = this.runEpoch
          this.suggestionsLoading = true
          this.suggestionsNotice = null
          try {
              const res = await $fetch('/api/suggestions', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: {
                      objective: {
                          title: objective.title,
                          description: objective.description,
                          era: objective.era
                      }
                  }
              }) as { success?: boolean; suggestions?: FigureSuggestion[]; blocked?: boolean; reason?: string }
              if (epoch !== this.runEpoch) return
              // A blocked objective must not masquerade as an empty result — surface it.
              if (res?.blocked) this.suggestionsNotice = res.reason || 'That objective was blocked by content moderation.'
              this.figureSuggestions = res?.suggestions ?? []
              this.suggestionsFor = objective.title
          } catch (error) {
              if (epoch !== this.runEpoch) return
              console.error('Failed to load figure suggestions:', error)
              this.figureSuggestions = []
              // Record that this objective WAS asked, even though it failed — the
              // picker uses suggestionsFor to tell "not yet asked" (skeletons)
              // from "asked and came up empty" (the honest famous-names fallback).
              this.suggestionsFor = objective.title
          } finally {
              if (epoch === this.runEpoch) this.suggestionsLoading = false
          }
      },
741 
      // ---------- timeline ledger ----------
      addTimelineEvent(
          evt: Omit<TimelineEvent, 'id' | 'timestamp' | 'valence'> & { valence?: Valence; timestamp?: Date }
      ) {
          this.timelineEvents.push({
              id: `evt-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
              figureName: evt.figureName,
              era: evt.era,
              headline: evt.headline,
              detail: evt.detail,
              diceRoll: evt.diceRoll,
              diceOutcome: evt.diceOutcome,
              progressChange: evt.progressChange,
              baseProgressChange: evt.baseProgressChange,
              valence: evt.valence ?? valenceOf(evt.progressChange),
              anachronism: evt.anachronism,
              causalChain: evt.causalChain,
              craft: evt.craft,
              whenSigned: evt.whenSigned,
              staked: evt.staked,
              timestamp: evt.timestamp ?? new Date()
          })
      },
765 
      // ---------- the living chronicle (Layer 3) ----------
      /**
       * Re-narrates the Chronicle from the freshly-bent timeline. Fired
       * non-blocking after a resolved turn (and at game end): the dice/progress
       * reveal never waits on prose. True to the game's name, the WHOLE account is
       * rewritten each turn — a later change can re-frame how earlier events read.
       * Graceful: a failed refresh keeps the prior telling, so the panel never
       * blanks; an empty timeline clears it (nothing to chronicle yet).
       */
      async refreshChronicle(): Promise<void> {
          if (!this.timelineEvents.length) {
              this.chronicle = null
              return
          }
          // Sequencing: rewrites overlap (each turn fires one, never awaited), so
          // only the LATEST issued refresh may land — an earlier telling arriving
          // late must not regress the account (or worse, the epilogue). The epoch
          // guard keeps a dead run's telling out of a fresh run entirely.
          const epoch = this.runEpoch
          const seq = ++this.chronicleSeq
          this.chronicleLoading = true
          try {
              const res = await $fetch('/api/chronicle', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: {
                      objective: this.currentObjective,
                      status: this.gameStatus,
                      progress: this.objectiveProgress,
                      timeline: this.timelineEvents.map(e => ({
                          era: e.era,
                          figureName: e.figureName,
                          headline: e.headline,
                          detail: e.detail,
                          progressChange: e.progressChange
                      }))
                  }
              }) as { success?: boolean; chronicle?: ChronicleEntry }
              if (epoch !== this.runEpoch || seq !== this.chronicleSeq) return
              if (res?.success && res.chronicle) this.chronicle = res.chronicle
          } catch (error) {
              if (epoch !== this.runEpoch || seq !== this.chronicleSeq) return
              console.error('Failed to refresh the chronicle:', error)
              // Keep the prior chronicle — a failed refresh never blanks the panel.
          } finally {
              if (epoch === this.runEpoch && seq === this.chronicleSeq) this.chronicleLoading = false
          }
      },
814 
      // ---------- simple setters ----------
      setLoading(loading: boolean) { this.isLoading = loading },
      setError(error: string | null) { this.error = error },
      clearModerationNotice() { this.moderationNotice = null },
      clearArchiveNotice() { this.archiveNotice = null },
820 
      // ---------- rate limiting ----------
      checkRateLimit(): boolean {
          const now = Date.now()
          if (this.lastMessageTime && (now - this.lastMessageTime) < RATE_LIMIT_MS) return false
          return true
      },
827 
      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)
      },
835 
      // ---------- counter & status ----------
      decrementMessages() {
          if (this.remainingMessages > 0) this.remainingMessages--
      },
840 
      /**
       * 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
              }
          }
      },
857 
      applyProgress(progressChange: number) {
          this.objectiveProgress = Math.max(0, Math.min(MAX_PROGRESS, this.objectiveProgress + progressChange))
      },
861 
      /**
       * Resolves win/lose AFTER a turn's progress has been applied.
       *
       * Victory the instant the objective hits 100%; defeat only once the
       * final message is spent without reaching it. This fixes the old
       * premature-defeat bug, where status flipped on the last decrement
       * BEFORE that turn's progress had a chance to land.
       */
      resolveGameStatus() {
          if (this.objectiveProgress >= MAX_PROGRESS) {
              this.gameStatus = 'victory'
          } else if (this.remainingMessages <= 0) {
              this.gameStatus = 'defeat'
          }
      },
877 
      // ---------- 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
895 
          if (!this.canSendMessage) return false
          if (!target) {
              this.setError('Choose who in history to send your message to first.')
              return false
          }
          if (!this.checkRateLimit()) {
              this.setRateLimit()
              this.setError('The timeline needs a moment — wait before sending again.')
              return false
          }
          if (!this.canContact) {
              const who = this.figureGrounding?.name || target
              this.setError(
                  this.contactLiveness === 'unresolved'
                      ? (this.figureGrounding?.transient
                          ? `Couldn't reach the record to verify "${target}" — try again in a moment.`
                          : `No historical record found for "${target}" — reach for a real figure (pick a match as you type).`)
                      : this.contactLiveness === 'before-birth'
                          ? `${who} isn't born yet in that year — choose a later moment to reach them.`
                          : this.contactLiveness === 'living'
                              ? (this.figureGrounding?.born
                                  ? `${who} is still living — Revisionist only reaches figures from history.`
                                  : `${who} couldn't be dated — Revisionist can only reach figures it can place in history.`)
                              : `${who} has died by that year — choose an earlier moment to reach them.`
              )
              return false
          }
923 
          this.setError(null)
          this.moderationNotice = null
          this.setActiveFigure(target)
          this.addUserMessage(text, target)
          this.decrementMessages()
          this.setLoading(true)
          this.lastMessageTime = Date.now()
931 
          // If the run is reset while this request is in flight, every write below
          // would land in a world that no longer exists — the epoch guard drops the
          // response (no fold-in, no refund: the new run's counter is not ours).
          const epoch = this.runEpoch
          const ledgerBefore = this.timelineEvents.length
          // Capture the contact year NOW: the slider can move while the request is
          // in flight, and the ledger must record the year this turn was SENT to.
          const sentWhen = this.contactWhen
          const sentMoment = this.contactMoment
          let resolved = false
          // Decide once whether to stagger the reveal (browser + motion allowed).
          const animate = canAnimateReveal()
944 
          try {
              const response = await $fetch<SendMessageApiResponse>('/api/send-message', {
                  method: 'POST',
                  headers: await this.aiHeaders({ 'Content-Type': 'application/json' }),
                  body: {
                      message: text,
                      figureName: target,
                      when: sentWhen != null ? formatContactMoment(sentWhen, sentMoment) : undefined,
                      whenSigned: sentWhen ?? undefined,
                      // The pinned moment travels as validated integers; the server
                      // re-derives the display string rather than trusting ours.
                      whenMonth: sentWhen != null ? sentMoment?.month : undefined,
                      whenDay: sentWhen != null ? sentMoment?.day : undefined,
                      stake,
                      // The pre-turn momentum the server amplifies the swing by, and
                      // returns advanced (the client stays the system of record).
                      momentum: this.momentum,
                      figureContext: this.figureGrounding?.resolved
                          ? {
                              description: this.figureGrounding.description,
                              lifespan: lifespanText(this.figureGrounding)
                          }
                          : undefined,
                      objective: this.currentObjective,
                      timeline: this.timelineEvents.map(e => ({
                          era: e.era,
                          figureName: e.figureName,
                          headline: e.headline,
                          detail: e.detail,
                          progressChange: e.progressChange,
                          whenSigned: e.whenSigned
                      })),
                      conversationHistory: this.conversationWith(target)
                  }
              })
980 
              if (epoch !== this.runEpoch) return false
982 
              if (response?.success && response.data?.characterResponse) {
                  const { figure, characterResponse, diceRoll, diceOutcome, timeline } = response.data
985 
                  if (figure?.name) {
                      this.registerFigure({
                          name: figure.name,
                          era: figure.era || '',
                          descriptor: figure.descriptor || ''
                      })
                  }
993 
                  // ---- 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
                  }
1001 
                  // Beat 1 — the die lands and the figure's reply writes itself in
                  // (its parts stage over ~0.55s via CSS). Flipping loading here
                  // (mid-sequence) is what lands the die now; the finally's flip
                  // becomes a no-op.
                  this.addAIMessageWithData({
                      text: characterResponse.message,
                      sender: 'ai',
                      figureName: target,
                      timestamp: new Date(),
                      diceRoll,
                      diceOutcome,
                      naturalRoll: response.data.naturalRoll ?? diceRoll,
                      rollModifier: response.data.rollModifier ?? 0,
                      craft: response.data.craft,
                      craftReason: response.data.craftReason,
                      continuity: response.data.continuity,
                      characterAction: characterResponse.action,
                      timelineImpact: timeline?.detail,
                      progressChange: timeline?.progressChange,
                      baseProgressChange: timeline?.baseProgressChange,
                      momentumAtSwing: timeline?.momentumAtSwing,
                      anachronism: timeline?.anachronism,
                      causalChain: timeline?.causalChain,
                      staked: response.data.staked
                  })
                  if (animate) this.setLoading(false)
1028 
                  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
1045 
                      // Beat 3 — the change drops onto the Spine ledger.
                      if (animate) {
                          await wait(REVEAL.node)
                          if (epoch !== this.runEpoch) return false
                      }
                      this.addTimelineEvent({
                          figureName: target,
                          era: timeline.era || figure?.era || (this.currentObjective?.era ?? ''),
                          headline: timeline.headline,
                          detail: timeline.detail,
                          diceRoll,
                          diceOutcome,
                          progressChange: timeline.progressChange ?? 0,
                          baseProgressChange: timeline.baseProgressChange,
                          valence: timeline.valence,
                          anachronism: timeline.anachronism,
                          causalChain: timeline.causalChain,
                          craft: response.data.craft,
                          whenSigned: sentWhen ?? undefined,
                          staked: response.data.staked
                      })
                      resolved = true
                  }
              } else {
                  // A graceful failure (HTTP 200, success:false): an AI layer gave
                  // out mid-turn. No ripple landed, so the dispatch is refunded —
                  // exactly like the thrown path below.
                  // Narrow to the failure variant (its data carries `blocked`).
                  const failed = response && !response.success ? response.data : undefined
                  if (failed?.blocked) {
                      // A content-moderation block, not an infra hiccup — show an
                      // honest, distinct banner (not "try again"). The composer
                      // keeps the player's words (sendMessage returns false).
                      this.moderationNotice = failed.moderationReason || 'That dispatch was blocked by content moderation and cannot be sent.'
                  } else {
                      this.setError(failed?.error || 'History did not answer. Try again.')
                  }
                  this.refundUnresolvedTurn()
              }
          } catch (error) {
              if (epoch !== this.runEpoch) return false
              console.error('Error sending message:', error)
              this.setError('The timeline resisted your message. Please try again.')
              this.refundUnresolvedTurn()
          } finally {
              if (epoch === this.runEpoch) {
                  this.setLoading(false)
                  this.resolveGameStatus()
              }
          }
1096 
          // The living chronicle re-narrates the world from the new timeline — but
          // only when this turn actually added a change, and never awaited: the turn
          // reveal must not wait on prose. By here the status is resolved, so the
          // final turn's chronicle carries the victory/defeat framing (the epilogue).
          let refresh: Promise<void> | null = null
          if (resolved && this.timelineEvents.length > ledgerBefore) {
              refresh = this.refreshChronicle()
              void refresh
          }
          // The run just ended: persist it (best-effort) so it survives reload, then
          // re-save once the epilogue's telling lands — the immediate save guards
          // against that refresh failing, the second captures the final Chronicle.
          if (this.gameStatus === 'victory' || this.gameStatus === 'defeat') {
              // This turn's refresh writes the EPILOGUE — the terminal telling that
              // carries the verdict. Mark it pending so the end screen shows "the
              // final account…" instead of the prior turn's stale telling. Cleared
              // when the telling lands OR the refresh fails (refreshChronicle keeps
              // the prior telling on failure) — so the panel reveals or falls back,
              // never hanging on the loading state.
              if (refresh) {
                  this.epiloguePending = true
                  void refresh.finally(() => { if (epoch === this.runEpoch) this.epiloguePending = false })
              }
              void this.saveRunSnapshot()
              if (refresh) void refresh.finally(() => { void this.saveRunSnapshot() })
          }
          return resolved
      },
1125 
      /**
       * 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 }
      },
1138 
      /** 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
      },
1144 
      /**
       * Commits a chosen objective and starts the run from a clean slate of
       * progress. Used by the mission-select screen for both curated picks and
       * freshly composed ones.
       */
      async chooseObjective(objective: GameObjective): Promise<boolean> {
          // Commit = the run is charged here. Mint the run id server-side, then
          // spend one run from the device's balance. Fails CLOSED: out of runs →
          // raise the paywall; begin-run or commit failing → surface an error and
          // do NOT start. A run that isn't a charged, server-backed run would be
          // rejected by the gameplay gate anyway, so starting it only strands the
          // player mid-run. The spend cap (not free play) is the outage backstop.
          let runId: string
          try {
              runId = await this.ensureRunId()
          } catch (error) {
              console.error('Could not begin the run:', error)
              this.error = 'Could not start the run. Please try again.'
              return false
          }
          try {
              const res = await $fetch('/api/run-commit', {
                  method: 'POST',
                  headers: { 'Content-Type': 'application/json' },
                  body: { runId }
              }) as { runsRemaining?: number }
              this.outOfRuns = false
              // Keep the header gauge live: the commit returns the post-charge
              // balance (−1 marks a degraded, ungated run — leave the gauge as is).
              if (typeof res?.runsRemaining === 'number' && res.runsRemaining >= 0) {
                  this.runsRemaining = res.runsRemaining
              }
          } catch (error) {
              if (isPaymentRequired(error)) {
                  this.outOfRuns = true
                  this.openBuyModal()
                  return false
              }
              if (isAtCapacity(error)) {
                  this.atCapacity = true
                  return false
              }
              console.error('Could not charge the run:', error)
              this.error = 'Could not start the run. Please try again.'
              return false
          }
          this.currentObjective = objective
          this.objectiveProgress = 0
          this.momentum = 0
          this.error = null
          return true
      },
1197 
      /**
       * Asks the server to compose a fresh objective with the model, WITHOUT
       * committing it — the caller previews it, then commits via chooseObjective.
       * Generation lives server-side because it needs the OpenAI key (the client
       * has no access to it). An optional steer (era + theme, closed enums) biases
       * the composition; the server re-validates it against the enums, so a bad
       * value is harmless. `avoid` is the titles already composed this session, so
       * a reroll lands somewhere new (#95) — the stateless server only knows what
       * the client supplies. Returns null rather than throwing if composing fails,
       * so the UI can quietly fall back to the curated pool.
       */
      async fetchAIObjective(steer: ObjectiveSteer = {}, avoid: string[] = []): Promise<GameObjective | null> {
          try {
              const query: Record<string, string | string[]> = {}
              if (steer.era) query.era = steer.era
              if (steer.theme) query.theme = steer.theme
              if (avoid.length) query.avoid = avoid
              const res = await $fetch('/api/objective', { method: 'GET', query, headers: await this.aiHeaders() }) as {
                  success?: boolean
                  objective?: GameObjective
              }
              return res?.success && res.objective ? res.objective : null
          } catch (error) {
              console.error('Failed to compose a fresh objective:', error)
              return null
          }
      },
1225 
      /**
       * Loads the device's run balance for the header gauge + account popover.
       * Grants the free trial on a brand-new device (server-side). Graceful: on
       * failure it leaves the prior value (the gauge simply doesn't update).
       */
      async loadBalance(): Promise<void> {
          try {
              const res = await $fetch('/api/balance') as { runsRemaining?: number; freeRuns?: number; deviceRef?: string; email?: string | null; isAnonymous?: boolean }
              if (typeof res?.runsRemaining === 'number') this.runsRemaining = res.runsRemaining
              if (typeof res?.freeRuns === 'number') this.freeRuns = res.freeRuns
              if (typeof res?.deviceRef === 'string') this.deviceRef = res.deviceRef
              this.accountEmail = res?.email ?? null
              this.accountAnonymous = res?.isAnonymous === true
          } catch (error) {
              console.error('Failed to load balance:', error)
          }
      },
1243 
      /** Opens the run-packs sales modal, loading the catalog first. */
      async openBuyModal(): Promise<void> {
          this.buyModalOpen = true
          await this.loadPacks()
      },
1249 
      /** Closes the sales modal. */
      closeBuyModal(): void {
          this.buyModalOpen = false
      },
1254 
      /** 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()
          }
      },
1265 
      /** Dismisses the post-purchase notice. */
      clearPurchaseNotice(): void {
          this.purchaseNotice = null
      },
1270 
      /** 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)
          }
      },
1284 
      /** 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
          }
      },
1300 
      getVictoryEfficiency() {
          if (this.gameStatus === 'victory') {
              const messagesSaved = this.remainingMessages
              const messagesUsed = TOTAL_MESSAGES - this.remainingMessages
              const efficiencyPercentage = Math.round((messagesSaved / TOTAL_MESSAGES) * 100)
1306 
              const efficiencyRating = rateEfficiency(messagesSaved)
1308 
              return {
                  messagesSaved,
                  messagesUsed,
                  efficiencyPercentage,
                  efficiencyRating,
                  isEarlyVictory: messagesSaved > 0
              }
          }
          return null
      },
1319 
      /**
       * 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
1336 
          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
1352 
          const snapshot: RunSnapshot = {
              version: RUN_SNAPSHOT_VERSION,
              runId,
              status,
              objective,
              objectiveProgress: this.objectiveProgress,
              messagesUsed: TOTAL_MESSAGES - this.remainingMessages,
              totalMessages: TOTAL_MESSAGES,
              bestRoll: mark(summary.bestRoll),
              worstRoll: mark(summary.worstRoll),
              efficiency: this.getVictoryEfficiency(),
              dispatches,
              timeline: events.map((e) => ({
                  id: e.id,
                  figureName: e.figureName,
                  era: e.era,
                  headline: e.headline,
                  detail: e.detail,
                  diceRoll: e.diceRoll,
                  diceOutcome: e.diceOutcome,
                  progressChange: e.progressChange,
                  baseProgressChange: e.baseProgressChange,
                  valence: e.valence,
                  craft: e.craft,
                  anachronism: e.anachronism,
                  staked: e.staked
              })),
              chronicle: this.chronicle
          }
1382 
          // 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
1390 
⋯ 65 lines hidden (lines 1391–1455)1391            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)
          }
      },
1405 
      resetGame() {
          // Tear the epoch first: anything still in flight belongs to the old run
          // and must find no purchase here. (The seq counters deliberately survive.)
          this.runEpoch++
          this.remainingMessages = TOTAL_MESSAGES
          this.messageHistory = []
          this.gameStatus = 'playing'
          this.isLoading = false
          this.error = null
          this.lastMessageTime = null
          this.isRateLimited = false
          // A new run gets a fresh id on its next server call; abandon any
          // in-flight mint so a dead run's id can't land in the new run.
          this.runId = null
          this.runIdInflight = null
          this.runSnapshotSaved = false
          // The paywall / capacity notices re-check on the next commit.
          this.outOfRuns = false
          this.atCapacity = false
          this.currentObjective = null
          // A fresh run carries no replay lineage (preseedReplay re-sets it after).
          this.replayState = null
          this.objectiveProgress = 0
          this.momentum = 0
          this.timelineEvents = []
          this.figures = []
          this.activeFigureName = ''
          this.figureGrounding = null
          this.groundingLoading = false
          this.contactWhen = null
          this.contactMoment = null
          this.figureSuggestions = []
          this.suggestionsLoading = false
          this.suggestionsFor = ''
          this.chronicle = null
          this.chronicleLoading = false
          this.epiloguePending = false
          this.figureStudy = null
          this.studyLoading = false
          this.studyFor = ''
          this.studyWhen = null
          this.archiveResult = null
          this.lookupLoading = false
          this.moderationNotice = null
          this.archiveNotice = null
          this.studyNotice = null
          this.suggestionsNotice = null
      }
  }
1455})

The route reads the sibling field, uuid-gates it, passes it through.

server/api/run-save.post.ts · 42 lines

server/api/run-save.post.ts42 lines · TypeScript

⋯ 28 lines hidden (lines 1–28)1/**
* POST /api/run-save — persist a finished run's snapshot, owned by the account
* subject. The client posts the end-of-run snapshot on victory/defeat; the server
* validates it, then stores it keyed by the run id so it survives reload and seeds
* the read-only "your runs" view.
*
* Best-effort by design: the client fires this without blocking the end screen, so a
* failure here degrades history, never the game. A degraded run (a non-uuid local id,
* never recorded server-side) has nothing to own — it's accepted as a no-op.
*/
11import { sanitizeSnapshot } from '~/server/utils/run-snapshot'
12import { runSnapshotStore } from '~/server/utils/run-snapshot-store'
13import { currentSubject } from '~/server/utils/auth'
14import { isUuid } from '~/server/utils/uuid'
15 
16export default defineEventHandler(async (event) => {
  if (getMethod(event) !== 'POST') {
      throw createError({ statusCode: 405, statusMessage: 'Method Not Allowed' })
  }
  const body = await readBody(event)
  const snapshot = sanitizeSnapshot(body)
  if (!snapshot) {
      throw createError({ statusCode: 400, statusMessage: 'Bad Request: invalid run snapshot' })
  }
  // A degraded (non-uuid local) run was never recorded server-side — nothing to own.
  if (!isUuid(snapshot.runId)) {
      return { saved: false, degraded: true }
  }
  // Replay lineage (issue #89): a sibling field, NOT part of the snapshot blob — the
  // source run's public share token, which the server resolves to the parent's stable
  // run id. uuid-gated so a malformed value is simply ignored (lineage is best-effort).
  const rawToken = typeof body?.remixedFromToken === 'string' ? body.remixedFromToken : ''
  const derivedFromToken = isUuid(rawToken) ? rawToken : undefined
  const subject = await currentSubject(event)
  try {
      await runSnapshotStore().saveRun(subject, snapshot, { derivedFromToken })
  } catch (error) {
⋯ 5 lines hidden (lines 38–42)38        console.error('Failed to save run snapshot:', error)
      throw createError({ statusCode: 500, statusMessage: 'Internal Server Error' })
  }
  return { saved: true }
42})

The UI: a focused replay, and one credit line everywhere

MissionSelect grows a replay mode: when replayState is set it shows just the seeded objective, ready to play, with the credit above it — not the full browse/compose briefing. begin() commits the seeded objective verbatim, so replay runs no generation. "Choose a different objective" drops the seed, so an opted-out run is never mislabeled.

The replay block, and begin() preferring the seeded objective.

components/MissionSelect.vue · 242 lines

components/MissionSelect.vue242 lines · Vue

⋯ 4 lines hidden (lines 1–4)1<template>
2  <!-- Mission briefing: choose (or compose) the run's grand objective, as a ledger. -->
3  <div data-testid="mission-select" class="rv-fade-in max-w-4xl mx-auto">
4    <!-- Replay (issue #89): seeded from a shared run's objective. A focused view — this
5         one objective, ready to play — not the full browse/compose ledger. -->
6    <template v-if="replay">
7      <div class="mb-7">
8        <p class="rv-label">Replay a shared objective</p>
9        <h2 class="rv-serif rv-fg text-2xl sm:text-3xl font-semibold mt-1.5 leading-tight">Take on this very objective</h2>
10        <RemixCreditLine :credit="replayCredit" class="mt-2" />
11      </div>
12 
13      <div data-testid="replay-objective" class="border-t border-b rv-line py-4 flex items-start gap-3 rv-tint"
14        :style="{ borderLeft: '2px solid var(--rv-accent)' }">
15        <span class="w-6 shrink-0 text-center text-lg leading-none select-none" aria-hidden="true">{{ replay.objective.icon }}</span>
16        <span class="min-w-0 flex-1">
17          <span class="flex items-center gap-2 flex-wrap">
18            <h3 class="rv-fg font-semibold">{{ replay.objective.title }}</h3>
19            <span v-if="replay.objective.era" class="rv-label">{{ replay.objective.era }}</span>
20          </span>
21          <!-- whitespace-pre-line: the brief is newline-separated "• " bullet lines (#82). -->
22          <span class="block rv-muted text-sm mt-0.5 leading-relaxed whitespace-pre-line">{{ replay.objective.description }}</span>
23        </span>
24      </div>
25 
26      <div class="mt-5 flex flex-col sm:flex-row sm:items-center sm:justify-between gap-3">
27        <button type="button" data-testid="replay-exit" class="rv-tap rv-hover-fg text-xs rv-mono uppercase tracking-wide"
28          @click="exitReplay">
29          ← Choose a different objective
30        </button>
31        <button type="button" data-testid="begin-button" class="rv-btn rv-btn--primary" :disabled="beginning" @click="begin">
32          {{ beginning ? 'Charting the timeline…' : 'Play this objective' }} <span aria-hidden="true">▷</span>
33        </button>
34      </div>
35    </template>
⋯ 194 lines hidden (lines 36–229)36 
37    <!-- Normal briefing: choose a curated objective, or compose a fresh one. -->
38    <template v-else>
39    <div class="mb-7">
40      <p class="rv-label">Choose your crusade</p>
41      <h2 class="rv-serif rv-fg text-2xl sm:text-3xl font-semibold mt-1.5 leading-tight">What will you set right?</h2>
42      <p class="rv-muted text-sm mt-2 max-w-xl">
43        Five messages. Anyone in history. One world to remake. Pick the cause that will define your run — or have a fresh one composed.
44      </p>
45    </div>
46 
47    <!-- Objectives as borderless hairline rows (a freshly composed one leads) -->
48    <div role="radiogroup" aria-label="Choose an objective" class="border-t rv-line">
49      <button v-for="obj in options" :key="(obj === fresh ? 'fresh:' : 'curated:') + obj.title" type="button"
50        data-testid="objective-option" role="radio" :aria-checked="isSelected(obj)"
51        class="w-full text-left flex items-start gap-3 py-3 pr-2 pl-3 border-b rv-line transition rv-hover"
52        :class="isSelected(obj) ? 'rv-tint' : ''"
53        :style="{ borderLeft: `2px solid ${isSelected(obj) ? 'var(--rv-accent)' : 'transparent'}` }" @click="select(obj)">
54        <span class="rv-dot mt-1.5" :class="isSelected(obj) ? 'rv-dot--accent' : 'rv-dot--hollow'" aria-hidden="true" />
55        <span class="w-6 shrink-0 text-center text-lg leading-none select-none" aria-hidden="true">{{ obj.icon }}</span>
56        <span class="min-w-0 flex-1">
57          <span class="flex items-center gap-2 flex-wrap">
58            <h3 class="rv-fg font-semibold">{{ obj.title }}</h3>
59            <span v-if="obj.era" class="rv-label">{{ obj.era }}</span>
60            <span v-if="obj === fresh" data-testid="fresh-badge" class="rv-accent text-[10px] uppercase tracking-wider">
61              ✨ freshly composed
62            </span>
63          </span>
64          <!-- whitespace-pre-line: the brief is newline-separated "• " bullet lines (issue #82). -->
65          <span class="block rv-muted text-sm mt-0.5 leading-relaxed whitespace-pre-line">{{ obj.description }}</span>
66        </span>
67      </button>
68    </div>
69 
70    <!-- Steer a fresh composition: two closed-enum dials, set before composing.
71         "No preference" leaves an axis to the model. Closed enums only (no free
72         text), so an out-of-bounds objective can't be steered into existence. -->
73    <fieldset class="mt-6 pt-4 border-t rv-line">
74      <legend class="rv-label">Steer a fresh composition <span class="rv-faint">· optional</span></legend>
75      <div class="mt-2 flex flex-col sm:flex-row gap-3 sm:gap-4">
76        <label class="flex-1 min-w-0 text-sm">
77          <span class="rv-label block mb-1">Era</span>
78          <select v-model="steerEra" data-testid="steer-era" class="rv-select text-sm" aria-label="Steer the era">
79            <option value="">No preference</option>
80            <option v-for="era in OBJECTIVE_ERAS" :key="era" :value="era">{{ era }}</option>
81          </select>
82        </label>
83        <label class="flex-1 min-w-0 text-sm">
84          <span class="rv-label block mb-1">Theme</span>
85          <select v-model="steerTheme" data-testid="steer-theme" class="rv-select text-sm" aria-label="Steer the theme">
86            <option value="">No preference</option>
87            <option v-for="theme in OBJECTIVE_THEMES" :key="theme" :value="theme">{{ theme }}</option>
88          </select>
89        </label>
90      </div>
91    </fieldset>
92 
93    <!-- Actions: compose a fresh objective · begin the run -->
94    <div class="mt-5 flex flex-col sm:flex-row sm:items-center sm:justify-between gap-3">
95      <div class="flex flex-col items-start gap-1">
96        <button type="button" data-testid="compose-objective" class="rv-btn text-sm" :disabled="composing" @click="rollFresh">
97          <span aria-hidden="true">✨</span> {{ composing ? 'Composing a fresh fate…' : 'Compose a fresh objective with AI' }}
98        </button>
99        <p v-if="activeSteer" data-testid="active-steer" class="text-xs rv-muted">Steering: {{ activeSteer }}</p>
100        <p v-if="composeError" data-testid="compose-error" class="text-xs rv-bad">{{ composeError }}</p>
101      </div>
102 
103      <button type="button" data-testid="begin-button" class="rv-btn rv-btn--primary" :disabled="!selected || beginning" @click="begin">
104        {{ beginning ? 'Charting the timeline…' : 'Begin rewriting history' }} <span aria-hidden="true">▷</span>
105      </button>
106    </div>
107    </template>
108 
109    <!-- Paywall: the free run is spent. The run-packs modal opens automatically on
110         the refused commit; this persistent notice lets the player reopen it if they
111         dismissed it. -->
112    <div v-if="gameStore.outOfRuns" data-testid="paywall" class="mt-4 pt-4 border-t rv-line">
113      <p class="text-sm rv-fg font-semibold">You're out of runs — your free run is spent.</p>
114      <p class="rv-muted text-xs mt-0.5">Grab a pack to keep rewriting history. One-time, never expires.</p>
115      <button type="button" data-testid="open-packs" class="rv-btn rv-btn--primary mt-3"
116        @click="gameStore.openBuyModal()">
117        See run packs <span aria-hidden="true">→</span>
118      </button>
119    </div>
120 
121    <!-- Capacity: the global spend cap paused new runs (in-progress runs continue). -->
122    <p v-else-if="gameStore.atCapacity" data-testid="at-capacity" class="text-sm rv-bad mt-3">
123      The timeline is at capacity right now — please try again shortly.
124    </p>
125 
126    <!-- Compliance disclosure, shown at the start of every run (Anthropic Usage
127         Policy: AI disclosure at session start; outputs may be inaccurate; an
128         adults-only posture). -->
129    <p data-testid="ai-disclosure" class="rv-faint text-xs leading-relaxed mt-8 pt-4 border-t rv-line max-w-2xl">
130      The historical figures here are played by AI, not real people, and every reply is
131      AI-generated <span class="rv-fg">alternate history — dramatized fiction, not historical fact</span>;
132      don't rely on it as accurate. Intended for adults (18+).
133    </p>
134  </div>
135</template>
136 
137<script setup lang="ts">
138/**
139 * MissionSelect — the opening briefing. Curated objectives + a live-composed one, as
140 * borderless hairline rows; selection uses identity, not titles. Nothing commits
141 * until Begin, so a freshly composed objective can be previewed and reconsidered.
142 */
143import { ref, shallowRef, computed } from 'vue'
144import { useGameStore } from '~/stores/game'
145import type { RemixCredit } from '~/utils/run-snapshot'
146import {
147    listCuratedObjectives,
148    OBJECTIVE_ERAS,
149    OBJECTIVE_THEMES,
150    type GameObjective,
151    type ObjectiveEra,
152    type ObjectiveTheme
153} from '~/server/utils/objectives'
154 
155const gameStore = useGameStore()
156 
157// Replay mode (issue #89): set when seeded from a shared run's objective. The briefing
158// shows just that objective, ready to play; Begin commits it verbatim (no generation).
159const replay = computed(() => gameStore.replayState)
160// The "remixed from" line above the seeded objective. The title is omitted (the objective
161// is shown right below), so it reads "Remixed from <name>" / "…an anonymous run", linking
162// back to the source when still shared.
163const replayCredit = computed<RemixCredit>(() => ({
164    attribution: replay.value?.sourceAttribution ?? null,
165    objectiveTitle: '',
166    sourceToken: replay.value?.sourceToken ?? null
167}))
168 
169const curated = listCuratedObjectives()
170// shallowRef, not ref: selection is by object identity (isSelected uses ===), and the
171// curated options are plain objects. A deep ref would return a *reactive proxy* on
172// `.value`, so `selected.value === obj` (raw) would be false — the row would highlight
173// on hover but its radio dot / aria-checked would never flip. shallowRef stores the
174// value as-is, keeping identity intact.
175const fresh = shallowRef<GameObjective | null>(null)
176const selected = shallowRef<GameObjective | null>(null)
177// Titles composed this session, fed back as the avoid-list so each reroll lands
178// somewhere new (#95). Resets naturally: MissionSelect is mounted only while there's
179// no objective (v-if in play.vue), so a new run remounts it with an empty list.
180const seenTitles = ref<string[]>([])
181const composing = ref(false)
182const composeError = ref<string | null>(null)
183const beginning = ref(false)
184 
185// Composition steer (closed enums; '' = no preference, left to the model).
186const steerEra = ref<ObjectiveEra | ''>('')
187const steerTheme = ref<ObjectiveTheme | ''>('')
188 
189const options = computed(() => (fresh.value ? [fresh.value, ...curated] : curated))
190 
191// A plain-language echo of the active steer, surfaced by the compose button.
192const activeSteer = computed(() =>
193    [steerEra.value, steerTheme.value].filter(Boolean).join(' · ') || null
194)
195 
196function isSelected(obj: GameObjective) {
197    return selected.value === obj
198}
199 
200function select(obj: GameObjective) {
201    selected.value = obj
202}
203 
204async function rollFresh() {
205    composing.value = true
206    composeError.value = null
207    const objective = await gameStore.fetchAIObjective({
208        era: steerEra.value || undefined,
209        theme: steerTheme.value || undefined
210    }, seenTitles.value)
211    composing.value = false
212 
213    if (objective) {
214        fresh.value = objective
215        selected.value = objective // auto-select the fresh one so Begin is one tap away
216        // Remember it so the next reroll avoids it (a curated fallback lands here too,
217        // so even a fallback won't be re-served).
218        if (!seenTitles.value.includes(objective.title)) seenTitles.value.push(objective.title)
219    } else {
220        composeError.value = 'The archives went quiet — pick one above, or try composing again.'
221    }
222}
223 
224// Leave replay mode for the full browse/compose briefing — this run becomes an original.
225function exitReplay() {
226    gameStore.clearReplayState()
227    selected.value = null
228}
229 
230async function begin() {
231    // In replay mode the seeded objective IS the choice (no browse list rendered);
232    // otherwise it's whatever the player selected. Either way chooseObjective commits
233    // it verbatim — replay runs no generation, just reuses the captured objective.
234    const objective = replay.value?.objective ?? selected.value
235    if (!objective || beginning.value) return
236    beginning.value = true
237    // Charges one run from the balance. If out of runs, chooseObjective raises the
238    // paywall (gameStore.outOfRuns) and opens the run-packs modal; no run starts.
239    await gameStore.chooseObjective(objective)
240    beginning.value = false
241}
242</script>

The share page wires the button to preseedReplay then routes to /play, and passes its own remixedFrom down to RunView (so a shared run that is itself a replay shows its credit). The credit is rendered by one small shared component, RemixCreditLine, reused by RunView (the public + saved pages) and EndGameScreen (the live end screen) — name only where opted in, a backlink only while the source is still shared.

Play this objective → preseed → /play; the page's own remixedFrom.

pages/r/[token].vue · 159 lines

pages/r/[token].vue159 lines · Vue

⋯ 42 lines hidden (lines 1–42)1<template>
2  <!-- A shared run, public + read-only (issue #88). Reached by an unguessable token, no
3       login. It replays the end screen from the sanitized public projection — the same
4       RunView a saved run uses — adds opt-in attribution, ways to pass it on, and a CTA
5       into a run of your own. Server-rendered so the link unfurls rich in social feeds. -->
6  <div class="min-h-screen rv-bg flex flex-col">
7    <header class="border-b rv-line">
8      <div class="px-5 py-2.5 flex items-center gap-4 max-w-3xl mx-auto w-full">
9        <GameTitle />
10        <button type="button" class="rv-tap rv-hover-fg text-base leading-none shrink-0 ml-auto"
11          :aria-label="isDark ? 'Switch to light mode' : 'Switch to dark mode'" @click="toggleDark">◐</button>
12      </div>
13    </header>
14 
15    <main class="flex-1 px-5 py-8">
16      <div class="max-w-4xl mx-auto">
17        <div v-if="pending" data-testid="share-loading" class="rv-faint italic text-sm mt-8">Opening the run…</div>
18 
19        <div v-else-if="!run" data-testid="share-not-found" class="mt-8 border-t rv-line pt-6">
20          <h2 class="rv-serif rv-fg text-2xl font-bold">This run isn't available</h2>
21          <p class="rv-muted text-sm mt-2">The link may be wrong, or the run was un-shared by its owner.</p>
22          <NuxtLink to="/play" data-testid="share-not-found-cta" class="rv-btn rv-btn--primary mt-4 inline-flex">
23            Rewrite your own history <span aria-hidden="true">▷</span>
24          </NuxtLink>
25        </div>
26 
27        <template v-else>
28          <p v-if="attribution" data-testid="share-attribution" class="rv-label">
29            A run shared by {{ attribution }}
30          </p>
31          <RunView :snapshot="run" :remixed-from="remixedFrom" class="mt-3" />
32 
33          <!-- Pass it on -->
34          <div class="mt-9 border-t rv-line pt-6">
35            <span class="rv-label rv-label--rule">Pass it on</span>
36            <ShareLinks :url="pageUrl" :text="shareText" />
37          </div>
38 
39          <!-- The funnel: turn a viewer into a player. The headline act is REPLAY —
40               start your own run on this very objective (issue #89), credited back to
41               this sharer — with a plain "from scratch" path kept as the alternative. -->
42          <div class="mt-7">
43            <p class="rv-muted text-sm mb-3">Think you can do better? Take on this very objective — your own five messages, your own timeline.</p>
44            <button type="button" data-testid="share-play-cta" class="rv-btn rv-btn--primary text-base inline-flex" @click="playObjective">
45              Play this objective <span aria-hidden="true">▷</span>
46            </button>
47            <p class="mt-3">
48              <button type="button" data-testid="share-scratch-cta" class="rv-tap rv-hover-fg text-xs rv-mono uppercase tracking-wide" @click="playFresh">
49                or rewrite your own history from scratch →
50              </button>
⋯ 35 lines hidden (lines 51–85)51            </p>
52          </div>
53        </template>
54      </div>
55    </main>
56 
57    <footer class="border-t rv-line px-5 py-3 text-[11px] rv-faint">
58      <div class="max-w-4xl mx-auto flex items-center gap-2">
59        <span class="rv-mono uppercase tracking-wide">Revisionist</span>
60        <span class="rv-hair-c" aria-hidden="true">·</span>
61        <span class="rv-serif italic">this timeline is written</span>
62      </div>
63    </footer>
64  </div>
65</template>
66 
67<script setup lang="ts">
68/**
69 * The public run page (/r/:token). Fetches the sanitized public projection from
70 * GET /api/share/:token (which 404s an unknown/revoked token → the "not available"
71 * state) and hands its snapshot to RunView — the very component the owner's saved-run
72 * page uses, so a shared run reads exactly like the real end screen. The SEO/unfurl meta
73 * is set with useServerSeoMeta so it's present in the SSR HTML crawlers read, with the
74 * og:image pointed at the per-run share card.
75 */
76import { computed } from 'vue'
77import { buildShareText, type PublicRun } from '~/utils/run-snapshot'
78import { useGameStore } from '~/stores/game'
79 
80const route = useRoute()
81const token = computed(() => String(route.params.token))
82 
83const { data, pending } = await useFetch<PublicRun>(() => `/api/share/${token.value}`)
84const run = computed(() => data.value?.run ?? null)
85const attribution = computed(() => data.value?.attribution ?? null)
86// When THIS shared run is itself a replay, its own "remixed from" credit (issue #89).
87const remixedFrom = computed(() => data.value?.remixedFrom ?? null)
88 
89// Replay (issue #89): seed a fresh run on this run's captured objective, credited back
90// to this sharer, then drop into the briefing. No generation — the objective is reused
91// verbatim; the visitor still commits (and is charged) by pressing Begin.
92const gameStore = useGameStore()
93async function playObjective() {
94    if (!run.value) return
95    gameStore.preseedReplay(run.value.objective, token.value, attribution.value)
96    await navigateTo('/play')
97}
98// The alternative: start from scratch — explicitly an original run, no lineage.
99async function playFresh() {
100    gameStore.clearReplayState()
101    await navigateTo('/play')
102}
103 
⋯ 56 lines hidden (lines 104–159)104// Absolute URLs for the canonical link + the share card. useRequestURL gives the real
105// origin during SSR (what the crawler fetched) and the window origin on the client.
106const reqUrl = useRequestURL()
107const pageUrl = computed(() => `${reqUrl.origin}/r/${token.value}`)
108const cardUrl = computed(() => `${reqUrl.origin}/api/og/${token.value}`)
109 
110const isVictory = computed(() => run.value?.status === 'victory')
111const verdict = computed(() => (isVictory.value ? 'History Rewritten' : 'The Timeline Held'))
112 
113const shareText = computed(() =>
114    run.value
115        ? buildShareText(run.value.objective.title, run.value.status, run.value.objectiveProgress)
116        : 'Revisionist — rewrite history, one message at a time.'
117)
118 
119const colorMode = useColorMode()
120const isDark = computed(() => colorMode.value === 'dark')
121function toggleDark() {
122    colorMode.preference = colorMode.value === 'dark' ? 'light' : 'dark'
123}
124 
125const metaTitle = computed(() => {
126    const r = run.value
127    if (!r) return 'A shared run — Revisionist'
128    return `${r.objective.title}: ${r.objectiveProgress}% rewritten — Revisionist`
129})
130const metaDescription = computed(() => {
131    const r = run.value
132    if (!r) return 'A run of Revisionist — rewrite history, one 160-character message at a time.'
133    const epilogue = r.chronicle?.title
134    return epilogue ? `${verdict.value} · "${epilogue}"` : `${verdict.value} · ${r.objective.title} (${r.objectiveProgress}% rewritten).`
135})
136 
137// Server-rendered unfurl: title/description + an OG/Twitter card pointed at the per-run
138// share image, so a pasted link looks good in X / Discord / iMessage.
139useServerSeoMeta({
140    ogSiteName: 'Revisionist',
141    ogTitle: metaTitle,
142    description: metaDescription,
143    ogDescription: metaDescription,
144    ogType: 'article',
145    ogUrl: pageUrl,
146    ogImage: cardUrl,
147    ogImageWidth: 1200,
148    ogImageHeight: 630,
149    ogImageType: 'image/png',
150    twitterCard: 'summary_large_image',
151    twitterTitle: metaTitle,
152    twitterDescription: metaDescription,
153    twitterImage: cardUrl
154})
155 
156// The browser tab title (server + client nav); kept out of useServerSeoMeta so the two
157// don't both write <title>.
158useHead({ title: metaTitle })
159</script>

The single credit renderer — anonymity + optional backlink in one place.

components/RemixCreditLine.vue · 23 lines

components/RemixCreditLine.vue23 lines · Vue

1<template>
2  <!-- The one-hop "remixed from" credit (issue #89): this run is a replay of another's
3       shared objective. Honors the source's privacy opt-in — a name only when they chose
4       one ("an anonymous run" otherwise), and a backlink only while they're still shared. -->
5  <p data-testid="remix-credit" class="rv-label">
6    <span aria-hidden="true">↻</span> Remixed from
7    <NuxtLink v-if="credit.sourceToken" :to="`/r/${credit.sourceToken}`" data-testid="remix-credit-link"
8      class="rv-accent hover:underline">{{ label }}</NuxtLink>
9    <span v-else>{{ label }}</span>
10  </p>
11</template>
12 
13<script setup lang="ts">
14import { computed } from 'vue'
15import type { RemixCredit } from '~/utils/run-snapshot'
16 
17const props = defineProps<{ credit: RemixCredit }>()
18 
19const who = computed(() => props.credit.attribution || 'an anonymous run')
20const label = computed(() =>
21    props.credit.objectiveTitle ? `${who.value}'s “${props.credit.objectiveTitle}”` : who.value
22)
23</script>