@henols/c64-re-tools 2.0.0 → 2.1.0-rc.1

package/skills/c64-provenance/scripts/provenance.ts

@@ -3,7 +3,8 @@
 // release is a PRG or an unpacker image.json. With --run, each release
 // runs in its own emulator, and each listed difference gets its first access
 // and whether the run changed it. The separate command gives evidence from
-// the program in the knowledge. The routine and match commands keep
+// the program in the knowledge, and the leftovers command lists what its
+// unused bytes hold: text, BASIC lines, fills and copies. The routine and match commands keep
 // routines that several programs share in a library folder and find them in the
 // program (D71).
 
@@ -42,10 +43,12 @@ import { runScript, UsageError } from "#src/script.ts";
 import { compareReleases, shiftSuggestion, suggestShifts, type Range, type Release } from "./lib/compare.ts";
 import { findRoutine, libraryFolder, LibraryError, readLibrary, routineFrom, saveRoutine, suggest } from "./lib/library.ts";
 import { watchRelease, type ImageState, type Start } from "./lib/runtime.ts";
+import { findLeftovers } from "./lib/leftovers.ts";
 import { separate } from "./lib/separate.ts";
 
 const USAGE = `provenance.ts <release> <release> [<release> ...] [options]
 provenance.ts separate [--out <file>] [--max-listed <n>]
+provenance.ts leftovers [--out <file>] [--min-text <n>] [--max-listed <n>]
 provenance.ts routine --library <folder> (--module <address> | --start <address> --end <address>)
                       [--name <name>] [--title <text>] [--replace]
 provenance.ts match --library <folder> [--out <file>] [--max-listed <n>]
@@ -63,6 +66,13 @@ and jump references in knowledge reach each code region from the entry, and what
 the program reads or executes outside its segments. --out writes all ranges to a file;
 the result lists at most --max-listed of each list (default 50) and its count.
 
+leftovers lists what the program in the knowledge holds besides its working
+code: text in PETSCII, screen codes, ASCII or with bit 7 set (Apple II) and
+assembler source (at least --min-text characters, default 8), BASIC lines away
+from the BASIC start, fills, untouched bytes outside code, exact copies of
+earlier bytes, and code regions that no call or jump reaches and no run executed. Each finding has the stages and the accesses of
+its bytes. --out writes all findings to a file.
+
 routine saves a routine of the program in the knowledge to a library: a plain folder of routine
 files, beside the projects (--library, relative to the working directory, as
 --project). It takes a module of the knowledge, or --start and --end. Its
@@ -195,6 +205,7 @@ async function run(argv: string[]): Promise<unknown> {
       steps: { type: "string" },
       out: { type: "string" },
       "max-listed": { type: "string" },
+      "min-text": { type: "string" },
       library: { type: "string" },
       module: { type: "string" },
       start: { type: "string" },
@@ -216,6 +227,11 @@ async function run(argv: string[]): Promise<unknown> {
     if (positionals.length !== 1) throw new UsageError("separate takes no release: it reads the program from the knowledge");
     return separateCommand(values.out, values["max-listed"]);
   }
+  if (positionals[0] === "leftovers") {
+    only("leftovers", ["out", "min-text", "max-listed"]);
+    if (positionals.length !== 1) throw new UsageError("leftovers takes no release: it reads the program from the knowledge");
+    return leftoversCommand(values.out, values["min-text"], values["max-listed"]);
+  }
   if (positionals[0] === "routine") {
     only("routine", ["library", "module", "start", "end", "name", "title", "replace"]);
     if (positionals.length !== 1) throw new UsageError("routine takes no image: it reads the program from the knowledge");
@@ -347,10 +363,8 @@ function stagesOf(stages: Array<Record<string, unknown>> | undefined): Array<{ e
   }));
 }
 
-/** separate: evidence from the program in the knowledge, with all ranges in --out and the first ones in the result. */
-function separateCommand(out: string | undefined, maxListed: string | undefined): unknown {
-  const max = maxListed ?? "50";
-  if (!/^\d{1,5}$/.test(max)) throw new UsageError(`--max-listed must be a whole number, not ${max}`);
+/** The program in the knowledge with its stages and coverage, and the separation of its bytes. */
+function programEvidence() {
   const db = openForRead();
   let program: ReturnType<typeof requireProgram>;
   let coverage: Uint8Array | undefined;
@@ -365,7 +379,6 @@ function separateCommand(out: string | undefined, maxListed: string | undefined)
     db?.close();
   }
   const stages = stagesOf(program.stages);
-  const loaded = { entry: program.entry, stages };
   const found = separate({
     segments: program.segments,
     memory: program.memory,
@@ -375,6 +388,17 @@ function separateCommand(out: string | undefined, maxListed: string | undefined)
     codeRegions: regions,
     references,
   });
+  return { program, stages, coverage, found };
+}
+
+const NO_STAGES = "The program in the knowledge has no stage log. Only a capture of c64-unpacker gives one. A capture of loads holds one part of a program and has none.";
+
+/** separate: evidence from the program in the knowledge, with all ranges in --out and the first ones in the result. */
+function separateCommand(out: string | undefined, maxListed: string | undefined): unknown {
+  const max = maxListed ?? "50";
+  if (!/^\d{1,5}$/.test(max)) throw new UsageError(`--max-listed must be a whole number, not ${max}`);
+  const { program, stages, coverage, found } = programEvidence();
+  const loaded = { entry: program.entry, stages };
   const show = (range: Range) => ({ start: formatC64Address(range.start), end: formatC64Address(range.end) });
   const ranges = found.ranges.map((range) => ({ ...show(range), ...(range.stage === undefined ? {} : { stage: range.stage }), ...(range.access === undefined ? {} : { access: range.access }) }));
   const codeRegions = found.codeRegions.map((region) => ({ ...show(region), type: region.type, ...(region.reachable === undefined ? {} : { reachable: region.reachable }), ...(region.executed === undefined ? {} : { executed: region.executed }) }));
@@ -386,7 +410,7 @@ function separateCommand(out: string | undefined, maxListed: string | undefined)
   return {
     ...(loaded.entry === undefined ? {} : { entry: formatC64Address(loaded.entry) }),
     ...(lastStage === undefined
-      ? { noStages: "The program in the knowledge has no stage log. Only a capture of c64-unpacker gives one. A capture of loads holds one part of a program and has none." }
+      ? { noStages: NO_STAGES }
       : {
           stages: lastStage + 1,
           bytesByStage: Object.fromEntries([...[...Array(lastStage + 1).keys()].map((stage): [string, number] => [String(stage), bytes((range) => range.stage === stage)]), ["none", bytes((range) => range.stage === undefined)]]),
@@ -403,6 +427,54 @@ function separateCommand(out: string | undefined, maxListed: string | undefined)
   };
 }
 
+/** The longest text that the result shows; --out has all of it. */
+const SHOWN_TEXT = 120;
+
+/** leftovers: what the program in the knowledge holds besides its working code, with all findings in --out and the first ones in the result. */
+function leftoversCommand(out: string | undefined, minText: string | undefined, maxListed: string | undefined): unknown {
+  const max = maxListed ?? "50";
+  if (!/^\d{1,5}$/.test(max)) throw new UsageError(`--max-listed must be a whole number, not ${max}`);
+  const min = minText ?? "8";
+  if (!/^\d{1,3}$/.test(min) || Number(min) < 4) throw new UsageError(`--min-text must be a whole number of 4 or more, not ${min}`);
+  const { program, stages, coverage, found } = programEvidence();
+  const leftovers = findLeftovers({
+    segments: program.segments,
+    memory: program.memory,
+    separation: found,
+    ...(program.segments.some((segment) => segment.start === 0x0801) ? { basicStart: 0x0801 } : {}),
+    minText: Number(min),
+  });
+  const show = <T extends Range & { stages?: number[]; access?: string[] }>({ start, end, stages: wrote, access, ...rest }: T) => ({
+    start: formatC64Address(start),
+    end: formatC64Address(end),
+    ...rest,
+    ...(wrote === undefined ? {} : { stages: wrote }),
+    ...(access === undefined ? {} : { access }),
+  });
+  const all = {
+    text: leftovers.text.map(show),
+    basic: leftovers.basic.map(({ linkedAt, ...rest }) => ({ ...show(rest), linkedAt: formatC64Address(linkedAt) })),
+    fill: leftovers.fill.map(({ pattern, ...rest }) => ({ ...show(rest), pattern: hexBytes(pattern) })),
+    residue: leftovers.residue.map((range) => ({ ...show(range), bytes: hexBytes([...program.memory.subarray(range.start, Math.min(range.end, range.start + 15) + 1)]) + (range.end - range.start >= 16 ? " ..." : "") })),
+    copies: leftovers.copies.map(({ copyOf, ...rest }) => ({ ...show(rest), copyOf: formatC64Address(copyOf) })),
+    deadCode: leftovers.deadCode.map(show),
+  };
+  const listed = <T>(items: T[]) => ({ count: items.length, listed: items.slice(0, Number(max)) });
+  if (out !== undefined) writeProjectFile(out, Buffer.from(`${JSON.stringify(all, null, 1)}\n`), { what: "--out" });
+  return {
+    ...(program.entry === undefined ? { noEntry: "The program in the knowledge has no entry, so deadCode is empty." } : { entry: formatC64Address(program.entry) }),
+    ...(stages === undefined ? { noStages: NO_STAGES } : { stages: stages.length }),
+    ...(coverage === undefined ? { noCoverage: "The knowledge has no coverage, so residue is empty and no finding has access. Add coverage with coverage of the c64-knowledge skill." } : {}),
+    text: listed(all.text.map((item) => (item.text.length > SHOWN_TEXT ? { ...item, text: `${item.text.slice(0, SHOWN_TEXT)} ...`, length: item.text.length } : item))),
+    basic: listed(all.basic),
+    fill: listed(all.fill),
+    residue: listed(all.residue),
+    copies: listed(all.copies),
+    deadCode: listed(all.deadCode),
+    ...(out === undefined ? {} : { out }),
+  };
+}
+
 const SEMANTIC: readonly Origin[] = ["user", "llm"];
 
 const platform = () => new Map(platformNames().map((entry) => [entry.name, entry.address]));

package/skills/c64-reverse-engineering/SKILL.md

@@ -63,6 +63,7 @@ Select the path for the scope:
 | The routines, code, data and references of the program | c64-static-analysis |
 | The platform meaning of an address or a register | c64-memory-map |
 | Differences between releases of the program | c64-provenance |
+| Leftovers of the development, a crack or a recrack: texts, old copies, unused bytes, dead code | c64-provenance `leftovers` |
 | A routine that another program of the workspace has, for example a music driver | c64-provenance, with the library |
 | Source code from the knowledge | c64-source |
 | Source code to build | c64-assembler |
@@ -78,19 +79,19 @@ Do the stages in this sequence. Go to the next stage only when its exit check is
 
 | Stage | Work | Exit check |
 |---|---|---|
-| 1. Acceptance | Ask the user for the criteria of the rebuild. Offer these: identical source, a verified loader, passed c64-testing scenarios, and a list of the code that no run executed. Also offer documentation of the flows, tables, formats and graphics. | The user gave the criteria. |
+| 1. Acceptance | Ask the user for the criteria of the rebuild. Offer these: identical source, a verified loader, passed c64-testing scenarios, passed replays of the recordings, and a list of the code that no run executed. Also offer documentation of the flows, tables, formats and graphics. | The user gave the criteria. |
 | 2. Get | c64-disk: list the disk. Extract the start file into `original/`. | The start file is in the project. |
 | 3. Start | c64-basic: find the SYS address of the BASIC start. | You have the entry address. |
 | 4. Unpack | c64-unpacker: examine the program. Capture a packed program into `.c64-re-tools/local/`. Then c64-knowledge: put the capture, or the PRG of a program without a packer, into the knowledge with `image`. | `program` of c64-knowledge shows the segments and the entry. |
-| 5. Run | c64-emulator and the run of c64-testing: run each part that the scope names. Write a coverage map for each part into `.c64-re-tools/local/`. Then c64-knowledge: add the maps with `coverage`. | `program` of c64-knowledge lists a coverage map for each part that the scope names. |
+| 5. Run | First record: ask the user to play each part that the scope names, with `record.ts --play` of c64-testing. Tell the user which parts. Record a part yourself only when the sessions of the user do not have it. Put the recordings in `tests/recordings/`. Then c64-emulator and the run of c64-testing for the parts that a recording cannot have. Write a coverage map for each part into `.c64-re-tools/local/`. Then c64-knowledge: add the maps and the `coverage.bin` of each recording with `coverage`. | `program` of c64-knowledge lists a coverage map for each part that the scope names. |
 | 6. Analyze | c64-static-analysis. It reads the program and the coverage from the knowledge. | No coverage conflict is open. |
 | 7. Name | c64-provenance: if the workspace has a library, find its routines with `match` and apply the batch. Then c64-knowledge and c64-memory-map: name each routine in the scope and give it a comment. Record the modules. When the scope has hundreds of routines, ask the user which routines to name. The source gives the other routines an `l_xxxx` label. | Each routine that the user selected has a name and a comment. |
 | 8. Generate | c64-source into `src/`. For an unpacked program, add `--loader`. | `check.identical` is true. For an unpacked program, `loader.verified` is true. |
-| 9. Build and test | c64-assembler with `--compare` into `build/`. c64-testing scenarios in `tests/`. | The criteria of stage 1 are true. |
+| 9. Build and test | c64-assembler with `--compare` into `build/`. c64-testing scenarios in `tests/`. Replay each recording on the rebuild with `replay.ts`: give the checkpoint routine, the state and the random state (`--pin`) with the names of stage 7. | The criteria of stage 1 are true. |
 | 10. Document | When the criteria ask for documentation: c64-docs into `README.md` and `docs/`. | `link.ts --check` of c64-docs gives no problem. |
 | 11. Hand over | Find each file that you made outside `.c64-re-tools/local/` and that is not a deliverable. Move it into `.c64-re-tools/local/`. Then give the answer (below). | Each file that you made outside `.c64-re-tools/local/` is a deliverable. |
 
-In stage 5, if you cannot get to a part of the program, ask the user how to get to it. Do stages 7 and 8 again until the source is clear. Each run of c64-source writes the source again.
+In stage 5, make the recordings before you change the program. A recording needs no names, and its coverage gives the analysis of stage 6 more code. If you cannot get to a part of the program, ask the user how to get to it. Do stages 7 and 8 again until the source is clear. Each run of c64-source writes the source again.
 
 After stage 7, save each routine that other programs can have to the library with c64-provenance `routine`. Examples are a music driver, a decruncher and a loader. Ask the user before you make a library.
 
@@ -100,6 +101,7 @@ After stage 7, save each routine that other programs can have to the library wit
 - the generated source
 - the built program and the loader
 - the c64-testing scenarios
+- the c64-testing recordings in `tests/recordings/`
 - the documentation in `README.md` and `docs/`, when the criteria ask for it
 - the runs in `runs/` that the knowledge gives as evidence
 - the scripts in `tools/` for the formats of this program, when you wrote them.
@@ -124,7 +126,7 @@ If the project has no layout, use this one. No script checks it. Each script tak
 original/      the disk image or the program as you got it
 src/           the generated source from c64-source
 build/         programs from c64-assembler
-tests/         c64-testing scenarios
+tests/         c64-testing scenarios, and the recordings in tests/recordings/
 runs/          the runs that the knowledge gives as evidence
 docs/          the documentation from c64-docs, with the reference in docs/reference/
 tools/         scripts for the formats of this program only

package/skills/c64-testing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: c64-testing
-description: Use this skill to test if a rebuilt or changed C64 program behaves as the original. It runs one scenario on the original and then on the rebuild in an emulator. It compares memory, registers, chip state and the screen with explicit rules, and gives PASS, FAIL or INCONCLUSIVE. It also makes a checklist for a human playtest. Use its run command to explore a program with many steps, for example to visit each room or level. A run keeps screens, coverage maps and snapshots as files. Do not use it to find the cause of a difference.
+description: Use this skill to test if a rebuilt or changed C64 program behaves as the original. It runs one scenario on the original and then on the rebuild in an emulator. It compares memory, registers, chip state and the screen with explicit rules, and gives PASS, FAIL or INCONCLUSIVE. It also makes a checklist for a human playtest. Use its run command to explore a program with many steps, for example to visit each room or level. A run keeps screens, coverage maps and snapshots as files. Use its record and replay commands to keep a long play session of the original and replay it on each rebuild. Do not use it to find the cause of a difference.
 ---
 
 # c64-testing
@@ -54,6 +54,53 @@ A memory item can have `"view": "ram"`. Then it reads the RAM under the ROMs and
 
 See [references/scenario-format.md](references/scenario-format.md), section Runs. The script prints one JSON object. The exit status is 0 when all steps ran, 1 when a step did not reach its target, and 2 for a bad call. A long run can need more time than one shell call. Then run it in the background.
 
+### Recordings
+
+A recording keeps a session of the original program, for example a play through some rooms of a game. A replay gives the same input to a rebuild and compares the game state. Make the recordings early, before you change the program. A recording needs no names. Its coverage also helps the static analysis.
+
+The record and replay scripts run the replay core `c64run` on this machine, not the emulator of the host runtime. The replay core has no disk drive. The program must be a PRG file.
+
+Ask the user to play first. Tell the user which parts of the program the recordings must have, for example each room, a fight and a lost life. Make a scripted recording only for a part that the sessions of the user do not have, or when the user cannot play.
+
+```
+node <skill>/scripts/record.ts tests/record/start.json --out tests/recordings/play1 --play --joystick 1
+```
+
+- With `--play`, a person plays the program after the steps of the record file. The steps can start the program, for example a key for an intro.
+- The script writes the address of a page to stderr. Give the address to the user. In a dev container, the port of the page (default 6465) must be forwarded.
+- On the page, the arrow keys, space and a gamepad move the joystick of `--joystick` (default 2). The other keys go to the C64 keyboard.
+- The script runs until the user clicks Stop on the page. Run it in the background. Then it writes the recording folder.
+
+A scripted recording has only steps. See [references/recording-format.md](references/recording-format.md). The steps are `frames`, `joystick`, `type`, `write`, `registers` and `runUntil` with `at` or `memory`.
+
+```
+node <skill>/scripts/record.ts tests/record/rooms.json --out tests/recordings/rooms
+node <skill>/scripts/replay.ts tests/recordings/rooms --checkpoint main_loop --state room --state lives --pin random_ptr:2 --rebuild build/game.prg --symbols build/game.json
+```
+
+- The record script writes the recording folder. The exit status is 0 when it recorded the session, 1 when the session did not complete, and 2 for a bad call. `executed` gives the instructions in the coverage map.
+- The replay script first replays the recording on the original. The original must end the session with the recorded state. Then the script replays the recording on the rebuild and compares the state at each checkpoint.
+- `--checkpoint` gives a routine, and `--state` gives each memory item to compare. Use the names that the knowledge has at the time of the replay. A `$` address is an address of the original. On the rebuild, it moves with the name before it.
+- The replay script gives PASS, FAIL or INCONCLUSIVE, with the exit status 0, 1 or 3. A FAIL gives the first checkpoint that is different and the state items that are different.
+- With `--out`, a FAIL writes the RAM of the two sides at that checkpoint. Compare the two files with `diff.ts`.
+- Without `--rebuild`, the replay script only replays the recording on the original.
+
+A checkpoint is one entry of a routine. Use a routine that the program executes one time in each pass of its game logic, for example the main loop. Do not use an interrupt handler.
+
+The input is the reads of the joystick ports and the keyboard matrix. It is also the reads of the four SID registers that a program can read: the paddles, the noise of voice 3 and its envelope. It is also the reads of `$DE00`-`$DFFF`, where a C64 without a cartridge gives the last byte on the bus. On a replay, the n-th read of each instruction gets the value of the n-th read in the recording. Thus a rebuild with different timing gets the same input and the same SID random numbers. A `write`, `registers` or `runUntil` step is not input. The replay does the step again at the same read of the program.
+
+A replay is deterministic. The replay core has no random source and no clock: the same recording gives the same session, to the cycle. Sometimes the recording has no value for a read of an input. Then the read gets a fixed value: `$FF` for the joystick, keyboard and paddle registers, `$00` for the others. `idleReads` in the result counts these reads on the rebuild. On the original, such a read makes the result INCONCLUSIVE.
+
+Control each source of random numbers:
+
+- A program that reads a seed from the SID gets the recorded value. You do not need to do more.
+- A program that reads a seed from the raster line or a CIA timer: add the address to `inputs` of the record file. Do this only when the program does not wait in a loop on that address.
+- A program that keeps its random state in RAM: give that state with `--pin`. An example is a pointer into a random table that moves each frame. At each checkpoint, the rebuild gets the values of the original there. A FAIL where an enemy or an event is different, but the input is the same, often shows that a pin is missing.
+
+Put a `runUntil` step with the checkpoint routine before a `registers` step. A `registers` step that sets the pc during an interrupt stops the program.
+
+Commit the recording folder with the scenarios. A recording is not knowledge.
+
 ### Differences
 
 ```
