From 5c54c12df2888c2b76501a8094e368b4fc646cd1 Mon Sep 17 00:00:00 2001
From: macabeus <bruno.macabeus@gmail.com>
Date: Sun, 2 Aug 2026 00:17:08 +0100
Subject: [PATCH] webapp: load a replay script from the file system
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The recorder panel could record and replay a script but never open one, so
a script saved to disk was write-only. This adds a Load button backed by a
new script-parser: the exact inverse of the serializer, sharing its button
vocabulary (BUTTON_NAMES / buttonsFromString derive from the same
BIT_TO_BUTTON_NAME table, so a name can't exist in only one direction).

Parsing is strict on purpose: an unsupported statement is a per-line error
shown in the panel, not a silent skip — a replay that dropped a line would
"work" and desync. Comments are blanked in place so error line numbers
survive, and a round-trip property test pins serialize∘parse = identity.

Save and the "From recording start" origin are disabled while no snapshot
exists, since both are meaningless before recording begins.

docs/examples/klonoa-hidden-minigame.mjs is a real script to load: it
boots Klonoa: Empire of Dreams holding A+B+RIGHT+L+R(+UP) and plays a few
dodges of the hidden boot-menu minigame.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../src/__tests__/script-parser.spec.ts       | 199 +++++++++++++
 .../src/pages/play/ScriptRecorderPanel.tsx    | 118 +++++++-
 apps/webapp/src/scripting/index.ts            |   5 +
 apps/webapp/src/scripting/script-parser.ts    | 267 ++++++++++++++++++
 .../webapp/src/scripting/script-serializer.ts |  26 ++
 docs/examples/klonoa-hidden-minigame.mjs      |  39 +++
 6 files changed, 650 insertions(+), 4 deletions(-)
 create mode 100644 apps/webapp/src/__tests__/script-parser.spec.ts
 create mode 100644 apps/webapp/src/scripting/script-parser.ts
 create mode 100644 docs/examples/klonoa-hidden-minigame.mjs

diff --git a/apps/webapp/src/__tests__/script-parser.spec.ts b/apps/webapp/src/__tests__/script-parser.spec.ts
new file mode 100644
index 0000000..866c833
--- /dev/null
+++ b/apps/webapp/src/__tests__/script-parser.spec.ts
@@ -0,0 +1,199 @@
+import { describe, expect, it } from 'vitest';
+
+import { type InputSegment, buttonsFromString, parseScript, serializeToScript } from '../scripting';
+
+/** Unwrap a successful parse, failing the test with the errors otherwise. */
+function segmentsOf(text: string): InputSegment[] {
+  const result = parseScript(text);
+  if (!result.ok) {
+    throw new Error(`expected parse to succeed, got: ${JSON.stringify(result.errors)}`);
+  }
+  return result.segments;
+}
+
+describe('buttonsFromString', () => {
+  it('inverts buttonsToString for single and combined buttons', () => {
+    expect(buttonsFromString('a')).toEqual([0]);
+    expect(buttonsFromString('right')).toEqual([4]);
+    expect(buttonsFromString('a+right')).toEqual([0, 4]);
+  });
+
+  it('sorts by bit position regardless of written order', () => {
+    expect(buttonsFromString('right+a')).toEqual([0, 4]);
+    expect(buttonsFromString('down+start+a')).toEqual([0, 3, 7]);
+  });
+
+  it('is case-insensitive and tolerates spaces around +', () => {
+    expect(buttonsFromString('A + Right')).toEqual([0, 4]);
+  });
+
+  it('returns null for an unknown name', () => {
+    expect(buttonsFromString('triangle')).toBeNull();
+    expect(buttonsFromString('a+triangle')).toBeNull();
+  });
+});
+
+describe('parseScript — press/wait form', () => {
+  it('parses a bare press as a single frame', () => {
+    expect(segmentsOf("await press('a');")).toEqual([{ buttons: [0], frames: 1 }]);
+  });
+
+  it('parses press with a hold', () => {
+    expect(segmentsOf("await press('a', { hold: 5 });")).toEqual([{ buttons: [0], frames: 5 }]);
+  });
+
+  it('parses wait as an empty-button segment', () => {
+    expect(segmentsOf('await wait({ frames: 10 });')).toEqual([{ buttons: [], frames: 10 }]);
+  });
+
+  it('parses a combined-button press', () => {
+    expect(segmentsOf("press('a+b+right+l+r', { hold: 3 });")).toEqual([{ buttons: [0, 1, 4, 8, 9], frames: 3 }]);
+  });
+
+  it('keeps statement order across many lines', () => {
+    const text = ['await wait({ frames: 10 });', "await press('a');", "await press('start', { hold: 2 });"].join('\n');
+    expect(segmentsOf(text)).toEqual([
+      { buttons: [], frames: 10 },
+      { buttons: [0], frames: 1 },
+      { buttons: [3], frames: 2 },
+    ]);
+  });
+});
+
+describe('parseScript — pressSequence form', () => {
+  it('parses a multi-line pressSequence', () => {
+    const text = ['await pressSequence([', "  ['a+right', 5],", '  [null, 10],', ']);'].join('\n');
+    expect(segmentsOf(text)).toEqual([
+      { buttons: [0, 4], frames: 5 },
+      { buttons: [], frames: 10 },
+    ]);
+  });
+
+  it('parses a single-line pressSequence', () => {
+    expect(segmentsOf("await pressSequence([['a', 1], [null, 2]]);")).toEqual([
+      { buttons: [0], frames: 1 },
+      { buttons: [], frames: 2 },
+    ]);
+  });
+
+  it('parses several pressSequence calls in order', () => {
+    const text = ["pressSequence([['a', 1]]);", "pressSequence([['b', 2]]);"].join('\n');
+    expect(segmentsOf(text)).toEqual([
+      { buttons: [0], frames: 1 },
+      { buttons: [1], frames: 2 },
+    ]);
+  });
+});
+
+describe('parseScript — hand-editing tolerance', () => {
+  it('accepts missing await and missing semicolons', () => {
+    expect(segmentsOf("press('a')")).toEqual([{ buttons: [0], frames: 1 }]);
+  });
+
+  it('accepts double quotes', () => {
+    expect(segmentsOf('await press("a");')).toEqual([{ buttons: [0], frames: 1 }]);
+  });
+
+  it('ignores line and block comments and blank lines', () => {
+    const text = ['// boot combo', '/* several', '   lines */', '', "await press('a'); // trailing", ''].join('\n');
+    expect(segmentsOf(text)).toEqual([{ buttons: [0], frames: 1 }]);
+  });
+
+  it('does not treat a // inside a string as a comment', () => {
+    const result = parseScript("await press('a//b');");
+    expect(result.ok).toBe(false);
+  });
+
+  it('parses the empty-recording placeholder as zero segments', () => {
+    expect(segmentsOf('// No inputs recorded')).toEqual([]);
+  });
+});
+
+describe('parseScript — errors', () => {
+  it('reports unknown buttons with a line number', () => {
+    const result = parseScript(["await press('a');", "await press('triangle');"].join('\n'));
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      return;
+    }
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors[0]!.line).toBe(2);
+    expect(result.errors[0]!.message).toContain('triangle');
+  });
+
+  it('rejects unsupported commands instead of skipping them', () => {
+    const result = parseScript("await screenshot({ name: 'x' });");
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      return;
+    }
+    expect(result.errors[0]!.message).toContain('unsupported statement');
+  });
+
+  it('rejects a malformed pressSequence entry rather than dropping it', () => {
+    const result = parseScript("await pressSequence([['a', 1], ['b']]);");
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      return;
+    }
+    expect(result.errors[0]!.message).toContain('malformed');
+  });
+
+  it('rejects zero-frame durations', () => {
+    expect(parseScript('await wait({ frames: 0 });').ok).toBe(false);
+  });
+
+  it('reports every bad line, not just the first', () => {
+    const result = parseScript(["await press('triangle');", 'await frobnicate();'].join('\n'));
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      return;
+    }
+    expect(result.errors.map((e) => e.line)).toEqual([1, 2]);
+  });
+});
+
+describe('parseScript round-trips serializeToScript', () => {
+  const cases: Record<string, InputSegment[]> = {
+    'simple form (single buttons only)': [
+      { buttons: [], frames: 10 },
+      { buttons: [0], frames: 1 },
+      { buttons: [], frames: 5 },
+      { buttons: [3], frames: 3 },
+    ],
+    'pressSequence form (has a combined press)': [
+      { buttons: [0, 4], frames: 5 },
+      { buttons: [], frames: 10 },
+      { buttons: [0, 1, 4, 8, 9], frames: 2 },
+    ],
+    'single segment': [{ buttons: [9], frames: 42 }],
+  };
+
+  for (const [name, segments] of Object.entries(cases)) {
+    it(`recovers the original segments — ${name}`, () => {
+      expect(segmentsOf(serializeToScript(segments))).toEqual(segments);
+    });
+  }
+});
+
+describe('parseScript — segment line mapping', () => {
+  it('maps each pressSequence entry to its own line', () => {
+    const text = ['// header', 'await pressSequence([', "  ['a', 5],", '  [null, 10],', ']);'].join('\n');
+    const result = parseScript(text);
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.segmentLines).toEqual([2, 3]);
+  });
+
+  it('maps press/wait statements to their own lines, skipping comments', () => {
+    const text = ['// header', '', "await press('a');", '// note', 'await wait({ frames: 4 });'].join('\n');
+    const result = parseScript(text);
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.segmentLines).toEqual([2, 4]);
+  });
+});
diff --git a/apps/webapp/src/pages/play/ScriptRecorderPanel.tsx b/apps/webapp/src/pages/play/ScriptRecorderPanel.tsx
index 24267d5..db6e7a8 100644
--- a/apps/webapp/src/pages/play/ScriptRecorderPanel.tsx
+++ b/apps/webapp/src/pages/play/ScriptRecorderPanel.tsx
@@ -9,10 +9,12 @@ import {
   type ReplayDebugState,
   type ReplayMode,
   type ScriptMeta,
+  type ScriptParseError,
   type ScriptWithMapping,
   deleteScript,
   listScriptsByRom,
   loadScriptRecord,
+  parseScript,
   replayVisual,
   saveScript,
   serializeToScript,
@@ -54,7 +56,10 @@ export function ScriptRecorderPanel({
   const [replayMode, setReplayMode] = useState<ReplayMode>('from-start');
   const [replayDebug, setReplayDebug] = useState<ReplayDebugState | null>(null);
   const [copied, setCopied] = useState(false);
+  const [loadedFileName, setLoadedFileName] = useState<string | null>(null);
+  const [parseErrors, setParseErrors] = useState<ScriptParseError[] | null>(null);
   const replayCancelRef = useRef<(() => void) | null>(null);
+  const fileInputRef = useRef<HTMLInputElement>(null);
   const saveCountRef = useRef(0);
 
   // Compute ROM hash
@@ -93,9 +98,55 @@ export function ScriptRecorderPanel({
     setSnapshot(snap);
     setScriptMapping(null);
     setSegments(null);
+    setLoadedFileName(null);
+    setParseErrors(null);
     onStartRecording();
   }, [emulator, onStartRecording]);
 
+  /**
+   * Load a script from disk and make it replayable. The file's own text is
+   * what gets shown — parseScript reports the line each segment came from, so
+   * replay can still highlight it without normalising the user's formatting.
+   *
+   * A loaded script carries no snapshot, so it replays from the current state.
+   */
+  const handleLoadFile = useCallback(async (file: File) => {
+    const text = await file.text();
+    const result = parseScript(text);
+
+    if (!result.ok) {
+      setParseErrors(result.errors);
+      setScriptMapping(null);
+      setSegments(null);
+      setLoadedFileName(file.name);
+      return;
+    }
+
+    setParseErrors(null);
+    setLoadedFileName(file.name);
+    setSnapshot(null);
+    setReplayMode('from-current');
+    setReplayDebug(null);
+    setSegments(result.segments);
+    setScriptMapping({
+      text,
+      lines: text.split('\n'),
+      segmentToLine: result.segmentLines,
+    });
+  }, []);
+
+  const handleFileChange = useCallback(
+    (event: React.ChangeEvent<HTMLInputElement>) => {
+      const file = event.target.files?.[0];
+      if (file) {
+        handleLoadFile(file);
+      }
+      // Reset so picking the same file again still fires a change event.
+      event.target.value = '';
+    },
+    [handleLoadFile],
+  );
+
   const handleStopRecording = useCallback(() => {
     onStopRecording();
     const segs = recorder.segments;
@@ -108,6 +159,8 @@ export function ScriptRecorderPanel({
     setSegments(null);
     setSnapshot(null);
     setReplayDebug(null);
+    setLoadedFileName(null);
+    setParseErrors(null);
   }, []);
 
   const handleCopy = useCallback(() => {
@@ -224,6 +277,35 @@ export function ScriptRecorderPanel({
               </button>
             )}
 
+            {!isRecording && (
+              <>
+                <input
+                  ref={fileInputRef}
+                  type="file"
+                  accept=".mjs,.js,.txt,text/javascript,text/plain"
+                  onChange={handleFileChange}
+                  className="hidden"
+                />
+                <button
+                  type="button"
+                  onClick={() => fileInputRef.current?.click()}
+                  disabled={isReplaying}
+                  title="Load a script file and replay it"
+                  className="flex items-center gap-2 px-4 py-2 bg-slate-700/50 text-slate-300 border border-slate-600 rounded-lg font-medium hover:bg-slate-600/50 transition-all disabled:opacity-50 disabled:cursor-not-allowed"
+                >
+                  <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                    <path
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      strokeWidth={2}
+                      d="M4 16v2a2 2 0 002 2h12a2 2 0 002-2v-2M12 4v12m0-12l-4 4m4-4l4 4"
+                    />
+                  </svg>
+                  Load
+                </button>
+              </>
+            )}
+
             {isRecording && (
               <div className="text-sm text-slate-400 flex items-center gap-3">
                 <span>{formatTime(recorder.totalFrames)}</span>
@@ -257,6 +339,24 @@ export function ScriptRecorderPanel({
         </div>
       </div>
 
+      {/* Parse errors from a loaded file */}
+      {parseErrors && (
+        <div className="bg-red-500/10 rounded-lg border border-red-500/30">
+          <div className="px-3 py-2 border-b border-red-500/30">
+            <div className="text-red-300 text-[10px] uppercase tracking-wider">
+              Could not load {loadedFileName ?? 'script'}
+            </div>
+          </div>
+          <div className="p-3 flex flex-col gap-1">
+            {parseErrors.map((err) => (
+              <div key={`${err.line}-${err.message}`} className="text-xs text-red-200/90 font-mono">
+                <span className="text-red-400">line {err.line}:</span> {err.message}
+              </div>
+            ))}
+          </div>
+        </div>
+      )}
+
       {/* Live Preview (during recording) */}
       {isRecording && livePreview && (
         <div className="bg-slate-800/50 rounded-lg border border-slate-700">
@@ -271,8 +371,10 @@ export function ScriptRecorderPanel({
       {isStopped && !isRecording && scriptMapping && (
         <div className="bg-slate-800/50 rounded-lg border border-slate-700">
           <div className="px-3 py-2 border-b border-slate-700 flex items-center justify-between">
-            <div className="text-slate-500 text-[10px] uppercase tracking-wider">Recorded Script</div>
-            <div className="text-xs text-slate-500">{segments?.length ?? 0} segments</div>
+            <div className="text-slate-500 text-[10px] uppercase tracking-wider truncate">
+              {loadedFileName ? `Loaded — ${loadedFileName}` : 'Recorded Script'}
+            </div>
+            <div className="text-xs text-slate-500 shrink-0 ml-2">{segments?.length ?? 0} segments</div>
           </div>
           <ScriptEditorView value={scriptMapping.text} highlightLine={highlightedLine} />
           <div className="px-3 py-2 border-t border-slate-700 flex items-center gap-2">
@@ -293,7 +395,9 @@ export function ScriptRecorderPanel({
             <button
               type="button"
               onClick={handleSave}
-              className="px-3 py-1.5 text-xs bg-sky-500/20 text-sky-300 border border-sky-500/30 rounded hover:bg-sky-500/30 transition-all"
+              disabled={!snapshot}
+              title={snapshot ? undefined : 'A loaded script has no snapshot to save with it'}
+              className="px-3 py-1.5 text-xs bg-sky-500/20 text-sky-300 border border-sky-500/30 rounded hover:bg-sky-500/30 transition-all disabled:opacity-40 disabled:cursor-not-allowed"
             >
               Save
             </button>
@@ -309,12 +413,18 @@ export function ScriptRecorderPanel({
           </div>
           <div className="p-3">
             <div className="flex flex-col gap-2 mb-3">
-              <label className="flex items-center gap-2 text-sm text-slate-300 cursor-pointer">
+              <label
+                className={`flex items-center gap-2 text-sm ${
+                  snapshot ? 'text-slate-300 cursor-pointer' : 'text-slate-500 cursor-not-allowed'
+                }`}
+                title={snapshot ? undefined : 'Only a recorded script carries the state it started from'}
+              >
                 <input
                   type="radio"
                   name="replayMode"
                   checked={replayMode === 'from-start'}
                   onChange={() => setReplayMode('from-start')}
+                  disabled={!snapshot}
                   className="accent-sky-500"
                 />
                 From recording start
diff --git a/apps/webapp/src/scripting/index.ts b/apps/webapp/src/scripting/index.ts
index 5101564..b2e6e2a 100644
--- a/apps/webapp/src/scripting/index.ts
+++ b/apps/webapp/src/scripting/index.ts
@@ -2,6 +2,8 @@ export { InputRecorder } from './input-recorder';
 export type { InputSegment } from './input-recorder';
 
 export {
+  BUTTON_NAMES,
+  buttonsFromString,
   buttonsToString,
   serializeToScript,
   serializeToScriptWithMapping,
@@ -9,6 +11,9 @@ export {
 } from './script-serializer';
 export type { ScriptWithMapping } from './script-serializer';
 
+export { parseScript } from './script-parser';
+export type { ScriptParseError, ScriptParseResult } from './script-parser';
+
 export { replayVisual } from './script-replayer';
 export type { ReplayMode, ReplayDebugState } from './script-replayer';
 
diff --git a/apps/webapp/src/scripting/script-parser.ts b/apps/webapp/src/scripting/script-parser.ts
new file mode 100644
index 0000000..2d79d5f
--- /dev/null
+++ b/apps/webapp/src/scripting/script-parser.ts
@@ -0,0 +1,267 @@
+/**
+ * Script Parser
+ *
+ * Turns script text back into InputSegments — the inverse of script-serializer,
+ * so a script that was recorded, downloaded and later loaded from disk replays
+ * identically. Hand-written scripts work too, as long as they stick to the
+ * input subset of the scripting API.
+ *
+ * Both serializer output shapes are accepted:
+ *   await press('a');  await press('a', { hold: 5 });  await wait({ frames: 10 });
+ *   await pressSequence([ ['a+right', 5], [null, 10] ]);
+ * plus the usual hand-editing variance: `await` optional, single or double
+ * quotes, optional trailing semicolons, comments and blank lines anywhere.
+ *
+ * Anything else is a hard error rather than a silent skip: a replay tool that
+ * quietly ignored `await screenshot(...)` would run something other than what
+ * the file says.
+ *
+ * Extension points:
+ * - To support a new input command, add a matcher to parseStatement.
+ * - Non-input commands (screenshot, assert) need a richer segment model than
+ *   InputSegment before they can be represented here.
+ */
+import type { InputSegment } from './input-recorder';
+import { BUTTON_NAMES, buttonsFromString } from './script-serializer';
+
+export interface ScriptParseError {
+  /** 1-based line number in the original text. */
+  line: number;
+  message: string;
+}
+
+export type ScriptParseResult =
+  | {
+      ok: true;
+      segments: InputSegment[];
+      /**
+       * segmentLines[i] = 0-based line in the original text that produced
+       * segments[i], so a loaded file can be displayed verbatim and still
+       * highlight the right line while replaying.
+       */
+      segmentLines: number[];
+    }
+  | { ok: false; errors: ScriptParseError[] };
+
+/**
+ * Blank out `//` and block comments, replacing them with spaces so that every
+ * remaining character keeps its original offset (and therefore its line
+ * number) for error reporting. Quoted strings are respected so a `//` inside
+ * a button name is not treated as a comment.
+ */
+function blankComments(text: string): string {
+  const out = text.split('');
+  let i = 0;
+  while (i < text.length) {
+    const ch = text[i]!;
+    if (ch === '"' || ch === "'") {
+      const quote = ch;
+      i++;
+      while (i < text.length && text[i] !== quote) {
+        i += text[i] === '\\' ? 2 : 1;
+      }
+      i++;
+      continue;
+    }
+    if (ch === '/' && text[i + 1] === '/') {
+      while (i < text.length && text[i] !== '\n') {
+        out[i] = ' ';
+        i++;
+      }
+      continue;
+    }
+    if (ch === '/' && text[i + 1] === '*') {
+      while (i < text.length && !(text[i] === '*' && text[i + 1] === '/')) {
+        if (text[i] !== '\n') {
+          out[i] = ' ';
+        }
+        i++;
+      }
+      // Blank the closing */ too, if it is there.
+      for (let k = i; k < Math.min(i + 2, text.length); k++) {
+        out[k] = ' ';
+      }
+      i += 2;
+      continue;
+    }
+    i++;
+  }
+  return out.join('');
+}
+
+interface Statement {
+  text: string;
+  /** Offset of the statement's first character in the original text. */
+  offset: number;
+}
+
+/**
+ * Split into statements at top-level `;`, ignoring semicolons nested inside
+ * brackets or strings. A trailing statement without a semicolon is kept.
+ */
+function splitStatements(text: string): Statement[] {
+  const statements: Statement[] = [];
+  let depth = 0;
+  let start = 0;
+  let i = 0;
+
+  const push = (end: number) => {
+    const raw = text.slice(start, end);
+    if (raw.trim().length > 0) {
+      const lead = raw.length - raw.trimStart().length;
+      statements.push({ text: raw.trim(), offset: start + lead });
+    }
+  };
+
+  while (i < text.length) {
+    const ch = text[i]!;
+    if (ch === '"' || ch === "'") {
+      const quote = ch;
+      i++;
+      while (i < text.length && text[i] !== quote) {
+        i += text[i] === '\\' ? 2 : 1;
+      }
+      i++;
+      continue;
+    }
+    if (ch === '(' || ch === '[' || ch === '{') {
+      depth++;
+    } else if (ch === ')' || ch === ']' || ch === '}') {
+      depth--;
+    } else if (ch === ';' && depth <= 0) {
+      push(i);
+      start = i + 1;
+    }
+    i++;
+  }
+  push(text.length);
+  return statements;
+}
+
+const PRESS_RE = /^(?:await\s+)?press\(\s*(['"])(.*?)\1\s*(?:,\s*\{\s*hold\s*:\s*(\d+)\s*\}\s*)?\)$/;
+const WAIT_RE = /^(?:await\s+)?wait\(\s*\{\s*frames\s*:\s*(\d+)\s*\}\s*\)$/;
+const PRESS_SEQUENCE_RE = /^(?:await\s+)?pressSequence\(\s*\[([\s\S]*)\]\s*\)$/;
+const ENTRY_RE = /\[\s*(?:(['"])(.*?)\1|null)\s*,\s*(\d+)\s*\]/g;
+
+/** Segments produced by one statement, with each one's offset inside it. */
+interface ParsedStatement {
+  segments: InputSegment[];
+  /** offsets[i] = character offset of segments[i] within the statement text. */
+  offsets: number[];
+}
+
+/** Parse one statement into segments, or return an error message. */
+function parseStatement(stmt: string): ParsedStatement | string {
+  const press = PRESS_RE.exec(stmt);
+  if (press) {
+    const bits = buttonsFromString(press[2]!);
+    if (bits === null || bits.length === 0) {
+      return `unknown button '${press[2]}' (expected one or more of ${BUTTON_NAMES.join(', ')}, joined by '+')`;
+    }
+    const frames = press[3] === undefined ? 1 : Number(press[3]);
+    if (frames < 1) {
+      return 'hold must be at least 1 frame';
+    }
+    return { segments: [{ buttons: bits, frames }], offsets: [0] };
+  }
+
+  const wait = WAIT_RE.exec(stmt);
+  if (wait) {
+    const frames = Number(wait[1]);
+    if (frames < 1) {
+      return 'frames must be at least 1';
+    }
+    return { segments: [{ buttons: [], frames }], offsets: [0] };
+  }
+
+  const sequence = PRESS_SEQUENCE_RE.exec(stmt);
+  if (sequence) {
+    const body = sequence[1]!;
+    // The regex anchors `pressSequence(` then `[`, so the body starts just
+    // after the first `[` — used to map entry offsets back to the statement.
+    const bodyStart = stmt.indexOf('[') + 1;
+    const segments: InputSegment[] = [];
+    const offsets: number[] = [];
+    ENTRY_RE.lastIndex = 0;
+    let match: RegExpExecArray | null;
+    while ((match = ENTRY_RE.exec(body)) !== null) {
+      const name = match[2];
+      const frames = Number(match[3]);
+      if (frames < 1) {
+        return 'each pressSequence entry needs at least 1 frame';
+      }
+      if (name === undefined) {
+        segments.push({ buttons: [], frames });
+      } else {
+        const bits = buttonsFromString(name);
+        if (bits === null || bits.length === 0) {
+          return `unknown button '${name}' (expected one or more of ${BUTTON_NAMES.join(', ')}, joined by '+')`;
+        }
+        segments.push({ buttons: bits, frames });
+      }
+      offsets.push(bodyStart + match.index);
+    }
+    // Guard against a malformed entry being silently skipped: everything in the
+    // array body other than the matched entries must be separators.
+    const leftover = body.replace(ENTRY_RE, '').replace(/[\s,]/g, '');
+    if (leftover.length > 0 || (segments.length === 0 && body.trim().length > 0)) {
+      return "malformed pressSequence entry — expected ['button', frames] or [null, frames]";
+    }
+    return { segments, offsets };
+  }
+
+  return 'unsupported statement — only press(), wait() and pressSequence() can be replayed';
+}
+
+/**
+ * Parse script text into the segments a replayer can run.
+ *
+ * A file with no input commands at all parses to zero segments rather than an
+ * error, so the placeholder the serializer writes for an empty recording
+ * ("// No inputs recorded") round-trips.
+ */
+export function parseScript(text: string): ScriptParseResult {
+  const blanked = blankComments(text);
+  const errors: ScriptParseError[] = [];
+  const segments: InputSegment[] = [];
+  const segmentLines: number[] = [];
+
+  // Offsets of each line start, so an offset maps to a line by binary search.
+  const lineStarts = [0];
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] === '\n') {
+      lineStarts.push(i + 1);
+    }
+  }
+  /** 0-based line index containing `offset`. */
+  const lineAt = (offset: number): number => {
+    let lo = 0;
+    let hi = lineStarts.length - 1;
+    while (lo < hi) {
+      const mid = (lo + hi + 1) >> 1;
+      if (lineStarts[mid]! <= offset) {
+        lo = mid;
+      } else {
+        hi = mid - 1;
+      }
+    }
+    return lo;
+  };
+
+  for (const stmt of splitStatements(blanked)) {
+    const result = parseStatement(stmt.text);
+    if (typeof result === 'string') {
+      errors.push({ line: lineAt(stmt.offset) + 1, message: result });
+    } else {
+      for (let i = 0; i < result.segments.length; i++) {
+        segments.push(result.segments[i]!);
+        segmentLines.push(lineAt(stmt.offset + (result.offsets[i] ?? 0)));
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    return { ok: false, errors };
+  }
+  return { ok: true, segments, segmentLines };
+}
diff --git a/apps/webapp/src/scripting/script-serializer.ts b/apps/webapp/src/scripting/script-serializer.ts
index 51edb9f..d1bf06b 100644
--- a/apps/webapp/src/scripting/script-serializer.ts
+++ b/apps/webapp/src/scripting/script-serializer.ts
@@ -28,6 +28,32 @@ const BIT_TO_BUTTON_NAME: Record<number, string> = {
   9: 'l',
 };
 
+/** Script button name → GBA button bit position (inverse of BIT_TO_BUTTON_NAME). */
+const BUTTON_NAME_TO_BIT: Record<string, number> = Object.fromEntries(
+  Object.entries(BIT_TO_BUTTON_NAME).map(([bit, name]) => [name, Number(bit)]),
+);
+
+/** The button names a script may use, for error messages. */
+export const BUTTON_NAMES: readonly string[] = Object.values(BIT_TO_BUTTON_NAME);
+
+/**
+ * Parse a '+'-separated button name string back into bit positions.
+ * Inverse of buttonsToString. Returns null if any name is unknown, so the
+ * caller can report which token was bad rather than silently dropping input.
+ */
+export function buttonsFromString(text: string): number[] | null {
+  const names = text.split('+').map((n) => n.trim());
+  const bits: number[] = [];
+  for (const name of names) {
+    const bit = BUTTON_NAME_TO_BIT[name.toLowerCase()];
+    if (bit === undefined) {
+      return null;
+    }
+    bits.push(bit);
+  }
+  return bits.sort((a, b) => a - b);
+}
+
 /** Convert button bit positions to a sorted '+'-separated name string. */
 export function buttonsToString(buttons: number[]): string | null {
   if (buttons.length === 0) {
diff --git a/docs/examples/klonoa-hidden-minigame.mjs b/docs/examples/klonoa-hidden-minigame.mjs
new file mode 100644
index 0000000..e99d11d
--- /dev/null
+++ b/docs/examples/klonoa-hidden-minigame.mjs
@@ -0,0 +1,39 @@
+// Klonoa: Empire of Dreams — the hidden boot minigame
+//
+// Holding A+B+RIGHT+L+R while the ROM boots makes AgbMain swap callback slot 1
+// for MainGameFrameLoop, which drops you on the "Delete all save data?" screen
+// with enemies raining down it. Adding UP to that combo also arms a player
+// avatar: MainGameFrameLoop latches the D-pad state into gMinigamePlayerArmed,
+// and Select then spawns Klonoa at (0x78, 0x9C) so L/R can dodge.
+//
+// AgbMain reads the key mirror once, masks it with 0x0313 (= A|B|RIGHT|R|L) and
+// requires an exact match, so the combo only registers if it is already held on
+// the very first frame.
+//
+// >> Load the ROM and replay this WITHOUT pressing Run first. <<
+// Loading a ROM resets the emulator and leaves it paused at frame 0, which is
+// exactly what the combo needs. Once the game has booted past AgbMain the
+// window is gone and replaying this does nothing.
+
+await pressSequence([
+  // Boot with the combo held. UP is the part that arms the avatar; drop it and
+  // the enemies still fall but Select does nothing.
+  ['a+b+right+l+r+up', 200],
+
+  // Let the menu settle.
+  [null, 120],
+
+  // Spawn Klonoa at the centre-bottom of the screen.
+  ['select', 4],
+  [null, 60],
+
+  // Dodge: R slides him right, L slides him left, 2px per frame, clamped to
+  // [0x10, 0xDF]. Touching a falling enemy plays hit animation 0x0C, which
+  // locks the controls until it finishes.
+  ['r', 45],
+  [null, 20],
+  ['l', 70],
+  [null, 20],
+  ['r', 50],
+  [null, 90],
+]);