Developer mode — a code-level reading (PR #122)

What changed, and why

Inspecting a stage in this game used to mean playing a real winning run by hand: pick an objective, write five real messages, hope the dice cooperate, and pay for plus wait on four AI layers every turn. This PR adds a dev-only panel that jumps straight to any stage and forces any outcome — driven by the real mechanics, not a faked UI.

The design splits cleanly in two. State jumps mutate the store directly to land on victory, defeat, a populated mid-game, or the stake offer, so the real end screen, Spine, and Chronicle render with no run and no server call. Forced turns fire the real sendMessage pipeline with only the four AI layers replaced by scripted output: the dice bands, anachronism amplifier, causal-chain decay, momentum, the progress clamp, win/lose, and the Chronicle all run for real.

The whole thing is gated so it never reaches players, and it deliberately does not bypass the charged-run paywall. The sections below walk the seam first (where the determinism is injected), then the safety gate, then the two surfaces, and finally how the fixture shape is shared with the e2e tests so the two can't drift.

The fixture lane: one branch at the gateway

Every model call in the game goes through one transport, completeStructured, routed per task. The dev lane adds a single branch at the very top: if a fixture is installed for this task, return its canned JSON and skip the provider entirely. Because it short-circuits before routeFor, the real lanes below are untouched, and the telemetry line still records the call honestly — with no usage, so no cost is ever attributed (the "no spend" guarantee).

The fixture check sits above the real dispatch; no usage → no cost recorded.

server/utils/ai-gateway.ts · 258 lines

server/utils/ai-gateway.ts258 lines · TypeScript

⋯ 148 lines hidden (lines 1–148)1/**
* The AI gateway — one transport for every structured model call, dispatched
* per task by the routing table (ai-routing.ts). Callers keep their own prompts,
* schemas, parsing, guards, and never-throw envelopes; the gateway only decides
* WHICH provider runs the request and HOW (model + parameters), and emits the
* cost telemetry the go-to-market plan's dispatch 1 requires.
*
* Telemetry: every call logs one structured line (task, lane, model, tokens
* in/out, latency, ok) — intentional production output, suppressed under vitest.
* The eval harness subscribes via setAiCallObserver to price bake-off lanes.
*/
12import OpenAI from 'openai'
13import Anthropic from '@anthropic-ai/sdk'
14import { routeFor, type AiTask, type AiLane } from './ai-routing'
15import { currentRunId } from './run-context'
16import { costUsd } from './cost'
17import { spendStore } from './spend-store'
18import { devFixtureFor } from './dev-fixtures'
19 
20let openaiClient: OpenAI | null = null
21let anthropicClient: Anthropic | null = null
22 
23/** Reads a runtime-config key, falling back to raw env outside a Nuxt context
*  (the eval harness exercises these utils directly in node). */
25function configuredKey(name: 'openaiApiKey' | 'anthropicApiKey', envName: string): string | undefined {
  let key: string | undefined
  try {
      key = useRuntimeConfig()[name] as string | undefined
  } catch {
      key = undefined
  }
  return key || process.env[envName]
33}
34 
35export function getOpenAIClient(): OpenAI {
  if (!openaiClient) {
      const apiKey = configuredKey('openaiApiKey', 'OPENAI_API_KEY')
      if (!apiKey) throw new Error('OpenAI API key is not configured')
      openaiClient = new OpenAI({
          apiKey,
          // Fail fast rather than hang on the SDK's 10-minute default if a
          // call stalls (e.g. a bad key or network hiccup).
          timeout: 30_000,
          maxRetries: 1
      })
  }
  return openaiClient
48}
49 
50export function getAnthropicClient(): Anthropic {
  if (!anthropicClient) {
      const apiKey = configuredKey('anthropicApiKey', 'ANTHROPIC_API_KEY')
      if (!apiKey) throw new Error('Anthropic API key is not configured')
      anthropicClient = new Anthropic({
          apiKey,
          // The epilogue's adaptive thinking can run long; everything else is
          // seconds. 60s bounds the worst case without hanging a turn forever.
          timeout: 60_000,
          maxRetries: 1
      })
  }
  return anthropicClient
63}
64 
65export interface AiUsage {
  inputTokens: number
  outputTokens: number
  cacheReadTokens: number
69}
70 
71export interface AiCallTelemetry {
  task: AiTask
  lane: AiLane
  model: string
  ms: number
  ok: boolean
  usage?: AiUsage
  /** The game run this call belongs to (from the request's x-run-id); absent
   *  outside a run-scoped request. The key that groups calls into a run. */
  runId?: string
  /** The call's dollar cost from the rate card; absent when usage is missing
   *  (a failed call) or the model has no listed rate. */
  usd?: number
84}
85 
86type AiCallObserver = (t: AiCallTelemetry) => void
87let observer: AiCallObserver | null = null
88 
89/** The eval harness (and future dashboards) subscribe here; null to clear. */
90export function setAiCallObserver(fn: AiCallObserver | null): void {
  observer = fn
92}
93 
94function emit(t: AiCallTelemetry): void {
  // Enrich once, here, so both the success and failure call sites get the run
  // id, and so the observer (the eval harness) sees the same priced line the
  // log does. usd needs usage, so it rides only on calls that reported tokens.
  const enriched: AiCallTelemetry = {
      ...t,
      runId: t.runId ?? currentRunId(),
      usd: t.usd ?? (t.usage ? costUsd(t.model, t.usage, t.lane) : undefined)
  }
  observer?.(enriched)
  // One greppable line per call — the GTM's "structured log line is enough to
  // start". Intentional production telemetry; quiet under the test runner.
  if (!process.env.VITEST) {
      console.info(`[ai] ${JSON.stringify(enriched)}`)
  }
  // Feed the spend cap: record this call's cost (best-effort, non-blocking).
  // Outside the VITEST guard — unlike the log line, recording must happen under
  // test (so the wiring is exercised) and for eval traffic (which spends real
  // money), not just in production.
  if (enriched.usd) void spendStore().record(enriched.usd)
114}
115 
116export interface ChatTurn {
  role: 'user' | 'assistant'
  content: string
119}
120 
121/**
* Thrown when Claude's own safety classifiers decline a request mid-flight
* (Claude 4 returns stop_reason "refusal"). It is NOT an infra error and NOT an
* empty answer — it's a model-side block, so callers surface it as a moderation
* block, not a "try again" refund. (See Anthropic's streaming-refusals guide.)
*/
127export class ModelRefusalError extends Error {
  constructor() {
      super('The model declined this request (safety refusal).')
      this.name = 'ModelRefusalError'
  }
132}
133 
134export interface StructuredRequest {
  task: AiTask
  /** The built prompt. Single-shot tasks send it as the whole request; with
   *  `turns` it becomes the system prompt over the conversation. */
  system: string
  turns?: ChatTurn[]
  /** OpenAI requires a schema name; Anthropic ignores it. */
  schemaName: string
  schema: Record<string, unknown>
143}
144 
145/**
* Runs one structured completion on the task's routed lane and returns the raw
* JSON text (trimmed), or null on an empty answer. Throws on transport errors —
* callers own their never-throw envelopes, exactly as before the seam.
*/
150export async function completeStructured(req: StructuredRequest): Promise<string | null> {
  // Dev-only deterministic fixtures (issue #105): when the dev panel has scripted
  // this task, return its canned JSON instead of calling a model — every mechanic
  // below the seam still runs for real, but no key is needed and nothing is spent.
  // Inert in production: the registry can only be populated behind the dev gate, so
  // here it is always empty and the real lanes below run untouched. Telemetry still
  // logs one line (lane 'fixture', no usage → no cost recorded).
  const fixture = devFixtureFor(req.task)
  if (fixture !== undefined) {
      emit({ task: req.task, lane: 'fixture', model: 'fixture', ms: 0, ok: true })
      return JSON.stringify(fixture)
  }
162 
  const { lane, route } = routeFor(req.task)
  const model = lane === 'anthropic' ? route.anthropic.model : route.openai.model
  const started = Date.now()
  try {
      const result = lane === 'anthropic' ? await viaAnthropic(req) : await viaOpenAI(req)
⋯ 91 lines hidden (lines 168–258)168        emit({ task: req.task, lane, model, ms: Date.now() - started, ok: true, usage: result.usage })
      return result.content
  } catch (error) {
      emit({ task: req.task, lane, model, ms: Date.now() - started, ok: false })
      throw error
  }
174}
175 
176interface LaneResult {
  content: string | null
  usage?: AiUsage
179}
180 
181async function viaOpenAI(req: StructuredRequest): Promise<LaneResult> {
  const { route } = routeFor(req.task)
  const params = route.openai
  const client = getOpenAIClient()
  const completion = await client.chat.completions.create({
      model: params.model,
      messages: [
          { role: 'system' as const, content: req.system },
          ...(req.turns ?? [])
      ],
      // gpt-5.5 is a reasoning model: omit temperature, keep effort low, leave
      // headroom for hidden reasoning tokens inside the output cap.
      ...(params.reasoningEffort ? { reasoning_effort: params.reasoningEffort } : {}),
      max_completion_tokens: params.maxTokens,
      response_format: {
          type: 'json_schema',
          json_schema: { name: req.schemaName, strict: true, schema: req.schema }
      }
  })
  const usage = completion.usage
      ? {
          inputTokens: completion.usage.prompt_tokens ?? 0,
          outputTokens: completion.usage.completion_tokens ?? 0,
          cacheReadTokens: completion.usage.prompt_tokens_details?.cached_tokens ?? 0
      }
      : undefined
  return { content: completion.choices?.[0]?.message?.content?.trim() || null, usage }
208}
209 
210async function viaAnthropic(req: StructuredRequest): Promise<LaneResult> {
  const { route } = routeFor(req.task)
  const params = route.anthropic
  const client = getAnthropicClient()
214 
  // Anthropic requires the first message to be a user turn. Single-shot tasks
  // send the whole built prompt AS the user message (no system param) — for
  // one-off structured generation the two are equivalent, and it avoids a
  // contentless "Proceed." turn. Conversational tasks keep system + turns.
  const turns = req.turns ?? []
  const system = turns.length ? req.system : undefined
  const messages: Anthropic.MessageParam[] = turns.length
      ? (turns[0].role === 'user' ? turns : [{ role: 'user' as const, content: '(The conversation resumes.)' }, ...turns])
      : [{ role: 'user' as const, content: req.system }]
224 
  const response = await client.messages.create({
      model: params.model,
      max_tokens: params.maxTokens,
      ...(system ? { system } : {}),
      messages,
      // Thinking rejects non-default sampling params — temperature only rides
      // on thinking-off calls (the family rule the routing table can't express).
      ...(params.temperature !== undefined && params.thinking !== 'adaptive' ? { temperature: params.temperature } : {}),
      ...(params.thinking === 'adaptive' ? { thinking: { type: 'adaptive' as const } } : {}),
      output_config: {
          ...(params.effort ? { effort: params.effort } : {}),
          format: { type: 'json_schema' as const, schema: req.schema }
      }
  })
239 
  // Claude's streaming classifiers can decline mid-flight (stop_reason
  // "refusal"); that's a model-side block, surfaced distinctly so callers
  // don't mistake it for an empty/infra response. Cast: the union may predate
  // this SDK's type for the value.
  if ((response.stop_reason as string) === 'refusal') {
      throw new ModelRefusalError()
  }
247 
  // Thinking blocks (epilogue) precede the text block; take the text.
  const text = response.content.find(
      (b): b is Anthropic.TextBlock => b.type === 'text'
  )?.text?.trim()
  const usage: AiUsage = {
      inputTokens: response.usage?.input_tokens ?? 0,
      outputTokens: response.usage?.output_tokens ?? 0,
      cacheReadTokens: response.usage?.cache_read_input_tokens ?? 0
  }
  return { content: text || null, usage }
258}

The lane union gains a 'fixture' member purely so that telemetry line is typed. routeFor never returns it (the routing table is still anthropic/openai only) — the gateway is the only place the fixture lane is ever selected.

server/utils/ai-routing.ts · 182 lines

server/utils/ai-routing.ts182 lines · TypeScript

⋯ 36 lines hidden (lines 1–36)1/**
* The per-task model routing table — the provider seam the go-to-market plan
* calls for (dispatch 1's bake-off lives behind this file). Every AI task names
* its lane and its full parameter payload here, because valid parameter sets
* differ by model family:
*
*   - Haiku 4.5 rejects `effort` and has no adaptive thinking — omit both.
*   - Sonnet 4.6 defaults `effort` to HIGH — always set it explicitly (this game
*     wants reflexes, not deliberation). `temperature` is accepted.
*   - Opus 4.8 rejects `temperature`/`top_p`/`top_k` — steer tone via prompts.
*     Thinking is adaptive-only; omitting `thinking` runs without thinking.
*
* Lane defaults were decided by the two-lane bake-off plus the prompt-tuning
* campaign (evals/bakeoff.eval.ts, evals/prompt-tune.eval.ts; snapshots +
* verdict in evals/results/) — quality-first, with cost a close second. All
* ten tasks run Anthropic: the prose tellings initially lost the blind
* pairwise 19-0 under the shared prompt, and the Claude-voice rewrite
* (buildChroniclePromptClaude) won them back on Sonnet. The OpenAI lane stays
* fully alive behind REVISIONIST_AI_LANE so a forced reverse migration is a
* config change, not a rewrite (the GTM's platform-risk counter).
*/
22 
23export type AiTask =
  | 'judge'
  | 'character'
  | 'timeline'
  | 'chronicler'
  | 'epilogue'
  | 'archivist-study'
  | 'archive-lookup'
  | 'objective'
  | 'objective-check'
  | 'suggester'
  | 'lifespan'
  | 'sentinel'
36 
37/** 'fixture' is the dev-only deterministic lane (issue #105): a scripted structured
*  output, no model call. Never selected by `routeFor` (the table is anthropic/openai
*  only) — the gateway short-circuits to it when a dev fixture is installed, behind
*  the dev gate. It exists in the union so telemetry can label a fixtured call. */
41export type AiLane = 'anthropic' | 'openai' | 'fixture'
⋯ 141 lines hidden (lines 42–182)42 
43export interface AnthropicParams {
  model: string
  maxTokens: number
  /** Omit on Opus-tier models — the API rejects sampling params there. */
  temperature?: number
  /** Omit on Haiku 4.5 — the API rejects the effort parameter there.
   *  'xhigh' exists on Opus 4.7+ and Fable 5 only. */
  effort?: 'low' | 'medium' | 'high' | 'xhigh'
  /** 'adaptive' turns thinking on (billed as output); omitted = no thinking. */
  thinking?: 'adaptive'
53}
54 
55export interface OpenAiParams {
  model: string
  /** gpt-5.5 bills hidden reasoning inside this cap — keep generous headroom. */
  maxTokens: number
  reasoningEffort?: 'low' | 'medium' | 'high'
60}
61 
62export interface TaskRoute {
  lane: AiLane
  anthropic: AnthropicParams
  openai: OpenAiParams
66}
67 
68/** The OpenAI lane's flagship — one place, like the old exported MODEL constant. */
69const GPT = 'gpt-5.5'
70const OPENAI_DEFAULTS: OpenAiParams = { model: GPT, maxTokens: 1200, reasoningEffort: 'low' }
71 
72/**
* With thinking off, Anthropic's max_tokens is TRUE output budget — no hidden
* reasoning billed inside it — so caps are sized to real output shapes instead
* of the old padded 1200.
*/
77export const AI_ROUTES: Record<AiTask, TaskRoute> = {
  // A rubric classifier in the critical path of every dispatch (it runs before
  // the die). Haiku for speed; the calibration eval is its gate.
  judge: {
      lane: 'anthropic',
      anthropic: { model: 'claude-haiku-4-5', maxTokens: 300, temperature: 0 },
      openai: OPENAI_DEFAULTS
  },
  // The player converses with this output every turn — prose is product.
  character: {
      lane: 'anthropic',
      anthropic: { model: 'claude-sonnet-4-6', maxTokens: 700, temperature: 0.9, effort: 'low' },
      openai: OPENAI_DEFAULTS
  },
  // The rules-critical judgment layer; code clamps swings into the rolled band,
  // the model places within band and rates anachronism.
  timeline: {
      lane: 'anthropic',
      anthropic: { model: 'claude-sonnet-4-6', maxTokens: 600, temperature: 0.3, effort: 'medium' },
      openai: OPENAI_DEFAULTS
  },
  // Re-narrates the whole timeline each turn. The original bake-off lost this
  // slot 9-0 under the shared prompt; the Claude-voice rewrite (V2's
  // transmission-chain bar, buildChroniclePromptClaude) won it back 8-5 in
  // blind pairwise on Sonnet at ~1/4 the prior cost-per-telling — and the
  // incumbent lane's quota outage made the flip availability-driven too.
  // Higher-N confirmation pending (evals/results/2026-06-11-verdict.md).
  chronicler: {
      lane: 'anthropic',
      anthropic: { model: 'claude-sonnet-4-6', maxTokens: 2000, temperature: 1, effort: 'high' },
      openai: OPENAI_DEFAULTS
  },
  // The final telling — the share artifact and the thing people pay for. The
  // Claude-voice V1 prompt on SONNET beat the incumbent 16-3 across two
  // dual-graded rounds (7-3, then 9-0 at N=12) — decisively confirmed, and
  // cheaper than the Opus/Fable candidates it outscored. Sonnet over Opus is
  // what the data said, twice; Fable won too but at 4x Sonnet's price for no
  // measured gain over it.
  epilogue: {
      lane: 'anthropic',
      anthropic: { model: 'claude-sonnet-4-6', maxTokens: 2000, temperature: 1, effort: 'high' },
      openai: OPENAI_DEFAULTS
  },
  // Feeds the player's wager calibration — accuracy matters.
  'archivist-study': {
      lane: 'anthropic',
      anthropic: { model: 'claude-sonnet-4-6', maxTokens: 800, temperature: 0.5, effort: 'low' },
      openai: OPENAI_DEFAULTS
  },
  // Factual micro-answers with a known-since stamp.
  'archive-lookup': {
      lane: 'anthropic',
      anthropic: { model: 'claude-haiku-4-5', maxTokens: 500, temperature: 0.3 },
      openai: OPENAI_DEFAULTS
  },
  // 0-1 calls per run; the objective steers every layer's valence.
  objective: {
      lane: 'anthropic',
      anthropic: { model: 'claude-sonnet-4-6', maxTokens: 600, temperature: 1, effort: 'low' },
      openai: OPENAI_DEFAULTS
  },
  // Gates a freshly composed objective on the safely-historical bounds (#71): a
  // cheap, temp-0 classifier (the figure-floor pattern) that catches the
  // living-people / current-events framings a year bound alone can't. Haiku,
  // off the critical generation path — at most twice per composition.
  'objective-check': {
      lane: 'anthropic',
      anthropic: { model: 'claude-haiku-4-5', maxTokens: 200, temperature: 0 },
      openai: OPENAI_DEFAULTS
  },
  // Tool-using agent verified against free grounding, curated floor beneath it.
  // maxTokens here is per ROUND of the agent loop.
  suggester: {
      lane: 'anthropic',
      anthropic: { model: 'claude-haiku-4-5', maxTokens: 1500, temperature: 0.7 },
      openai: { model: GPT, maxTokens: 2500 }
  },
  // A dates classifier with hard validation guards behind it (issue #31 bridge).
  lifespan: {
      lane: 'anthropic',
      anthropic: { model: 'claude-haiku-4-5', maxTokens: 300, temperature: 0 },
      openai: OPENAI_DEFAULTS
  },
  // The safety Sentinel — classifies a whole exchange against the verbatim
  // Usage Policy (server/utils/usage-policy.ts). Haiku at temp 0 for a
  // consistent, cheap classifier, exactly the tier Anthropic's content-
  // moderation guide recommends. Runs once per user action, never on the
  // critical generation path's tokens.
  sentinel: {
      lane: 'anthropic',
      anthropic: { model: 'claude-haiku-4-5', maxTokens: 400, temperature: 0 },
      openai: OPENAI_DEFAULTS
  }
170}
171 
172/**
* Resolves a task to its lane + parameters. REVISIONIST_AI_LANE overrides the
* whole table ('openai' | 'anthropic') — the emergency lever, and how the eval
* matrix runs identical fixtures down each lane.
*/
177export function routeFor(task: AiTask): { lane: AiLane; route: TaskRoute } {
  const route = AI_ROUTES[task]
  const override = process.env.REVISIONIST_AI_LANE
  const lane = override === 'openai' || override === 'anthropic' ? override : route.lane
  return { lane, route }
182}

The registry and the dev gate

What feeds that branch is a tiny process-global registry, set once per forced turn. This mirrors the codebase's existing global-state seams (setAiCallObserver, the REVISIONIST_AI_LANE lever): dev is a single operator, so a per-request store buys nothing, and one set covers both /api/send-message and the separate /api/chronicle request that follows.

devModeEnabled() is the single source of truth for the gate — a dev build, or an explicit staging opt-in. It is the only thing standing between this code and a production player, so it is deliberately strict: the env var must be exactly true.

The gate, then the registry: set behind the gate, read by the gateway and the dice seam.

server/utils/dev-fixtures.ts · 61 lines

server/utils/dev-fixtures.ts61 lines · TypeScript

⋯ 20 lines hidden (lines 1–20)1/**
2 * Developer-mode deterministic AI fixtures (issue #105).
3 *
4 * When dev mode is on, the dev panel scripts the four AI layers (Judge, Character,
5 * Timeline, Chronicler/epilogue) and the die, so a turn runs the ENTIRE real
6 * pipeline below the seam — dice math, swing bands, the anachronism amplifier,
7 * causal-chain decay, momentum, the progress clamp, win/lose, and the living
8 * Chronicle — with no model calls: no keys, no spend.
9 *
10 * The registry is process-global mutable state, like `setAiCallObserver` and the
11 * `REVISIONIST_AI_LANE` lever: dev is a single operator, and the gate keeps it
12 * inert in production. It is populated ONLY through the dev-gated `/api/dev/fixtures`
13 * route (`devModeEnabled()` there), so in a prod build nothing can set it — every
14 * AI call then falls through to the real lane, untouched.
15 *
16 * Crucially this is NOT a paywall bypass: it only fakes generation. A forced turn
17 * still goes through the real `/api/send-message`, which still enforces `runIsActive`
18 * (the charged-run gate), so dev mode never grants a free *real* play.
19 */
20import type { AiTask } from './ai-routing'
21 
22/**
23 * Is dev mode enabled? True in a Nuxt dev build (`import.meta.dev`), or behind an
24 * explicit opt-in for a deployed staging preview (`REVISIONIST_DEV_MODE=true`).
25 * Never true in a normal production build — the single source of truth both the
26 * fixture route and the dice seam gate on.
27 */
28export function devModeEnabled(): boolean {
29    return import.meta.dev || process.env.REVISIONIST_DEV_MODE === 'true'
30}
31 
32interface DevFixtureState {
33    /** The scripted JSON object each AI task returns (the consumer JSON-stringifies). */
34    scripts: Partial<Record<AiTask, unknown>>
⋯ 4 lines hidden (lines 35–38)35    /** The forced natural d20 (1–20) for the turn, or undefined for a real roll. */
36    roll?: number
37}
38 
39let state: DevFixtureState | null = null
40 
41/** Install (or, with null, clear) the active fixture script. Called only by the
42 *  dev-gated route. */
43export function setDevFixtures(next: DevFixtureState | null): void {
44    state = next
45}
46 
47/** The scripted output for a task, or undefined when none is set (→ the task runs
48 *  on its real lane). */
49export function devFixtureFor(task: AiTask): unknown | undefined {
50    return state?.scripts[task]
51}
52 
53/** The forced natural roll for a dev turn, or undefined (→ a real `rollD20()`). */
54export function devForcedRoll(): number | undefined {
55    return state?.roll
56}
57 
58/** Whether any fixture script is currently installed. */
59export function devFixturesActive(): boolean {
60    return state !== null
61}

The dev-gated route

The panel arms a turn by POSTing a TurnFixture here. The handler is the registry's only writer. It hard-gates on devModeEnabled() first — in production this route behaves as if it doesn't exist — then turns the fixture into the four layers' scripted outputs (both prose tasks share the one telling) plus a forced die.

404 unless dev; then install the per-task scripts + the forced roll, or clear.

server/api/dev/fixtures.post.ts · 44 lines

server/api/dev/fixtures.post.ts44 lines · TypeScript

⋯ 15 lines hidden (lines 1–15)1/**
* Dev-only endpoint that arms (or clears) the deterministic AI fixtures for the
* next turn(s) — issue #105. The dev panel POSTs a `TurnFixture`; the server turns
* it into the four AI layers' scripted outputs plus a forced die, so a subsequent
* real `/api/send-message` (and its Chronicle refresh) runs the whole pipeline with
* no model calls.
*
* Hard-gated on `devModeEnabled()`: in a production build this route 404s, so the
* fixture registry can never be populated there. It fakes only AI OUTPUT — the real
* `/api/send-message` still enforces the charged-run paywall — so it is not a
* free-play vector.
*/
13import { setDevFixtures, devModeEnabled } from '~/server/utils/dev-fixtures'
14import { turnFixtureScripts, forcedRollFor, type TurnFixture } from '~/utils/fixtures/turn-fixture'
15 
16export default defineEventHandler(async (event) => {
  // Not even present in production — same posture as a route that doesn't exist.
  if (!devModeEnabled()) {
      throw createError({ statusCode: 404, statusMessage: 'Not Found' })
  }
21 
  const body = await readBody(event)
23 
  // Clear: disarm the fixtures so real AI runs again.
  if (body?.clear === true) {
      setDevFixtures(null)
      return { ok: true, cleared: true }
  }
29 
  const fixture = (body?.fixture ?? {}) as TurnFixture
  const s = turnFixtureScripts(fixture)
  setDevFixtures({
      // Both prose tasks (mid-run + the terminal epilogue) share the one telling.
      scripts: {
          judge: s.judge,
          character: s.character,
          timeline: s.timeline,
          chronicler: s.chronicle,
          epilogue: s.chronicle
      },
      roll: forcedRollFor(fixture)
  })
  return { ok: true }
44})

Forcing the die, inside the real turn

The dice are the one part of a turn that is not behind the AI seam — send-message rolls them directly. So determinism needs a second, equally-gated hook right at the roll. When dev mode is on and a roll is armed, it stands in for rollD20(); the craft modifier still applies on top, and everything after (band selection, the amplifiers, the clamp) is the untouched real path.

A gated forced roll replaces rollD20(); the rest of the turn is unchanged.

server/api/send-message.post.ts · 372 lines

server/api/send-message.post.ts372 lines · TypeScript

⋯ 212 lines hidden (lines 1–212)1import { MAX_MESSAGE_CHARS } from '~/utils/game-config'
2import { toContactMoment, formatContactMoment } from '~/utils/contact-moment'
3import { isContentless } from '~/utils/substance'
4import { nextMomentum, MOMENTUM_MAX } from '~/utils/momentum'
5import {
  cleanArray,
  cleanString,
  clampInt,
  MAX_ERA_CHARS,
  MAX_FIGURE_NAME_CHARS,
  MAX_GROUNDING_CHARS,
  MAX_HISTORY_ENTRIES,
  MAX_LEDGER_DETAIL_CHARS,
  MAX_LEDGER_SWING,
  MAX_OBJECTIVE_DESC_CHARS,
  MAX_OBJECTIVE_TITLE_CHARS,
  MAX_TIMELINE_ENTRIES
18} from '~/server/utils/validate'
19 
20export default defineEventHandler(async (event) => {
  // Only allow POST requests
  if (getMethod(event) !== 'POST') {
      throw createError({
          statusCode: 405,
          statusMessage: 'Method Not Allowed'
      })
  }
28 
  const body = await readBody(event)
30 
  // The client UI bounds these, but a direct POST is untrusted and every field
  // below feeds a gpt-5.5 prompt — so validate the boundary here, not just in the
  // store. (Surfaced by the input-validation-gap loop.)
  if (!body || typeof body.message !== 'string' || !body.message.trim()) {
      throw createError({
          statusCode: 400,
          statusMessage: 'Bad Request: message parameter is required'
      })
  }
  if (body.message.trim().length > MAX_MESSAGE_CHARS) {
      throw createError({
          statusCode: 400,
          statusMessage: `Bad Request: message exceeds ${MAX_MESSAGE_CHARS} characters`
      })
  }
  if (typeof body.figureName !== 'string' || !body.figureName.trim()) {
      throw createError({
          statusCode: 400,
          statusMessage: 'Bad Request: figureName parameter is required'
      })
  }
52 
  const { when = null, figureContext = null, objective = null } = body
  const message = body.message.trim()
  // A name is interpolated into every prompt (and the Wikipedia lookup upstream),
  // so it gets a hard cap like every other prompt-feeding string.
  const figure = cleanString(body.figureName, MAX_FIGURE_NAME_CHARS)
  // The grounded contact year (signed: AD positive / BC negative) — anchors the
  // causal-distance read and the character's world-brief. Optional + untrusted.
  const figureYear = typeof body.whenSigned === 'number' && Number.isFinite(body.whenSigned)
      ? clampInt(body.whenSigned, 12000)
      : undefined
  // The pinned moment (issue #32) arrives as untrusted integers and is
  // re-validated here; the display string the prompts see is DERIVED, never
  // the client's. Sub-year detail is prompt flavor only — every mechanic
  // below (world-brief, liveness, the wager) still computes on figureYear.
  const figureMoment = figureYear !== undefined ? toContactMoment(body.whenMonth, body.whenDay) : null
  const whenLabel = figureYear !== undefined ? formatContactMoment(figureYear, figureMoment) : undefined
  // The last-stand wager: the client offers it only on the final dispatch; the
  // doubling is applied after amplification, and the response echoes it.
  const staked = body.stake === true
  // The run's PRE-turn momentum (0..4), client-authoritative between turns (no
  // server run-state today). The server reads it to compute the gains factor and
  // returns the advanced value; untrusted, so coerce + clamp to the meter (#62).
  const momentum = Math.max(0, Math.min(MOMENTUM_MAX, Math.floor(Number(body.momentum) || 0)))
76 
  // Normalize the objective into the context the Timeline Engine needs (coerced +
  // bounded — a non-string or megabyte field would otherwise reach the prompt raw).
  const objectiveContext = {
      title: cleanString(objective?.title, MAX_OBJECTIVE_TITLE_CHARS) || 'Alter the course of history',
      description: cleanString(objective?.description, MAX_OBJECTIVE_DESC_CHARS) || 'Bend the chain of events toward a better world.',
      era: cleanString(objective?.era, MAX_ERA_CHARS)
  }
  // The objective's far anchor year (signed: AD+/BC−) — the foothold the
  // causal-chain dial decays toward. Optional + untrusted; absent → no-op.
  const objectiveAnchorYear = typeof objective?.anchorYear === 'number' && Number.isFinite(objective.anchorYear)
      ? clampInt(objective.anchorYear, 12000)
      : undefined
89 
  // Sanitize the client-supplied ledger + thread: cap the counts and coerce each
  // field, so a crafted body can't crash a `.map`, forge an unbounded prior
  // history, or amplify token cost.
  const timeline = cleanArray(body.timeline, MAX_TIMELINE_ENTRIES).map((raw) => {
      const e = (raw ?? {}) as Record<string, unknown>
      return {
          era: cleanString(e.era, MAX_ERA_CHARS),
          headline: cleanString(e.headline, MAX_OBJECTIVE_TITLE_CHARS),
          detail: cleanString(e.detail, MAX_LEDGER_DETAIL_CHARS),
          progressChange: clampInt(e.progressChange, MAX_LEDGER_SWING),
          whenSigned: typeof e.whenSigned === 'number' && Number.isFinite(e.whenSigned)
              ? clampInt(e.whenSigned, 12000)
              : undefined
      }
  })
  const conversationHistory = cleanArray(body.conversationHistory, MAX_HISTORY_ENTRIES)
      .map((raw) => (raw ?? {}) as Record<string, unknown>)
      .filter((m) => (m.sender === 'user' || m.sender === 'ai') && typeof m.text === 'string')
      .map((m) => ({ sender: m.sender as 'user' | 'ai', text: cleanString(m.text, MAX_MESSAGE_CHARS) }))
109 
  try {
      // Paywall enforcement: the run must be charged and owned by this device,
      // or a forged / unpaid run id could draw free generation. Fails open if
      // the balance store is unreachable (see run-guard) so an outage never
      // blocks a legit in-progress run.
      const { runIsActive } = await import('~/server/utils/run-guard')
      if (!(await runIsActive(event))) {
          return {
              success: false as const,
              message: 'Run not active',
              data: { userMessage: message, error: 'This run is no longer active. Start a new run to continue.' }
          }
      }
123 
      const { callCharacterAI, callTimelineAI, callJudgeAI } = await import('~/server/utils/openai')
      const { rollD20, applyCraftModifier, categorizeRoll } = await import('~/utils/dice')
      const { CRAFT_MODIFIER } = await import('~/utils/craft')
      const { devModeEnabled, devForcedRoll } = await import('~/server/utils/dev-fixtures')
      const { hardBlockCheck, moderateAction } = await import('~/server/utils/moderation')
129 
      // A blocked turn never burns a message: success:false + data.blocked lets
      // the store show a distinct, honest "blocked" banner (not an infra retry).
      const blockedResponse = (reason: string) => ({
          success: false as const,
          message: 'Blocked by moderation',
          data: { userMessage: message, blocked: true as const, moderationReason: reason, error: reason }
      })
137 
      // Moderation, stage 1 — a deterministic hard block on the raw dispatch
      // BEFORE we spend a generation token. The unforgivable categories (sexual
      // content, anything involving minors, self-harm facilitation) need no
      // context; the contextual Sentinel runs post-generation over the exchange.
      const inputBlock = await hardBlockCheck(message, 'turn', 'input')
      if (inputBlock.blocked) return blockedResponse(inputBlock.block.reason)
144 
      // Contact gating, enforced authoritatively here (#72 deceased-only + #73
      // require-grounding): the client payload is untrusted, and a direct POST (or
      // a send racing the grounding debounce) could otherwise reach a living or
      // ungrounded figure. Re-ground the name ourselves — cache-backed in the warm
      // path (the same in-process cache /api/figure just filled), one bounded
      // external lookup on a cold cache — and:
      //   • resolved + not deceased → block (living, or undatable: fail closed)
      //   • unresolved + transient  → retry (a lookup we couldn't complete)
      //   • unresolved + definitive → block (#73: no free-form; reach a real figure)
      // This gate enforces existence + liveness (the safety floor); a deceased
      // figure's lifetime window is a client-side UX nicety (anachronism is
      // mechanically allowed via the wager), so it is deliberately not re-checked here.
      const { groundFigure, isDeceased } = await import('~/server/utils/figure-grounding')
      const grounded = await groundFigure(figure)
      if (grounded.resolved && !isDeceased(grounded)) {
          return blockedResponse('This figure is still living and cannot be contacted — Revisionist only reaches figures from history.')
      }
      if (!grounded.resolved) {
          return grounded.transient
              ? {
                  success: false as const,
                  message: 'Could not verify the figure',
                  data: { userMessage: message, error: "Couldn't reach the record to verify who this is — please try again in a moment." }
              }
              : blockedResponse('No historical record found for this name — reach for a real, documented figure.')
      }
171 
      // The client supplies figureContext (it grounded the figure via /api/figure),
      // so treat it as untrusted: coerce + bound each field before it becomes a
      // "fact" in the character system prompt.
      const grounding = {
          when: whenLabel ?? (cleanString(when, MAX_ERA_CHARS) || undefined),
          // The figure should take a pinned moment with period-appropriate
          // granularity rather than false precision (the prompt line is
          // conditional so year-only turns stay byte-identical).
          momentRefined: figureMoment !== null,
          description: cleanString(figureContext?.description, MAX_GROUNDING_CHARS) || undefined,
          lifespan: cleanString(figureContext?.lifespan, MAX_ERA_CHARS) || undefined
      }
184 
      // The Judge also reads the run's thread — the figure's last reply (their last
      // revealed condition/price) and a digest of recent ledger headlines — to grade
      // CONTINUITY: does this dispatch build on what came before? Both are empty on
      // turn 1, so the Judge prompt stays byte-identical there.
      const lastFigureReply = [...conversationHistory].reverse().find(m => m.sender === 'ai')?.text ?? ''
      const ledgerDigest = timeline
          .filter(e => e.headline)
          .slice(-5)
          .map(e => `${e.era ? `[${e.era}] ` : ''}${e.headline}`)
194 
      // Step 1: The Judge grades the dispatch's craft — the one place player skill
      // directly tilts fate. A Judge outage grades 'sound' (modifier 0): an infra
      // hiccup must never tilt the die either way.
      const judged = await callJudgeAI({
          objective: objectiveContext,
          figureName: figure,
          when: grounding.when,
          momentRefined: figureMoment !== null,
          userMessage: message,
          lastFigureReply,
          ledgerDigest
      })
      const craft = judged.success && judged.judge ? judged.judge.craft : 'sound'
      const craftReason = judged.success && judged.judge ? judged.judge.reason : ''
      // Continuity feeds the run-level momentum meter (slice 3); an outage → 'neutral'.
      const continuity = judged.success && judged.judge ? judged.judge.continuity : 'neutral'
      const rollModifier = CRAFT_MODIFIER[craft]
212 
      // Step 2: Roll the dice of fate, tilted by craft (clamped to the die's faces).
      // Dev mode (issue #105) can force the natural die so a forced turn lands a
      // chosen band deterministically; the craft modifier still applies on top, and
      // the gate keeps this a real `rollD20()` in production.
      const forcedRoll = devModeEnabled() ? devForcedRoll() : undefined
      const natural = forcedRoll !== undefined
          ? { roll: forcedRoll, outcome: categorizeRoll(forcedRoll) }
          : rollD20()
      const diceResult = applyCraftModifier(natural.roll, rollModifier)
222 
      // Step 3: The chosen figure replies and acts, in character, blind to the goal.
⋯ 149 lines hidden (lines 224–372)224        // Grounding (when + real facts) anchors the role-play; the world-brief hands
      // them the altered history their own moment would already know (changes at or
      // before their year), so a turn-4 figure doesn't role-play the unaltered world.
      // Headlines only — `detail` narrates downstream ripples (often stamped with
      // later eras) and would hand the figure the future outright.
      const worldBrief = figureYear === undefined
          ? []
          : timeline
              .filter(e => typeof e.whenSigned === 'number' && e.whenSigned <= figureYear && e.headline)
              .slice(-5)
              .map(e => `${e.era ? `[${e.era}] ` : ''}${e.headline}`)
      // Keep the figure honest: a contentless dispatch gives them nothing to act
      // on, so even a favorable roll yields confusion, not a fabricated deed (#62).
      const contentless = isContentless(message)
      const character = await callCharacterAI(figure, message, conversationHistory, diceResult.outcome, grounding, worldBrief, contentless)
      if (!character.success || !character.characterResponse) {
          // A model-side safety refusal is a block, not an infra hiccup.
          if (character.refused) return blockedResponse(character.error || 'This dispatch was declined by content moderation and cannot be sent.')
          return {
              success: false,
              message: 'Failed to generate character response',
              data: {
                  userMessage: message,
                  error: character.error || 'Character AI failed'
              }
          }
      }
251 
      const reply = character.characterResponse
253 
      // Enforce the message-length constraint on the figure's reply.
      if (reply.message && reply.message.length > MAX_MESSAGE_CHARS) {
          console.warn(`Figure reply exceeded ${MAX_MESSAGE_CHARS} characters (${reply.message.length}); truncating.`)
          reply.message = reply.message.substring(0, MAX_MESSAGE_CHARS - 3) + '...'
      }
259 
      // Step 4: The Timeline Engine judges how the action ripples toward the objective.
      const timelineResult = await callTimelineAI({
          objective: objectiveContext,
          figureName: figure,
          era: reply.era || objectiveContext.era,
          userMessage: message,
          characterMessage: reply.message,
          characterAction: reply.action,
          diceRoll: diceResult.roll,
          diceOutcome: diceResult.outcome,
          timeline,
          figureYear,
          figureMoment: figureMoment ? whenLabel : undefined,
          objectiveAnchorYear,
          craft,
          momentum
      })
277 
      if (!timelineResult.success || !timelineResult.ripple) {
          if (timelineResult.refused) return blockedResponse(timelineResult.error || 'This dispatch was declined by content moderation and cannot be sent.')
          return {
              success: false,
              message: 'Failed to generate timeline analysis',
              data: {
                  userMessage: message,
                  diceRoll: diceResult.roll,
                  diceOutcome: diceResult.outcome,
                  characterResponse: { message: reply.message, action: reply.action },
                  error: timelineResult.error || 'Timeline AI failed'
              }
          }
      }
292 
      const ripple = timelineResult.ripple
294 
      // Moderation, stage 2 — the contextual Sentinel reviews the WHOLE exchange
      // (full thread + this dispatch + the figure's reply and the timeline's
      // narration) against the verbatim Usage Policy, and the detector hard-blocks
      // the outputs. A block here suppresses the reveal: the generated text never
      // ships, and the turn is refunded with an honest banner.
      const moderation = await moderateAction({
          surface: 'turn',
          objective: { title: objectiveContext.title, description: objectiveContext.description },
          figureName: figure,
          era: reply.era || objectiveContext.era,
          conversation: conversationHistory.map(m => ({ role: m.sender === 'user' ? 'user' : 'assistant', text: m.text })),
          userText: message,
          outputs: [reply.message, reply.action, ripple.headline, ripple.detail].filter((t): t is string => !!t)
      })
      if (moderation.blocked) return blockedResponse(moderation.block.reason)
310 
      // The last stand: a staked dispatch doubles its resolved swing, both ways,
      // and may escape the per-turn fuse up to the full meter. The valence badge
      // is re-asserted AFTER the doubling — the sign-guard inside callTimelineAI
      // ran on the pre-stake value, and a doubled swing must wear its own color.
      const { applyStake, VALENCE_SIGN_GUARD_MIN } = await import('~/utils/swing-bands')
      const finalProgressChange = staked ? applyStake(ripple.progressChange) : ripple.progressChange
      const finalValence = staked && Math.abs(finalProgressChange) > VALENCE_SIGN_GUARD_MIN
          ? (finalProgressChange > 0 ? 'positive' as const : 'negative' as const)
          : ripple.valence
320 
      // Advance the run-level momentum meter from this turn's continuity + roll; the
      // client overwrites its meter from this on ingest (issue #62).
      const nextM = nextMomentum(momentum, continuity, diceResult.outcome)
324 
      return {
          success: true,
          message: 'Timeline updated',
          data: {
              userMessage: message,
              figure: {
                  name: figure,
                  era: reply.era,
                  descriptor: reply.persona
              },
              // The effective (craft-tilted) roll drives the bands and the UI; the
              // natural roll + modifier ride along so the reveal can show the tilt.
              diceRoll: diceResult.roll,
              diceOutcome: diceResult.outcome,
              naturalRoll: natural.roll,
              rollModifier,
              craft,
              craftReason,
              continuity,
              momentum: nextM,
              staked,
              characterResponse: { message: reply.message, action: reply.action },
              timeline: {
                  headline: ripple.headline,
                  detail: ripple.detail,
                  era: reply.era || objectiveContext.era,
                  progressChange: finalProgressChange,
                  baseProgressChange: ripple.baseProgressChange,
                  // The PRE-turn momentum that amplified this swing — for the
                  // reveal's equation (distinct from data.momentum, the new meter).
                  momentumAtSwing: momentum,
                  valence: finalValence,
                  anachronism: ripple.anachronism,
                  causalChain: ripple.causalChain
              },
              error: null
          }
      }
  } catch (error) {
      // Log the detail server-side; the wire gets a clean line (internal error
      // text — stack hints, key issues, SDK messages — is not for the client).
      console.error('API endpoint error:', error)
      throw createError({
          statusCode: 500,
          statusMessage: 'Internal Server Error'
      })
  }
372})

The gate is read here too, not just at the route, so even a populated registry can never force a roll in a prod build. The dependency is lazily imported alongside the turn's other server utils.

server/api/send-message.post.ts · 372 lines

server/api/send-message.post.ts372 lines · TypeScript

⋯ 123 lines hidden (lines 1–123)1import { MAX_MESSAGE_CHARS } from '~/utils/game-config'
2import { toContactMoment, formatContactMoment } from '~/utils/contact-moment'
3import { isContentless } from '~/utils/substance'
4import { nextMomentum, MOMENTUM_MAX } from '~/utils/momentum'
5import {
  cleanArray,
  cleanString,
  clampInt,
  MAX_ERA_CHARS,
  MAX_FIGURE_NAME_CHARS,
  MAX_GROUNDING_CHARS,
  MAX_HISTORY_ENTRIES,
  MAX_LEDGER_DETAIL_CHARS,
  MAX_LEDGER_SWING,
  MAX_OBJECTIVE_DESC_CHARS,
  MAX_OBJECTIVE_TITLE_CHARS,
  MAX_TIMELINE_ENTRIES
18} from '~/server/utils/validate'
19 
20export default defineEventHandler(async (event) => {
  // Only allow POST requests
  if (getMethod(event) !== 'POST') {
      throw createError({
          statusCode: 405,
          statusMessage: 'Method Not Allowed'
      })
  }
28 
  const body = await readBody(event)
30 
  // The client UI bounds these, but a direct POST is untrusted and every field
  // below feeds a gpt-5.5 prompt — so validate the boundary here, not just in the
  // store. (Surfaced by the input-validation-gap loop.)
  if (!body || typeof body.message !== 'string' || !body.message.trim()) {
      throw createError({
          statusCode: 400,
          statusMessage: 'Bad Request: message parameter is required'
      })
  }
  if (body.message.trim().length > MAX_MESSAGE_CHARS) {
      throw createError({
          statusCode: 400,
          statusMessage: `Bad Request: message exceeds ${MAX_MESSAGE_CHARS} characters`
      })
  }
  if (typeof body.figureName !== 'string' || !body.figureName.trim()) {
      throw createError({
          statusCode: 400,
          statusMessage: 'Bad Request: figureName parameter is required'
      })
  }
52 
  const { when = null, figureContext = null, objective = null } = body
  const message = body.message.trim()
  // A name is interpolated into every prompt (and the Wikipedia lookup upstream),
  // so it gets a hard cap like every other prompt-feeding string.
  const figure = cleanString(body.figureName, MAX_FIGURE_NAME_CHARS)
  // The grounded contact year (signed: AD positive / BC negative) — anchors the
  // causal-distance read and the character's world-brief. Optional + untrusted.
  const figureYear = typeof body.whenSigned === 'number' && Number.isFinite(body.whenSigned)
      ? clampInt(body.whenSigned, 12000)
      : undefined
  // The pinned moment (issue #32) arrives as untrusted integers and is
  // re-validated here; the display string the prompts see is DERIVED, never
  // the client's. Sub-year detail is prompt flavor only — every mechanic
  // below (world-brief, liveness, the wager) still computes on figureYear.
  const figureMoment = figureYear !== undefined ? toContactMoment(body.whenMonth, body.whenDay) : null
  const whenLabel = figureYear !== undefined ? formatContactMoment(figureYear, figureMoment) : undefined
  // The last-stand wager: the client offers it only on the final dispatch; the
  // doubling is applied after amplification, and the response echoes it.
  const staked = body.stake === true
  // The run's PRE-turn momentum (0..4), client-authoritative between turns (no
  // server run-state today). The server reads it to compute the gains factor and
  // returns the advanced value; untrusted, so coerce + clamp to the meter (#62).
  const momentum = Math.max(0, Math.min(MOMENTUM_MAX, Math.floor(Number(body.momentum) || 0)))
76 
  // Normalize the objective into the context the Timeline Engine needs (coerced +
  // bounded — a non-string or megabyte field would otherwise reach the prompt raw).
  const objectiveContext = {
      title: cleanString(objective?.title, MAX_OBJECTIVE_TITLE_CHARS) || 'Alter the course of history',
      description: cleanString(objective?.description, MAX_OBJECTIVE_DESC_CHARS) || 'Bend the chain of events toward a better world.',
      era: cleanString(objective?.era, MAX_ERA_CHARS)
  }
  // The objective's far anchor year (signed: AD+/BC−) — the foothold the
  // causal-chain dial decays toward. Optional + untrusted; absent → no-op.
  const objectiveAnchorYear = typeof objective?.anchorYear === 'number' && Number.isFinite(objective.anchorYear)
      ? clampInt(objective.anchorYear, 12000)
      : undefined
89 
  // Sanitize the client-supplied ledger + thread: cap the counts and coerce each
  // field, so a crafted body can't crash a `.map`, forge an unbounded prior
  // history, or amplify token cost.
  const timeline = cleanArray(body.timeline, MAX_TIMELINE_ENTRIES).map((raw) => {
      const e = (raw ?? {}) as Record<string, unknown>
      return {
          era: cleanString(e.era, MAX_ERA_CHARS),
          headline: cleanString(e.headline, MAX_OBJECTIVE_TITLE_CHARS),
          detail: cleanString(e.detail, MAX_LEDGER_DETAIL_CHARS),
          progressChange: clampInt(e.progressChange, MAX_LEDGER_SWING),
          whenSigned: typeof e.whenSigned === 'number' && Number.isFinite(e.whenSigned)
              ? clampInt(e.whenSigned, 12000)
              : undefined
      }
  })
  const conversationHistory = cleanArray(body.conversationHistory, MAX_HISTORY_ENTRIES)
      .map((raw) => (raw ?? {}) as Record<string, unknown>)
      .filter((m) => (m.sender === 'user' || m.sender === 'ai') && typeof m.text === 'string')
      .map((m) => ({ sender: m.sender as 'user' | 'ai', text: cleanString(m.text, MAX_MESSAGE_CHARS) }))
109 
  try {
      // Paywall enforcement: the run must be charged and owned by this device,
      // or a forged / unpaid run id could draw free generation. Fails open if
      // the balance store is unreachable (see run-guard) so an outage never
      // blocks a legit in-progress run.
      const { runIsActive } = await import('~/server/utils/run-guard')
      if (!(await runIsActive(event))) {
          return {
              success: false as const,
              message: 'Run not active',
              data: { userMessage: message, error: 'This run is no longer active. Start a new run to continue.' }
          }
      }
123 
      const { callCharacterAI, callTimelineAI, callJudgeAI } = await import('~/server/utils/openai')
      const { rollD20, applyCraftModifier, categorizeRoll } = await import('~/utils/dice')
      const { CRAFT_MODIFIER } = await import('~/utils/craft')
      const { devModeEnabled, devForcedRoll } = await import('~/server/utils/dev-fixtures')
⋯ 245 lines hidden (lines 128–372)128        const { hardBlockCheck, moderateAction } = await import('~/server/utils/moderation')
129 
      // A blocked turn never burns a message: success:false + data.blocked lets
      // the store show a distinct, honest "blocked" banner (not an infra retry).
      const blockedResponse = (reason: string) => ({
          success: false as const,
          message: 'Blocked by moderation',
          data: { userMessage: message, blocked: true as const, moderationReason: reason, error: reason }
      })
137 
      // Moderation, stage 1 — a deterministic hard block on the raw dispatch
      // BEFORE we spend a generation token. The unforgivable categories (sexual
      // content, anything involving minors, self-harm facilitation) need no
      // context; the contextual Sentinel runs post-generation over the exchange.
      const inputBlock = await hardBlockCheck(message, 'turn', 'input')
      if (inputBlock.blocked) return blockedResponse(inputBlock.block.reason)
144 
      // Contact gating, enforced authoritatively here (#72 deceased-only + #73
      // require-grounding): the client payload is untrusted, and a direct POST (or
      // a send racing the grounding debounce) could otherwise reach a living or
      // ungrounded figure. Re-ground the name ourselves — cache-backed in the warm
      // path (the same in-process cache /api/figure just filled), one bounded
      // external lookup on a cold cache — and:
      //   • resolved + not deceased → block (living, or undatable: fail closed)
      //   • unresolved + transient  → retry (a lookup we couldn't complete)
      //   • unresolved + definitive → block (#73: no free-form; reach a real figure)
      // This gate enforces existence + liveness (the safety floor); a deceased
      // figure's lifetime window is a client-side UX nicety (anachronism is
      // mechanically allowed via the wager), so it is deliberately not re-checked here.
      const { groundFigure, isDeceased } = await import('~/server/utils/figure-grounding')
      const grounded = await groundFigure(figure)
      if (grounded.resolved && !isDeceased(grounded)) {
          return blockedResponse('This figure is still living and cannot be contacted — Revisionist only reaches figures from history.')
      }
      if (!grounded.resolved) {
          return grounded.transient
              ? {
                  success: false as const,
                  message: 'Could not verify the figure',
                  data: { userMessage: message, error: "Couldn't reach the record to verify who this is — please try again in a moment." }
              }
              : blockedResponse('No historical record found for this name — reach for a real, documented figure.')
      }
171 
      // The client supplies figureContext (it grounded the figure via /api/figure),
      // so treat it as untrusted: coerce + bound each field before it becomes a
      // "fact" in the character system prompt.
      const grounding = {
          when: whenLabel ?? (cleanString(when, MAX_ERA_CHARS) || undefined),
          // The figure should take a pinned moment with period-appropriate
          // granularity rather than false precision (the prompt line is
          // conditional so year-only turns stay byte-identical).
          momentRefined: figureMoment !== null,
          description: cleanString(figureContext?.description, MAX_GROUNDING_CHARS) || undefined,
          lifespan: cleanString(figureContext?.lifespan, MAX_ERA_CHARS) || undefined
      }
184 
      // The Judge also reads the run's thread — the figure's last reply (their last
      // revealed condition/price) and a digest of recent ledger headlines — to grade
      // CONTINUITY: does this dispatch build on what came before? Both are empty on
      // turn 1, so the Judge prompt stays byte-identical there.
      const lastFigureReply = [...conversationHistory].reverse().find(m => m.sender === 'ai')?.text ?? ''
      const ledgerDigest = timeline
          .filter(e => e.headline)
          .slice(-5)
          .map(e => `${e.era ? `[${e.era}] ` : ''}${e.headline}`)
194 
      // Step 1: The Judge grades the dispatch's craft — the one place player skill
      // directly tilts fate. A Judge outage grades 'sound' (modifier 0): an infra
      // hiccup must never tilt the die either way.
      const judged = await callJudgeAI({
          objective: objectiveContext,
          figureName: figure,
          when: grounding.when,
          momentRefined: figureMoment !== null,
          userMessage: message,
          lastFigureReply,
          ledgerDigest
      })
      const craft = judged.success && judged.judge ? judged.judge.craft : 'sound'
      const craftReason = judged.success && judged.judge ? judged.judge.reason : ''
      // Continuity feeds the run-level momentum meter (slice 3); an outage → 'neutral'.
      const continuity = judged.success && judged.judge ? judged.judge.continuity : 'neutral'
      const rollModifier = CRAFT_MODIFIER[craft]
212 
      // Step 2: Roll the dice of fate, tilted by craft (clamped to the die's faces).
      // Dev mode (issue #105) can force the natural die so a forced turn lands a
      // chosen band deterministically; the craft modifier still applies on top, and
      // the gate keeps this a real `rollD20()` in production.
      const forcedRoll = devModeEnabled() ? devForcedRoll() : undefined
      const natural = forcedRoll !== undefined
          ? { roll: forcedRoll, outcome: categorizeRoll(forcedRoll) }
          : rollD20()
      const diceResult = applyCraftModifier(natural.roll, rollModifier)
222 
      // Step 3: The chosen figure replies and acts, in character, blind to the goal.
      // Grounding (when + real facts) anchors the role-play; the world-brief hands
      // them the altered history their own moment would already know (changes at or
      // before their year), so a turn-4 figure doesn't role-play the unaltered world.
      // Headlines only — `detail` narrates downstream ripples (often stamped with
      // later eras) and would hand the figure the future outright.
      const worldBrief = figureYear === undefined
          ? []
          : timeline
              .filter(e => typeof e.whenSigned === 'number' && e.whenSigned <= figureYear && e.headline)
              .slice(-5)
              .map(e => `${e.era ? `[${e.era}] ` : ''}${e.headline}`)
      // Keep the figure honest: a contentless dispatch gives them nothing to act
      // on, so even a favorable roll yields confusion, not a fabricated deed (#62).
      const contentless = isContentless(message)
      const character = await callCharacterAI(figure, message, conversationHistory, diceResult.outcome, grounding, worldBrief, contentless)
      if (!character.success || !character.characterResponse) {
          // A model-side safety refusal is a block, not an infra hiccup.
          if (character.refused) return blockedResponse(character.error || 'This dispatch was declined by content moderation and cannot be sent.')
          return {
              success: false,
              message: 'Failed to generate character response',
              data: {
                  userMessage: message,
                  error: character.error || 'Character AI failed'
              }
          }
      }
251 
      const reply = character.characterResponse
253 
      // Enforce the message-length constraint on the figure's reply.
      if (reply.message && reply.message.length > MAX_MESSAGE_CHARS) {
          console.warn(`Figure reply exceeded ${MAX_MESSAGE_CHARS} characters (${reply.message.length}); truncating.`)
          reply.message = reply.message.substring(0, MAX_MESSAGE_CHARS - 3) + '...'
      }
259 
      // Step 4: The Timeline Engine judges how the action ripples toward the objective.
      const timelineResult = await callTimelineAI({
          objective: objectiveContext,
          figureName: figure,
          era: reply.era || objectiveContext.era,
          userMessage: message,
          characterMessage: reply.message,
          characterAction: reply.action,
          diceRoll: diceResult.roll,
          diceOutcome: diceResult.outcome,
          timeline,
          figureYear,
          figureMoment: figureMoment ? whenLabel : undefined,
          objectiveAnchorYear,
          craft,
          momentum
      })
277 
      if (!timelineResult.success || !timelineResult.ripple) {
          if (timelineResult.refused) return blockedResponse(timelineResult.error || 'This dispatch was declined by content moderation and cannot be sent.')
          return {
              success: false,
              message: 'Failed to generate timeline analysis',
              data: {
                  userMessage: message,
                  diceRoll: diceResult.roll,
                  diceOutcome: diceResult.outcome,
                  characterResponse: { message: reply.message, action: reply.action },
                  error: timelineResult.error || 'Timeline AI failed'
              }
          }
      }
292 
      const ripple = timelineResult.ripple
294 
      // Moderation, stage 2 — the contextual Sentinel reviews the WHOLE exchange
      // (full thread + this dispatch + the figure's reply and the timeline's
      // narration) against the verbatim Usage Policy, and the detector hard-blocks
      // the outputs. A block here suppresses the reveal: the generated text never
      // ships, and the turn is refunded with an honest banner.
      const moderation = await moderateAction({
          surface: 'turn',
          objective: { title: objectiveContext.title, description: objectiveContext.description },
          figureName: figure,
          era: reply.era || objectiveContext.era,
          conversation: conversationHistory.map(m => ({ role: m.sender === 'user' ? 'user' : 'assistant', text: m.text })),
          userText: message,
          outputs: [reply.message, reply.action, ripple.headline, ripple.detail].filter((t): t is string => !!t)
      })
      if (moderation.blocked) return blockedResponse(moderation.block.reason)
310 
      // The last stand: a staked dispatch doubles its resolved swing, both ways,
      // and may escape the per-turn fuse up to the full meter. The valence badge
      // is re-asserted AFTER the doubling — the sign-guard inside callTimelineAI
      // ran on the pre-stake value, and a doubled swing must wear its own color.
      const { applyStake, VALENCE_SIGN_GUARD_MIN } = await import('~/utils/swing-bands')
      const finalProgressChange = staked ? applyStake(ripple.progressChange) : ripple.progressChange
      const finalValence = staked && Math.abs(finalProgressChange) > VALENCE_SIGN_GUARD_MIN
          ? (finalProgressChange > 0 ? 'positive' as const : 'negative' as const)
          : ripple.valence
320 
      // Advance the run-level momentum meter from this turn's continuity + roll; the
      // client overwrites its meter from this on ingest (issue #62).
      const nextM = nextMomentum(momentum, continuity, diceResult.outcome)
324 
      return {
          success: true,
          message: 'Timeline updated',
          data: {
              userMessage: message,
              figure: {
                  name: figure,
                  era: reply.era,
                  descriptor: reply.persona
              },
              // The effective (craft-tilted) roll drives the bands and the UI; the
              // natural roll + modifier ride along so the reveal can show the tilt.
              diceRoll: diceResult.roll,
              diceOutcome: diceResult.outcome,
              naturalRoll: natural.roll,
              rollModifier,
              craft,
              craftReason,
              continuity,
              momentum: nextM,
              staked,
              characterResponse: { message: reply.message, action: reply.action },
              timeline: {
                  headline: ripple.headline,
                  detail: ripple.detail,
                  era: reply.era || objectiveContext.era,
                  progressChange: finalProgressChange,
                  baseProgressChange: ripple.baseProgressChange,
                  // The PRE-turn momentum that amplified this swing — for the
                  // reveal's equation (distinct from data.momentum, the new meter).
                  momentumAtSwing: momentum,
                  valence: finalValence,
                  anachronism: ripple.anachronism,
                  causalChain: ripple.causalChain
              },
              error: null
          }
      }
  } catch (error) {
      // Log the detail server-side; the wire gets a clean line (internal error
      // text — stack hints, key issues, SDK messages — is not for the client).
      console.error('API endpoint error:', error)
      throw createError({
          statusCode: 500,
          statusMessage: 'Internal Server Error'
      })
  }
372})

The shared fixture shape

One description of a scripted turn feeds two seams that must agree: the dev lane (which turns it into per-task AI outputs) and the e2e route-mock harness (which turns it into a /api/send-message wire response). TurnFixture is that one shape — pure, type-only dependencies, so it imports safely from client, server, and the Playwright transform alike. Every field is optional; a bare {} is a sensible "sound success".

The knob type: figure, judge, dice, timeline, chronicle — overlapping fields drive both seams.

utils/fixtures/turn-fixture.ts · 138 lines

utils/fixtures/turn-fixture.ts138 lines · TypeScript

⋯ 32 lines hidden (lines 1–32)1/**
* The shared turn-fixture shape (issue #105 — developer mode).
*
* One pure description of a scripted turn, read by two seams that must never drift:
*
*   - The dev-mode fixture AI lane (`server/utils/dev-fixtures.ts`), which turns this
*     into the per-task structured outputs the four AI layers would have generated —
*     so a forced turn runs the REAL pipeline (dice, swing bands, anachronism, causal
*     chain, momentum, the progress clamp, win/lose, the Chronicle) with no model
*     calls: no keys, no spend.
*   - The e2e route-mock harness (`tests/e2e/support/game.ts`), which turns the same
*     fields into a `/api/send-message` wire response.
*
* Pure + dependency-light on purpose: only type imports (all erased at build), so it
* is safe to import from the client bundle, the server, and the Playwright transform
* alike. Every field is optional; a bare `{}` yields a sensible "sound success" turn.
*/
18import type { Craft } from '~/utils/craft'
19import type { Continuity } from '~/utils/continuity'
20import type { Anachronism } from '~/server/utils/anachronism'
21 
22/** Timeline valence — the same closed set the Timeline Engine returns. Inlined to
*  keep this module free of a store/server runtime dependency. */
24export type Valence = 'positive' | 'negative' | 'neutral'
25 
26/**
* A scripted turn. The dev lane reads the AI-seam fields (craft, continuity, the
* figure reply, the ripple, the chronicle) and the forced roll; the e2e harness
* reads the wire fields (diceRoll, diceOutcome, …). Overlapping fields (figureName,
* era, headline, detail, progressChange, valence, anachronism, craft, staked) mean
* the same knobs drive both seams.
*/
33export interface TurnFixture {
  // --- the figure (Character layer / wire `figure` + `characterResponse`) ---
  figureName?: string
  era?: string
  /** The figure's short factual descriptor (Character `persona`; wire `descriptor`). */
  persona?: string
  descriptor?: string
  /** The figure's in-character reply. */
  message?: string
  /** The concrete thing the figure decides to do. */
  action?: string
44 
  // --- the Judge (craft + continuity) ---
  craft?: Craft
  craftReason?: string
  /** Whether the dispatch builds on the run's thread — drives the momentum meter. */
  continuity?: Continuity
50 
  // --- the dice ---
  /** The natural d20 (1–20) the dev lane forces, before the craft modifier. The
   *  effective roll = clamp(roll + CRAFT_MODIFIER[craft], 1, 20), banded normally. */
  roll?: number
  /** Wire-only echoes the e2e harness uses for its mocked response. */
  diceRoll?: number
  diceOutcome?: string
  naturalRoll?: number
  rollModifier?: number
60 
  // --- the Timeline Engine (the ripple) ---
  headline?: string
  detail?: string
  /** The engine's base swing. The server clamps it into the ROLLED band, then the
   *  real anachronism amplifier, causal-chain decay, and craft/momentum gains run. */
  progressChange?: number
  baseProgressChange?: number
  valence?: Valence
  anachronism?: Anachronism
  /** True when this turn is the staked last stand (the wire echo). */
  staked?: boolean
72 
  // --- the Chronicler (the prose telling / epilogue) ---
  chronicleTitle?: string
  chronicleParagraphs?: string[]
76}
77 
78/** The per-AI-task structured outputs a `TurnFixture` scripts — each is the raw
⋯ 60 lines hidden (lines 79–138)79 *  object that task's consumer in `server/utils/openai.ts` will `JSON.parse`. */
80export interface TurnFixtureScripts {
  judge: { craft: Craft; continuity: Continuity; reason: string }
  character: { message: string; action: string; era: string; persona: string }
  timeline: {
      headline: string
      detail: string
      progressChange: number
      valence: Valence
      anachronism: Anachronism
  }
  /** Shared by the `chronicler` (mid-run) and `epilogue` (terminal) tasks. */
  chronicle: { title: string; paragraphs: string[] }
92}
93 
94/**
* Builds the four AI layers' outputs from a fixture, filling every required field so
* each consumer's validation passes and parses cleanly. Defaults describe a plain,
* in-period "sound" turn — callers override only what a scenario needs.
*/
99export function turnFixtureScripts(f: TurnFixture = {}): TurnFixtureScripts {
  const era = f.era ?? 'Alexandria, 48 BC'
  return {
      judge: {
          craft: f.craft ?? 'sound',
          continuity: f.continuity ?? 'neutral',
          reason: f.craftReason ?? 'A clear, period-fluent ask.'
      },
      character: {
          message: f.message ?? 'A striking notion — I shall weigh it.',
          action: f.action ?? 'The figure sets the idea in motion.',
          era,
          persona: f.persona ?? f.descriptor ?? 'A figure of history'
      },
      timeline: {
          headline: f.headline ?? 'History bends toward the aim',
          detail: f.detail ?? 'The intervention ripples outward and the world shifts.',
          // 20 sits inside the Success band; the server re-clamps to whatever band
          // the (forced) roll actually lands in, so this is just a sane default.
          progressChange: f.progressChange ?? 20,
          valence: f.valence ?? 'positive',
          anachronism: f.anachronism ?? 'in-period'
      },
      chronicle: {
          title: f.chronicleTitle ?? 'The Account So Far',
          paragraphs: f.chronicleParagraphs ?? [
              'A stranger\'s words have bent the timeline.',
              'The old certainties waver, and a new course takes shape.'
          ]
      }
  }
130}
131 
132/** The forced natural d20 a `TurnFixture` injects at the dice seam, or undefined to
*  let the real `rollD20()` run. Prefers `roll`, then the wire `naturalRoll`. */
134export function forcedRollFor(f: TurnFixture = {}): number | undefined {
  if (typeof f.roll === 'number') return f.roll
  if (typeof f.naturalRoll === 'number') return f.naturalRoll
  return undefined
138}

turnFixtureScripts fills every required field so each consumer in server/utils/openai.ts parses cleanly (closed-enum craft/continuity/valence/ anachronism, a non-empty chronicle). forcedRollFor extracts the die.

utils/fixtures/turn-fixture.ts · 138 lines

utils/fixtures/turn-fixture.ts138 lines · TypeScript

⋯ 98 lines hidden (lines 1–98)1/**
* The shared turn-fixture shape (issue #105 — developer mode).
*
* One pure description of a scripted turn, read by two seams that must never drift:
*
*   - The dev-mode fixture AI lane (`server/utils/dev-fixtures.ts`), which turns this
*     into the per-task structured outputs the four AI layers would have generated —
*     so a forced turn runs the REAL pipeline (dice, swing bands, anachronism, causal
*     chain, momentum, the progress clamp, win/lose, the Chronicle) with no model
*     calls: no keys, no spend.
*   - The e2e route-mock harness (`tests/e2e/support/game.ts`), which turns the same
*     fields into a `/api/send-message` wire response.
*
* Pure + dependency-light on purpose: only type imports (all erased at build), so it
* is safe to import from the client bundle, the server, and the Playwright transform
* alike. Every field is optional; a bare `{}` yields a sensible "sound success" turn.
*/
18import type { Craft } from '~/utils/craft'
19import type { Continuity } from '~/utils/continuity'
20import type { Anachronism } from '~/server/utils/anachronism'
21 
22/** Timeline valence — the same closed set the Timeline Engine returns. Inlined to
*  keep this module free of a store/server runtime dependency. */
24export type Valence = 'positive' | 'negative' | 'neutral'
25 
26/**
* A scripted turn. The dev lane reads the AI-seam fields (craft, continuity, the
* figure reply, the ripple, the chronicle) and the forced roll; the e2e harness
* reads the wire fields (diceRoll, diceOutcome, …). Overlapping fields (figureName,
* era, headline, detail, progressChange, valence, anachronism, craft, staked) mean
* the same knobs drive both seams.
*/
33export interface TurnFixture {
  // --- the figure (Character layer / wire `figure` + `characterResponse`) ---
  figureName?: string
  era?: string
  /** The figure's short factual descriptor (Character `persona`; wire `descriptor`). */
  persona?: string
  descriptor?: string
  /** The figure's in-character reply. */
  message?: string
  /** The concrete thing the figure decides to do. */
  action?: string
44 
  // --- the Judge (craft + continuity) ---
  craft?: Craft
  craftReason?: string
  /** Whether the dispatch builds on the run's thread — drives the momentum meter. */
  continuity?: Continuity
50 
  // --- the dice ---
  /** The natural d20 (1–20) the dev lane forces, before the craft modifier. The
   *  effective roll = clamp(roll + CRAFT_MODIFIER[craft], 1, 20), banded normally. */
  roll?: number
  /** Wire-only echoes the e2e harness uses for its mocked response. */
  diceRoll?: number
  diceOutcome?: string
  naturalRoll?: number
  rollModifier?: number
60 
  // --- the Timeline Engine (the ripple) ---
  headline?: string
  detail?: string
  /** The engine's base swing. The server clamps it into the ROLLED band, then the
   *  real anachronism amplifier, causal-chain decay, and craft/momentum gains run. */
  progressChange?: number
  baseProgressChange?: number
  valence?: Valence
  anachronism?: Anachronism
  /** True when this turn is the staked last stand (the wire echo). */
  staked?: boolean
72 
  // --- the Chronicler (the prose telling / epilogue) ---
  chronicleTitle?: string
  chronicleParagraphs?: string[]
76}
77 
78/** The per-AI-task structured outputs a `TurnFixture` scripts — each is the raw
*  object that task's consumer in `server/utils/openai.ts` will `JSON.parse`. */
80export interface TurnFixtureScripts {
  judge: { craft: Craft; continuity: Continuity; reason: string }
  character: { message: string; action: string; era: string; persona: string }
  timeline: {
      headline: string
      detail: string
      progressChange: number
      valence: Valence
      anachronism: Anachronism
  }
  /** Shared by the `chronicler` (mid-run) and `epilogue` (terminal) tasks. */
  chronicle: { title: string; paragraphs: string[] }
92}
93 
94/**
* Builds the four AI layers' outputs from a fixture, filling every required field so
* each consumer's validation passes and parses cleanly. Defaults describe a plain,
* in-period "sound" turn — callers override only what a scenario needs.
*/
99export function turnFixtureScripts(f: TurnFixture = {}): TurnFixtureScripts {
  const era = f.era ?? 'Alexandria, 48 BC'
  return {
      judge: {
          craft: f.craft ?? 'sound',
          continuity: f.continuity ?? 'neutral',
          reason: f.craftReason ?? 'A clear, period-fluent ask.'
      },
      character: {
          message: f.message ?? 'A striking notion — I shall weigh it.',
          action: f.action ?? 'The figure sets the idea in motion.',
          era,
          persona: f.persona ?? f.descriptor ?? 'A figure of history'
      },
      timeline: {
          headline: f.headline ?? 'History bends toward the aim',
          detail: f.detail ?? 'The intervention ripples outward and the world shifts.',
          // 20 sits inside the Success band; the server re-clamps to whatever band
          // the (forced) roll actually lands in, so this is just a sane default.
          progressChange: f.progressChange ?? 20,
          valence: f.valence ?? 'positive',
          anachronism: f.anachronism ?? 'in-period'
      },
      chronicle: {
          title: f.chronicleTitle ?? 'The Account So Far',
          paragraphs: f.chronicleParagraphs ?? [
              'A stranger\'s words have bent the timeline.',
              'The old certainties waver, and a new course takes shape.'
          ]
      }
  }
130}
131 
132/** The forced natural d20 a `TurnFixture` injects at the dice seam, or undefined to
*  let the real `rollD20()` run. Prefers `roll`, then the wire `naturalRoll`. */
134export function forcedRollFor(f: TurnFixture = {}): number | undefined {
  if (typeof f.roll === 'number') return f.roll
  if (typeof f.naturalRoll === 'number') return f.naturalRoll
  return undefined
138}

The e2e harness now imports that type and aliases its own RippleFixture to it, so the two can't drift. The import is type-only — erased at build — so it adds no runtime coupling to the Playwright run; the existing wire builder reads the same field names unchanged.

tests/e2e/support/game.ts · 271 lines

tests/e2e/support/game.ts271 lines · TypeScript

1import type { Page } from '@playwright/test'
2import { expect } from '@nuxt/test-utils/playwright'
3import type { TurnFixture } from '../../../utils/fixtures/turn-fixture'
4 
5/**
* Shared e2e helpers. The game is AI-backed, so real runs would be slow, costly,
* and non-deterministic — every spec mocks the two API routes (`page.route`) and
* drives the real UI flow against fixed responses. No OpenAI key is needed.
*/
10 
11/**
* A scripted turn. Aliased to the canonical `TurnFixture` (issue #105) so the e2e
* mocks and dev mode's fixture lane share ONE shape and can't drift — the import is
* type-only (erased at build), so it adds no runtime coupling to the Playwright run.
*/
16export type RippleFixture = TurnFixture
⋯ 255 lines hidden (lines 17–271)17 
18/** Builds a /api/send-message payload in the exact shape the game store consumes. */
19function sendMessageResponse(f: RippleFixture = {}) {
  const progressChange = f.progressChange ?? 20
  const era = f.era ?? 'Alexandria, 48 BC'
  const diceRoll = f.diceRoll ?? 14
  return {
      success: true,
      message: 'Timeline updated',
      data: {
          userMessage: 'mocked',
          figure: {
              name: f.figureName ?? 'Cleopatra',
              era,
              descriptor: f.descriptor ?? 'Queen of Egypt'
          },
          diceRoll,
          diceOutcome: f.diceOutcome ?? 'Success',
          // Judge-of-craft fields: the default is an untilted die (sound, ±0),
          // so specs that predate the judge keep their exact dice displays.
          naturalRoll: f.naturalRoll ?? diceRoll,
          rollModifier: f.rollModifier ?? 0,
          craft: f.craft ?? 'sound',
          craftReason: f.craftReason ?? '',
          staked: f.staked ?? false,
          characterResponse: {
              message: f.message ?? 'A bold notion — I shall weigh it.',
              action: f.action ?? 'Cleopatra dispatches envoys to Rome a decade early'
          },
          timeline: {
              headline: f.headline ?? 'Envoys redraw the map of power',
              detail: f.detail ?? 'Egypt courts Rome ahead of schedule and alliances shift.',
              era,
              progressChange,
              // Defaults to the final swing (an in-period, unamplified turn), so
              // the reveal's equation only appears when a fixture asks for it.
              baseProgressChange: f.baseProgressChange ?? progressChange,
              valence: f.valence ?? (progressChange > 0 ? 'positive' : progressChange < 0 ? 'negative' : 'neutral'),
              anachronism: f.anachronism ?? 'in-period'
          },
          error: null
      }
  }
60}
61 
62/** Routes /api/send-message to a fixed ripple (or a per-call function for variation). */
63export async function mockSendMessage(page: Page, fixture: RippleFixture | (() => RippleFixture) = {}) {
  await page.route('**/api/send-message', async (route) => {
      const f = typeof fixture === 'function' ? fixture() : fixture
      // Echo back the figure the player actually addressed (the store registers
      // contacts from the response), unless the fixture pins one explicitly.
      let requested: string | undefined
      try {
          requested = (route.request().postDataJSON() as { figureName?: string })?.figureName
      } catch {
          /* no/!json body */
      }
      await route.fulfill({
          status: 200,
          contentType: 'application/json',
          body: JSON.stringify(sendMessageResponse({ ...f, figureName: f.figureName ?? requested }))
      })
  })
80}
81 
82/** Routes /api/objective to a fixed, freshly "composed" objective. */
83export async function mockObjective(
  page: Page,
  objective: { title: string; description: string; era: string; icon: string }
86) {
  await page.route('**/api/objective', async (route) => {
      await route.fulfill({
          status: 200,
          contentType: 'application/json',
          body: JSON.stringify({ success: true, objective })
      })
  })
94}
95 
96/** A resolved, DECEASED figure — the default contact fixture. #73 requires a
*  grounded, deceased figure to send, so a deceased default keeps the happy-path
*  specs sending without each re-registering grounding. (Cleopatra, 69–30 BC.) */
99const RESOLVED_FIGURE = {
  resolved: true,
  name: 'Cleopatra',
  description: 'Queen of Egypt',
  born: { signed: -69, display: '69 BC' },
  died: { signed: -30, display: '30 BC' },
  living: false
106}
107 
108/**
* Routes /api/figure (the grounding lookup FigurePicker fires on selection) to a
* fixed result. Defaults to a resolved, deceased figure (RESOLVED_FIGURE) so the
* contact is sendable under the #73 require-grounding gate without every spec
* re-registering. Pass `{ resolved: false }` to exercise the unresolved/blocked path.
*
* NOTE: the route pattern must NOT swallow /api/figure-search (the autocomplete),
* which has its own mock below — hence the exact-or-query matcher.
*/
117export async function mockFigure(page: Page, figure: Record<string, unknown> = RESOLVED_FIGURE) {
  await page.route(/\/api\/figure(\?|$)/, async (route) => {
      await route.fulfill({
          status: 200,
          contentType: 'application/json',
          body: JSON.stringify({ name: '', resolved: false, ...figure })
      })
  })
125}
126 
127/**
* Routes /api/figure-search (the name-autocomplete combobox, fired while typing)
* to a fixed result set — default empty, so existing specs type without a
* dropdown appearing and never touch live Wikipedia.
*/
132export async function mockFigureSearch(
  page: Page,
  results: Array<{ name: string; description?: string; thumbnail?: string }> = []
135) {
  await page.route('**/api/figure-search*', async (route) => {
      await route.fulfill({
          status: 200,
          contentType: 'application/json',
          body: JSON.stringify({ results })
      })
  })
143}
144 
145const DEFAULT_SUGGESTIONS = [
  { name: 'Wilhelm II', reason: 'German Emperor who could restrain Vienna before the crisis spread.', lifespan: '1859 – 1941' },
  { name: 'Edward Grey', reason: "Britain's foreign secretary — early mediation could cool the crisis.", lifespan: '1862 – 1933' },
  { name: 'Nicholas II', reason: 'Russian Emperor; limiting mobilization could avert escalation.', lifespan: '1868 – 1918' }
149]
150 
151/**
* Routes /api/suggestions (the tool-using agent FigurePicker loads on mount) to a
* fixed set, so specs never trigger the live agent. Registered inside startCuratedRun
* because the load fires as the board mounts.
*/
156async function mockSuggestions(page: Page, suggestions = DEFAULT_SUGGESTIONS) {
  await page.route('**/api/suggestions', async (route) => {
      await route.fulfill({
          status: 200,
          contentType: 'application/json',
          body: JSON.stringify({ success: true, suggestions, fallback: false })
      })
  })
164}
165 
166/**
* Routes /api/chronicle (the non-blocking living-chronicle refresh fired after each
* resolved turn) to a fixed telling, so specs stay offline + deterministic. The call
* is fire-and-forget, so most specs never assert on it — but it must be mocked or it
* would hit the live network mid-run.
*/
172export async function mockChronicle(
  page: Page,
  chronicle: { title: string; paragraphs: string[] } = {
      title: 'The Account So Far',
      paragraphs: ["History bends under a stranger's words.", 'The old certainties waver.']
  }
178) {
  await page.route('**/api/chronicle', async (route) => {
      await route.fulfill({
          status: 200,
          contentType: 'application/json',
          body: JSON.stringify({ success: true, chronicle })
      })
  })
186}
187 
188/**
* Routes /api/research (the Archivist study, fired when the player clicks "Study
* them") to a fixed brief, so specs stay offline + deterministic.
*/
192export async function mockResearch(
  page: Page,
  study = {
      atThisMoment: 'At the height of their powers.',
      grasp: ['the state of their art'],
      reaching: ['the next problem before them'],
      cannotYetKnow: 'what the centuries after them would discover'
  }
200) {
  await page.route('**/api/research', async (route) => {
      await route.fulfill({
          status: 200,
          contentType: 'application/json',
          body: JSON.stringify({ success: true, study })
      })
  })
208}
209 
210/** Routes /api/lookup (the Archive's freeform topic lookup) to a fixed result. */
211export async function mockLookup(
  page: Page,
  lookup = {
      topic: 'Gunpowder',
      summary: 'An explosive mix of saltpeter, charcoal, and sulfur.',
      requires: ['saltpeter', 'charcoal', 'sulfur'],
      knownSince: 'China, ~9th century'
  }
219) {
  await page.route('**/api/lookup', async (route) => {
      await route.fulfill({
          status: 200,
          contentType: 'application/json',
          body: JSON.stringify({ success: true, lookup })
      })
  })
227}
228 
229/** From the mission briefing, choose the first curated objective and begin the run. */
230export async function startCuratedRun(page: Page) {
  // FigurePicker grounds whoever you select and loads suggestions on mount; default
  // both to deterministic, offline fixtures. (A later mockFigure call wins, since
  // route handlers run last-registered-first; suggestions load on mount, so they're
  // mocked here, before the board appears.) The chronicle refresh fires after the
  // first turn resolves, and the Archive study fires on demand — mock both here too.
  await mockFigure(page)
  await mockFigureSearch(page)
  await mockSuggestions(page)
  await mockChronicle(page)
  await mockResearch(page)
  await mockLookup(page)
  await expect(page.locator('[data-testid="mission-select"]')).toBeVisible()
  await page.locator('[data-testid="objective-option"]').first().click()
  await page.locator('[data-testid="begin-button"]').click()
  // The board is now live.
  await expect(page.locator('[data-testid="message-input"]')).toBeVisible()
247}
248 
249/** Picks a figure by typing into the contact input (decoupled from the now
*  objective-relevant suggestion chips). */
251export async function selectFigure(page: Page, name: string) {
  await page.locator('[data-testid="figure-picker"]').getByRole('combobox').fill(name)
253}
254 
255/**
* The send button. Located by its ARIA name rather than data-testid: the testid is
* a fallthrough attr on the <SendButton> wrapper and doesn't reach the rendered
* <button>, but the static aria-label does (and survives the "Sending…"/"Please
* wait…" label changes, since aria-label fixes the accessible name).
*/
261export function sendButton(page: Page) {
  return page.getByRole('button', { name: 'Send message' })
263}
264 
265/** Fills the composer and sends, asserting the button is ready first. */
266export async function fillAndSend(page: Page, text: string) {
  await page.locator('[data-testid="message-input"] textarea').fill(text)
  const send = sendButton(page)
  await expect(send).toBeEnabled()
  await send.click()
271}

Surface one: state jumps

All dev logic lives in a composable, never in the production store — state jumps use $patch plus existing actions, so stores/game.ts is untouched. A jump lands a stage the way a resolved turn would. jumpToVictory seeds a few ledger entries and a chronicle, sets progress to 100 with messages to spare, and flips the status — so the real EndGameScreen, the Spine, and the efficiency rating all render.

Victory in one action: seed the ledger, set the knobs, flip the status.

composables/useDevTools.ts · 290 lines

composables/useDevTools.ts290 lines · TypeScript

⋯ 125 lines hidden (lines 1–125)1/**
* Developer-mode orchestration (issue #105).
*
* Two surfaces, one composable:
*
*   1. STATE JUMPS (client-only) — land on a stage to inspect it (victory, defeat, a
*      populated mid-game, the stake offer) and set knobs (progress / remaining /
*      momentum) directly. These never call the server, never charge a run, and never
*      spend: they drive the store the same way a resolved turn would.
*
*   2. FORCED TURNS (the faithful path) — fire the REAL `sendMessage` pipeline with
*      the AI seam scripted (via `/api/dev/fixtures`) and the die forced, so the swing
*      bands, anachronism amplifier, causal-chain decay, momentum, progress clamp,
*      win/lose, Spine append, and Chronicle all run for real, deterministically, with
*      no keys and no model spend. The turn still goes through the charged-run paywall
*      (one free dev run backs unlimited forced turns — the server has no per-run
*      message cap, and this panel keeps `remainingMessages` topped), so dev mode is
*      not a free-play bypass.
*
* All dev logic lives here (and in the gated server seam), never in the production
* store: state jumps use `$patch` + existing actions, so `stores/game.ts` is untouched.
*/
23import { computed } from 'vue'
24import { useGameStore } from '~/stores/game'
25import { listCuratedObjectives, type GameObjective } from '~/server/utils/objectives'
26import { DiceOutcome } from '~/utils/dice'
27import type { Craft } from '~/utils/craft'
28import type { Continuity } from '~/utils/continuity'
29import type { Anachronism } from '~/server/utils/anachronism'
30import type { GroundedFigure } from '~/server/utils/figure-grounding'
31import type { TurnFixture } from '~/utils/fixtures/turn-fixture'
32 
33/** A real, deceased figure so the server's own grounding gate resolves (it re-grounds
*  the name against Wikipedia; that needs no key and costs nothing). Cleopatra, 69–30 BC. */
35const DEV_FIGURE: GroundedFigure = {
  name: 'Cleopatra',
  resolved: true,
  description: 'Queen of Egypt, last of the Ptolemaic dynasty',
  born: { year: 69, bce: true, signed: -69, display: '69 BC' },
  died: { year: 30, bce: true, signed: -30, display: '30 BC' },
  living: false
42}
43const DEV_FIGURE_ERA = 'Alexandria, 48 BC'
44const DEV_FIGURE_WHEN = -40
45 
46/** Forced-die + base-swing per target band (natural d20; the craft modifier still
*  applies on top, and the server re-clamps the swing into the effective rolled band). */
48const OUTCOME_PRESET: Record<DiceOutcome, { roll: number; progressChange: number }> = {
  [DiceOutcome.CRITICAL_SUCCESS]: { roll: 20, progressChange: 45 },
  [DiceOutcome.SUCCESS]: { roll: 16, progressChange: 30 },
  [DiceOutcome.NEUTRAL]: { roll: 10, progressChange: 8 },
  [DiceOutcome.FAILURE]: { roll: 5, progressChange: -15 },
  [DiceOutcome.CRITICAL_FAILURE]: { roll: 1, progressChange: -35 }
54}
55 
56/** A few sample ledger entries to populate the Spine / end screen for inspection. */
57const SAMPLE_LEDGER = [
  { headline: 'Envoys redraw the map of power', detail: 'Egypt courts Rome ahead of schedule and the alliances shift.', diceRoll: 16, diceOutcome: DiceOutcome.SUCCESS, progressChange: 22, craft: 'sharp' as Craft, whenSigned: -44 },
  { headline: 'The great library is spared the flames', detail: 'Scrolls that history lost are copied and sent abroad for safekeeping.', diceRoll: 11, diceOutcome: DiceOutcome.NEUTRAL, progressChange: 8, craft: 'sound' as Craft, whenSigned: -42 },
  { headline: 'A rival faction takes offense', detail: 'The senate bristles at Alexandria\'s new confidence, and knives are sharpened.', diceRoll: 4, diceOutcome: DiceOutcome.FAILURE, progressChange: -9, craft: 'vague' as Craft, whenSigned: -40 }
61]
62 
63export interface ForceTurnOptions {
  craft?: Craft
  continuity?: Continuity
  anachronism?: Anachronism
  staked?: boolean
68}
69 
70export function useDevTools() {
  const gameStore = useGameStore()
72 
  /** The dev objective — anchored near Cleopatra so the causal chain reads strong. */
  function devObjective(): GameObjective {
      const all = listCuratedObjectives()
      return all.find(o => o.anchorYear === -48) ?? all[0]
  }
78 
  /** Set the current objective WITHOUT charging a run (for offline inspection). */
  function ensureObjective() {
      if (!gameStore.currentObjective) {
          gameStore.$patch({ currentObjective: devObjective() })
      }
  }
85 
  /** Point the composer at a known, grounded, deceased figure — no /api/figure call. */
  function autoFillFigure() {
      gameStore.registerFigure({ name: DEV_FIGURE.name, era: DEV_FIGURE_ERA, descriptor: 'Queen of Egypt' })
      gameStore.setActiveFigure(DEV_FIGURE.name)
      gameStore.$patch({
          figureGrounding: DEV_FIGURE,
          contactWhen: DEV_FIGURE_WHEN,
          contactMoment: null,
          groundingLoading: false
      })
  }
97 
  /** Seed up to `n` sample changes onto the Spine (skips if the ledger already has any). */
  function seedLedger(n: number) {
      if (gameStore.timelineEvents.length) return
      SAMPLE_LEDGER.slice(0, n).forEach(s =>
          gameStore.addTimelineEvent({
              figureName: DEV_FIGURE.name,
              era: DEV_FIGURE_ERA,
              headline: s.headline,
              detail: s.detail,
              diceRoll: s.diceRoll,
              diceOutcome: s.diceOutcome,
              progressChange: s.progressChange,
              craft: s.craft,
              whenSigned: s.whenSigned
          })
      )
  }
115 
  const DEV_CHRONICLE = {
      title: 'A History Being Rewritten',
      paragraphs: [
          'In this telling, a stranger\'s dispatches have bent the course of events.',
          'What was settled now wavers, and the world leans toward an unfamiliar shape.'
      ]
  }
123 
  // ---------- state jumps (client-only) ----------
125 
  function jumpToVictory() {
      ensureObjective()
      seedLedger(3)
      gameStore.$patch({
          objectiveProgress: 100,
          remainingMessages: 2,
          momentum: 3,
          gameStatus: 'victory',
          chronicle: { title: 'A World Remade', paragraphs: DEV_CHRONICLE.paragraphs },
          epiloguePending: false
      })
  }
138 
  function jumpToDefeat() {
      ensureObjective()
⋯ 150 lines hidden (lines 141–290)141        seedLedger(2)
      gameStore.$patch({
          objectiveProgress: 38,
          remainingMessages: 0,
          momentum: 0,
          gameStatus: 'defeat',
          chronicle: { title: 'The Tide Held', paragraphs: DEV_CHRONICLE.paragraphs },
          epiloguePending: false
      })
  }
151 
  function seedMidGame() {
      ensureObjective()
      autoFillFigure()
      seedLedger(2)
      gameStore.$patch({
          objectiveProgress: 36,
          remainingMessages: 3,
          momentum: 2,
          gameStatus: 'playing',
          chronicle: DEV_CHRONICLE
      })
  }
164 
  /** Final message, win out of normal reach → `canStake` becomes true and the
   *  inline stake control renders for inspection. */
  function setupStakeOffer() {
      ensureObjective()
      autoFillFigure()
      seedLedger(1)
      gameStore.$patch({
          objectiveProgress: 20,
          remainingMessages: 1,
          momentum: 1,
          gameStatus: 'playing',
          chronicle: DEV_CHRONICLE
      })
  }
179 
  /** Back to the mission-select briefing (a full reset). */
  function toMissionSelect() {
      gameStore.resetGame()
  }
184 
  // ---------- knob setters (client-only) ----------
186 
  const clamp = (n: number, lo: number, hi: number) => Math.max(lo, Math.min(hi, Math.round(n)))
  function setProgress(n: number) { gameStore.$patch({ objectiveProgress: clamp(n, 0, 100) }) }
  function setRemaining(n: number) { gameStore.$patch({ remainingMessages: clamp(n, 0, 5) }) }
  function setMomentum(n: number) { gameStore.$patch({ momentum: clamp(n, 0, 4) }) }
191 
  // ---------- the fixture AI lane (server-gated) ----------
193 
  async function armFixtures(fixture: TurnFixture): Promise<void> {
      await $fetch('/api/dev/fixtures', { method: 'POST', body: { fixture } })
  }
  async function clearFixtures(): Promise<void> {
      await $fetch('/api/dev/fixtures', { method: 'POST', body: { clear: true } })
  }
200 
  // ---------- forced turns (the real pipeline) ----------
202 
  /** Commit a charged dev run + an objective + a figure, so forced turns can fire.
   *  Returns false (and leaves a store error) if the device is out of runs. */
  async function startDevRun(): Promise<boolean> {
      const ok = await gameStore.chooseObjective(devObjective())
      if (!ok) return false
      autoFillFigure()
      gameStore.$patch({ remainingMessages: 5, objectiveProgress: 0, momentum: 0, timelineEvents: [] })
      return true
  }
212 
  /**
   * Fire one forced turn through the real `sendMessage`. Scripts the four AI layers
   * + the die for the chosen band, then sends — the swing, progress, Spine, momentum,
   * and Chronicle all resolve for real. Ensures a charged run first.
   */
  async function forceTurn(outcome: DiceOutcome, opts: ForceTurnOptions = {}): Promise<boolean> {
      if (!gameStore.runId && !(await startDevRun())) return false
      const preset = OUTCOME_PRESET[outcome]
      const fixture: TurnFixture = {
          figureName: DEV_FIGURE.name,
          era: DEV_FIGURE_ERA,
          persona: 'Queen of Egypt',
          message: 'A bold notion — I shall set it in motion.',
          action: 'Cleopatra acts decisively on the idea.',
          craft: opts.craft ?? 'sound',
          craftReason: 'A dev-forced craft grade.',
          continuity: opts.continuity ?? 'neutral',
          roll: preset.roll,
          headline: `${outcome}: the timeline answers`,
          detail: 'A dev-forced ripple, resolved through the real mechanics.',
          progressChange: preset.progressChange,
          valence: preset.progressChange > 0 ? 'positive' : preset.progressChange < 0 ? 'negative' : 'neutral',
          anachronism: opts.anachronism ?? 'in-period',
          chronicleTitle: DEV_CHRONICLE.title,
          chronicleParagraphs: DEV_CHRONICLE.paragraphs
      }
      // Let rapid dev clicks through (skip the 1s cooldown) and keep the run playable.
      gameStore.$patch({ isRateLimited: false, lastMessageTime: null })
      if (!opts.staked) {
          if (gameStore.gameStatus !== 'playing') gameStore.$patch({ gameStatus: 'playing' })
          if (gameStore.remainingMessages <= 0) gameStore.$patch({ remainingMessages: 5 })
      }
      await armFixtures(fixture)
      return gameStore.sendMessage('A dev-forced dispatch to history.', DEV_FIGURE.name, { stake: opts.staked })
  }
248 
  /** Set up the stake offer, then fire the final dispatch staked (real doubling). */
  async function forceStakedTurn(outcome: DiceOutcome = DiceOutcome.SUCCESS, opts: ForceTurnOptions = {}): Promise<boolean> {
      if (!gameStore.runId && !(await startDevRun())) return false
      setupStakeOffer()
      return forceTurn(outcome, { ...opts, staked: true })
  }
255 
  // ---------- the live inspector ----------
257 
  const inspector = computed(() => {
      const lastAi = [...gameStore.messageHistory].reverse().find(m => m.sender === 'ai' && m.diceRoll != null)
      const mod = lastAi?.rollModifier
      const rollLine = lastAi
          ? `${lastAi.naturalRoll ?? lastAi.diceRoll}${mod ? (mod > 0 ? `+${mod}` : `${mod}`) : ''} → ${lastAi.diceRoll} · ${lastAi.diceOutcome}`
          : '—'
      return {
          gameStatus: gameStore.gameStatus,
          objectiveProgress: gameStore.objectiveProgress,
          remainingMessages: gameStore.remainingMessages,
          momentum: gameStore.momentum,
          runEpoch: gameStore.runEpoch,
          ledgerCount: gameStore.timelineEvents.length,
          lastRoll: rollLine,
          runId: gameStore.runId ? `${gameStore.runId.slice(0, 8)}…` : '(none)',
          canStake: gameStore.canStake,
          isLoading: gameStore.isLoading
      }
  })
277 
  return {
      inspector,
      // stage jumps
      jumpToVictory, jumpToDefeat, seedMidGame, setupStakeOffer, toMissionSelect,
      // knobs
      setProgress, setRemaining, setMomentum,
      // setup
      autoFillFigure, startDevRun,
      // forced turns + fixtures
      forceTurn, forceStakedTurn, armFixtures, clearFixtures,
      DiceOutcome
  }
290}

The stake offer is the fiddly edge case: it appears only on the final message when a win is out of normal reach. The recipe sets exactly that — one message left, progress low enough that the gap exceeds the per-turn swing — so the store's real canStake getter turns true and the inline stake control renders.

composables/useDevTools.ts · 290 lines

composables/useDevTools.ts290 lines · TypeScript

⋯ 166 lines hidden (lines 1–166)1/**
* Developer-mode orchestration (issue #105).
*
* Two surfaces, one composable:
*
*   1. STATE JUMPS (client-only) — land on a stage to inspect it (victory, defeat, a
*      populated mid-game, the stake offer) and set knobs (progress / remaining /
*      momentum) directly. These never call the server, never charge a run, and never
*      spend: they drive the store the same way a resolved turn would.
*
*   2. FORCED TURNS (the faithful path) — fire the REAL `sendMessage` pipeline with
*      the AI seam scripted (via `/api/dev/fixtures`) and the die forced, so the swing
*      bands, anachronism amplifier, causal-chain decay, momentum, progress clamp,
*      win/lose, Spine append, and Chronicle all run for real, deterministically, with
*      no keys and no model spend. The turn still goes through the charged-run paywall
*      (one free dev run backs unlimited forced turns — the server has no per-run
*      message cap, and this panel keeps `remainingMessages` topped), so dev mode is
*      not a free-play bypass.
*
* All dev logic lives here (and in the gated server seam), never in the production
* store: state jumps use `$patch` + existing actions, so `stores/game.ts` is untouched.
*/
23import { computed } from 'vue'
24import { useGameStore } from '~/stores/game'
25import { listCuratedObjectives, type GameObjective } from '~/server/utils/objectives'
26import { DiceOutcome } from '~/utils/dice'
27import type { Craft } from '~/utils/craft'
28import type { Continuity } from '~/utils/continuity'
29import type { Anachronism } from '~/server/utils/anachronism'
30import type { GroundedFigure } from '~/server/utils/figure-grounding'
31import type { TurnFixture } from '~/utils/fixtures/turn-fixture'
32 
33/** A real, deceased figure so the server's own grounding gate resolves (it re-grounds
*  the name against Wikipedia; that needs no key and costs nothing). Cleopatra, 69–30 BC. */
35const DEV_FIGURE: GroundedFigure = {
  name: 'Cleopatra',
  resolved: true,
  description: 'Queen of Egypt, last of the Ptolemaic dynasty',
  born: { year: 69, bce: true, signed: -69, display: '69 BC' },
  died: { year: 30, bce: true, signed: -30, display: '30 BC' },
  living: false
42}
43const DEV_FIGURE_ERA = 'Alexandria, 48 BC'
44const DEV_FIGURE_WHEN = -40
45 
46/** Forced-die + base-swing per target band (natural d20; the craft modifier still
*  applies on top, and the server re-clamps the swing into the effective rolled band). */
48const OUTCOME_PRESET: Record<DiceOutcome, { roll: number; progressChange: number }> = {
  [DiceOutcome.CRITICAL_SUCCESS]: { roll: 20, progressChange: 45 },
  [DiceOutcome.SUCCESS]: { roll: 16, progressChange: 30 },
  [DiceOutcome.NEUTRAL]: { roll: 10, progressChange: 8 },
  [DiceOutcome.FAILURE]: { roll: 5, progressChange: -15 },
  [DiceOutcome.CRITICAL_FAILURE]: { roll: 1, progressChange: -35 }
54}
55 
56/** A few sample ledger entries to populate the Spine / end screen for inspection. */
57const SAMPLE_LEDGER = [
  { headline: 'Envoys redraw the map of power', detail: 'Egypt courts Rome ahead of schedule and the alliances shift.', diceRoll: 16, diceOutcome: DiceOutcome.SUCCESS, progressChange: 22, craft: 'sharp' as Craft, whenSigned: -44 },
  { headline: 'The great library is spared the flames', detail: 'Scrolls that history lost are copied and sent abroad for safekeeping.', diceRoll: 11, diceOutcome: DiceOutcome.NEUTRAL, progressChange: 8, craft: 'sound' as Craft, whenSigned: -42 },
  { headline: 'A rival faction takes offense', detail: 'The senate bristles at Alexandria\'s new confidence, and knives are sharpened.', diceRoll: 4, diceOutcome: DiceOutcome.FAILURE, progressChange: -9, craft: 'vague' as Craft, whenSigned: -40 }
61]
62 
63export interface ForceTurnOptions {
  craft?: Craft
  continuity?: Continuity
  anachronism?: Anachronism
  staked?: boolean
68}
69 
70export function useDevTools() {
  const gameStore = useGameStore()
72 
  /** The dev objective — anchored near Cleopatra so the causal chain reads strong. */
  function devObjective(): GameObjective {
      const all = listCuratedObjectives()
      return all.find(o => o.anchorYear === -48) ?? all[0]
  }
78 
  /** Set the current objective WITHOUT charging a run (for offline inspection). */
  function ensureObjective() {
      if (!gameStore.currentObjective) {
          gameStore.$patch({ currentObjective: devObjective() })
      }
  }
85 
  /** Point the composer at a known, grounded, deceased figure — no /api/figure call. */
  function autoFillFigure() {
      gameStore.registerFigure({ name: DEV_FIGURE.name, era: DEV_FIGURE_ERA, descriptor: 'Queen of Egypt' })
      gameStore.setActiveFigure(DEV_FIGURE.name)
      gameStore.$patch({
          figureGrounding: DEV_FIGURE,
          contactWhen: DEV_FIGURE_WHEN,
          contactMoment: null,
          groundingLoading: false
      })
  }
97 
  /** Seed up to `n` sample changes onto the Spine (skips if the ledger already has any). */
  function seedLedger(n: number) {
      if (gameStore.timelineEvents.length) return
      SAMPLE_LEDGER.slice(0, n).forEach(s =>
          gameStore.addTimelineEvent({
              figureName: DEV_FIGURE.name,
              era: DEV_FIGURE_ERA,
              headline: s.headline,
              detail: s.detail,
              diceRoll: s.diceRoll,
              diceOutcome: s.diceOutcome,
              progressChange: s.progressChange,
              craft: s.craft,
              whenSigned: s.whenSigned
          })
      )
  }
115 
  const DEV_CHRONICLE = {
      title: 'A History Being Rewritten',
      paragraphs: [
          'In this telling, a stranger\'s dispatches have bent the course of events.',
          'What was settled now wavers, and the world leans toward an unfamiliar shape.'
      ]
  }
123 
  // ---------- state jumps (client-only) ----------
125 
  function jumpToVictory() {
      ensureObjective()
      seedLedger(3)
      gameStore.$patch({
          objectiveProgress: 100,
          remainingMessages: 2,
          momentum: 3,
          gameStatus: 'victory',
          chronicle: { title: 'A World Remade', paragraphs: DEV_CHRONICLE.paragraphs },
          epiloguePending: false
      })
  }
138 
  function jumpToDefeat() {
      ensureObjective()
      seedLedger(2)
      gameStore.$patch({
          objectiveProgress: 38,
          remainingMessages: 0,
          momentum: 0,
          gameStatus: 'defeat',
          chronicle: { title: 'The Tide Held', paragraphs: DEV_CHRONICLE.paragraphs },
          epiloguePending: false
      })
  }
151 
  function seedMidGame() {
      ensureObjective()
      autoFillFigure()
      seedLedger(2)
      gameStore.$patch({
          objectiveProgress: 36,
          remainingMessages: 3,
          momentum: 2,
          gameStatus: 'playing',
          chronicle: DEV_CHRONICLE
      })
  }
164 
  /** Final message, win out of normal reach → `canStake` becomes true and the
   *  inline stake control renders for inspection. */
  function setupStakeOffer() {
      ensureObjective()
      autoFillFigure()
      seedLedger(1)
      gameStore.$patch({
          objectiveProgress: 20,
          remainingMessages: 1,
          momentum: 1,
          gameStatus: 'playing',
          chronicle: DEV_CHRONICLE
      })
  }
179 
  /** Back to the mission-select briefing (a full reset). */
  function toMissionSelect() {
⋯ 109 lines hidden (lines 182–290)182        gameStore.resetGame()
  }
184 
  // ---------- knob setters (client-only) ----------
186 
  const clamp = (n: number, lo: number, hi: number) => Math.max(lo, Math.min(hi, Math.round(n)))
  function setProgress(n: number) { gameStore.$patch({ objectiveProgress: clamp(n, 0, 100) }) }
  function setRemaining(n: number) { gameStore.$patch({ remainingMessages: clamp(n, 0, 5) }) }
  function setMomentum(n: number) { gameStore.$patch({ momentum: clamp(n, 0, 4) }) }
191 
  // ---------- the fixture AI lane (server-gated) ----------
193 
  async function armFixtures(fixture: TurnFixture): Promise<void> {
      await $fetch('/api/dev/fixtures', { method: 'POST', body: { fixture } })
  }
  async function clearFixtures(): Promise<void> {
      await $fetch('/api/dev/fixtures', { method: 'POST', body: { clear: true } })
  }
200 
  // ---------- forced turns (the real pipeline) ----------
202 
  /** Commit a charged dev run + an objective + a figure, so forced turns can fire.
   *  Returns false (and leaves a store error) if the device is out of runs. */
  async function startDevRun(): Promise<boolean> {
      const ok = await gameStore.chooseObjective(devObjective())
      if (!ok) return false
      autoFillFigure()
      gameStore.$patch({ remainingMessages: 5, objectiveProgress: 0, momentum: 0, timelineEvents: [] })
      return true
  }
212 
  /**
   * Fire one forced turn through the real `sendMessage`. Scripts the four AI layers
   * + the die for the chosen band, then sends — the swing, progress, Spine, momentum,
   * and Chronicle all resolve for real. Ensures a charged run first.
   */
  async function forceTurn(outcome: DiceOutcome, opts: ForceTurnOptions = {}): Promise<boolean> {
      if (!gameStore.runId && !(await startDevRun())) return false
      const preset = OUTCOME_PRESET[outcome]
      const fixture: TurnFixture = {
          figureName: DEV_FIGURE.name,
          era: DEV_FIGURE_ERA,
          persona: 'Queen of Egypt',
          message: 'A bold notion — I shall set it in motion.',
          action: 'Cleopatra acts decisively on the idea.',
          craft: opts.craft ?? 'sound',
          craftReason: 'A dev-forced craft grade.',
          continuity: opts.continuity ?? 'neutral',
          roll: preset.roll,
          headline: `${outcome}: the timeline answers`,
          detail: 'A dev-forced ripple, resolved through the real mechanics.',
          progressChange: preset.progressChange,
          valence: preset.progressChange > 0 ? 'positive' : preset.progressChange < 0 ? 'negative' : 'neutral',
          anachronism: opts.anachronism ?? 'in-period',
          chronicleTitle: DEV_CHRONICLE.title,
          chronicleParagraphs: DEV_CHRONICLE.paragraphs
      }
      // Let rapid dev clicks through (skip the 1s cooldown) and keep the run playable.
      gameStore.$patch({ isRateLimited: false, lastMessageTime: null })
      if (!opts.staked) {
          if (gameStore.gameStatus !== 'playing') gameStore.$patch({ gameStatus: 'playing' })
          if (gameStore.remainingMessages <= 0) gameStore.$patch({ remainingMessages: 5 })
      }
      await armFixtures(fixture)
      return gameStore.sendMessage('A dev-forced dispatch to history.', DEV_FIGURE.name, { stake: opts.staked })
  }
248 
  /** Set up the stake offer, then fire the final dispatch staked (real doubling). */
  async function forceStakedTurn(outcome: DiceOutcome = DiceOutcome.SUCCESS, opts: ForceTurnOptions = {}): Promise<boolean> {
      if (!gameStore.runId && !(await startDevRun())) return false
      setupStakeOffer()
      return forceTurn(outcome, { ...opts, staked: true })
  }
255 
  // ---------- the live inspector ----------
257 
  const inspector = computed(() => {
      const lastAi = [...gameStore.messageHistory].reverse().find(m => m.sender === 'ai' && m.diceRoll != null)
      const mod = lastAi?.rollModifier
      const rollLine = lastAi
          ? `${lastAi.naturalRoll ?? lastAi.diceRoll}${mod ? (mod > 0 ? `+${mod}` : `${mod}`) : ''} → ${lastAi.diceRoll} · ${lastAi.diceOutcome}`
          : '—'
      return {
          gameStatus: gameStore.gameStatus,
          objectiveProgress: gameStore.objectiveProgress,
          remainingMessages: gameStore.remainingMessages,
          momentum: gameStore.momentum,
          runEpoch: gameStore.runEpoch,
          ledgerCount: gameStore.timelineEvents.length,
          lastRoll: rollLine,
          runId: gameStore.runId ? `${gameStore.runId.slice(0, 8)}…` : '(none)',
          canStake: gameStore.canStake,
          isLoading: gameStore.isLoading
      }
  })
277 
  return {
      inspector,
      // stage jumps
      jumpToVictory, jumpToDefeat, seedMidGame, setupStakeOffer, toMissionSelect,
      // knobs
      setProgress, setRemaining, setMomentum,
      // setup
      autoFillFigure, startDevRun,
      // forced turns + fixtures
      forceTurn, forceStakedTurn, armFixtures, clearFixtures,
      DiceOutcome
  }
290}

Surface two: forced turns

A forced turn is the faithful path. It ensures a charged run exists (the normal chooseObjective flow — a real charge, no bypass), arms the fixture for the chosen band, then calls the real sendMessage. The swing, progress, Spine, momentum, and Chronicle all resolve for real; only the four AI layers are scripted.

Ensure a run, arm the fixture (incl. the forced roll), fire the real sendMessage.

composables/useDevTools.ts · 290 lines

composables/useDevTools.ts290 lines · TypeScript

⋯ 217 lines hidden (lines 1–217)1/**
* Developer-mode orchestration (issue #105).
*
* Two surfaces, one composable:
*
*   1. STATE JUMPS (client-only) — land on a stage to inspect it (victory, defeat, a
*      populated mid-game, the stake offer) and set knobs (progress / remaining /
*      momentum) directly. These never call the server, never charge a run, and never
*      spend: they drive the store the same way a resolved turn would.
*
*   2. FORCED TURNS (the faithful path) — fire the REAL `sendMessage` pipeline with
*      the AI seam scripted (via `/api/dev/fixtures`) and the die forced, so the swing
*      bands, anachronism amplifier, causal-chain decay, momentum, progress clamp,
*      win/lose, Spine append, and Chronicle all run for real, deterministically, with
*      no keys and no model spend. The turn still goes through the charged-run paywall
*      (one free dev run backs unlimited forced turns — the server has no per-run
*      message cap, and this panel keeps `remainingMessages` topped), so dev mode is
*      not a free-play bypass.
*
* All dev logic lives here (and in the gated server seam), never in the production
* store: state jumps use `$patch` + existing actions, so `stores/game.ts` is untouched.
*/
23import { computed } from 'vue'
24import { useGameStore } from '~/stores/game'
25import { listCuratedObjectives, type GameObjective } from '~/server/utils/objectives'
26import { DiceOutcome } from '~/utils/dice'
27import type { Craft } from '~/utils/craft'
28import type { Continuity } from '~/utils/continuity'
29import type { Anachronism } from '~/server/utils/anachronism'
30import type { GroundedFigure } from '~/server/utils/figure-grounding'
31import type { TurnFixture } from '~/utils/fixtures/turn-fixture'
32 
33/** A real, deceased figure so the server's own grounding gate resolves (it re-grounds
*  the name against Wikipedia; that needs no key and costs nothing). Cleopatra, 69–30 BC. */
35const DEV_FIGURE: GroundedFigure = {
  name: 'Cleopatra',
  resolved: true,
  description: 'Queen of Egypt, last of the Ptolemaic dynasty',
  born: { year: 69, bce: true, signed: -69, display: '69 BC' },
  died: { year: 30, bce: true, signed: -30, display: '30 BC' },
  living: false
42}
43const DEV_FIGURE_ERA = 'Alexandria, 48 BC'
44const DEV_FIGURE_WHEN = -40
45 
46/** Forced-die + base-swing per target band (natural d20; the craft modifier still
*  applies on top, and the server re-clamps the swing into the effective rolled band). */
48const OUTCOME_PRESET: Record<DiceOutcome, { roll: number; progressChange: number }> = {
  [DiceOutcome.CRITICAL_SUCCESS]: { roll: 20, progressChange: 45 },
  [DiceOutcome.SUCCESS]: { roll: 16, progressChange: 30 },
  [DiceOutcome.NEUTRAL]: { roll: 10, progressChange: 8 },
  [DiceOutcome.FAILURE]: { roll: 5, progressChange: -15 },
  [DiceOutcome.CRITICAL_FAILURE]: { roll: 1, progressChange: -35 }
54}
55 
56/** A few sample ledger entries to populate the Spine / end screen for inspection. */
57const SAMPLE_LEDGER = [
  { headline: 'Envoys redraw the map of power', detail: 'Egypt courts Rome ahead of schedule and the alliances shift.', diceRoll: 16, diceOutcome: DiceOutcome.SUCCESS, progressChange: 22, craft: 'sharp' as Craft, whenSigned: -44 },
  { headline: 'The great library is spared the flames', detail: 'Scrolls that history lost are copied and sent abroad for safekeeping.', diceRoll: 11, diceOutcome: DiceOutcome.NEUTRAL, progressChange: 8, craft: 'sound' as Craft, whenSigned: -42 },
  { headline: 'A rival faction takes offense', detail: 'The senate bristles at Alexandria\'s new confidence, and knives are sharpened.', diceRoll: 4, diceOutcome: DiceOutcome.FAILURE, progressChange: -9, craft: 'vague' as Craft, whenSigned: -40 }
61]
62 
63export interface ForceTurnOptions {
  craft?: Craft
  continuity?: Continuity
  anachronism?: Anachronism
  staked?: boolean
68}
69 
70export function useDevTools() {
  const gameStore = useGameStore()
72 
  /** The dev objective — anchored near Cleopatra so the causal chain reads strong. */
  function devObjective(): GameObjective {
      const all = listCuratedObjectives()
      return all.find(o => o.anchorYear === -48) ?? all[0]
  }
78 
  /** Set the current objective WITHOUT charging a run (for offline inspection). */
  function ensureObjective() {
      if (!gameStore.currentObjective) {
          gameStore.$patch({ currentObjective: devObjective() })
      }
  }
85 
  /** Point the composer at a known, grounded, deceased figure — no /api/figure call. */
  function autoFillFigure() {
      gameStore.registerFigure({ name: DEV_FIGURE.name, era: DEV_FIGURE_ERA, descriptor: 'Queen of Egypt' })
      gameStore.setActiveFigure(DEV_FIGURE.name)
      gameStore.$patch({
          figureGrounding: DEV_FIGURE,
          contactWhen: DEV_FIGURE_WHEN,
          contactMoment: null,
          groundingLoading: false
      })
  }
97 
  /** Seed up to `n` sample changes onto the Spine (skips if the ledger already has any). */
  function seedLedger(n: number) {
      if (gameStore.timelineEvents.length) return
      SAMPLE_LEDGER.slice(0, n).forEach(s =>
          gameStore.addTimelineEvent({
              figureName: DEV_FIGURE.name,
              era: DEV_FIGURE_ERA,
              headline: s.headline,
              detail: s.detail,
              diceRoll: s.diceRoll,
              diceOutcome: s.diceOutcome,
              progressChange: s.progressChange,
              craft: s.craft,
              whenSigned: s.whenSigned
          })
      )
  }
115 
  const DEV_CHRONICLE = {
      title: 'A History Being Rewritten',
      paragraphs: [
          'In this telling, a stranger\'s dispatches have bent the course of events.',
          'What was settled now wavers, and the world leans toward an unfamiliar shape.'
      ]
  }
123 
  // ---------- state jumps (client-only) ----------
125 
  function jumpToVictory() {
      ensureObjective()
      seedLedger(3)
      gameStore.$patch({
          objectiveProgress: 100,
          remainingMessages: 2,
          momentum: 3,
          gameStatus: 'victory',
          chronicle: { title: 'A World Remade', paragraphs: DEV_CHRONICLE.paragraphs },
          epiloguePending: false
      })
  }
138 
  function jumpToDefeat() {
      ensureObjective()
      seedLedger(2)
      gameStore.$patch({
          objectiveProgress: 38,
          remainingMessages: 0,
          momentum: 0,
          gameStatus: 'defeat',
          chronicle: { title: 'The Tide Held', paragraphs: DEV_CHRONICLE.paragraphs },
          epiloguePending: false
      })
  }
151 
  function seedMidGame() {
      ensureObjective()
      autoFillFigure()
      seedLedger(2)
      gameStore.$patch({
          objectiveProgress: 36,
          remainingMessages: 3,
          momentum: 2,
          gameStatus: 'playing',
          chronicle: DEV_CHRONICLE
      })
  }
164 
  /** Final message, win out of normal reach → `canStake` becomes true and the
   *  inline stake control renders for inspection. */
  function setupStakeOffer() {
      ensureObjective()
      autoFillFigure()
      seedLedger(1)
      gameStore.$patch({
          objectiveProgress: 20,
          remainingMessages: 1,
          momentum: 1,
          gameStatus: 'playing',
          chronicle: DEV_CHRONICLE
      })
  }
179 
  /** Back to the mission-select briefing (a full reset). */
  function toMissionSelect() {
      gameStore.resetGame()
  }
184 
  // ---------- knob setters (client-only) ----------
186 
  const clamp = (n: number, lo: number, hi: number) => Math.max(lo, Math.min(hi, Math.round(n)))
  function setProgress(n: number) { gameStore.$patch({ objectiveProgress: clamp(n, 0, 100) }) }
  function setRemaining(n: number) { gameStore.$patch({ remainingMessages: clamp(n, 0, 5) }) }
  function setMomentum(n: number) { gameStore.$patch({ momentum: clamp(n, 0, 4) }) }
191 
  // ---------- the fixture AI lane (server-gated) ----------
193 
  async function armFixtures(fixture: TurnFixture): Promise<void> {
      await $fetch('/api/dev/fixtures', { method: 'POST', body: { fixture } })
  }
  async function clearFixtures(): Promise<void> {
      await $fetch('/api/dev/fixtures', { method: 'POST', body: { clear: true } })
  }
200 
  // ---------- forced turns (the real pipeline) ----------
202 
  /** Commit a charged dev run + an objective + a figure, so forced turns can fire.
   *  Returns false (and leaves a store error) if the device is out of runs. */
  async function startDevRun(): Promise<boolean> {
      const ok = await gameStore.chooseObjective(devObjective())
      if (!ok) return false
      autoFillFigure()
      gameStore.$patch({ remainingMessages: 5, objectiveProgress: 0, momentum: 0, timelineEvents: [] })
      return true
  }
212 
  /**
   * Fire one forced turn through the real `sendMessage`. Scripts the four AI layers
   * + the die for the chosen band, then sends — the swing, progress, Spine, momentum,
   * and Chronicle all resolve for real. Ensures a charged run first.
   */
  async function forceTurn(outcome: DiceOutcome, opts: ForceTurnOptions = {}): Promise<boolean> {
      if (!gameStore.runId && !(await startDevRun())) return false
      const preset = OUTCOME_PRESET[outcome]
      const fixture: TurnFixture = {
          figureName: DEV_FIGURE.name,
          era: DEV_FIGURE_ERA,
          persona: 'Queen of Egypt',
          message: 'A bold notion — I shall set it in motion.',
          action: 'Cleopatra acts decisively on the idea.',
          craft: opts.craft ?? 'sound',
          craftReason: 'A dev-forced craft grade.',
          continuity: opts.continuity ?? 'neutral',
          roll: preset.roll,
          headline: `${outcome}: the timeline answers`,
          detail: 'A dev-forced ripple, resolved through the real mechanics.',
          progressChange: preset.progressChange,
          valence: preset.progressChange > 0 ? 'positive' : preset.progressChange < 0 ? 'negative' : 'neutral',
          anachronism: opts.anachronism ?? 'in-period',
          chronicleTitle: DEV_CHRONICLE.title,
          chronicleParagraphs: DEV_CHRONICLE.paragraphs
      }
      // Let rapid dev clicks through (skip the 1s cooldown) and keep the run playable.
      gameStore.$patch({ isRateLimited: false, lastMessageTime: null })
      if (!opts.staked) {
          if (gameStore.gameStatus !== 'playing') gameStore.$patch({ gameStatus: 'playing' })
          if (gameStore.remainingMessages <= 0) gameStore.$patch({ remainingMessages: 5 })
      }
      await armFixtures(fixture)
      return gameStore.sendMessage('A dev-forced dispatch to history.', DEV_FIGURE.name, { stake: opts.staked })
  }
248 
  /** Set up the stake offer, then fire the final dispatch staked (real doubling). */
  async function forceStakedTurn(outcome: DiceOutcome = DiceOutcome.SUCCESS, opts: ForceTurnOptions = {}): Promise<boolean> {
      if (!gameStore.runId && !(await startDevRun())) return false
      setupStakeOffer()
      return forceTurn(outcome, { ...opts, staked: true })
  }
255 
  // ---------- the live inspector ----------
⋯ 34 lines hidden (lines 257–290)257 
  const inspector = computed(() => {
      const lastAi = [...gameStore.messageHistory].reverse().find(m => m.sender === 'ai' && m.diceRoll != null)
      const mod = lastAi?.rollModifier
      const rollLine = lastAi
          ? `${lastAi.naturalRoll ?? lastAi.diceRoll}${mod ? (mod > 0 ? `+${mod}` : `${mod}`) : ''} → ${lastAi.diceRoll} · ${lastAi.diceOutcome}`
          : '—'
      return {
          gameStatus: gameStore.gameStatus,
          objectiveProgress: gameStore.objectiveProgress,
          remainingMessages: gameStore.remainingMessages,
          momentum: gameStore.momentum,
          runEpoch: gameStore.runEpoch,
          ledgerCount: gameStore.timelineEvents.length,
          lastRoll: rollLine,
          runId: gameStore.runId ? `${gameStore.runId.slice(0, 8)}…` : '(none)',
          canStake: gameStore.canStake,
          isLoading: gameStore.isLoading
      }
  })
277 
  return {
      inspector,
      // stage jumps
      jumpToVictory, jumpToDefeat, seedMidGame, setupStakeOffer, toMissionSelect,
      // knobs
      setProgress, setRemaining, setMomentum,
      // setup
      autoFillFigure, startDevRun,
      // forced turns + fixtures
      forceTurn, forceStakedTurn, armFixtures, clearFixtures,
      DiceOutcome
  }
290}

armFixtures is the client half of the seam: it POSTs the TurnFixture to the dev-gated route before the turn fires.

composables/useDevTools.ts · 290 lines

composables/useDevTools.ts290 lines · TypeScript

⋯ 193 lines hidden (lines 1–193)1/**
* Developer-mode orchestration (issue #105).
*
* Two surfaces, one composable:
*
*   1. STATE JUMPS (client-only) — land on a stage to inspect it (victory, defeat, a
*      populated mid-game, the stake offer) and set knobs (progress / remaining /
*      momentum) directly. These never call the server, never charge a run, and never
*      spend: they drive the store the same way a resolved turn would.
*
*   2. FORCED TURNS (the faithful path) — fire the REAL `sendMessage` pipeline with
*      the AI seam scripted (via `/api/dev/fixtures`) and the die forced, so the swing
*      bands, anachronism amplifier, causal-chain decay, momentum, progress clamp,
*      win/lose, Spine append, and Chronicle all run for real, deterministically, with
*      no keys and no model spend. The turn still goes through the charged-run paywall
*      (one free dev run backs unlimited forced turns — the server has no per-run
*      message cap, and this panel keeps `remainingMessages` topped), so dev mode is
*      not a free-play bypass.
*
* All dev logic lives here (and in the gated server seam), never in the production
* store: state jumps use `$patch` + existing actions, so `stores/game.ts` is untouched.
*/
23import { computed } from 'vue'
24import { useGameStore } from '~/stores/game'
25import { listCuratedObjectives, type GameObjective } from '~/server/utils/objectives'
26import { DiceOutcome } from '~/utils/dice'
27import type { Craft } from '~/utils/craft'
28import type { Continuity } from '~/utils/continuity'
29import type { Anachronism } from '~/server/utils/anachronism'
30import type { GroundedFigure } from '~/server/utils/figure-grounding'
31import type { TurnFixture } from '~/utils/fixtures/turn-fixture'
32 
33/** A real, deceased figure so the server's own grounding gate resolves (it re-grounds
*  the name against Wikipedia; that needs no key and costs nothing). Cleopatra, 69–30 BC. */
35const DEV_FIGURE: GroundedFigure = {
  name: 'Cleopatra',
  resolved: true,
  description: 'Queen of Egypt, last of the Ptolemaic dynasty',
  born: { year: 69, bce: true, signed: -69, display: '69 BC' },
  died: { year: 30, bce: true, signed: -30, display: '30 BC' },
  living: false
42}
43const DEV_FIGURE_ERA = 'Alexandria, 48 BC'
44const DEV_FIGURE_WHEN = -40
45 
46/** Forced-die + base-swing per target band (natural d20; the craft modifier still
*  applies on top, and the server re-clamps the swing into the effective rolled band). */
48const OUTCOME_PRESET: Record<DiceOutcome, { roll: number; progressChange: number }> = {
  [DiceOutcome.CRITICAL_SUCCESS]: { roll: 20, progressChange: 45 },
  [DiceOutcome.SUCCESS]: { roll: 16, progressChange: 30 },
  [DiceOutcome.NEUTRAL]: { roll: 10, progressChange: 8 },
  [DiceOutcome.FAILURE]: { roll: 5, progressChange: -15 },
  [DiceOutcome.CRITICAL_FAILURE]: { roll: 1, progressChange: -35 }
54}
55 
56/** A few sample ledger entries to populate the Spine / end screen for inspection. */
57const SAMPLE_LEDGER = [
  { headline: 'Envoys redraw the map of power', detail: 'Egypt courts Rome ahead of schedule and the alliances shift.', diceRoll: 16, diceOutcome: DiceOutcome.SUCCESS, progressChange: 22, craft: 'sharp' as Craft, whenSigned: -44 },
  { headline: 'The great library is spared the flames', detail: 'Scrolls that history lost are copied and sent abroad for safekeeping.', diceRoll: 11, diceOutcome: DiceOutcome.NEUTRAL, progressChange: 8, craft: 'sound' as Craft, whenSigned: -42 },
  { headline: 'A rival faction takes offense', detail: 'The senate bristles at Alexandria\'s new confidence, and knives are sharpened.', diceRoll: 4, diceOutcome: DiceOutcome.FAILURE, progressChange: -9, craft: 'vague' as Craft, whenSigned: -40 }
61]
62 
63export interface ForceTurnOptions {
  craft?: Craft
  continuity?: Continuity
  anachronism?: Anachronism
  staked?: boolean
68}
69 
70export function useDevTools() {
  const gameStore = useGameStore()
72 
  /** The dev objective — anchored near Cleopatra so the causal chain reads strong. */
  function devObjective(): GameObjective {
      const all = listCuratedObjectives()
      return all.find(o => o.anchorYear === -48) ?? all[0]
  }
78 
  /** Set the current objective WITHOUT charging a run (for offline inspection). */
  function ensureObjective() {
      if (!gameStore.currentObjective) {
          gameStore.$patch({ currentObjective: devObjective() })
      }
  }
85 
  /** Point the composer at a known, grounded, deceased figure — no /api/figure call. */
  function autoFillFigure() {
      gameStore.registerFigure({ name: DEV_FIGURE.name, era: DEV_FIGURE_ERA, descriptor: 'Queen of Egypt' })
      gameStore.setActiveFigure(DEV_FIGURE.name)
      gameStore.$patch({
          figureGrounding: DEV_FIGURE,
          contactWhen: DEV_FIGURE_WHEN,
          contactMoment: null,
          groundingLoading: false
      })
  }
97 
  /** Seed up to `n` sample changes onto the Spine (skips if the ledger already has any). */
  function seedLedger(n: number) {
      if (gameStore.timelineEvents.length) return
      SAMPLE_LEDGER.slice(0, n).forEach(s =>
          gameStore.addTimelineEvent({
              figureName: DEV_FIGURE.name,
              era: DEV_FIGURE_ERA,
              headline: s.headline,
              detail: s.detail,
              diceRoll: s.diceRoll,
              diceOutcome: s.diceOutcome,
              progressChange: s.progressChange,
              craft: s.craft,
              whenSigned: s.whenSigned
          })
      )
  }
115 
  const DEV_CHRONICLE = {
      title: 'A History Being Rewritten',
      paragraphs: [
          'In this telling, a stranger\'s dispatches have bent the course of events.',
          'What was settled now wavers, and the world leans toward an unfamiliar shape.'
      ]
  }
123 
  // ---------- state jumps (client-only) ----------
125 
  function jumpToVictory() {
      ensureObjective()
      seedLedger(3)
      gameStore.$patch({
          objectiveProgress: 100,
          remainingMessages: 2,
          momentum: 3,
          gameStatus: 'victory',
          chronicle: { title: 'A World Remade', paragraphs: DEV_CHRONICLE.paragraphs },
          epiloguePending: false
      })
  }
138 
  function jumpToDefeat() {
      ensureObjective()
      seedLedger(2)
      gameStore.$patch({
          objectiveProgress: 38,
          remainingMessages: 0,
          momentum: 0,
          gameStatus: 'defeat',
          chronicle: { title: 'The Tide Held', paragraphs: DEV_CHRONICLE.paragraphs },
          epiloguePending: false
      })
  }
151 
  function seedMidGame() {
      ensureObjective()
      autoFillFigure()
      seedLedger(2)
      gameStore.$patch({
          objectiveProgress: 36,
          remainingMessages: 3,
          momentum: 2,
          gameStatus: 'playing',
          chronicle: DEV_CHRONICLE
      })
  }
164 
  /** Final message, win out of normal reach → `canStake` becomes true and the
   *  inline stake control renders for inspection. */
  function setupStakeOffer() {
      ensureObjective()
      autoFillFigure()
      seedLedger(1)
      gameStore.$patch({
          objectiveProgress: 20,
          remainingMessages: 1,
          momentum: 1,
          gameStatus: 'playing',
          chronicle: DEV_CHRONICLE
      })
  }
179 
  /** Back to the mission-select briefing (a full reset). */
  function toMissionSelect() {
      gameStore.resetGame()
  }
184 
  // ---------- knob setters (client-only) ----------
186 
  const clamp = (n: number, lo: number, hi: number) => Math.max(lo, Math.min(hi, Math.round(n)))
  function setProgress(n: number) { gameStore.$patch({ objectiveProgress: clamp(n, 0, 100) }) }
  function setRemaining(n: number) { gameStore.$patch({ remainingMessages: clamp(n, 0, 5) }) }
  function setMomentum(n: number) { gameStore.$patch({ momentum: clamp(n, 0, 4) }) }
191 
  // ---------- the fixture AI lane (server-gated) ----------
193 
  async function armFixtures(fixture: TurnFixture): Promise<void> {
      await $fetch('/api/dev/fixtures', { method: 'POST', body: { fixture } })
  }
  async function clearFixtures(): Promise<void> {
      await $fetch('/api/dev/fixtures', { method: 'POST', body: { clear: true } })
  }
200 
  // ---------- forced turns (the real pipeline) ----------
202 
  /** Commit a charged dev run + an objective + a figure, so forced turns can fire.
⋯ 87 lines hidden (lines 204–290)204     *  Returns false (and leaves a store error) if the device is out of runs. */
  async function startDevRun(): Promise<boolean> {
      const ok = await gameStore.chooseObjective(devObjective())
      if (!ok) return false
      autoFillFigure()
      gameStore.$patch({ remainingMessages: 5, objectiveProgress: 0, momentum: 0, timelineEvents: [] })
      return true
  }
212 
  /**
   * Fire one forced turn through the real `sendMessage`. Scripts the four AI layers
   * + the die for the chosen band, then sends — the swing, progress, Spine, momentum,
   * and Chronicle all resolve for real. Ensures a charged run first.
   */
  async function forceTurn(outcome: DiceOutcome, opts: ForceTurnOptions = {}): Promise<boolean> {
      if (!gameStore.runId && !(await startDevRun())) return false
      const preset = OUTCOME_PRESET[outcome]
      const fixture: TurnFixture = {
          figureName: DEV_FIGURE.name,
          era: DEV_FIGURE_ERA,
          persona: 'Queen of Egypt',
          message: 'A bold notion — I shall set it in motion.',
          action: 'Cleopatra acts decisively on the idea.',
          craft: opts.craft ?? 'sound',
          craftReason: 'A dev-forced craft grade.',
          continuity: opts.continuity ?? 'neutral',
          roll: preset.roll,
          headline: `${outcome}: the timeline answers`,
          detail: 'A dev-forced ripple, resolved through the real mechanics.',
          progressChange: preset.progressChange,
          valence: preset.progressChange > 0 ? 'positive' : preset.progressChange < 0 ? 'negative' : 'neutral',
          anachronism: opts.anachronism ?? 'in-period',
          chronicleTitle: DEV_CHRONICLE.title,
          chronicleParagraphs: DEV_CHRONICLE.paragraphs
      }
      // Let rapid dev clicks through (skip the 1s cooldown) and keep the run playable.
      gameStore.$patch({ isRateLimited: false, lastMessageTime: null })
      if (!opts.staked) {
          if (gameStore.gameStatus !== 'playing') gameStore.$patch({ gameStatus: 'playing' })
          if (gameStore.remainingMessages <= 0) gameStore.$patch({ remainingMessages: 5 })
      }
      await armFixtures(fixture)
      return gameStore.sendMessage('A dev-forced dispatch to history.', DEV_FIGURE.name, { stake: opts.staked })
  }
248 
  /** Set up the stake offer, then fire the final dispatch staked (real doubling). */
  async function forceStakedTurn(outcome: DiceOutcome = DiceOutcome.SUCCESS, opts: ForceTurnOptions = {}): Promise<boolean> {
      if (!gameStore.runId && !(await startDevRun())) return false
      setupStakeOffer()
      return forceTurn(outcome, { ...opts, staked: true })
  }
255 
  // ---------- the live inspector ----------
257 
  const inspector = computed(() => {
      const lastAi = [...gameStore.messageHistory].reverse().find(m => m.sender === 'ai' && m.diceRoll != null)
      const mod = lastAi?.rollModifier
      const rollLine = lastAi
          ? `${lastAi.naturalRoll ?? lastAi.diceRoll}${mod ? (mod > 0 ? `+${mod}` : `${mod}`) : ''} → ${lastAi.diceRoll} · ${lastAi.diceOutcome}`
          : '—'
      return {
          gameStatus: gameStore.gameStatus,
          objectiveProgress: gameStore.objectiveProgress,
          remainingMessages: gameStore.remainingMessages,
          momentum: gameStore.momentum,
          runEpoch: gameStore.runEpoch,
          ledgerCount: gameStore.timelineEvents.length,
          lastRoll: rollLine,
          runId: gameStore.runId ? `${gameStore.runId.slice(0, 8)}…` : '(none)',
          canStake: gameStore.canStake,
          isLoading: gameStore.isLoading
      }
  })
277 
  return {
      inspector,
      // stage jumps
      jumpToVictory, jumpToDefeat, seedMidGame, setupStakeOffer, toMissionSelect,
      // knobs
      setProgress, setRemaining, setMomentum,
      // setup
      autoFillFigure, startDevRun,
      // forced turns + fixtures
      forceTurn, forceStakedTurn, armFixtures, clearFixtures,
      DiceOutcome
  }
290}

The panel, the mount, and the gate

The panel is just the surface over that composable: an inspector readout, the stage jumps, the knobs, and the forced-turn controls. It self-gates in its script — the same import.meta.dev || config.public.devMode condition — so in a normal prod build the whole component tree-shakes away.

The client gate mirrors the server's devModeEnabled().

components/DevPanel.vue · 289 lines

components/DevPanel.vue289 lines · Vue

⋯ 103 lines hidden (lines 1–103)1<template>
<div v-if="enabled" class="dev-root" data-testid="dev-panel">
  <!-- Collapsed: a small floating tab. Deliberately garish so it's never mistaken
       for player chrome — it ships only in dev / staging, never to players. -->
  <button v-if="!open" type="button" class="dev-fab" data-testid="dev-panel-toggle"
    title="Developer mode (issue #105)" @click="open = true">🛠 DEV</button>
7 
  <section v-else class="dev-card" aria-label="Developer mode">
    <header class="dev-head">
      <span class="dev-title">🛠 Dev mode</span>
      <button type="button" class="dev-x" aria-label="Close dev panel" @click="open = false">✕</button>
    </header>
13 
    <!-- Live inspector -->
    <div class="dev-grid" data-testid="dev-inspector">
      <span>status</span><b>{{ inspector.gameStatus }}</b>
      <span>progress</span><b>{{ inspector.objectiveProgress }}%</b>
      <span>messages</span><b>{{ inspector.remainingMessages }}</b>
      <span>momentum</span><b>{{ inspector.momentum }}</b>
      <span>ledger</span><b>{{ inspector.ledgerCount }}</b>
      <span>epoch</span><b>{{ inspector.runEpoch }}</b>
      <span>run</span><b>{{ inspector.runId }}</b>
      <span>canStake</span><b>{{ inspector.canStake ? 'yes' : 'no' }}</b>
      <span>last roll</span><b class="dev-roll">{{ inspector.lastRoll }}</b>
    </div>
26 
    <!-- Stage jumps (client-only, no run, no spend) -->
    <p class="dev-legend">Jump to stage</p>
    <div class="dev-row">
      <button type="button" @click="dev.jumpToVictory()">Victory</button>
      <button type="button" @click="dev.jumpToDefeat()">Defeat</button>
      <button type="button" @click="dev.seedMidGame()">Mid-game</button>
      <button type="button" @click="dev.setupStakeOffer()">Stake offer</button>
      <button type="button" @click="dev.toMissionSelect()">Mission select</button>
    </div>
36 
    <!-- Direct knobs -->
    <p class="dev-legend">Set knobs</p>
    <div class="dev-knobs">
      <label>progress <input v-model.number="progress" type="number" min="0" max="100"
        @change="dev.setProgress(progress)"></label>
      <label>messages <input v-model.number="remaining" type="number" min="0" max="5"
        @change="dev.setRemaining(remaining)"></label>
      <label>momentum <input v-model.number="momentum" type="number" min="0" max="4"
        @change="dev.setMomentum(momentum)"></label>
    </div>
47 
    <!-- Forced turns through the REAL pipeline (deterministic AI seam + die) -->
    <p class="dev-legend">Force a turn <small>(real pipeline · charged run · no spend)</small></p>
    <div class="dev-tunables">
      <label>craft
        <select v-model="craft">
          <option v-for="c in CRAFT_LEVELS" :key="c" :value="c">{{ c }}</option>
        </select>
      </label>
      <label>continuity
        <select v-model="continuity">
          <option v-for="c in CONTINUITY_LEVELS" :key="c" :value="c">{{ c }}</option>
        </select>
      </label>
      <label>anachronism
        <select v-model="anachronism">
          <option v-for="a in ANACHRONISM_LEVELS" :key="a" :value="a">{{ a }}</option>
        </select>
      </label>
    </div>
    <div class="dev-row">
      <button type="button" :disabled="busy" @click="fire(dev.DiceOutcome.CRITICAL_SUCCESS)">Crit success</button>
      <button type="button" :disabled="busy" @click="fire(dev.DiceOutcome.SUCCESS)">Success</button>
      <button type="button" :disabled="busy" @click="fire(dev.DiceOutcome.NEUTRAL)">Neutral</button>
      <button type="button" :disabled="busy" @click="fire(dev.DiceOutcome.FAILURE)">Failure</button>
      <button type="button" :disabled="busy" @click="fire(dev.DiceOutcome.CRITICAL_FAILURE)">Crit fail</button>
    </div>
    <div class="dev-row">
      <button type="button" :disabled="busy" @click="fireStaked()">⚑ Staked turn</button>
      <button type="button" :disabled="busy" @click="run('start')">Start dev run</button>
      <button type="button" @click="dev.clearFixtures()">Clear AI fixtures</button>
    </div>
79 
    <p v-if="note" class="dev-note" data-testid="dev-note">{{ note }}</p>
  </section>
</div>
83</template>
84 
85<script setup lang="ts">
86/**
* The developer-mode panel (issue #105). A floating, client-only overlay that drives
* the game store: jump to any stage, set knobs, and fire forced turns through the real
* `sendMessage` pipeline with the AI seam scripted deterministically (no keys, no
* spend). All logic lives in `useDevTools`; this is just the surface.
*
* Gated on `import.meta.dev || $config.public.devMode` — tree-shaken out of a normal
* production build, optionally enabled on a deployed staging preview. Never shipped to
* players. Mounted once in pages/play.vue inside <ClientOnly>, floating above the
* end-screen takeover (z-60 > z-50).
*/
97import { ref } from 'vue'
98import { useDevTools } from '~/composables/useDevTools'
99import { CRAFT_LEVELS } from '~/utils/craft'
100import { CONTINUITY_LEVELS } from '~/utils/continuity'
101import { ANACHRONISM_LEVELS } from '~/server/utils/anachronism'
102import type { Craft } from '~/utils/craft'
103import type { Continuity } from '~/utils/continuity'
104import type { Anachronism } from '~/server/utils/anachronism'
105import type { DiceOutcome } from '~/utils/dice'
106 
107const config = useRuntimeConfig()
108const enabled = import.meta.dev || config.public.devMode === true
109 
110const dev = useDevTools()
111const { inspector } = dev
112 
113const open = ref(false)
114const busy = ref(false)
115const note = ref('')
116 
⋯ 173 lines hidden (lines 117–289)117const progress = ref(50)
118const remaining = ref(3)
119const momentum = ref(0)
120const craft = ref<Craft>('sound')
121const continuity = ref<Continuity>('neutral')
122const anachronism = ref<Anachronism>('in-period')
123 
124async function fire(outcome: DiceOutcome) {
  busy.value = true
  note.value = ''
  try {
      const ok = await dev.forceTurn(outcome, { craft: craft.value, continuity: continuity.value, anachronism: anachronism.value })
      note.value = ok ? `Fired ${outcome}.` : 'Turn did not resolve (out of runs? see the board).'
  } finally {
      busy.value = false
  }
133}
134 
135async function fireStaked() {
  busy.value = true
  note.value = ''
  try {
      const ok = await dev.forceStakedTurn(dev.DiceOutcome.SUCCESS, { craft: craft.value, continuity: continuity.value, anachronism: anachronism.value })
      note.value = ok ? 'Fired a staked turn.' : 'Staked turn did not resolve (out of runs?).'
  } finally {
      busy.value = false
  }
144}
145 
146async function run(_: 'start') {
  busy.value = true
  note.value = ''
  try {
      const ok = await dev.startDevRun()
      note.value = ok ? 'Dev run started (objective + figure set).' : 'Could not start a run (out of free runs — restart the dev server).'
  } finally {
      busy.value = false
  }
155}
156</script>
157 
158<style scoped>
dev-root {
  position: fixed;
  right: 12px;
  bottom: 12px;
  z-index: 60;
  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
  font-size: 11px;
166}
dev-fab {
  background: #1b1033;
  color: #ffd166;
  border: 1px solid #ffd166;
  border-radius: 8px;
  padding: 6px 10px;
  cursor: pointer;
  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.4);
  letter-spacing: 0.05em;
176}
dev-card {
  width: 280px;
  max-height: 80vh;
  overflow-y: auto;
  background: rgba(20, 14, 38, 0.97);
  color: #e8e0ff;
  border: 1px solid #ffd166;
  border-radius: 10px;
  padding: 10px 12px;
  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.5);
