@moonbase-machines/player 0.9.0 → 0.10.0

package/play.js

@@ -0,0 +1,186 @@
+// The player: one way in for every title and every way to play it, the Original (the game's own disk on the machine
+// it was made for) and the Remake (its scenes on the remake's engine, or the title's own engine). The player makes its
+// part of the page and owns it, the same for all: the section and its classes, the stage and its size, the options
+// line and the status, the keys, the sound, the printer, the saves on the player's disk, and what the page asks of it;
+// the engine plays the game on the stage and does nothing of the page's.
+//
+//   await play({ way, slug, title, data, root, disk, backend, preview, words, screen, watch, claim, pace, route, mini,
+//                roms, studies, downloadDisk })
+//     way          'original' or 'remake' (the default)
+//     slug         the title's name in addresses: its section's class, its disk
+//     title        the title's folder, an absolute URL (title.js, its scenes, compiled/, its own modules), where it
+//                  has one; a game without one (a study) has only its data
+//     data         its game's data, an absolute URL (<name>.json: its disks' files, its kind, its saves), or for a
+//                  title of its own engine the folder its data is in
+//     root         the page's section the player is made in
+//     disk         the title's player's disk (disk/disk.js); else the player opens it, `title/<slug>`, on `backend`
+//                  where the page gives one (the browser's own, unless it does)
+//     preview      the preview's build: what only it has may be used
+//     words        the page's words the player shows: { printer: { line, print, tear } }
+//     screen       [width, height], the screen's shape in its own dots where the page draws its own over it
+//   and what a page that follows the game asks:
+//     watch        called with { engine, press, quick } once the game is ready: its engine (where it has one), a key
+//                  pressed as the player presses one, and the game at full speed or not
+//     claim        k => true to take a key of the player's before the game does
+//     pace         how much of the original's waits: 1 all (the default), 0 none, between a part of each; a number or
+//                  a function, read at each wait
+//   and what only a workshop has, given by its pages, never looked for here:
+//     route        a route to play first, { name, route, keys }: its keys, and the pilots' key handling
+//     mini         a mini view for a title with an `inset`, (at, { memory }) => { mode(m) }
+//     roms         the makers' ROMs this machine has (engines/original.js; a Commodore 64 remake's { chargen })
+//     studies      files of its own for a Commodore 64 game's disk, in the drive, not kept
+//     downloadDisk a Commodore 64 game's disk offered to download, with what is saved on it
+//
+// An engine (engines/original.js, engines/scenes.js, or the title's own, its title.js `engine` a module in its folder)
+// exports `play(game)`: given `game`, the player's own for it (below), it makes what it draws on the stage and returns
+// its handle, or nothing where it cannot start (and has said why in the status):
+//   { run(), press(k)?, key(e, k)?, keys(list)?, route(route)?, start()?, sound(on)?, soundOn?, quick(on)?,
+//     engine?, diskImage()? }
+// run() starts it; press(k) a key, the machine's code (none for a title of its own engine with no machine's keys,
+// which reads the keyboard itself); key(e, k), for an engine that reads the keyboard itself, each
+// keydown and keyup with its code (undefined where the machine has none); keys(list), ?keys= at the start; route, the
+// page's route; start(), at the player's first gesture (sound may start only then); sound(on) and soundOn, the
+// Sound box; quick(on) the game at full speed; engine, what `watch` gives a page; diskImage(), the disk to download.
+import { titleOf, loadTitle, read } from './remake/load.js';
+import { openDisk, titleDisk } from './disk/disk.js';
+import { savesFor } from './saves.js';
+import { code, named } from './keys.js';
+import { paperBox, phoneKeys, KEYS_MARKUP } from './parts.js';
+
+// each machine's screen, in its own dots: an Apple's hi-res page, a Commodore 64's frame, border and all
+const SCREENS = { prodos: [280, 192], dos33: [280, 192], c64: [384, 272] };
+const ENGINES = { original: () => import('./engines/original.js'), card: () => import('./engines/scenes.js'), vector: () => import('./engines/scenes.js') };
+
+export async function play(options) {
+  const { way = 'remake', slug, root, preview = false, words } = options;
+  root.classList.add('player', way);
+  if (slug) root.classList.add(slug);
+  root.innerHTML = `<div class="stage"></div><p class="options"><span id="status">Loading.</span>${KEYS_MARKUP}`
+    + '<label hidden><input type="checkbox" id="sound" checked> Sound</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>'
+    + '<button id="disk" type="button" hidden>Download the disk</button></p>';
+  root.append(paperBox(words.printer));
+  const $ = id => root.querySelector('#' + id);
+  const stage = root.querySelector('.stage'), status = $('status'), soundBox = $('sound');
+  const fail = err => { status.textContent = 'The game stopped: ' + err.message; status.className = 'error'; console.error(err); };
+  try {
+    // ?fixed: the title with its bugs fixed, for one that has such a version (its title.js `fixed`)
+    const fixed = new URLSearchParams(location.search).has('fixed');
+    const folder = options.title ? new URL(options.title) : null, data = new URL(options.data);
+    // the title, and for its remake its scripts; the game's data (none here for a title of its own engine, which
+    // reads its own from its folder)
+    let title = null, scripts = {}, game = null;
+    if (way === 'remake') ({ title, scripts, disk: game } = await loadTitle(folder, { data, fixed }));
+    else if (folder) title = await titleOf(folder);
+    if (!game && /\.json$/.test(data.pathname)) game = await read(data, 'json');
+    const kind = game?.kind;
+    // the title's own styles, where it has them (its title.js `style`), in place before it draws by them
+    if (title?.style && !document.querySelector(`link[data-title="${title.slug}"]`)) {
+      const link = Object.assign(document.createElement('link'), { rel: 'stylesheet', href: new URL(title.style, folder).href });
+      link.dataset.title = title.slug; document.head.append(link);
+      await new Promise(done => { link.onload = link.onerror = done; });
+    }
+    const disk = options.disk ?? await openDisk(titleDisk(slug), { backend: options.backend });
+    // (a save the disk's backend could not store, said, not lost)
+    disk.failed = err => { status.textContent = 'A file was not kept: ' + err.message; status.className = 'error'; };
+    const [dots, lines] = options.screen ?? title?.screen ?? SCREENS[kind] ?? SCREENS.prodos;
+    fit(stage, root, dots, lines);
+
+    // a printer on device 4, for a Commodore 64 game: on unless its box is off (the choice kept in this browser),
+    // what it prints drawn below the screen as a sheet of paper, until it is torn off
+    let printer = null;
+    const g = {
+      way, slug, title, scripts, game, folder, data, stage, status, fail, disk, preview, words, fixed, $,
+      saves: game ? savesFor(game, disk) : null, roms: options.roms, studies: options.studies, mini: options.mini ?? null,
+      chargen: null,   // (the engine's Commodore 64 characters, for the printer's paper)
+      pace: () => { const p = options.pace; return typeof p === 'function' ? p() : p ?? 1; },
+      // an engine's own control on the options line, after the sound
+      control(html) { $('printer').parentElement.insertAdjacentHTML('beforebegin', html); },
+      // the engine's sound turned on or off by the game itself (Aztlan's Game > Sounds): the box with it
+      sounding(on) { soundBox.checked = on; },
+    };
+    if (kind === 'c64') {
+      const { Printer, paper } = await import('@moonbase-machines/c64/printer.js');
+      const box = $('printer'), sheet = $('paper'), shown = $('paper-box');
+      try { box.checked = localStorage.getItem('printer') !== '0'; } catch {}
+      box.parentElement.hidden = false;
+      printer = g.printer = new Printer({ on: box.checked });
+      box.addEventListener('change', () => { printer.on = box.checked; try { localStorage.setItem('printer', box.checked ? '1' : '0'); } catch {} });
+      printer.changed = () => { shown.hidden = !printer.lines.length; if (printer.lines.length) paper(sheet, printer, g.chargen); };
+      $('tear').addEventListener('click', () => printer.tear());
+      $('print-paper').addEventListener('click', () => window.print());   // (the sheet alone: its print style)
+    }
+    // the choice of the fixed version, where there is one: the page again, with ?fixed or without
+    if (way === 'remake' && title?.fixed) {
+      const box = $('fixed');
+      box.checked = fixed; box.parentElement.hidden = false;
+      box.addEventListener('change', () => { const u = new URL(location.href); if (box.checked) u.searchParams.set('fixed', ''); else u.searchParams.delete('fixed'); location.href = u.href.replace('fixed=&', 'fixed&').replace(/fixed=$/, 'fixed'); });
+    }
+
+    const engine = way === 'original' ? await ENGINES.original() : title.own ?? await ENGINES[title.engine]();
+    const handle = await engine.play(g);
+    if (!handle) return;
+
+    // the sound, where the engine has it: the box as the engine starts it, and the engine told of each change
+    if (handle.sound) {
+      soundBox.parentElement.hidden = false; soundBox.checked = handle.soundOn ?? true;
+      soundBox.addEventListener('change', () => handle.sound(soundBox.checked));
+    }
+    // the keys, one listener for every engine: the machine's code for each (keys.js), offered to the page first
+    // (`claim`), then the engine's: the event itself where it reads the keyboard, else the code pressed
+    const keyed = e => {
+      const k = code(e, kind), down = e.type === 'keydown';
+      if (down && k !== undefined && !e.repeat && options.claim?.(k)) { e.preventDefault(); return; }
+      if (down) handle.start?.();
+      if (handle.key) { handle.key(e, k); return; }
+      if (!down || k === undefined || e.repeat || !handle.press) return;   // (a held key is one key)
+      e.preventDefault(); handle.press(k);
+    };
+    addEventListener('keydown', keyed); addEventListener('keyup', keyed);
+    stage.addEventListener('pointerdown', () => handle.start?.());
+    phoneKeys(root, stage);
+    // the disk as it stands, its own files and those saved, to download where the page offers it (a .d64 that VICE
+    // or a real 64 can use)
+    if (options.downloadDisk && handle.diskImage) {
+      const button = $('disk'), name = data.pathname.split('/').pop().replace(/\.json$/, '');
+      button.hidden = false;
+      button.addEventListener('click', () => {
+        const a = Object.assign(document.createElement('a'), { href: URL.createObjectURL(new Blob([handle.diskImage()], { type: 'application/octet-stream' })), download: name + '.d64' });
+        a.click(); URL.revokeObjectURL(a.href);
+      });
+    }
+    // a page that follows the game: its engine, a key pressed as the player presses one, the game at full speed
+    options.watch?.({ engine: handle.engine, press: k => { handle.start?.(); handle.press?.(k); }, quick: on => handle.quick?.(on) });
+    // a route the page gives, played first; then the game; then ?keys=space,space,right,return, to go straight to a
+    // scene
+    if (options.route) {
+      if (!handle.route) throw new Error('a route cannot be played on the ' + way);
+      await handle.route(options.route);
+    }
+    handle.run();
+    const start = new URLSearchParams(location.search).get('keys');
+    if (start) { const list = start.split(',').map(n => named(n, kind)); if (handle.keys) handle.keys(list); else for (const k of list) handle.press?.(k); }
+  } catch (err) { fail(err); }
+}
+
+// The screen sized evenly: a whole number of the device's pixels to each of the screen's dots, so every dot is drawn
+// the same size and a line one dot thick is as thick as any other; the next whole number up from the column's width,
+// a little wider than it and centred on it, unless that is wider than the window or taller than the stage may be (its
+// max-height, where the page sets one: a phone on its side); kept so as the window, or its zoom, changes. The scale,
+// in the page's pixels to a dot, is the section's --scale too, for a title drawn in CSS.
+function fit(stage, column, dots, lines) {
+  const size = () => {
+    const dpr = window.devicePixelRatio || 1, pad = parseFloat(getComputedStyle(column).paddingLeft) * 2;
+    const room = column.clientWidth - pad, most = document.documentElement.clientWidth - 16, tall = parseFloat(getComputedStyle(stage).maxHeight);
+    let k = Math.ceil(room * dpr / dots - 0.01);
+    if (dots * k / dpr > most) k = Math.max(1, Math.floor(most * dpr / dots));
+    if (tall && lines * k / dpr > tall) k = Math.max(1, Math.floor(tall * dpr / lines));
+    const w = dots * k / dpr;
+    Object.assign(stage.style, { width: w + 'px', height: lines * k / dpr + 'px', aspectRatio: 'auto', marginLeft: (room - w) / 2 + 'px' });
+    column.style.setProperty('--scale', k / dpr);
+  };
+  size();
+  addEventListener('resize', size);
+}