@@ -100,10 +147,15 @@ Read:
 Automatic write:
 - none.
 
+Write with c64-knowledge:
+- the coverage of a recording: `knowledge.ts coverage tests/recordings/<name>/coverage.bin`.
+- a finding that a recording shows, with `--evidence test:tests/recordings/<name>/recording.json`.
+
 Do not store:
 - test results
 - screenshots
-- playtest results.
+- playtest results
+- recordings.
 
 ## Result
 
@@ -120,6 +172,13 @@ PASS, FAIL or INCONCLUSIVE, the checkpoints and the smallest differences that ex
 - A program that uses random numbers: set the random seed with a `write` step on both sides. If that is not possible, observe only values that do not depend on the random numbers.
 - The two sides start differently, for example the original after a cracked intro. Give the steps that only one side needs a `side`. Then make the memory the same with a `normalize` step. It writes the entry state of the capture in the knowledge.
 - Frame counts drift by one frame between the sides: the sides got to the same address at different raster positions. Do not sync on an IRQ handler. Sync on a value that the IRQ changes, with `runUntil` `memory`, or on an address and a raster line together.
+- INCONCLUSIVE, "does not reproduce": the original does not end the session with the recorded state. Record the session again with this `c64run`.
+- INCONCLUSIVE, "never came to the checkpoint": the original did not execute the checkpoint routine in the session. Give another routine.
+- INCONCLUSIVE, "is not the program of the recording": the program file changed after the recording. Record the session again.
+- A record result with `recorded` false: a step did not reach its target. Change the step.
+- A record result with `executed` 0: the program never read its input from RAM, so the coverage map is empty. The recording can still replay.
+- A FAIL from a replay: compare the two RAM files of `--out` with `diff.ts`. Then examine the first different state item with the c64-emulator skill.
+- A program that loads more files from a disk: the replay core has no disk drive. Use a test scenario in the emulator.
 - A byte that cannot be the same on both sides, for example a read-only collision register: use `exclude` with the reason. Do not use `exclude` to hide a real difference.
 
 Do not add a mask or a tolerance only to make a test pass. A tolerance must have a reason in the behavior of the program.