187}
dev-head {
  display: flex;
  align-items: center;
  justify-content: space-between;
  margin-bottom: 8px;
193}
dev-title {
  color: #ffd166;
  font-weight: 700;
  letter-spacing: 0.05em;
198}
dev-x {
  background: none;
  border: none;
  color: #e8e0ff;
  cursor: pointer;
  font-size: 13px;
205}
dev-grid {
  display: grid;
  grid-template-columns: auto 1fr;
  gap: 1px 8px;
  background: rgba(0, 0, 0, 0.25);
  border-radius: 6px;
  padding: 6px 8px;
  margin-bottom: 8px;
214}
dev-grid span {
  color: #a99fd0;
217}
dev-grid b {
  text-align: right;
220}
dev-roll {
  font-size: 10px;
223}
dev-legend {
  color: #ffd166;
  margin: 8px 0 4px;
  text-transform: uppercase;
  letter-spacing: 0.06em;
  font-size: 10px;
230}
dev-legend small {
  text-transform: none;
  letter-spacing: 0;
  color: #a99fd0;
235}
dev-row {
  display: flex;
  flex-wrap: wrap;
  gap: 4px;
  margin-bottom: 4px;
241}
dev-row button {
  flex: 1 1 auto;
  background: #2a1d4d;
  color: #e8e0ff;
  border: 1px solid #4a3a78;
  border-radius: 6px;
  padding: 5px 7px;
  cursor: pointer;
  white-space: nowrap;
251}
dev-row button:hover:not(:disabled) {
  border-color: #ffd166;
254}
dev-row button:disabled {
  opacity: 0.5;
  cursor: progress;
258}
dev-knobs,
dev-tunables {
  display: flex;
  flex-wrap: wrap;
  gap: 6px;
  margin-bottom: 4px;
265}
dev-knobs label,
dev-tunables label {
  display: flex;
  flex-direction: column;
  gap: 2px;
  color: #a99fd0;
  flex: 1 1 30%;
273}
dev-knobs input,
dev-tunables select {
  background: #140e26;
  color: #e8e0ff;
  border: 1px solid #4a3a78;
  border-radius: 5px;
  padding: 3px 5px;
  font-family: inherit;
  font-size: 11px;
283}
dev-note {
  margin-top: 8px;
  color: #9be39b;
  font-size: 10px;
288}
289</style>

