@moonbase-machines/player 0.9.1 → 0.11.0

package/play.js

@@ -0,0 +1,195 @@
+// 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 title's disk, and what the page asks of it;
+// the engine plays the game on the stage and does nothing of the page's. The page tells the player everything: the
+// disk and the settings are the page's to give (its provider, provider.js), and the player reads no address and
+// keeps nothing in the browser itself.
+//
+//   await play({ way, slug, title, data, root, disk, settings, preview, words, screen, watch, claim, pace, keys,
+//                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 disk (disk/disk.js `openDisk`, `title/<slug>`), the page's to open where it keeps files
+//     settings     the person's settings, the page's typed store (settings.js): each declared setting's value, kept
+//     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:
+//     keys         keys to press at the start, by name (space, return, left...), to go straight to a scene
+//     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 declares the settings it acts on
+// (`game.setting(declaration)`, settings.js, each shown only so), 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)?, 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), the page's `keys` at the start;
+// route, the page's route; start(), at the player's first gesture (sound may start only then); sound(on), the
+// player's speaker on or off (the Sound setting; a game's own sound setting stays the game's); 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 { 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') };
+// the settings the player itself acts on (settings.js): the speaker; a Commodore 64's printer; a title's version with
+// its bugs fixed
+const SOUND = { name: 'sound', type: 'boolean', default: true, owner: 'person', words: 'Sound' };
+const PRINTER = { name: 'printer', type: 'boolean', default: true, owner: 'person', words: 'Printer' };
+const FIXED = { name: 'fixed', type: 'boolean', default: false, owner: 'person', words: 'Bugs fixed', title: 'The game with its bugs fixed: it starts again' };
+
+export async function play(options) {
+  const { way = 'remake', slug, root, disk, settings, 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}<span class="settings"></span>`
+    + '<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'), line = root.querySelector('.options .settings');
+  const fail = err => { status.textContent = 'The game stopped: ' + err.message; status.className = 'error'; console.error(err); };
+  // A setting the player or its engine acts on, by its declaration (settings.js): its value from the page's store,
+  // and its control on the options line where the page offers it, a box for a boolean, a menu for an enum, each
+  // change kept and told; `first`, before the others (the sound)
+  const setting = (def, { first = false } = {}) => {
+    const s = { value: settings.get(def), told: [], on(f) { this.told.push(f); return this; } };
+    if (!settings.offered(def)) return s;
+    const label = document.createElement('label'), choice = Array.isArray(def.type);
+    if (def.title) label.title = def.title;
+    const control = choice
+      ? Object.assign(document.createElement('select'), { innerHTML: def.type.map((v, i) => `<option value="${v}">${def.labels[i]}</option>`).join('') })
+      : Object.assign(document.createElement('input'), { type: 'checkbox' });
+    control.id = def.name;
+    if (choice) { control.value = s.value; label.append(def.words + ' ', control); } else { control.checked = s.value; label.append(control, ' ' + def.words); }
+    control.addEventListener('change', () => { s.value = choice ? control.value : control.checked; settings.set(def, s.value); for (const f of s.told) f(s.value); });
+    line[first ? 'prepend' : 'append'](label);
+    return s;
+  };
+  try {
+    if (!disk || !settings) throw new Error('the page gives the player its disk and its settings');
+    // the title with its bugs fixed, for one that has such a version (its title.js `fixed`), a setting: its scripts
+    // chosen as it loads, so a change loads the page again
+    const fixed = settings.get(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; });
+    }
+    // (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);
+
+    const g = {
+      way, slug, title, scripts, game, folder, data, stage, status, fail, disk, preview, words, fixed, $, setting,
+      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 part of the options line that is no setting (Aztlan's preview selector), after the settings
+      control(html) { line.insertAdjacentHTML('afterend', html); },
+    };
+    // a printer on device 4, for a Commodore 64 game: on unless the setting is off, what it prints drawn below the
+    // screen as a sheet of paper, until it is torn off
+    if (kind === 'c64') {
+      const { Printer, paper } = await import('@moonbase-machines/c64/printer.js');
+      const on = setting(PRINTER);
+      const printer = g.printer = new Printer({ on: on.value });
+      on.on(v => { printer.on = v; });
+      const sheet = $('paper'), shown = $('paper-box');
+      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)
+    }
+    if (way === 'remake' && title?.fixed) setting(FIXED).on(() => location.reload());
+
+    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 player's speaker, on or off
+    if (handle.sound) { const on = setting(SOUND, { first: true }); handle.sound(on.value); on.on(v => handle.sound(v)); }
+    // 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 the page's keys, 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();
+    if (options.keys?.length) { const list = options.keys.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/provider.js

@@ -0,0 +1,27 @@
+// The provider: where a visit keeps a person's files and settings, chosen once, and every page's disks and settings
+// from it. A site makes one a page from a module of its own, choosing the backend (this browser's; an account's, the
+// site's API's, when signed in) and giving a visit's values and its policy; a page with no site (moonbase-play's) makes
+// this one with nothing given. The player and the programs never choose: a page passes the title's disk and the
+// settings to play() (play.js), and a program that saves opens its disks here. Nothing here knows of an address.
+//
+//   const { disk, settings } = await provider({ backend, visit, fixed, hidden })
+//     backend    where files are kept (disk/disk.js says what one is); none given, this browser's, IndexedDB
+//                (disk/local.js), or where the browser keeps nothing (a private window may not) memory, for this
+//                visit only, and the disks say so (`kept`)
+//     visit      def => a setting's value for this visit, the site's to give (settings.js); fixed and hidden, the
+//                page's policy of the settings
+//   await disk(name)    a disk by its name, on the backend: titleDisk(slug), programDisk(name) (disk/disk.js)
+//   settings            the person's settings, the typed store (settings.js), on the disk settingsDisk('person')
+import { openDisk } from './disk/disk.js';
+import { local } from './disk/local.js';
+import { memory } from './disk/memory.js';
+import { settingsStore } from './settings.js';
+
+export async function provider({ backend, visit, fixed = {}, hidden = [] } = {}) {
+  if (!backend) { try { backend = await local(); } catch { backend = memory({ kept: false }); } }
+  const disk = name => openDisk(name, { backend });
+  const settings = settingsStore({ disks: { person: await disk(settingsDisk('person')) }, visit, fixed, hidden });
+  return { disk, settings };
+}
+
+export const settingsDisk = owner => `settings/${owner}`;

package/remake/card.js

@@ -135,8 +135,9 @@ 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;
     // (the stack pointer as the call to the routine left it: the frames' place, less the call's two bytes)
@@ -437,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/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/settings.js

@@ -0,0 +1,82 @@
+// A person's settings: what the player, its engines and a site's pages let a person choose (the sound, the printer,
+// the old style text, a page's own choices), each declared where it acts, in one shape, and kept through the provider
+// (provider.js) on a disk of the owner's, settings/<owner>, where the person's files go. The store is typed against
+// the declarations: only a declared setting can be read or kept, every value checked against its type. Nothing here
+// knows of an address: a site that lets its address set a setting for a visit reads it itself and gives the value.
+//
+// A declaration: { name, type, default, owner, words, labels?, title? }
+//   name     its name, in the store's file (and for a site, in whatever sets it for a visit)
+//   type     'boolean', or an array of its fixed values, an enum
+//   default  its value where nothing gives one
+//   owner    whose it is: 'person' (the only owner yet; a parent's or teacher's later is another layer here, with
+//            nothing changed where the setting is declared)
+//   words    what its control calls it; labels, an enum's values' words in order; title, a note on the control
+//
+//   check(type, value)       whether a value is of the type
+//   describe(type)           the type in words, for saying what was refused
+//
+//   const settings = settingsStore({ disks, visit, fixed, hidden })
+//     disks     { owner: disk }, the owner's settings disk (settings/<owner>), opened by the provider; its one file,
+//               `settings`, the values by name
+//     visit     def => a value for this visit, or undefined: the site's, from wherever it lets a visit set one (its
+//               address, say); checked here, a value not of the type refused and said once; never kept
+//     fixed     { name: value }, what the page fixes, over everything; hidden, [name], what it does not offer
+//   settings.get(def)          its value: the page's fixed one, else the visit's, else the kept one where it is of
+//                              the type (one that is not falls back, said), else its default
+//   settings.set(def, value)   kept, for the next visit; a promise, kept when stored (a value not of the type throws)
+//   settings.offered(def)      whether its control is shown: not where the page hides it or fixes it
+import { textBytes, bytesText } from './disk/disk.js';
+
+const FILE = 'settings';
+
+export function check(type, value) {
+  if (Array.isArray(type)) return type.includes(value);
+  if (type === 'boolean') return typeof value === 'boolean';
+  throw new Error('settings: no such type: ' + JSON.stringify(type));
+}
+
+export const describe = type => Array.isArray(type) ? 'one of ' + type.map(v => v === '' ? 'nothing' : v).join(', ') : 'on or off';
+
+export function settingsStore({ disks, visit = () => undefined, fixed = {}, hidden = [] }) {
+  const said = new Set();
+  const say = (key, what) => { if (!said.has(key)) { said.add(key); console.warn(what); } };
+  const layers = Object.fromEntries(Object.entries(disks).map(([owner, disk]) => {
+    let kept = null;
+    try { kept = JSON.parse(bytesText(disk.read(FILE)) ?? '{}'); } catch {}
+    return [owner, { disk, kept: kept && typeof kept === 'object' && !Array.isArray(kept) ? kept : {} }];
+  }));
+  // (the declaration itself checked as it is first met: its owner has a store here, its default is of its type)
+  const seen = new Set();
+  const layer = def => {
+    const l = layers[def.owner];
+    if (!l) throw new Error(`settings: no store for the owner ${def.owner} (${def.name})`);
+    if (!seen.has(def.name)) { seen.add(def.name); if (!check(def.type, def.default)) throw new Error(`settings: ${def.name}'s default ${JSON.stringify(def.default)} is not ${describe(def.type)}`); }
+    return l;
+  };
+  return {
+    get(def) {
+      const l = layer(def);
+      if (def.name in fixed) {
+        if (!check(def.type, fixed[def.name])) throw new Error(`settings: ${def.name} fixed at ${JSON.stringify(fixed[def.name])}, not ${describe(def.type)}`);
+        return fixed[def.name];
+      }
+      const v = visit(def);
+      if (v !== undefined) {
+        if (check(def.type, v)) return v;
+        say('visit ' + def.name, `${def.name}: ${JSON.stringify(v)} for this visit refused: not ${describe(def.type)}`);
+      }
+      if (def.name in l.kept) {
+        if (check(def.type, l.kept[def.name])) return l.kept[def.name];
+        say('kept ' + def.name, `${def.name}: the kept ${JSON.stringify(l.kept[def.name])} is not ${describe(def.type)}; its default used`);
+      }
+      return def.default;
+    },
+    set(def, value) {
+      const l = layer(def);
+      if (!check(def.type, value)) throw new Error(`settings: ${def.name} cannot be ${JSON.stringify(value)}: not ${describe(def.type)}`);
+      l.kept[def.name] = value;
+      return l.disk.write(FILE, textBytes(JSON.stringify(l.kept)));
+    },
+    offered: def => !hidden.includes(def.name) && !(def.name in fixed),
+  };
+}

