@moonbase-machines/player 0.0.0-stage → 0.9.0

package/remake/raster.js

@@ -0,0 +1,72 @@
+// The original's screen, dot for dot, for the scenes that read it back. PROB6 steers Helen's car by
+// the colors of the dots ahead of it, so the remake must know what the original's screen shows
+// there, whatever the view draws. The raster is 192 rows of 140 colors, painted by each step as the
+// original's routines paint the double hi-res screen, and read by read-dot. The view never sees it.
+import { screen, draw, line as lineDots } from '@moonbase-machines/vector/draw.js';
+import { put } from '@moonbase-machines/vector/objects.js';
+import { width, dots } from '@moonbase-machines/vector/font.js';
+import { LAYOUT } from './layout.js';
+
+export class Raster {
+  constructor() { this.dots = screen(15); this.kept = null; }   // $5BE1 clears the screen white
+  // Nature Park's menus over a game: the screen kept and cleared to black ($4C5D), and put back
+  // as it was ($4CFB), with what an object kept under it
+  keepScreen() { this.screenKept = { dots: this.dots, kept: this.kept }; this.dots = screen(0); }
+  putScreen() { if (this.screenKept) ({ dots: this.dots, kept: this.kept } = this.screenKept); this.screenKept = null; }
+  // Animal Rescue's PART3 at $E000: rows 19 to 115 moved two bytes to the left in each half of the
+  // screen. A row is 560 bits, aux and main bytes in turn, seven bits a byte and four a dot; bytes
+  // 2 to 73 of the row, bits 14 to 517, take the bits 28 on, so the dots move seven, the ends half
+  // way through a dot, and bytes 74 to 79 stay
+  scroll() {
+    for (let y = 19; y <= 115; y++) {
+      const row = this.dots[y], bits = [];
+      for (const c of row) bits.push(c >> 3 & 1, c >> 2 & 1, c >> 1 & 1, c & 1);
+      for (let b = 14; b < 518; b++) bits[b] = bits[b + 28];
+      for (let x = 0; x < 140; x++) row[x] = bits[4 * x] << 3 | bits[4 * x + 1] << 2 | bits[4 * x + 2] << 1 | bits[4 * x + 3];
+    }
+  }
+  set(x, y, c) { if (x >= 0 && x < 140 && y >= 0 && y < 192) this.dots[y][x] = c & 15; }
+  get(x, y) { return x >= 0 && x < 140 && y >= 0 && y < 192 ? this.dots[y][x] : 0; }
+  // a run of a row, both ends drawn ($7947)
+  span(c, left, right, y) { for (let x = left; x <= right; x++) this.set(x, y, c); }
+  // rows filled across the screen, with white edge columns when `edges` ($5F4B)
+  rows(c, count, first, edges) {
+    for (let y = first; y < first + count; y++) { this.span(c, 0, 139, y); if (edges) { this.set(0, y, 15); this.set(139, y, 15); } }
+  }
+  whiteLines(y) { this.span(15, 0, 139, y); this.span(15, 0, 139, y + 1); }
+  // $65D2: the window outlined in black and filled, and the two boxes, each two white rows and its
+  // rows in its color with white edges; $80 leaves a part as it is
+  box(layout, window, one, two) {
+    const [bottom, top1, top2] = LAYOUT[layout] ?? LAYOUT[0x32];
+    if (window !== 0x80) {
+      this.span(0, 1, 138, 1); this.span(0, 1, 138, bottom - 1);
+      for (let y = 2; y < bottom - 1; y++) { this.set(1, y, 0); this.set(138, y, 0); this.span(window, 2, 137, y); }
+    }
+    if (one !== 0x80) { this.whiteLines(top1); this.rows(one, top2 - top1 - 2, top1 + 2, true); }
+    if (two !== 0x80) { this.whiteLines(top2); this.rows(two, 190 - top2 - 2, top2 + 2, true); }
+  }
+  // a panel: its box's two white rows and its rows in its color, with white edges
+  panel(top, bottom, c) { this.whiteLines(top); this.rows(c, bottom - top - 1, top + 2, true); }
+  picture(shapes) { draw(shapes, this.dots); }
+  rectangle(c, x, y, w, h) { for (let r = y; r < y + h; r++) this.span(c, x, x + w - 1, r); }
+  outline(c, x, y, w, h) { this.span(c, x, x + w - 1, y); this.span(c, x, x + w - 1, y + h - 1); for (let r = y; r < y + h; r++) { this.set(x, r, c); this.set(x + w - 1, r, c); } }
+  line(c, x0, y0, x1, y1) { for (const [x, y] of lineDots(x0, y0, x1, y1)) this.set(x, y, c); }
+  // An object: 'keep' keeps the ground under it, so that object 0 puts it back, and its clear
+  // color shows the ground ($686F); 'clear' shows the ground and keeps none ($6863); 'whole' puts
+  // it down whole, its clear color and all ($686D)
+  object(o, x, y, how) {
+    if (how === 'keep') this.kept = { x, y, rows: o.rows.map((row, dy) => row.map((_, dx) => this.get(x + dx, y + dy))) };
+    put(this.dots, o, x, y, how === 'whole');
+  }
+  restore() { const k = this.kept; if (!k) return; k.rows.forEach((row, dy) => row.forEach((c, dx) => this.set(k.x + dx, k.y + dy, c))); }
+  // a glyph's cell painted, ink on its dots and paper on the rest, `h` rows a glyph row, as many
+  // glyph rows as the line is high; the cell takes in the spacing after the glyph, `space`
+  glyph(ch, x, y, ink, paper, h = 1, height = 9, space = 0) {
+    const w = width(ch);
+    // a spacer, a code below $20, is that many dots of the paper
+    if (ch.charCodeAt(0) < 0x20) { for (let gy = 0; gy < Math.min(9, height); gy++) for (let gx = 0; gx < w; gx++) for (let k = 0; k < h; k++) this.set(x + gx, y + gy * h + k, paper); return w; }
+    const on = new Set(dots(ch).map(([gx, gy]) => gx + ',' + gy));
+    for (let gy = 0; gy < Math.min(9, height); gy++) for (let gx = 0; gx < w + space; gx++) for (let k = 0; k < h; k++) this.set(x + gx, y + gy * h + k, on.has(gx + ',' + gy) ? ink : paper);
+    return w;
+  }
+}