It mounts once on the play page, inside <ClientOnly>, beside the existing coach-mark overlay — so it floats across every stage.

pages/play.vue · 617 lines

pages/play.vue617 lines · Vue

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

The staging opt-in is the first runtimeConfig.public entry: one env var, REVISIONIST_DEV_MODE, read by both the client panel (via config.public.devMode) and the server gate (via process.env), so the two never disagree.

nuxt.config.ts · 81 lines

nuxt.config.ts81 lines · TypeScript

⋯ 63 lines hidden (lines 1–63)1/**
* Nuxt 3 Configuration
* https://nuxt.com/docs/api/configuration/nuxt-config
*/
5export default defineNuxtConfig({
// Ensure compatibility with modern Nuxt features
compatibilityDate: '2025-05-15',
8 
// Enable devtools for development
devtools: { enabled: true },
11 
// Register required modules
modules: ['@nuxt/ui', '@pinia/nuxt', '@nuxtjs/supabase'],
14 
// Supabase Auth (accounts). Anonymous-first: every visitor gets an anonymous
// user so the balance keys on a real user id from the first second; signing in
// with a magic link upgrades that same user in place (balance carries over).
// redirect:false — we DON'T gate play behind sign-in (anonymous play is the
// free-trial hook); buying is what requires an account. It also means the module
// registers no /confirm callback route, so the magic-link return is finalized in
// pages/play.vue (see utils/auth-return.ts). For that return to arrive, the
// Supabase project's Auth → URL Configuration → Redirect URLs must allowlist the
// deployed origin's /play (e.g. https://<origin>/play); otherwise Supabase falls
// back to the Site URL and the link never reaches the handler. The client key is
// the PUBLISHABLE key (safe to ship); the service key stays server-only in the
// balance store. Placeholders keep `nuxt build` working in CI without secrets;
// the real values come from NUXT_PUBLIC_SUPABASE_URL / _KEY at runtime.
supabase: {
  url: process.env.SUPABASE_URL || 'https://placeholder.supabase.co',
  key: process.env.SUPABASE_PUBLISHABLE_KEY || 'sb_publishable_placeholder',
  redirect: false,
  // We don't use generated DB types (the balance store talks to Supabase with the
  // service client directly); disable the lookup so the module doesn't warn.
  types: false
},
36 
// Global CSS imports
css: ['~/assets/css/main.css'],
39 
// Color mode (via @nuxtjs/color-mode, bundled with @nuxt/ui). classSuffix '' so the
// class on <html> is exactly `dark` / `light` — what the .dark token block and
// Tailwind's dark: variant key off. Defaulting to `system` respects the OS pref, and
// the module's inline no-flash script + cookie persistence replace the old manual
// classList toggle (which didn't persist and could FOUC).
colorMode: {
  classSuffix: '',
  preference: 'system',
  fallback: 'light'
},
50 
// Runtime configuration
runtimeConfig: {
  // Private keys (only available on server-side)
  openaiApiKey: process.env.OPENAI_API_KEY,
  anthropicApiKey: process.env.ANTHROPIC_API_KEY,
  // Supabase — the run store (server-side only). Absent → in-memory dev store.
  supabaseUrl: process.env.SUPABASE_URL,
  supabaseSecretKey: process.env.SUPABASE_SECRET_KEY,
  // Stripe — run packs (server-side only). Absent → checkout returns 503.
  stripeSecretKey: process.env.STRIPE_SECRET_KEY,
  stripeWebhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
  // Canonical site origin for Stripe redirect URLs (never the client Host header).
  siteUrl: process.env.REVISIONIST_BASE_URL,
  // Public keys (exposed to client-side)
  public: {
    // Developer mode (issue #105). A dev build always has it (`import.meta.dev`);
    // this flag additionally opts a DEPLOYED staging preview in. Never set in
    // production. The server gates the fixture lane on the same env var, so the
    // client panel and the server seam agree on one source of truth.
    devMode: process.env.REVISIONIST_DEV_MODE === 'true'
  }
},
⋯ 9 lines hidden (lines 73–81)73 
// The standalone agents/ tooling package has its own deps + tsconfig; keep it
// out of the app's type program so `nuxt typecheck` never compiles the loops.
typescript: {
  tsConfig: {
    exclude: ['../agents']
  }
}
81})

Verification

The full unit suite stays green at 872 tests (19 new), and nuxt typecheck is clean. The new tests pin the load-bearing pieces: the dev gate (the prod-bypass guard), the gateway fixture branch including its no-cost telemetry, the shared fixture shape, and the state-jump recipes.

Beyond the suite, the real pipeline was driven end to end against a booted dev server with no API keys: a forced crit-success landed +45 through the real bands with the real causal-chain read; a forced failure with impossible anachronism widened −15 to −30 via the real loss amplifier; and the Chronicle resolved from the same armed fixture. The panel renders, and the victory and stake-offer jumps land the real stages.