package/test/play.test.js

@@ -0,0 +1,152 @@
+// 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); the settings store
+// typed against its declarations (settings.js) and the provider giving a page its disks and settings on one backend
+// (provider.js); the package knowing nothing of an address and keeping nothing in the browser itself; 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 { settingsStore, check } from '@moonbase-machines/player/settings.js';
+import { provider, settingsDisk } from '@moonbase-machines/player/provider.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]);
+});
+
+// (what the console is told, for the tests of what is refused)
+const warned = async f => { const said = [], warn = console.warn; console.warn = m => said.push(m); try { await f(); } finally { console.warn = warn; } return said; };
+
+test('a setting\'s type: on or off, or one of fixed values', () => {
+  assert.ok(check('boolean', false) && !check('boolean', 'off') && check(['a', 'b'], 'a') && !check(['a', 'b'], 'c'));
+  assert.throws(() => check('text', 'x'), /no such type/);
+});
+
+const SOUND = { name: 'sound', type: 'boolean', default: true, owner: 'person', words: 'Sound' };
+const MINI = { name: 'mini', type: ['', 'live', 'pictures'], default: '', owner: 'person', words: 'Mini view', labels: ['Off', 'Live', 'Pictures'] };
+const OLD = { name: 'old-style', type: 'boolean', default: false, owner: 'person', words: 'Old style text' };
+const FIXED = { name: 'fixed', type: 'boolean', default: false, owner: 'person', words: 'Bugs fixed' };
+
+test('a setting by its declaration: the page\'s fixed value, else the visit\'s, else the kept one, else its default; offered unless hidden or fixed', async () => {
+  const backend = memory(), person = () => openDisk(settingsDisk('person'), { backend });
+  const first = settingsStore({ disks: { person: await person() } });
+  assert.equal(first.get(SOUND), true, 'its default');
+  await first.set(SOUND, false); await first.set(MINI, 'pictures');
+  const visit = def => ({ 'old-style': true, mini: 'live', sound: false })[def.name];
+  const again = settingsStore({ disks: { person: await person() }, visit, fixed: { fixed: true }, hidden: ['mini'] });
+  assert.equal(again.get(SOUND), false, 'the visit\'s, and kept');
+  assert.equal(again.get(MINI), 'live', 'the visit\'s over the kept');
+  assert.equal(again.get(OLD), true, 'the visit\'s on');
+  assert.equal(again.get(FIXED), true, 'the page\'s fixed value over all');
+  assert.deepEqual([SOUND, MINI, FIXED].map(again.offered), [true, false, false]);
+  assert.deepEqual(JSON.parse(new TextDecoder().decode((await person()).read('settings'))), { sound: false, mini: 'pictures' }, 'the visit\'s values never kept');
+});
+
+test('a setting\'s value is checked: a visit\'s value not of the type refused and said once, a kept value not of the type its default, a set of the wrong type thrown', async () => {
+  const backend = memory(), disk = await openDisk(settingsDisk('person'), { backend });
+  disk.write('settings', new TextEncoder().encode(JSON.stringify({ sound: 'loud', mini: 'live' })));
+  const store = settingsStore({ disks: { person: disk }, visit: def => ({ mini: 'huge', 'old-style': 'maybe' })[def.name] });
+  const said = await warned(() => { assert.equal(store.get(SOUND), true, 'the kept value refused: its default'); assert.equal(store.get(MINI), 'live', 'huge refused: the kept'); store.get(MINI); assert.equal(store.get(OLD), false); });
+  assert.deepEqual(said, ['sound: the kept "loud" is not on or off; its default used', 'mini: "huge" for this visit refused: not one of nothing, live, pictures', 'old-style: "maybe" for this visit refused: not on or off']);
+  assert.throws(() => store.set(SOUND, 'off'), /sound cannot be "off": not on or off/);
+  assert.throws(() => store.set(MINI, 'big'), /not one of nothing, live, pictures/);
+  assert.throws(() => store.get({ ...SOUND, owner: 'teacher' }), /no store for the owner teacher/);
+  assert.throws(() => store.get({ name: 'bad', type: 'boolean', default: 'on', owner: 'person' }), /default "on" is not on or off/);
+  assert.throws(() => settingsStore({ disks: { person: disk }, fixed: { sound: 'off' } }).get(SOUND), /fixed at "off"/);
+});
+
+test('the provider: every disk on the one backend it is given, and the settings kept there too', async () => {
+  const backend = memory();
+  const { disk, settings } = await provider({ backend, visit: def => def.name === 'sound' ? false : undefined, hidden: ['vectors'] });
+  const title = await disk('title/one');
+  await title.write('SAVED', [1]);
+  await settings.set(MINI, 'live');
+  assert.deepEqual((await backend.load('title/one')).map(f => f.name), ['SAVED']);
+  assert.deepEqual((await backend.load('settings/person')).map(f => f.name), ['settings']);
+  assert.equal(settings.get(SOUND), false);
+  assert.equal(settings.offered({ name: 'vectors', type: 'boolean', default: false, owner: 'person' }), false);
+});
+
+// the package's own code knows nothing of an address and keeps nothing in the browser: the page gives it everything
+// (bin/moonbase-play.mjs is a page of its own, the one place an address is read, by that page)
+test('the player, its engines, its settings and its provider know no address and no browser storage; the player opens no disk', () => {
+  const own = ['play.js', 'settings.js', 'provider.js', 'engines/original.js', 'engines/scenes.js', 'saves.js', 'keys.js', 'parts.js', 'disk/disk.js', 'disk/dialogs.js'];
+  const found = [];
+  for (const f of own) {
+    const lines = readFileSync(join(packages, 'player', f), 'utf8').replace(/\/\*[\s\S]*?\*\//g, c => c.replace(/[^\n]/g, '')).split('\n');
+    lines.forEach((l, i) => {
+      const c = l.replace(/(^|\s)\/\/.*$/, '');
+      if (/location\.(search|hash|href)|URLSearchParams|localStorage|sessionStorage/.test(c)) found.push(`${f}:${i + 1}`);
+      if (/openDisk/.test(c) && !['provider.js', 'disk/disk.js'].includes(f)) found.push(`${f}:${i + 1} opens a disk`);
+      if (/\blocal\(/.test(c) && f !== 'provider.js') found.push(`${f}:${i + 1} chooses a backend`);
+    });
+  }
+  assert.deepEqual(found, []);
+});
+
+// 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, []);
+});