package/skills/c64-testing/references/recording-format.md

@@ -0,0 +1,96 @@
+# Recording format
+
+## Record file
+
+A record file (for `record.ts`) is one JSON object in a project file.
+
+```json
+{
+  "name": "first rooms",
+  "program": "original/game.prg",
+  "steps": [
+    { "frames": 300 },
+    { "joystick": { "port": 2, "direction": "center", "fire": true } },
+    { "frames": 30 },
+    { "joystick": { "port": 2, "direction": "right" } },
+    { "frames": 500 }
+  ]
+}
+```
+
+- `name`: a short text.
+- `program`: a PRG file, relative to the project folder.
+- `symbols`: optional. `knowledge` (default), `none`, or a JSON file: the output of the c64-assembler skill, or an object of names and `$` addresses. The steps use these names.
+- `load`: optional. With `false` (default), the program must load at `$0801` with a BASIC start line, and the C64 types `RUN`. With `true`, the program goes into memory and the C64 stays at READY. Then a `registers` step with `pc` starts the program.
+- `checkpoint`, `state` and `pin`: optional. The comparison that a replay uses when the replay gives none. `checkpoint` is the name or `$` address of a routine. Each entry of the routine is a checkpoint. `state` is 1 to 16 memory items that the checkpoints compare. `pin` is the random state in RAM. An item is a name, a `$` address, or `{ "at", "size" }` with a size from 1 to 4096. Give `checkpoint` and `state` together.
+- `inputs`: optional. The I/O addresses (or ranges such as `$de00-$dfff`) whose reads are input. The default is `$dc00` and `$dc01`: the joystick ports and the keyboard matrix. It also has `$d419` to `$d41c` (the paddles, and the noise and envelope of SID voice 3), and `$de00-$dfff` (no device: the last byte on the bus). Add `$d012` or a CIA timer only for a program that reads a seed there and does not wait in a loop on it.
+- `steps`: the steps.
+
+## Steps
+
+The steps have the form of the steps of a scenario.
+
+| Step | Effect |
+|---|---|
+| `{ "frames": 300 }` | Run 300 frames (19656 cycles each). |
+| `{ "joystick": { "port": 2, "direction": "left", "fire": true } }` | Set a joystick. It stays in this state until the next joystick step. |
+| `{ "type": "RUN\n" }` | Press each key of the text on the keyboard matrix, for 3 frames, then release it for 3 frames. |
+| `{ "write": { "at": "next_room", "bytes": [1] } }` | Write bytes into RAM. |
+| `{ "registers": { "pc": "change_room", "a": 16 } }` | Set registers at the next instruction. `pc` continues the program at that address. |
+| `{ "runUntil": { "at": "main_loop" }, "timeoutFrames": 300 }` | Run until the CPU gets to an address. |
+| `{ "runUntil": { "memory": { "at": "room", "equals": 2 } }, "timeoutFrames": 600 }` | Run until a byte has a value. The script reads the byte at the end of each frame. |
+
+The replay core has no `runUntil` with `raster`.
+
+A `type` step can press A to Z, 0 to 9, space, return (`\n`) and `+-.:@,*;=/!"#$%&'()[]<>?`. It types a to z as A to Z.
+
+`joystick`, `type` and `frames` steps are input and time. The recording keeps their effect in the reads, so a replay does not do these steps again.
+
+`write`, `registers` and `runUntil` steps are events. The recording keeps a point in the program for each event. The point is the next read at the input site with the most reads. That site is not in ROM. A replay does the event at the same read. An event that comes directly after another event runs at once after that event.
+
+## Play
+
+With `--play`, `record.ts` does the steps, then a person plays. The page on `http://localhost:<port>/` (`--http-port`, default 6465) shows the screen at 50 frames each second. It has no sound.
+
+| Page input | C64 input |
+|---|---|
+| Arrow keys, space | The joystick of `--joystick` (default 2): directions and fire. |
+| A gamepad | The same joystick: the left stick or the cross for directions, button 1 or 2 for fire. |
+| A-Z, 0-9, the symbols of a `type` step, Return, Backspace (DEL), Escape (RUN/STOP), F1-F8 | The C64 keyboard. |
+
+Stop on the page ends the session, and the script writes the recording folder. The input of the page goes into the reads, as the input of the steps does.
+
+## Recording folder
+
+`record.ts` writes these files into the `--out` folder:
+
+| File | Content |
+|---|---|
+| `recording.json` | The program and its SHA-256, the symbols, and the comparison of the record file. Also the inputs, the events, the input sites, the cycles of the session and the state hash at its end. |
+| `reads.txt` | One line `<site> <addr> <from> <value>` for each change of the value at a site. From the read with the index `<from>`, the reads at `<site>` from `<addr>` get `<value>`. One line `end <site> <addr> <count>` for each site gives its number of reads. |
+| `coverage.bin` | The coverage map of the session: 65536 bytes, one for each address, in the format of the coverage maps of the emulator. It starts at the first input read of code in RAM, thus after a loader or a relocation. |
+
+A site is the address of the instruction that reads. The values are hex. `<from>` and `<count>` are decimal.
+
+## Replay
+
+`replay.ts` replays a recording folder:
+
+1. It replays the recording on the original program. The session must end with the recorded cycles and state hash. Else the result is INCONCLUSIVE. It also takes the state at each checkpoint of the original.
+2. With `--rebuild`, it replays the recording on the rebuild. At each checkpoint, the rebuild first gets the pinned values of the original. Then the script compares the state. The cycles can be different.
+
+The comparison comes from `--checkpoint`, `--state` and `--pin`, or else from the record file. A recording without names (`symbols` is `none`) takes the names of the knowledge at the time of the replay.
+
+For the rebuild, the script finds each name with the names of the rebuild (`--symbols`). A `$` address is an address of the original. It moves with the name before it in the original: the script finds the same name in the rebuild and adds the same offset. Code moves with a code label, and data with any name. A site in ROM does not move. Give a state item a name, or the state moves with the code before it.
+
+The result is one JSON object:
+
+- `result`: PASS, FAIL or INCONCLUSIVE.
+- `side`: `original` for the check of the original only, `rebuild` with `--rebuild`.
+- `checkpoint`: the routine of the comparison.
+- `checkpoints` and `compared`: the checkpoints of the original, and the checkpoints of the rebuild that were the same.
+- `firstDifference`: on a FAIL, the checkpoint (1 is the first), the cycle on each side, and each state item that is different, as hex.
+- `reason`: why the result is FAIL or INCONCLUSIVE.
+- `movedSites`: the number of sites at a different address in the rebuild.
+- `idleReads`: the input reads of the rebuild that the recording had no value for. Such a read is at a site that the recording does not have, or after its end. Each got the fixed value `$FF` (joystick, keyboard, paddles) or `$00`. An input site that the site map did not find shows here.
+- `files`: with `--out`, the RAM of each side at the first different checkpoint, `original-<n>.bin` and `rebuild-<n>.bin`.