package/remake/scenes.js

@@ -0,0 +1,243 @@
+// A title of scenes played, the remake's own engine (main.js hands it the game): its scripts on the engine, its events
+// drawn by the view, on the stage; its controls on the options line, the sound, the old style text, a C64 title's
+// printer, the bugs fixed where the title has a version so, the mini view where the page gives one. A run's events
+// are drawn one after another, with a moment for each sound and flash, so that what the original took time over takes
+// time here too.
+import { Printer, paper } from '@moonbase-machines/c64/printer.js';
+import { makeEngine } from './load.js';
+import { Speaker } from '../audio.js';
+import { SID } from '@moonbase-machines/c64/sid.js';
+import { matrixOf } from '@moonbase-machines/c64/kernal.js';
+import { standIn } from '@moonbase-machines/c64/rom.js';
+import { withSaves, keepSaves } from '@moonbase-machines/apple2e/saves.js';
+import { Drive } from '@moonbase-machines/c64/drive.js';
+import { keepDrive } from '@moonbase-machines/c64/saves.js';
+import { paperBox, phoneKeys, KEYS_MARKUP } from '../parts.js';
+import { View } from './view.js';
+import { CardView } from './card-view.js';
+import { C64View } from './c64-view.js';
+
+export async function play(game) {
+  const { title, scripts, disk, root, stage, status, fail, kept, words, fixed } = game;
+  root.classList.add('game');   // (the screen of a machine: the stage the game's own shape, player.css)
+  stage.innerHTML = `<svg id="screen" preserveAspectRatio="xMidYMid meet" tabindex="0" aria-label="The game's screen"></svg>`;
+  status.insertAdjacentHTML('afterend', `${KEYS_MARKUP}<label><input type="checkbox" id="sound"> Sound</label><label><input type="checkbox" id="old-style"> Old style text</label><label hidden><input type="checkbox" id="printer" checked> Printer</label><label hidden title="The game with its bugs fixed: it starts again"><input type="checkbox" id="fixed"> Bugs fixed</label><label hidden>Mini view <select id="mini"><option value="">Off</option><option value="live">Live</option><option value="pictures">Pictures</option></select></label>`);
+  root.append(paperBox(words.printer));
+  const $ = id => root.querySelector('#' + id);
+  const svg = $('screen'), soundBox = $('sound');
+  phoneKeys(root, stage);
+
+try {
+  // the choice of the fixed version, where there is one: the page again, with ?fixed or without
+  const fixedBox = $('fixed');
+  if (fixedBox && title.fixed) {
+    fixedBox.checked = fixed; fixedBox.parentElement.hidden = false;
+    fixedBox.addEventListener('change', () => { const u = new URL(location.href); if (fixedBox.checked) u.searchParams.set('fixed', ''); else u.searchParams.delete('fixed'); location.href = u.href.replace('fixed=&', 'fixed&').replace(/fixed=$/, 'fixed'); });
+  }
+  // its view's own drawing, for a title that has one (its title.js `view`, load.js)
+  const extra = title.viewSteps ?? {};
+  // a Commodore 64's character ROM, for its view: Commodore's where the page gives them (`roms`), else moonbase's own
+  const chargen = disk.kind === 'c64' ? game.roms?.chargen ?? standIn().chargen : null;
+
+  // A printer on device 4, for a Commodore 64 title (@moonbase-machines/c64/printer.js): on unless its box is off,
+  // what it prints drawn below the screen as a sheet of paper, until it is torn off
+  if (disk.kind === 'c64') {
+    const box = $('printer'), sheet = $('paper'), shown = $('paper-box');
+    try { box.checked = localStorage.getItem('remake-printer') !== '0'; } catch {}
+    box.parentElement.hidden = false;
+    const printer = title.printer = new Printer({ on: box.checked });
+    box.addEventListener('change', () => { printer.on = box.checked; try { localStorage.setItem('remake-printer', box.checked ? '1' : '0'); } catch {} });
+    printer.changed = () => { shown.hidden = !printer.lines.length; if (printer.lines.length) paper(sheet, printer, chargen); };
+    $('tear').addEventListener('click', () => printer.tear());
+    $('print-paper').addEventListener('click', () => window.print());   // (the sheet alone: its print style)
+  }
+  // what the game saves, on the player's disk: an Apple title's data disk (@moonbase-machines/apple2e/saves.js), a
+  // Commodore 64 title's drive (@moonbase-machines/c64/saves.js, the drive card.js puts on the bus)
+  title.disk = withSaves(disk, kept);
+  if (disk.kind === 'c64') keepDrive(title.drive = new Drive(Uint8Array.from(atob(disk.image), ch => ch.charCodeAt(0))), kept);
+  const engine = makeEngine(title, scripts);
+  if (title.files) keepSaves(disk, title.files, kept);
+  const queue = [];
+  // The view, and every event it has drawn, so that it can be drawn again from the start when
+  // the old style text is turned on or off. The choice is kept in this browser.
+  const oldStyleBox = $('old-style'), history = [];
+  const remember = { get() { try { return localStorage.getItem('remake-old-style') === '1'; } catch { return false; } }, set(v) { try { localStorage.setItem('remake-old-style', v ? '1' : '0'); } catch {} } };
+  oldStyleBox.checked = remember.get() || new URLSearchParams(location.search).has('old-style');   // ?old-style, for a screenshot
+  let onView = null;   // (the mini view's, given each view made)
+  const makeView = () => { svg.replaceChildren(); const v = disk.kind === 'c64' ? new C64View(svg, { engine, chargen }) : title.engine === 'card' ? new CardView(svg, { engine, inset: game.mini ? title.inset : null }) : new View(svg, { disk, volume: Object.keys(disk.volumes)[0], engine, extra }); v.oldStyle = oldStyleBox.checked; onView?.(v); return v; };
+  let view = makeView();
+  engine.on(e => queue.push(view.snapshot({ ...e })));
+  // The mini view, where the page gives one (`mini`) and the title has a place for it (its title.js `inset`): Off,
+  // Live or Pictures, the choice kept in this browser; shown in the band at the top of the screen while the band is
+  // there. A picture only: the game's screen otherwise as it is
+  const miniBox = $('mini');
+  if (title.inset && game.mini) {
+    miniBox.parentElement.hidden = false;
+    try { miniBox.value = localStorage.getItem('remake-mini') ?? ''; } catch {}
+    const { top, bottom, view: [left, right] } = title.inset, at = document.createElement('div');
+    at.className = 'mini'; at.hidden = true;
+    Object.assign(at.style, { left: `${left / 5.6}%`, top: `${top / 3.84}%`, width: `${(right - left) / 5.6}%`, height: `${(bottom - top + 1) / 3.84}%` });
+    svg.parentElement.append(at);
+    const mini = await game.mini(at, { memory: () => engine.mem });
+    // (each view's painting followed by the mini view shown or not, as the band is there or not)
+    onView = v => { v.insetOn = !!miniBox.value; const prompts = v.prompts.bind(v); v.prompts = () => { prompts(); at.hidden = !(miniBox.value && v.banded); }; };
+    onView(view);
+    const show = () => { view.insetOn = !!miniBox.value; mini.mode(miniBox.value); view.prompts(); };
+    miniBox.addEventListener('change', () => { try { localStorage.setItem('remake-mini', miniBox.value); } catch {} show(); });
+    show();
+  }
+  oldStyleBox.addEventListener('change', () => {
+    remember.set(oldStyleBox.checked);
+    view = makeView();
+    for (const e of history) view.apply(e);
+    view.prompts();
+  });
+
+  // the sound: the original's are off until the teacher turns them on, at the engine's sound flag.
+  // A title that keeps the original's time (a card title's, Engine.time) clicks the speaker as
+  // the original did, and the clicks are played as the emulator plays them (audio.js), the
+  // box the sound's on and off.
+  const speaker = engine.timed ? new Speaker() : null;
+  if (speaker) soundBox.checked = true;
+  const hear = () => { if (disk.kind !== 'c64') speaker?.feed(soundBox.checked ? engine.clicks : [], engine.cycles); engine.clicks.length = 0; };
+  const V = title.map?.vars ?? { sound: 0, soundOn: 0 };
+  let audio = null;
+  const tone = (from, to, ms) => {
+    if (!(engine.mem[V.sound] & V.soundOn)) return;
+    audio ??= new AudioContext();
+    const o = audio.createOscillator(), g = audio.createGain(), t = audio.currentTime;
+    o.type = 'square'; o.frequency.setValueAtTime(from, t); o.frequency.linearRampToValueAtTime(to, t + ms / 1000);
+    g.gain.setValueAtTime(0.06, t); g.gain.linearRampToValueAtTime(0, t + ms / 1000);
+    o.connect(g).connect(audio.destination); o.start(t); o.stop(t + ms / 1000);
+  };
+  const pitch = p => 16000 / (p + 8);
+  soundBox.addEventListener('change', () => { if (!speaker) engine.mem[V.sound] = soundBox.checked ? V.soundOn : 0; });
+
+  // how long each step takes to be seen or heard, in milliseconds
+  const PACE = { sound: 220, beep: 60, 'flash-box': 60, flash: 250, object: 30, 'object-keep': 30 };
+  const pace = () => game.pace ?? 1;   // (the original's waits, a part of each: 1 all, 0 none; read at each wait)
+  let drawing = false;
+  const sleep = ms => new Promise(r => setTimeout(r, ms));
+  async function runs() {
+    if (drawing) return;
+    drawing = true;
+    try {
+      for (;;) {
+        const r = engine.run();
+        hear();
+        // the original took time here, a disk's read or a wait it counted out: the screen as it
+        // is, for that long (card.js)
+        if (r === 'pace') {
+          for (const e of queue.splice(0)) { history.push(e); view.apply(e); }
+          view.prompts(); if (!quick && pace()) await sleep(engine.delay * pace()); engine.delay = 0;
+          continue;
+        }
+        engine.delay = 0;
+        while (queue.length) {
+          const e = queue.shift();
+          history.push(e);
+          view.apply(e);
+          if (quick) continue;   // (at full speed: no sound, no wait)
+          if (e.step === 'sound') { const [end, start] = e.words.split(' ').map(h => parseInt(h, 16)); tone(pitch(start), pitch(end), 180); }
+          if (e.step === 'beep') tone(pitch(e.a & 31) * 2, pitch(e.a & 31) * 2, 50);
+          if (!pace()) continue;   // (none of the original's waits: its sounds still)
+          if (PACE[e.step]) await sleep(PACE[e.step] * pace());
+          if (e.step === 'pause') await sleep(e.ms * pace());   // a delay the original counted out
+        }
+        view.prompts();
+        status.textContent = r === 'end' ? 'The end.' : 'Waiting for a key.';
+        if (!engine.keys.length || r === 'end') break;
+      }
+    } catch (err) { fail(err); }
+    drawing = false;
+  }
+
+  // keys as the Apple's keyboard gave them
+  // (a Commodore 64's in PETSCII: its cursor keys, DEL and RUN/STOP, and its letters capitals)
+  const KEYS = disk.kind === 'c64'
+    ? { ArrowLeft: 157, ArrowRight: 29, ArrowDown: 17, ArrowUp: 145, Enter: 13, Backspace: 20, Delete: 20, Escape: 3, ' ': 32 }
+    : { ArrowLeft: 8, ArrowRight: 21, ArrowDown: 10, ArrowUp: 11, Enter: 13, Backspace: 127, Delete: 127, Escape: 27, ' ': 32 };
+  let quick = false;
+  const press = k => { engine.press(k); audio?.resume(); speaker?.start(); if (disk.kind !== 'c64') runs(); };
+  // (a page that follows the game, the island's, given it: the engine, its memory, a key pressed as the
+  // player presses one, and `quick(on)`, the game at full speed, none of its waits, to jump ahead in it)
+  game.watch?.({ engine, press, quick: on => { quick = on; } });
+  // A game that goes on without waiting for keys, as Nature Park's truck: each turn of its loop is
+  // a step `tick`, which takes a key or none. A turn passes every 100 milliseconds, as the
+  // original's took, with the key pressed since the last or still held, as the Apple's keyboard
+  // told the game a key was down.
+  const ticking = () => engine.waitingOn?.words?.[0] === 'tick';
+  let held = null, tapped = null;
+  setInterval(() => {
+    if (!ticking() || drawing || engine.keys.length) return;
+    const k = tapped ?? held ?? -1; tapped = null;
+    press(k);
+  }, 100);
+  window.addEventListener('keydown', e => {
+    if (e.metaKey || e.altKey) return;
+    const k = e.ctrlKey ? (/^[a-z]$/i.test(e.key) ? e.key.toUpperCase().charCodeAt(0) & 0x1f : undefined) : KEYS[e.key] ?? (e.key.length === 1 ? (disk.kind === 'c64' ? e.key.toUpperCase() : e.key).charCodeAt(0) : undefined);
+    if (k === undefined) return;
+    e.preventDefault();
+    if (ticking()) { tapped = held = k; return; }
+    // a Commodore 64's key held down in its keyboard's matrix, which its KERNAL scans and repeats
+    // as long as it is held, as the original's did (@moonbase-machines/c64/kernal.js); a character typed only
+    // with shift into the buffer
+    const m = disk.kind === 'c64' && !e.ctrlKey && matrixOf(k);
+    if (m) { if (!e.repeat) { engine.clock.held = { ...m, key: e.key }; audio?.resume(); speaker?.start(); } return; }
+    if (!e.repeat && !game.claim?.(k)) press(k);   // (the player's key offered to the page first: `claim`, main.js)
+  });
+  window.addEventListener('keyup', e => {
+    held = null;
+    const h = engine.clock?.held;
+    if (h?.key === e.key) { if (h.seen) engine.clock.held = null; else h.up = true; }
+  });
+  svg.addEventListener('click', e => { const key = e.target.closest('.key')?.dataset.key; if (key) press(+key); });
+  svg.focus();
+  // A Commodore 64 title runs on the clock, as the original did, waiting for a key or not: a
+  // sixtieth of a second of the original's cycles at a time (the engine's run stops at each 16 ms of
+  // them), its raster and its interrupt at the time they come (card.js), and the screen
+  // painted after each. And the SID, its writes played a sixtieth of a second at a time, as the
+  // emulator plays a frame's (original.js).
+  if (disk.kind === 'c64') {
+    // a route the page gives (`route`, a workshop's pilots' route) played first as the pilots play it, each key when
+    // the game waits for one, off the clock, so that it goes where it went on both sides; then the game goes on as
+    // usual
+    if (game.route) {
+      const { route, name: routeName, keys: { expand, give, petscii, pollsAt } } = game.route;
+      title.seed = route.seed;   // (RND's numbers from the route's seed, as the pilots have them)
+      if (route.printer && title.printer) { title.printer.on = true; $('printer').checked = true; }
+      status.textContent = 'Playing the route ' + routeName + '.';
+      // (a key behind the one pressed goes into the KERNAL's buffer, as the pilots hold a key)
+      const side = { press: k => engine.press(k), also: k => { const m = engine.mem, put = v => { if (m[0xc6] < 10) { m[0x277 + m[0xc6]] = v; m[0xc6]++; } }; if (engine.keys.length) put(engine.keys.shift()); put(k); } };
+      const go = () => { let r; do { engine.delay = 0; r = engine.run(); } while (r === 'pace'); queue.length = 0; };
+      go();
+      for (const [i, [k]] of expand(route.keys).entries()) { give(side, k, petscii); engine.polls = pollsAt(route, i + 1) ?? undefined; go(); }
+      engine.polls = undefined; view.prompts();
+    }
+    engine.sid = []; engine.clock = { irq: 0, ahead: [], since: 0 };
+    let sid = null, from = null, sent = 0, stopped = false;
+    status.textContent = 'Playing.';
+    setInterval(() => {
+      engine.delay -= 1000 / 60;   // a load's time, or the last run's
+      if (!stopped && !engine.ended && engine.delay < 16) {
+        engine.delay = Math.max(0, engine.delay);
+        // a key of ?keys when the game is waiting for one, two seconds at least after the last, as
+        // a player would press them (a wait the game counts out goes on by itself on the clock)
+        if (engine.clock.ahead.length && engine.idle > (engine.routines.polls ?? 200) && !engine.keys.length && ++engine.clock.since > 120) { engine.press(engine.clock.ahead.shift()); engine.clock.since = 0; }
+        try { engine.run(); queue.length = 0; view.prompts(); } catch (err) { stopped = true; fail(err); }
+        if (engine.ended) status.textContent = 'The end.';
+      }
+      if (speaker?.node && soundBox.checked) {
+        sid ??= new SID(speaker.rate); from ??= performance.now();
+        const n = Math.floor((performance.now() - from) / 1000 * speaker.rate) - sent;
+        if (n > 0) { const wave = sid.render(n, engine.sid.map(([, r, v]) => [0, r, v])); sent += n; speaker.node.port.postMessage(wave, [wave.buffer]); }
+      }
+      engine.sid.length = 0;
+    }, 1000 / 60);
+  }
+  // ?keys=space,space,right,return presses keys at the start, to go straight to a scene
+  const start = new URLSearchParams(location.search).get('keys');
+  if (start) for (const k of start.split(',')) { const a = { space: 32, return: 13, escape: 27, delete: 127, left: 8, right: 21, down: 10, up: 11, 'control-e': 5, 'control-t': 20, none: -1 }[k] ?? k.charCodeAt(0); if (disk.kind === 'c64') engine.clock.ahead.push({ 8: 157, 21: 29, 10: 17, 11: 145, 127: 20, 27: 3 }[a] ?? a); else engine.press(a); }
+  if (disk.kind !== 'c64') runs();
+} catch (err) { fail(err); }
+}