package/player.css

@@ -3,16 +3,17 @@
    where the page names them (--screen, --muted, --gold, --alert, --line, --surface, --ink, --bg, --accent,
    --accent-ink, --sans), else these. */
 
-.game .stage { position: relative; width: min(100%, 960px, calc((var(--vvh, 100vh) - 260px) * 560 / 384)); margin: 0 auto; aspect-ratio: 560 / 384; background: var(--screen, #000); border-radius: 10px; overflow: hidden; box-shadow: 0 10px 30px -12px #0006; }
-.game .stage canvas, .game .stage svg { position: absolute; inset: 0; width: 100%; height: 100%; }
-.game .stage canvas { image-rendering: pixelated; }
+/* (the stage's size the player's, play.js `fit`: a whole number of the device's pixels to each of the screen's dots) */
+.player .stage { position: relative; margin: 0 auto; background: var(--screen, #000); border-radius: 10px; overflow: hidden; box-shadow: 0 10px 30px -12px #0006; }
+.player .stage canvas, .player .stage svg { position: absolute; inset: 0; width: 100%; height: 100%; }
+.player .stage canvas { image-rendering: pixelated; }
 /* the remake's mini view, where the page gives one: in the band at the top of the screen, placed by the title's inset */
-.game .stage .mini { position: absolute; overflow: hidden; border-radius: 3px; background: #000; pointer-events: none; }
-.game .stage .mini.toggle { pointer-events: auto; cursor: pointer; }
-.game .stage .mini canvas, .game .stage .mini img { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; image-rendering: auto; }
-.game.remake .stage { background: #fff; }
-.game.remake .stage svg .key { cursor: pointer; }
-.game.remake .stage svg .key:hover rect { stroke: var(--gold, #a8801f); }
+.player .stage .mini { position: absolute; overflow: hidden; border-radius: 3px; background: #000; pointer-events: none; }
+.player .stage .mini.toggle { pointer-events: auto; cursor: pointer; }
+.player .stage .mini canvas, .player .stage .mini img { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; image-rendering: auto; }
+.player.remake .stage { background: #fff; }
+.player.remake .stage svg .key { cursor: pointer; }
+.player.remake .stage svg .key:hover rect { stroke: var(--gold, #a8801f); }
 .options { display: flex; flex-wrap: wrap; gap: 8px 18px; align-items: center; justify-content: center; font-size: 15px; color: var(--muted, #5d6475); margin: 14px 0; }
 #status.error { color: var(--alert, #9b3d2e); }
 #paper { display: block; width: 100%; height: auto; border-radius: 2px; box-shadow: 0 2px 8px #0005; }

package/remake/card.js

@@ -135,11 +135,13 @@ export function cardRoutines(title) {
   else installRom({ cpu, game: title.disk, sw: { lcRead: 0 }, io: a => io(engine, a), file: n => files.file(n), get files() { return files.files; }, put: (path, f) => files.put(path, f), remove: path => files.remove(path), clicks: { push: c => engine.clicks.push(engine.cycles + c - romFrom) }, log() {}, halted: false });
   const rom = (e, at) => {
     const f = cpu.hooks.get(at);
-    // a Commodore 64's BASIC, which MENU runs NOTEBOOK (compiled BASIC) and ZOOTIME (BASIC) with
-    if (!f && c64 && at >= 0xa000 && at < 0xc000) throw new Error('a BASIC program (Zoopak\'s NOTEBOOK or ZOOTIME): not written yet in the remake');
+    // a Commodore 64's BASIC, which a BASIC program calls, as Zoopak's MENU runs NOTEBOOK (compiled BASIC) and
+    // ZOOTIME (BASIC) with
+    if (!f && c64 && at >= 0xa000 && at < 0xc000) throw new Error('a BASIC program, calling BASIC\'s ROM at $' + hex4(at) + ': not written yet in the remake');
     if (!f) throw new Error('no ROM routine at $' + hex4(at));
     engine = e;
-    Object.assign(cpu, { a: e.a, x: e.x, y: e.y, c: e.c, z: e.z, n: e.n, v: e.v });
+    // (the stack pointer as the call to the routine left it: the frames' place, less the call's two bytes)
+    Object.assign(cpu, { a: e.a, x: e.x, y: e.y, c: e.c, z: e.z, n: e.n, v: e.v, pc: at, sp: e.sp() - 2 & 0xff });
     // a routine that reads the keyboard (RDKEY) waits, with no key, and the step runs again
     const start = romFrom = cpu.cycles;
     const r = f(cpu);
@@ -150,6 +152,9 @@ export function cardRoutines(title) {
     e.delay += (cpu.cycles - start + 6) / CLOCK * 1000; e.cycles += cpu.cycles - start + 6;
     Object.assign(e, { a: cpu.a & 0xff, x: cpu.x & 0xff, y: cpu.y & 0xff, c: cpu.c, z: cpu.z, n: cpu.n });
     if (r === 'return') return r;   // (a routine that returns from its caller too: $E206 at a statement's end)
+    // a routine that goes on elsewhere, not back: DOS 3.3's error exit, from a command printed through COUT, to where
+    // DOS goes on (rom.js `dosError`)
+    if (r === false && cpu.pc !== at) return { to: cpu.pc };
   };
 
   // Where an address of the lifted code is: a label in a script. The scenes all run at $AD00,
@@ -199,10 +204,11 @@ export function cardRoutines(title) {
     return [name, 'L' + hex4(at)];
   };
   // an address the ROM's routine answers: above $D000, unless the card is read there and a script
-  // has its code there (Pieces of Eight's PO8:BLINK, over HPOSN and DRAW); on a Commodore 64, where
+  // has its code there (Pieces of Eight's PO8:BLINK, over HPOSN and DRAW), or below where rom.js answers DOS's own
+  // (INITIOHK, $A851) and no script has code; on a Commodore 64, where
   // the 6510's port shows the KERNAL ($E000 on) or BASIC ($A000 to $BFFF: Tell-A-Tale's numbers,
   // over MENU's code in the RAM under it)
-  const romAt = (e, a) => c64 ? (a >= 0xe000 ? (e.mem[1] & 2) !== 0 : a >= 0xa000 && a < 0xc000 ? (e.mem[1] & 3) === 3 : a === 0x73 || a === 0x79) : a >= 0xd000 && !(lc.read && labelled(e, a).length);
+  const romAt = (e, a) => c64 ? (a >= 0xe000 ? (e.mem[1] & 2) !== 0 : a >= 0xa000 && a < 0xc000 ? (e.mem[1] & 3) === 3 : a === 0x73 || a === 0x79) : a >= 0xd000 ? !(lc.read && labelled(e, a).length) : cpu.hooks.has(a) && !labelled(e, a).length;
   // the stir of START.SYSTEM's wait: its calls are no steps
   const stirring = step => toolkit.stir && step?.at >= toolkit.stir.from && step.at <= toolkit.stir.to;
   const emit = (e, ev, quiet) => { if (quiet) e.inside++; e.emit(ev); if (quiet) e.inside--; };
@@ -235,7 +241,16 @@ export function cardRoutines(title) {
     inputs(e, name, args); emit(e, unplaced(describe(name, [], e, undefined, undefined, a => e.mem[a])), stirring(step));
     const v = c64 && VECTORED[name], to = v && (e.mem[v[0]] | e.mem[v[0] + 1] << 8);
     if (v && to !== v[1]) { const [script, label] = find(e, to); e.callInside(script, label, x => { if (GIVES[name]) x.emit(result(name, { a: x.a, x: x.x, y: x.y, c: x.c })); }, step?.at == null ? undefined : (step.at + 2) & 0xffff); return; }
-    if (rom(e, at) === 'wait') return 'wait';
+    const r = rom(e, at);
+    if (r === 'wait') return 'wait';
+    // (gone on elsewhere: the code there run inside the step, the routine's return still on the stack, as the
+    // original's is, until that code drops it, as Pieces of Eight's handler ($93F0) does with a TXS to the frames
+    // under it, kept at their place for it (Engine.stackPage))
+    if (r?.to !== undefined) {
+      e.stackPage();
+      e.stack.push({ name: e.name, pc: e.pc, inside: true, ret: step?.at == null ? undefined : (step.at + 2) & 0xffff }); e.inside++;
+      return routines['goto-engine'](e, ['$' + hex4(r.to)], step);
+    }
     if (GIVES[name] && c64) e.emit(result(name, { a: e.a, x: e.x, y: e.y, c: e.c }));
   };
 
@@ -301,6 +316,8 @@ export function cardRoutines(title) {
         if (c64 && ENDS.has(a)) pullRegisters(e);   // the end of an interrupt: the registers back, then its RTI
         back(e); return;   // as its RTS: out of a routine it ends
       }
+      // (code the game has written since, a JMP: on through it, as Pieces of Eight's at $A6D8, into DOS's error exit)
+      if (!c64 && e.mem[a] === 0x4c && !labelled(e, a).length) return routines['goto-engine'](e, ['$' + hex4(e.mem[a + 1] | e.mem[a + 2] << 8)], step);
       e.enter(...find(e, a));
     },
   };
@@ -421,7 +438,7 @@ export function cardRoutines(title) {
   // as the observer has the original take it (the pilots' observer), and then the VIC's raster
   // interrupt, where the game has turned it on ($D01A), at the line it set (Find Me's split of its
   // screen into two character sets), $D019 saying which it is. On the page's clock (
-  // scenes.js sets `e.clock`), each is taken as the original's chips took it: the CIA's every 16,421
+  // engines/scenes.js sets `e.clock`), each is taken as the original's chips took it: the CIA's every 16,421
   // cycles of the original's time, the raster's when its line comes (routines.before). Not while
   // the game has them masked (SEI). The routine starts as the KERNAL's own entry ($FF48) leaves
   // it, with A, X and Y pushed, and the KERNAL's end ($EA31, $EA7B, $EA7E, $EA81), or its own PLAs

package/remake/engine.js

@@ -324,19 +324,32 @@ export class Engine {
     }
     const f = this.stack.pop(); if (a) this.a = this.flags(f.a); else [this.n, this.z, this.c, this.v] = f.flags;
   }
-  // the machine's own instructions a scene keeps. TSX gives the stack's place, as the
-  // original's stack pointer would be with these frames on it, and keeps the frames under
-  // it; TXS goes back to the frames kept at the place it is given (Detect-A-Pet's save and
+  // the stack's place, as the original's stack pointer would be with these frames on it: each
+  // frame its bytes, a call's two (its return address) and a push's one
+  sp() { return 0xff - this.stack.reduce((n, f) => n + (f.name === undefined ? 1 : f.half ? 1 : 2), 0) & 0xff; }
+  // the frames kept at their place, for a TXS to go back to, and their bytes in the stack page as
+  // the original's are there: a call's return address, high byte first from the bottom, as JSR
+  // pushes it (half of one pulled, its high byte), and a push's byte, PHP's as the 6502's (Pieces of Eight's DOS error
+  // handler, $93F0, reads the return address under its own to see who called)
+  stackPage() {
+    const sp = this.sp();
+    (this.stacks ??= new Map()).set(sp, this.stack.map(f => ({ ...f })));
+    let at = 0xff;
+    for (const f of this.stack) {
+      const r = f.ret ?? 0;
+      if (f.name === undefined) this.mem[0x100 + at--] = f.a ?? (f.flags ? f.flags[0] << 7 | f.flags[3] << 6 | 0x30 | f.flags[1] << 1 | f.flags[2] : 0);
+      else { this.mem[0x100 + at--] = r >> 8; if (!f.half) this.mem[0x100 + at--] = r & 0xff; }
+    }
+    return sp;
+  }
+  // the machine's own instructions a scene keeps. TSX gives the stack's place (`stackPage`); TXS
+  // goes back to the frames kept at the place it is given (Detect-A-Pet's save and
   // load keep the stack page and its pointer), and to none at any other, as the town's
   // resets the stack and drops every script called. SED and CLD set decimal mode, and SEI and
   // CLI the mask a Commodore 64's interrupt waits on (card.js). The rest (a byte that
   // is no instruction) change nothing the remake holds.
   asm(op) {
-    if (op === 'TSX') {
-      const sp = 0xff - this.stack.reduce((n, f) => n + (f.name === undefined ? 1 : f.half ? 1 : 2), 0) & 0xff;
-      (this.stacks ??= new Map()).set(sp, this.stack.map(f => ({ ...f })));
-      this.x = this.flags(sp);
-    }
+    if (op === 'TSX') this.x = this.flags(this.stackPage());
     if (op === 'TXS') {
       const kept = this.stacks?.get(this.x);
       this.stack = kept ? kept.map(f => ({ ...f })) : []; this.visited = null; this.inside = this.stack.filter(f => f.inside).length;

package/remake/load.js

@@ -1,8 +1,9 @@
-// One way to start a title's remake, for the remake's page (main.js), a replay and Node (a pilot's observer): the
+// One way to start a title's remake, for the player (play.js), a replay and Node (a pilot's observer): the
 // title's title.js, from the folder it is in, with the modules it names (its problems, its paint); its scripts,
 // compiled to JavaScript (bin/moonbase-compile.mjs) or, with `scenes`, the scene files themselves to run line by line;
 // its game's data, from where the page keeps it; and an engine made from them.
 //
+//   const title = await titleOf(folder)                 the title alone: its title.js and the modules it names
 //   const { title, scripts, disk, folder } = await loadTitle(folder, { data })
 //     folder   the title's folder, an absolute URL (its title.js, its scenes, compiled/, its own modules)
 //     data     its game's data, an absolute URL (<slug>.json: its disks' files, its kind, its saves)
@@ -11,7 +12,7 @@
 // With `fixed`, a title that has a version with its bugs fixed (its title.js `fixed`, a script for each it replaces)
 // runs those scripts in place of its own. A title whose engine is its own (its title.js `engine` the name of a module
 // in its folder, not 'card' or 'vector') has no scripts here: its engine is loaded with its other modules, as
-// `title.own`, and runs the game itself (main.js).
+// `title.own`, and runs the game itself (play.js).
 import { Engine } from './engine.js';
 import { vectorRoutines } from './vector.js';
 import { cardRoutines } from './card.js';
@@ -29,13 +30,19 @@ async function read(url, as) {
 }
 const defaultOf = async url => (await import(url.href)).default;
 
-export async function loadTitle(folder, { data, scenes = false, fixed = false } = {}) {
+export async function titleOf(folder) {
   folder = new URL(folder);
   const title = { ...(await defaultOf(new URL('title.js', folder))) };
   // the modules a title has of its own, as its title.js names them (problems.js, paint.js), and its view's own
   // drawing (view.js), where it says it has one
   for (const name of title.modules ?? []) title[name] = await defaultOf(new URL(name + '.js', folder));
   if (title.view) title.viewSteps = await defaultOf(new URL('view.js', folder));
+  return title;
+}
+
+export async function loadTitle(folder, { data, scenes = false, fixed = false } = {}) {
+  folder = new URL(folder);
+  const title = await titleOf(folder);
   if (!ENGINES[title.engine]) {
     title.own = await import(new URL(title.engine + '.js', folder).href);
     return { title, scripts: {}, disk: null, folder };
@@ -46,6 +53,8 @@ export async function loadTitle(folder, { data, scenes = false, fixed = false }
   return { title, scripts, disk, folder };
 }
 
+export { read };
+
 export function makeEngine(title, scripts) {
   // (a ProDOS title's memory starts with what ProDOS leaves, as the original's does)
   const memory = { ...(title.disk?.kind === 'prodos' ? started(title.disk) : {}), ...title.memory };

package/saves.js

@@ -0,0 +1,22 @@
+// What a game saves, on the player's disk, the one way for every way to play (play.js gives it to the engine as
+// `game.saves`): an Apple game's volume it saves on (@moonbase-machines/apple2e/saves.js, its data's `saves`), a
+// Commodore 64 game's drive (@moonbase-machines/c64/saves.js). A game saved in one way loads in the other.
+//
+//   const saves = savesFor(data, disk)
+//     saves.data              the game's data with what is kept put on its volume, for the machine or the engine
+//     saves.keep(files)       the game's files watched (a machine's, an engine's, a drive's on line 1), each change kept
+//     saves.drive(drive)      a Commodore 64's drive given what is kept, and what it saves kept
+//     saves.disks(disks)      line 1: what is kept written onto the disk images Apple's ROMs boot
+//     saves.driveFiles(m, disks)  line 1: the files as the drive's tracks hold them, for `keep`
+import { withSaves, keepSaves, onDisks, driveFiles } from '@moonbase-machines/apple2e/saves.js';
+import { keepDrive } from '@moonbase-machines/c64/saves.js';
+
+export function savesFor(data, disk) {
+  return {
+    data: withSaves(data, disk),
+    keep: files => keepSaves(data, files, disk),
+    drive: drive => keepDrive(drive, disk),
+    disks: disks => onDisks(data, disks, disk),
+    driveFiles: (m, disks) => driveFiles(m, disks, data),
+  };
+}

package/test/play.test.js

@@ -0,0 +1,78 @@
+// The player's parts that every way to play shares (play.js): the keys as each machine takes them (keys.js), the
+// saves on the player's disk (saves.js), a write the disk's backend cannot store (disk/disk.js); and no title named in
+// the packages' code, only in their comments, as examples.
+//
+//   node --test test/*.test.js
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { code, named } from '@moonbase-machines/player/keys.js';
+import { savesFor } from '@moonbase-machines/player/saves.js';
+import { openDisk } from '@moonbase-machines/player/disk/disk.js';
+import { memory } from '@moonbase-machines/player/disk/memory.js';
+import { Drive } from '@moonbase-machines/c64/drive.js';
+import { make } from '@moonbase-machines/c64/d64.js';
+
+const key = (k, mods = {}) => ({ key: k, ctrlKey: false, metaKey: false, altKey: false, ...mods });
+
+test('a key is the Apple\'s code or the Commodore 64\'s, by the machine\'s kind', () => {
+  assert.equal(code(key('ArrowLeft'), 'prodos'), 8);
+  assert.equal(code(key('ArrowLeft'), 'c64'), 157);
+  assert.equal(code(key('Tab'), 'dos33'), 9);
+  assert.equal(code(key('a'), 'prodos'), 97, 'the Apple a small letter as typed');
+  assert.equal(code(key('a'), 'c64'), 65, 'the 64 its capital');
+  assert.equal(code(key('e', { ctrlKey: true }), 'prodos'), 5, 'control-E');
+  assert.equal(code(key('a', { metaKey: true }), 'prodos'), undefined, 'the browser\'s own');
+  assert.equal(code(key('a'), undefined), undefined, 'a title of its own engine has no table');
+  assert.equal(code(key('Shift'), 'prodos'), undefined);
+  assert.deepEqual(['space', 'left', 'A'].map(n => named(n, 'prodos')), [32, 8, 65]);
+  assert.deepEqual(['left', 'delete'].map(n => named(n, 'c64')), [157, 20]);
+});
+
+test('the saves: a game\'s volume given what is kept, and a change to its files kept', async () => {
+  const disk = await openDisk('title/one', { backend: memory() });
+  disk.write('KEPT', [1, 2], { type: 'BIN', aux: 0x2000 });
+  const game = { kind: 'prodos', volumes: { GAME: {} }, saves: { volume: 'SAVES', dos: 'prodos' } };
+  const saves = savesFor(game, disk);
+  assert.deepEqual(Object.keys(saves.data.volumes), ['GAME', 'SAVES']);
+  assert.equal(saves.data.volumes.SAVES.KEPT.type, 'BIN');
+  // a Commodore 64's drive: what it saves is kept on the disk
+  const drive = new Drive(make({ name: 'DISK', id: 'MB', files: [] }));
+  savesFor({ kind: 'c64' }, disk).drive(drive);
+  drive.keep('SAVED', Uint8Array.of(1, 8, 9));
+  await disk.written();
+  assert.deepEqual([...disk.read('SAVED')], [1, 8, 9]);
+});
+
+test('a write the backend cannot store is said, and the writes after it are stored', async () => {
+  const backend = memory(), put = backend.put;
+  let refuse = true;
+  backend.put = (d, f) => refuse && f.name === 'BAD' ? Promise.reject(new Error('full')) : put.call(backend, d, f);
+  const disk = await openDisk('title/two', { backend }), said = [];
+  disk.failed = err => said.push(err.message);
+  await assert.rejects(disk.write('BAD', [1]), /full/);
+  await disk.write('GOOD', [2]);
+  await disk.written();
+  assert.deepEqual(said, ['full']);
+  refuse = false;
+  assert.deepEqual([...(await openDisk('title/two', { backend })).read('GOOD')], [2]);
+});
+
+// the titles, by name and by address; the packages' code, their comments taken out
+const TITLES = /pieces[ -]of[ -]eight|detect-a-pet|goldfields|zoopak|nature[ -]park|animal[ -]rescue|aztlan|crayon|po8/i;
+const packages = new URL('../../', import.meta.url).pathname;
+const sources = dir => readdirSync(dir).flatMap(n => {
+  const f = join(dir, n);
+  if (['node_modules', 'dist', 'test'].includes(n)) return [];
+  return statSync(f).isDirectory() ? sources(f) : /\.m?js$/.test(n) ? [f] : [];
+});
+
+test('no title is named in the packages\' code, only in their comments', () => {
+  const found = [];
+  for (const f of sources(packages)) {
+    const lines = readFileSync(f, 'utf8').replace(/\/\*[\s\S]*?\*\//g, c => c.replace(/[^\n]/g, '')).split('\n');
+    lines.forEach((l, i) => { const c = l.replace(/(^|\s)\/\/.*$/, ''); if (TITLES.test(c)) found.push(`${f.slice(packages.length)}:${i + 1}`); });
+  }
+  assert.deepEqual(found, []);
+});