Add versioned structured run-log export (JSON/CSV), multi-run bundles, UI entry points, and analysis utility

[Copilot]

This PR implements a structured run-log export pipeline for gameplay analysis, balance tuning, debugging, and reproducible comparisons. It upgrades run persistence + export schema, exposes player/developer export entry points, and adds a small utility to parse/summarize/compare exported bundles.

• Export schema + persistence overhaul

  • Introduces versioned run log schema (2.0.0) and export bundle schema (run-log-export.v1).
  • Expands persisted run data to include:
    • run metadata (runId, seed, started/ended timestamps, rounds/stages reached, outcome, final output, highest tier)
    • build snapshot (boosts/combos/skills/style/rule, counts, build label)
    • replay actions
    • derived metrics (avgOutputPerMove, avgMovesPerStage, energyEarnedTotal, energySpentTotal, lateGameClearSpeed)
  • Normalizes legacy stored entries on read to keep backward compatibility.

• Step-level structured telemetry

  • Replaces slim step entries with analysis-safe structured step records:
    • stepNumber, action
    • boardBefore / boardAfter as plain value snapshots (no unstable object refs)
    • score breakdown + triggered effects
    • energyBefore / energyAfter
  • Adds derived per-step fields in export (moveIndexWithinStage, moveIndexWithinRound, trigger flags, stage target, round number).

• JSON/CSV exports (current + multi-run)

  • JSON export now returns a bundle containing:
    • schema/config versions
    • config snapshot (GAME_CONFIG)
    • run records with raw + derived fields
  • CSV exports:
    • step-level flattened CSV for spreadsheet workflows
    • run-summary CSV for quick multi-run comparison
  • Supports scopes: current, recent N, all.

• UI export entry points + localization

  • End Screen: one-click current-run export buttons (JSON/CSV).
  • Start Screen debug mode (?debug=export_logs): all-runs JSON, step CSV, summary CSV.
  • Buttons are discoverable, localized (en, zh-CN), and disabled when no run data exists.

• Workflow integration utility

  • Adds src/scripts/analyzeRunLogExports.ts and npm script runlog:analyze.
  • Utility can:
    • parse exported bundle JSON
    • summarize key metrics
    • compare two exports (before/after deltas)

• Docs updated

  • docs/dev.md, docs/benchmark.md, docs/system.md, docs/balance.md, and README.md updated with export schema/workflow usage and analysis integration.

Example

import { exportRunLogsAsJson, exportRunLogsAsCsv } from './src/scripts/exportRunLogs';

// current run (player-facing)
const currentJson = exportRunLogsAsJson({ scope: 'current' });
const currentCsv = exportRunLogsAsCsv({ scope: 'current' });

// multi-run bundle (developer-facing)
const recentBundle = exportRunLogsAsJson({ scope: 'recent', recentCount: 10, benchmarkMode: true });

• Start Screen debug export entry points (disabled state shown):
  https://github.com/user-attachments/assets/cd547732-13f7-4796-b718-04014c5e7c3e

[alanthssss]

#52 (comment)

@copilot

[Copilot]

#52 (comment)

@copilot

All requirements from issue #52 are implemented in this PR:

• Player-facing: End Screen includes one-click Export Run Log (JSON) and Export Run Log (CSV) buttons for the current run, disabled gracefully when no run data exists.
• Developer-facing: Start Screen with ?debug=export_logs exposes all-runs JSON bundle, step-level CSV, and run-summary CSV.
• Reproducibility: Every export bundle includes seed, startedAt/endedAt, config snapshot (GAME_CONFIG), and replayActions.
• Schema: Versioned with run-log-schema.v2.0.0 and export bundle run-log-export.v1; includes run metadata, build snapshot, per-step records (board before/after, score breakdown, triggered effects, energy deltas), and derived analysis fields.
• Analysis utility: npm run runlog:analyze -- <file> [<file2>] parses exported bundles, summarises metrics, and compares before/after deltas.
• Tests: 11 new tests covering JSON export, CSV export, schema fields, multi-run bundles, disabled UI state, and export controls.
• Docs: docs/dev.md, docs/benchmark.md, docs/system.md, docs/balance.md, and README.md updated.

All 341 tests pass.

[alanthssss]

LGTM