package/skills/c64-testing/scripts/lib/play.ts

@@ -0,0 +1,144 @@
+// A person plays the program in the replay core: a page on localhost shows
+// the screen and sends the keyboard and gamepad. The core runs one frame each
+// 20 ms. The reads of the program keep the input, so the recording needs
+// nothing from the page. Stop on the page ends the session.
+
+import { createServer, type ServerResponse } from "node:http";
+
+import { PAL_FRAME_CYCLES, type C64RunSession } from "#src/native/c64run.ts";
+
+const FRAME_MS = 20;
+
+export interface PlayOptions {
+  /** The TCP port of the page; 0 takes a free one. */
+  httpPort: number;
+  /** The control port that the arrow keys, space and the gamepad move. */
+  joystick: 1 | 2;
+  /** Called with the address of the page when it listens. */
+  ready: (url: string) => void;
+}
+
+/** The C64 keys of the page: KeyboardEvent.key → the key code of the replay core. */
+const KEYS: Record<string, number> = { Enter: 0x0d, Backspace: 0x01, F1: 0xf1, F2: 0xf2, F3: 0xf3, F4: 0xf4, F5: 0xf5, F6: 0xf6, F7: 0xf7, F8: 0xf8, Escape: 0x03 };
+
+const PAGE = String.raw`<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>c64-testing record</title>
+<style>
+body{margin:0;background:#111;color:#ddd;font:14px system-ui,sans-serif;display:flex;flex-direction:column;align-items:center;gap:12px;padding:16px}
+canvas{image-rendering:pixelated;width:min(784px,100%);aspect-ratio:392/272;background:#000}
+button{font:inherit;padding:6px 16px}
+</style></head><body>
+<canvas id="screen" width="392" height="272"></canvas>
+<div>Joystick: arrow keys and space, or a gamepad. Other keys go to the C64 keyboard. <span id="state">connecting</span></div>
+<button id="stop">Stop and save the recording</button>
+<script>
+const canvas = document.getElementById("screen"), context = canvas.getContext("2d"), state = document.getElementById("state");
+let palette = [], image = context.createImageData(392, 272), frames = 0;
+const source = new EventSource("frames");
+source.addEventListener("palette", (event) => { palette = event.data.split(" ").map((hex) => [0, 2, 4].map((at) => parseInt(hex.slice(at, at + 2), 16))); });
+source.onmessage = (event) => {
+  const [width, height, data] = event.data.split(" ");
+  if (image.width != width) { canvas.width = width; canvas.height = height; image = context.createImageData(+width, +height); }
+  const bytes = atob(data);
+  for (let at = 0; at < bytes.length; at++) { const rgb = palette[bytes.charCodeAt(at)] || [0, 0, 0]; image.data.set(rgb, at * 4); image.data[at * 4 + 3] = 255; }
+  context.putImageData(image, 0, 0);
+  state.textContent = "frame " + ++frames;
+};
+source.onerror = () => { state.textContent = "the session ended"; };
+const held = new Set();
+const bits = { ArrowUp: 1, ArrowDown: 2, ArrowLeft: 4, ArrowRight: 8, " ": 16 };
+let sent = -1;
+function send(path) { fetch(path, { method: "POST" }); }
+function joystick() {
+  let mask = 0;
+  for (const key of held) mask |= bits[key] || 0;
+  for (const pad of navigator.getGamepads ? navigator.getGamepads() : []) {
+    if (!pad) continue;
+    const [x, y] = pad.axes;
+    if (y < -0.5 || pad.buttons[12]?.pressed) mask |= 1;
+    if (y > 0.5 || pad.buttons[13]?.pressed) mask |= 2;
+    if (x < -0.5 || pad.buttons[14]?.pressed) mask |= 4;
+    if (x > 0.5 || pad.buttons[15]?.pressed) mask |= 8;
+    if (pad.buttons[0]?.pressed || pad.buttons[1]?.pressed) mask |= 16;
+  }
+  if (mask !== sent) { sent = mask; send("joystick?mask=" + mask); }
+  requestAnimationFrame(joystick);
+}
+requestAnimationFrame(joystick);
+function key(event, down) {
+  if (event.key in bits) { event.preventDefault(); down ? held.add(event.key) : held.delete(event.key); return; }
+  const name = event.key.length === 1 ? event.key.toUpperCase() : event.key;
+  if (name.length === 1 || /^(Enter|Backspace|Escape|F[1-8])$/.test(name)) { event.preventDefault(); if (!event.repeat) send("key?name=" + encodeURIComponent(name) + "&down=" + (down ? 1 : 0)); }
+}
+addEventListener("keydown", (event) => key(event, true));
+addEventListener("keyup", (event) => key(event, false));
+document.getElementById("stop").onclick = () => { send("stop"); state.textContent = "saving"; };
+</script></body></html>`;
+
+/** The key code of a key name from the page, or undefined for a key that the C64 does not have. */
+function keyCode(name: string): number | undefined {
+  if (name in KEYS) return KEYS[name];
+  return name.length === 1 && /[A-Z0-9 +\-.:@,*;=/!"#$%&'()[\]<>?]/.test(name) ? name.charCodeAt(0) : undefined;
+}
+
+/** Runs the core in real time with the page as its joystick and keyboard, until Stop. */
+export async function play(core: C64RunSession, options: PlayOptions): Promise<void> {
+  const palette = (await core.command("palette")).split(" ").slice(1).join(" ");
+  const viewers = new Set<ServerResponse>();
+  const pending: string[] = [];
+  let mask = 0;
+  let stop: () => void = () => {};
+  const stopped = new Promise<void>((resolve) => (stop = resolve));
+  const server = createServer((request, response) => {
+    const url = new URL(request.url ?? "/", "http://localhost");
+    if (request.method === "GET" && url.pathname === "/") {
+      response.writeHead(200, { "content-type": "text/html; charset=utf-8" }).end(PAGE);
+    } else if (request.method === "GET" && url.pathname === "/frames") {
+      response.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-store" });
+      response.write(`event: palette\ndata: ${palette}\n\n`);
+      viewers.add(response);
+      request.on("close", () => viewers.delete(response));
+    } else if (request.method === "POST" && url.pathname === "/joystick") {
+      mask = Number(url.searchParams.get("mask")) & 0x1f;
+      response.writeHead(204).end();
+    } else if (request.method === "POST" && url.pathname === "/key") {
+      const code = keyCode(url.searchParams.get("name") ?? "");
+      if (code !== undefined) pending.push(`key ${code.toString(16)} ${url.searchParams.get("down") === "1" ? "down" : "up"}`);
+      response.writeHead(204).end();
+    } else if (request.method === "POST" && url.pathname === "/stop") {
+      response.writeHead(204).end();
+      stop();
+    } else {
+      response.writeHead(404).end();
+    }
+  });
+  await new Promise<void>((resolve) => server.listen(options.httpPort, "127.0.0.1", resolve));
+  const address = server.address();
+  options.ready(`http://localhost:${typeof address === "object" && address !== null ? address.port : options.httpPort}/`);
+  let running = true;
+  void stopped.then(() => (running = false));
+  let tick = (await core.status("status")).tick;
+  let sent = -1;
+  try {
+    while (running) {
+      const started = Date.now();
+      if (mask !== sent) {
+        await core.command(options.joystick === 1 ? `joy ${mask.toString(16)} 0` : `joy 0 ${mask.toString(16)}`);
+        sent = mask;
+      }
+      while (pending.length > 0) await core.command(pending.shift()!);
+      tick += PAL_FRAME_CYCLES;
+      await core.status(`run ${tick}`);
+      if (viewers.size > 0) {
+        const frame = (await core.command("frame")).slice(3);
+        for (const viewer of viewers) viewer.write(`data: ${frame}\n\n`);
+      }
+      await new Promise((resolve) => setTimeout(resolve, Math.max(0, FRAME_MS - (Date.now() - started))));
+    }
+  } finally {
+    await core.command("joy 0 0");
+    for (const viewer of viewers) viewer.end();
+    await new Promise((resolve) => server.close(resolve));
+  }
+}