package/remake/script.js

@@ -0,0 +1,60 @@
+// A scene script: the steps of a part or a problem, a step to a line, as a lifter's --script
+// writes them and as they are edited after. A line may start with the address in the original
+// it came from, which is kept so that the pilots can say where two runs part.
+//
+//   L8157:                         a label
+//   8157  object 3 4 44            a step: the engine's work, with its inputs
+//   814F  a = $8235                a statement on the registers a, x, y and memory
+//   8152  if zero goto L8157       a branch on a flag, or on a compare: if a == 1 goto L8157
+//   data $86E4 01 02 03 04         bytes of the original's tables, at their addresses
+//   ; a comment
+//
+// parse() gives { steps, labels, data }: each step is { at, op, args, text }.
+
+const WORD = /"(?:[^"\\]|\\.)*"|\S+/g;
+
+export function parse(source, name = 'script') {
+  const steps = [], labels = {}, data = [];
+  source.split('\n').forEach((raw, n) => {
+    const line = raw.replace(/^\s+|\s+$/g, '');
+    if (!line || line.startsWith(';')) return;
+    const where = name + ':' + (n + 1);
+    let m;
+    if ((m = /^(L[0-9A-F]{4}|[A-Za-z_][\w-]*):$/.exec(line))) { labels[m[1]] = steps.length; return; }
+    if ((m = /^data \$([0-9A-F]+)((?: [0-9A-F]{2})+)$/i.exec(line))) { data.push({ at: parseInt(m[1], 16), bytes: m[2].trim().split(' ').map(h => parseInt(h, 16)) }); return; }
+    m = /^([0-9A-F]{4})\s+(.*)$/.exec(line);
+    const at = m ? parseInt(m[1], 16) : null, body = m ? m[2] : line;
+    steps.push({ at, words: words(body), text: body, where, index: steps.length });
+  });
+  return { steps, labels, data };
+}
+
+// a line's words, a quoted one as { string }
+export const words = body => body.match(WORD).map(w => w.startsWith('"') ? { string: JSON.parse(w) } : w);
+
+// an operand: a number, a register, a flag, or a place in memory; [$0D19] is the address the
+// code keeps at $0D19 and $0D1A, written there as it runs, as an instruction's own operand is
+//   12  a  x  y  carry  $866A  $86E4[y]  $12[x]  ($12)[y]  ($12[x])  [$0D19][y]
+export function operand(word) {
+  if (typeof word !== 'string') return { string: word.string };
+  if (/^-?\d+$/.test(word)) return { number: +word };
+  if (/^[axy]$/.test(word) || word === 'carry' || word === 'borrow') return { reg: word };
+  let m;
+  if ((m = /^\$([0-9A-F]+)(?:\[([xy])\])?$/i.exec(word))) return { at: parseInt(m[1], 16), index: m[2], zp: m[1].length <= 2 };
+  if ((m = /^\(\$([0-9A-F]{2})\)\[y\]$/i.exec(word))) return { through: parseInt(m[1], 16) };
+  // ($27[x]): the address kept at the zero page's $27 plus X, as LDA ($27,X)
+  if ((m = /^\(\$([0-9A-F]{2})\[x\]\)$/i.exec(word))) return { pair: parseInt(m[1], 16) };
+  if ((m = /^\[\$([0-9A-F]{4})\](?:\[([xy])\])?$/i.exec(word))) return { via: parseInt(m[1], 16), index: m[2] };
+  throw new Error('not an operand: ' + word);
+}
+
+// The cycles a branch takes more when it goes: one, and one more when it goes to another page
+// than the instruction after it. A line that compares and branches (if a != 13 goto L) is two
+// instructions, the compare's size before the branch's.
+const SIZE = w => /^\d+$/.test(w) || /^\$[0-9A-F]{2}(\[[xy]\])?$/i.test(w) || /^\(\$/.test(w) ? 2 : 3;
+export function branchTaken(step) {
+  if (step.at === null) return 1;
+  const w = step.words, to = parseInt(w.at(-1).slice(1), 16);
+  const next = (step.at + (w.length === 6 ? SIZE(w[3]) : 0) + 2) & 0xffff;
+  return /^L[0-9A-F]{4}$/.test(w.at(-1)) && (to & 0xff00) !== (next & 0xff00) ? 2 : 1;
+}