@moonbase-machines/player 0.0.0-stage → 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Wharton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+# @moonbase-machines/player
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The player for Mark Wharton's titles of 1985 to 1995, the one way each is played in a page, in two ways to play:
+
+- **Original** (`original.js`): the game's own disk, untouched, on Moonbase's Apple IIe or Commodore 64
+  (`@moonbase-machines/apple2e`, `c64`), on Moonbase's own ROMs, which need nothing of Apple's or Commodore's.
+- **Remake** (`remake/main.js`): the game's scenes, lifted from its code and compiled to JavaScript, on an engine:
+  the remake's own for a title of scenes (`card` or `vector`), or the title's own, a module in its folder. Either
+  way the player makes the page's part, the stage, the options line and the status; the title brings its engine
+  and its view.
+
+What a player saves, a game saved, goes on **the player's disk** (`disk/`): a title's own disk of files in this
+browser (IndexedDB), with its own dialogs (`disk/dialogs.js`, in a modal window, `modal.js`). A game saved in one
+way loads in the other.
+
+No title is named in it. A title is a folder of its own, kept with the title, which the page gives the player:
+
+- `title.js`, what the title is: its engine (`'card'`, `'vector'` or a module of its own), its scripts and the one
+  it starts with, its `map` (the routines its scenes call, by address, and what its engine needs beside them:
+  `remake/cards.js` and `remake/vector.js` say what each engine reads), the modules it brings (`modules`, its
+  problems; `view`, its view's own drawing), its font's own glyphs (`font`), its stylesheet (`style`);
+- its scenes (`<name>.scene`) and `compiled/` (`moonbase-compile`).
+
+Beside it the game's data, `<name>.json` (its disks' files, its kind, and where it saves: `saves`).
+
+```html
+<link rel="stylesheet" href="/packages/player/player.css">
+<script type="importmap">{"imports": {"@moonbase-machines/player/": "/packages/player/", "@moonbase-machines/apple2e/": "/packages/apple2e/", "@moonbase-machines/c64/": "/packages/c64/", "@moonbase-machines/charset/": "/packages/charset/", "@moonbase-machines/mos6502/": "/packages/mos6502/", "@moonbase-machines/vector/": "/packages/vector/"}}</script>
+<section id="player"></section>
+<script type="module">
+  import { play } from '@moonbase-machines/player/remake/main.js';
+  import { openDisk } from '@moonbase-machines/player/disk/disk.js';
+  await play({ title: new URL('title/', location).href, data: new URL('game.json', location).href,
+    root: document.getElementById('player'), disk: await openDisk('title/game'), words: { printer: { line: '', print: 'Print', tear: 'Tear off' } } });
+</script>
+```
+
+`moonbase-compile <title folder>` compiles a title's scenes; `moonbase-play [folder] [port]` serves a title's page
+on this machine (http://127.0.0.1:8002/), the packages from `node_modules`.
+
+Part of Moonbase (moonbase.au). MIT; see LICENSE. Each file opens with what it is and what it covers.

package/audio.js

@@ -0,0 +1,54 @@
+// The speaker. The Apple II makes sound by clicking the speaker, a toggle at $C030, and the
+// machine keeps the cycle of each click. `Speaker` turns a run of cycles into a square wave
+// at the sound card's rate and plays it through a worklet, which keeps a queue of what it has
+// been given and holds the last level when the queue runs dry.
+const CYCLES_PER_SECOND = 1020484;
+
+const WORKLET = `
+class SpeakerProcessor extends AudioWorkletProcessor {
+  constructor() { super(); this.queue = []; this.at = 0; this.level = 0; this.port.onmessage = e => this.queue.push(e.data); }
+  process(inputs, outputs) {
+    const out = outputs[0][0];
+    for (let i = 0; i < out.length; i++) {
+      while (this.queue.length && this.at >= this.queue[0].length) { this.queue.shift(); this.at = 0; }
+      if (this.queue.length) this.level = this.queue[0][this.at++];
+      out[i] = this.level;
+    }
+    return true;
+  }
+}
+registerProcessor('speaker', SpeakerProcessor);
+`;
+
+export class Speaker {
+  constructor() { this.context = null; this.node = null; this.level = 0; this.from = null; }
+
+  // start on a gesture, as browsers require
+  async start() {
+    if (this.context) return;
+    this.context = new AudioContext();
+    await this.context.audioWorklet.addModule(URL.createObjectURL(new Blob([WORKLET], { type: 'text/javascript' })));
+    this.node = new AudioWorkletNode(this.context, 'speaker');
+    this.node.connect(this.context.destination);
+    this.rate = this.context.sampleRate;
+    if (this.context.state !== 'running') await this.context.resume();
+  }
+
+  // the wave for the cycles from the last call up to `cycles`, given the clicks in between
+  feed(clicks, cycles) {
+    if (!this.node) return;
+    if (this.from === null) this.from = cycles;   // from when the sound starts, not from the machine's first cycle
+    const perSample = CYCLES_PER_SECOND / this.rate;
+    const n = Math.floor((cycles - this.from) / perSample);
+    if (n <= 0) return;
+    const wave = new Float32Array(n);
+    let ci = 0;
+    for (let i = 0; i < n; i++) {
+      const t = this.from + (i + 1) * perSample;
+      while (ci < clicks.length && clicks[ci] <= t) { this.level = this.level ? 0 : 0.25; ci++; }
+      wave[i] = this.level;
+    }
+    this.from += n * perSample;
+    this.node.port.postMessage(wave, [wave.buffer]);
+  }
+}

package/bin/moonbase-compile.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+// A title's scene scripts compiled to JavaScript (remake/compile.js): each <name>.scene in the title's folder written
+// as compiled/<name>.js beside it, which the remake runs.
+//
+//   moonbase-compile <title folder> ...            every scene of each
+//   moonbase-compile --check <title folder> ...    says which compiled script is not its scene's, and fails
+import { readFileSync, writeFileSync, readdirSync, existsSync, mkdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { compile } from '../remake/compile.js';
+
+const args = process.argv.slice(2), check = args.includes('--check'), folders = args.filter(a => a !== '--check');
+if (!folders.length) { console.error('moonbase-compile [--check] <title folder> ...'); process.exit(1); }
+let stale = 0, written = 0;
+for (const folder of folders) {
+  const dir = pathToFileURL(resolve(folder) + '/'), io = (await import(new URL('title.js', dir))).default.io;
+  for (const f of readdirSync(dir).filter(f => f.endsWith('.scene'))) {
+    const name = f.slice(0, -6), js = compile(readFileSync(new URL(f, dir), 'utf8'), name, io ? { io } : undefined), out = new URL('compiled/' + name + '.js', dir);
+    if (existsSync(out) && readFileSync(out, 'utf8') === js) continue;
+    if (check) { console.log(`${folder}/compiled/${name}.js is not compiled from ${f}`); stale++; } else { mkdirSync(new URL('compiled/', dir), { recursive: true }); writeFileSync(out, js); written++; }
+  }
+}
+if (check) { if (stale) process.exit(1); } else console.log(`${written} compiled`);

package/bin/moonbase-play.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+// A title played on this machine: its page at http://127.0.0.1:8002/, its Remake where it has one, and an Original for
+// each game's data beside it (/?way=original, or with more than one /?game=<name>), on the browser's own player's
+// disk; each file sent with `Cache-Control: no-cache` so that a refresh asks for every module again. The folder holds
+// the title's folder, title/ (title.js, its scenes, compiled/), if it is remade, and its games' data, <name>.json
+// each, or for a title of its own engine data/; the @moonbase-machines packages are served from node_modules at
+// /packages/, where the page's import map finds them. A folder with an index.html of its own is served as it is.
+//
+//   moonbase-play [folder] [port] [host]     the folder (play/ unless given)
+import { createServer } from 'node:http';
+import { readFile, stat } from 'node:fs/promises';
+import { existsSync, readdirSync } from 'node:fs';
+import { extname, join, normalize, resolve, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const [folder = 'play', port = 8002, host = '127.0.0.1'] = process.argv.slice(2);
+const root = resolve(folder) + sep, packages = resolve('node_modules/@moonbase-machines') + sep;
+// (what a browser shows rather than downloads; anything else, a disk image among them, as bytes)
+const TYPES = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.mjs': 'text/javascript; charset=utf-8', '.json': 'application/json', '.css': 'text/css',
+  '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp', '.svg': 'image/svg+xml', '.ico': 'image/x-icon',
+  '.pdf': 'application/pdf', '.txt': 'text/plain; charset=utf-8', '.wav': 'audio/wav', '.scene': 'text/plain; charset=utf-8' };
+const PACKAGES = ['mos6502', 'charset', 'c64', 'apple2e', 'vector', 'player'];
+const esc = s => String(s).replace(/[&<>"]/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
+
+// the page: the title's name, its ways, the player
+async function page() {
+  const remade = existsSync(join(root, 'title', 'title.js'));
+  const title = remade ? (await import(pathToFileURL(join(root, 'title', 'title.js')).href)).default : null;
+  // (its games: each <name>.json beside the title, its data, and the title's own first)
+  const games = await Promise.all(readdirSync(root).filter(f => f.endsWith('.json') && f !== 'package.json').sort((a, b) => (b === title?.slug + '.json') - (a === title?.slug + '.json') || a.slice(0, -5).localeCompare(b.slice(0, -5)))
+    .map(async f => ({ name: f.slice(0, -5), data: f, game: JSON.parse(await readFile(join(root, f), 'utf8')) })));
+  const slug = title?.slug ?? games[0]?.name, name = title?.name ?? games[0]?.game.title ?? slug;
+  // (the ways: the remake, its data the title's own or, for a title of its own engine, data/; an original for each game)
+  const ways = [...(title ? [{ label: 'Remake', search: '', module: 'remake/main.js', data: existsSync(join(root, slug + '.json')) ? slug + '.json' : 'data/' }] : []),
+    ...games.map((g, i) => ({ label: games.length > 1 ? g.game.title : 'Original', search: !title && !i ? '' : games.length > 1 ? `?game=${g.name}` : '?way=original', module: 'original.js', data: g.data }))];
+  const map = { imports: Object.fromEntries(PACKAGES.map(p => [`@moonbase-machines/${p}/`, `/packages/${p}/`])) };
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${esc(name)}</title>
+<link rel="stylesheet" href="/packages/player/player.css">
+<style>body { margin: 0; font: 17px/1.6 system-ui, sans-serif; color: #1b2233; background: #fbf9f4; } main { max-width: 1000px; margin: 0 auto; padding: 16px; } h1 { font-size: 28px; margin: 0 0 8px; } nav a { margin-right: 14px; } nav a[aria-current] { font-weight: 600; color: inherit; text-decoration: none; }</style>
+<script type="importmap">${JSON.stringify(map)}</script>
+</head>
+<body>
+<main>
+<h1>${esc(name)}</h1>
+${ways.length > 1 ? `<nav>${ways.map(w => `<a href="/${w.search}">${esc(w.label)}</a>`).join('')}</nav>` : ''}
+<section id="player"></section>
+</main>
+<script type="module">
+const ways = ${JSON.stringify(ways)};
+const way = ways.find(w => w.search === location.search) ?? ways[0];
+for (const a of document.querySelectorAll('nav a')) if (a.search === way.search) a.setAttribute('aria-current', 'page');
+const [{ play }, { openDisk, titleDisk }] = await Promise.all([import('@moonbase-machines/player/' + way.module), import('@moonbase-machines/player/disk/disk.js')]);
+const at = path => new URL(path, location.origin + '/').href;
+await play({ title: at('title/'), data: at(way.data), root: document.getElementById('player'), disk: await openDisk(titleDisk(${JSON.stringify(slug)})),
+  words: { printer: { line: 'What the printer has printed.', print: 'Print', tear: 'Tear off' } } });
+</script>
+</body>
+</html>
+`;
+}
+
+createServer(async (req, res) => {
+  const path = normalize(decodeURIComponent(new URL(req.url, 'http://x').pathname));
+  try {
+    if ((path === sep || path === sep + 'index.html') && !existsSync(join(root, 'index.html'))) {
+      res.writeHead(200, { 'Content-Type': TYPES['.html'], 'Cache-Control': 'no-cache' }).end(await page());
+      return;
+    }
+    let file = path.startsWith(sep + 'packages' + sep) ? join(packages, path.slice(10)) : join(root, path);
+    if (![root, packages].some(r => file.startsWith(r))) { res.writeHead(403).end(); return; }
+    if ((await stat(file)).isDirectory()) file = join(file, 'index.html');
+    const body = await readFile(file);
+    res.writeHead(200, { 'Content-Type': TYPES[extname(file).toLowerCase()] ?? 'application/octet-stream', 'Cache-Control': 'no-cache' });
+    res.end(body);
+  } catch (err) { res.writeHead(404, { 'Content-Type': 'text/plain' }).end('not found: ' + path + (err.code === 'ENOENT' ? '' : '\n' + err.message)); }
+}).listen(+port, host, () => console.log(`http://${host}:${port}/`));

package/data.js

@@ -0,0 +1,39 @@
+// A game's data as the player wants it, in Node: every file of each volume, base64, with its type and load address;
+// a ProDOS game names its system file, a DOS 3.3 game the files to load and where and the address to call, as its
+// BASIC program does, a C64 game the name to LOAD; where it saves, `saves`. An Apple game's disks are given back
+// whole as well, for a machine with Apple's own ROMs, which boots them (`images`, @moonbase-machines/apple2e/disk2.js,
+// blocks.js), the data naming them.
+//
+//   const { data, images } = gameData(slug, { title, kind, disks, system, call, loads, wait, start, saves })
+//     kind      'prodos', 'dos33' or 'c64'
+//     disks     each disk image's bytes, in order (a 140K .dsk, a .2mg; a C64's .d64)
+//     saves     where the game saves, { volume, dos } (@moonbase-machines/apple2e/saves.js), if it does
+//   data      the game's data, for <slug>.json
+//   images    an Apple game's disks, [{ name: <slug>-<n>.dsk or .2mg, bytes }]
+import { prodos } from '@moonbase-machines/apple2e/prodos-disk.js';
+import { dos33 } from '@moonbase-machines/apple2e/dos33-disk.js';
+import { read as d64 } from '@moonbase-machines/c64/d64.js';
+
+const b64 = bytes => Buffer.from(bytes).toString('base64');
+
+export function gameData(slug, game) {
+  const data = { title: game.title, kind: game.kind, volumes: {}, system: game.system, call: game.call, loads: game.loads, wait: game.wait, start: game.start, images: undefined };
+  const images = game.kind === 'c64' ? [] : game.disks.map((bytes, n) => ({ name: slug + '-' + (n + 1) + (bytes.length === 143360 ? '.dsk' : '.2mg'), bytes }));
+  if (images.length) data.images = images.map(i => i.name);
+  for (const image of game.disks) {
+    if (game.kind === 'prodos') {
+      const disk = prodos(image), files = {};
+      for (const f of disk.files) if (f.typeName !== 'DIR') files[f.path] = { type: f.typeName, aux: f.aux, size: f.size, data: b64(f.body) };
+      data.volumes[disk.volume] = files;
+    } else if (game.kind === 'c64') {
+      d64(image);   // checked, and the whole image kept, since the drive in the browser reads it by the sector
+      data.image = b64(image);
+    } else {
+      const disk = dos33(image), files = {};
+      for (const f of disk.files) files[f.name] = { type: f.type, aux: f.address || 0, size: f.body.length, data: b64(f.body) };
+      data.volumes['DISK'] = files;
+    }
+  }
+  if (game.saves) data.saves = game.saves;
+  return { data, images };
+}

package/disk/dialogs.js

@@ -0,0 +1,101 @@
+// The disk's own dialogs, the same in every game that hands saving to the system (as Aztlan for Macintosh
+// handed it to the Mac's): a game is saved by name, and opened from the disk's list, or from a file
+// downloaded before. A game that asks on its own screen (the 8-bit games) keeps its own prompt; the disk
+// only keeps what it saves. Each is a modal window (../modal.js) opened where the game says, its host: in
+// its screen, in the frame its own windows have (Aztlan's, window definition 1, the Mac's dialog box), and
+// so looking as its own windows look; with no host, on the page, as the site's (site/assets/site.css).
+//
+//   const { saveAs, openFrom, ask, tell } = dialogs({ within, className })   the game's host
+//   await saveAs(disk, { suggested })      a name, or null: offers to replace a file of that name
+//   await openFrom(disk, { file })         { name, bytes } from the disk, or null: the disk's manager, the
+//                                          same for every game, its games listed, each to open, download
+//                                          or delete, and a downloaded one put back on it from a file
+//                                          (`file`, the game's own: { extension, type }, '.zip' and its type)
+//   await ask(heading, body, buttons, { aside })   a dialog of a game's own: [label, value] buttons, the
+//                                          last the default, a function's value what it returns; `aside`,
+//                                          buttons of the dialog's own on the same line, at its left
+//   await tell(heading)                    a word, and OK
+import { modal } from '../modal.js';
+
+export function dialogs({ within, className = '' } = {}) {
+  function ask(heading, body, buttons, { aside = [] } = {}) {
+    return new Promise(done => {
+      const content = document.createElement('div'); content.className = 'disk';
+      const h = document.createElement('h2'); h.textContent = heading;
+      const row = document.createElement('p'); row.className = 'buttons';
+      for (const [label, value] of buttons) {
+        const b = Object.assign(document.createElement('button'), { type: 'button', textContent: label });
+        b.onclick = async () => { m.close(); done(typeof value === 'function' ? await value() : value); };
+        row.append(b);
+      }
+      row.lastChild?.classList.add('default');
+      if (aside.length) { const left = document.createElement('span'); left.className = 'aside'; left.append(...aside); row.prepend(left); }
+      content.append(h, ...body, row);
+      // (Escape: nothing chosen)
+      const m = modal({ within, className, content, cancel: () => { m.close(); done(null); } });
+    });
+  }
+  const tell = heading => ask(heading, [], [['OK', null]]);
+
+  async function saveAs(disk, { suggested = '' } = {}) {
+    const input = Object.assign(document.createElement('input'), { value: suggested, maxLength: 31 });
+    setTimeout(() => input.select());
+    const label = document.createElement('label'); label.append('Save as ', input);
+    const name = await ask('Save', [label, ...keptNote(disk)], [['Cancel', null], ['Save', () => input.value.trim() || null]]);
+    if (!name) return null;
+    if (disk.read(name) && !await ask(`Replace "${name}"?`, [], [['Cancel', false], ['Replace', true]])) return null;
+    return name;
+  }
+
+  async function openFrom(disk, { file: { extension = '', type = 'application/octet-stream' } = {} } = {}) {
+    const select = Object.assign(document.createElement('select'), { size: 6 });
+    const note = document.createElement('p'); note.className = 'note';
+    const input = Object.assign(document.createElement('input'), { type: 'file', accept: [extension, type].filter(Boolean).join(','), hidden: true });
+    const button = text => Object.assign(document.createElement('button'), { type: 'button', textContent: text });
+    const from = button('File…'), download = button('Download'), remove = button('Delete');
+    const fill = () => {
+      select.replaceChildren(...disk.list().map(f => new Option(`${f.name}  ·  ${new Date(f.modified).toLocaleString()}`, f.name)));
+      select.selectedIndex = select.options.length ? 0 : -1;
+      select.hidden = !select.options.length;
+      note.textContent = select.options.length ? 'On your disk:' : 'Nothing saved on your disk yet.';
+      remove.disabled = download.disabled = !select.options.length;
+    };
+    fill();
+    const chosen = ask('Open', [note, select, input, ...keptNote(disk)], [['Cancel', null], ['Open', () => select.value || null]], { aside: [from, download, remove] });
+    const open = () => select.closest('.modal').querySelector('.default').click();
+    // (File…: a game downloaded before, put back on the disk by its file's name, and opened)
+    from.onclick = () => input.click();
+    input.onchange = async () => {
+      const f = input.files[0], n = f.name.slice(0, f.name.length - (extension && f.name.endsWith(extension) ? extension.length : 0));
+      if (disk.read(n) && !await ask(`Replace "${n}"?`, [], [['Cancel', false], ['Replace', true]])) return;
+      disk.write(n, new Uint8Array(await f.arrayBuffer()));
+      fill(); select.value = n; open();
+    };
+    // (a game taken off the disk as its file, to keep, or for the original: Aztlan's for Infinite Mac)
+    download.onclick = () => {
+      const n = select.value; if (!n) return;
+      const a = Object.assign(document.createElement('a'), { href: URL.createObjectURL(new Blob([disk.read(n)], { type })), download: n + extension });
+      a.click(); setTimeout(() => URL.revokeObjectURL(a.href), 1000);
+    };
+    // (a file deleted only once asked, in a dialog over this one, Cancel its default)
+    remove.onclick = async () => {
+      const n = select.value; if (!n) return;
+      if (!await ask(`Delete "${n}"?`, [warning('It is gone from your disk for good.')], [['Delete', true], ['Cancel', false]])) return;
+      await disk.remove(n); fill(); select.focus();
+    };
+    select.ondblclick = open;
+    const name = await chosen;
+    return name ? { name, bytes: disk.read(name) } : null;
+  }
+  return { saveAs, openFrom, ask, tell };
+}
+
+const warning = text => Object.assign(document.createElement('p'), { className: 'note', textContent: text });
+
+// (where the browser keeps nothing, a word saying so: the game is there until the page closes)
+function keptNote(disk) {
+  if (disk.kept) return [];
+  const p = document.createElement('p'); p.className = 'note';
+  p.textContent = 'This browser is not keeping files: download a game to keep it.';
+  return [p];
+}

package/disk/disk.js

@@ -0,0 +1,57 @@
+// The player's disk: the files a person makes, kept by name on a disk of their own, one for each title
+// and one for each program that saves (Microsoft BASIC's tape and disk, the editors). Every game and
+// program that saves does so here, and only here; its files are its own bytes, in its own format, with
+// what the format needs beside them (`meta`, a ProDOS file's type and aux).
+//
+// A disk is read whole when it is opened, before the program starts, and kept in memory: the machines
+// read files at once, inside an instruction (@moonbase-machines/apple2e/machine.js's MLI call,
+// @moonbase-machines/c64/drive.js's find), so a read is never waited for. A write changes the copy at once and is stored behind
+// it, in order.
+//
+//   const disk = await openDisk(name, { backend })   backend: local() (local.js, the default)
+//                                                     or memory() (memory.js)
+//   disk.list()                 [{ name, size, modified, meta }], newest first
+//   disk.read(name)             its bytes, or null
+//   disk.write(name, bytes, meta)   a promise, kept when stored
+//   disk.remove(name)           a promise
+//   disk.written()              a promise: every write so far stored
+//   disk.name, disk.kept        the disk's name; whether its files outlast the page
+//
+// A disk's name says whose it is, so a title and a program can never share one: titleDisk(slug), a title's
+// player's, 'title/zoopak'; programDisk(name), one of the site's own programs', 'program/basic'.
+//
+// The backend is where a disk's files are kept: { kept, load(disk), put(disk, file), delete(disk, name) },
+// a file { name, bytes, meta, modified }. This browser's is local(); an account's will be the API's.
+import { local } from './local.js';
+import { memory } from './memory.js';
+
+export async function openDisk(name, { backend } = {}) {
+  // (a browser that keeps nothing, as a private window may: the disk in memory, and said so)
+  if (!backend) { try { backend = await local(); } catch { backend = memory({ kept: false }); } }
+  const files = new Map((await backend.load(name)).map(f => [f.name, f]));
+  let queue = Promise.resolve();
+  const later = job => (queue = queue.then(job));
+  return {
+    name,
+    kept: backend.kept,
+    list: () => [...files.values()].sort((a, b) => b.modified - a.modified).map(({ name, bytes, meta, modified }) => ({ name, size: bytes.length, modified, meta })),
+    read: n => files.get(n)?.bytes ?? null,
+    write(n, bytes, meta = {}) {
+      const f = { name: n, bytes: Uint8Array.from(bytes), meta, modified: Date.now() };
+      files.set(n, f);
+      return later(() => backend.put(name, f));
+    },
+    remove(n) {
+      files.delete(n);
+      return later(() => backend.delete(name, n));
+    },
+    written: () => queue,
+  };
+}
+
+export const titleDisk = slug => `title/${slug}`;
+export const programDisk = name => `program/${name}`;
+
+// a text file's bytes and back, for the programs whose files are text (UTF-8)
+export const textBytes = s => new TextEncoder().encode(s);
+export const bytesText = b => b ? new TextDecoder().decode(b) : null;

package/disk/local.js

@@ -0,0 +1,28 @@
+// A disk's files kept in this browser, in IndexedDB: the database `moonbase`, its store `files`, each file
+// keyed by its account, its disk and its name. The account is `local`, this browser's own, until there
+// are accounts; theirs will be kept by the API, behind the same calls.
+//
+//   await local({ account })   a backend: { kept, load(disk), put(disk, file), delete(disk, name) }
+// (named here once, for a tool that puts a file on a disk too)
+export const DB = 'moonbase', VERSION = 1, STORE = 'files', KEY = ['account', 'disk', 'name'], ACCOUNT = 'local';
+
+const opened = () => new Promise((done, fail) => {
+  const r = indexedDB.open(DB, VERSION);
+  r.onupgradeneeded = () => r.result.createObjectStore(STORE, { keyPath: KEY });
+  r.onsuccess = () => done(r.result);
+  r.onerror = () => fail(r.error);
+});
+const asked = r => new Promise((done, fail) => { r.onsuccess = () => done(r.result); r.onerror = () => fail(r.error); });
+
+export async function local({ account = ACCOUNT } = {}) {
+  const db = await opened();
+  const store = mode => db.transaction(STORE, mode).objectStore(STORE);
+  return {
+    kept: true,
+    // (the disk's files: those keyed from [account, disk] up to the next disk's)
+    load: async disk => (await asked(store('readonly').getAll(IDBKeyRange.bound([account, disk], [account, disk, []]))))
+      .map(({ name, bytes, meta, modified }) => ({ name, bytes, meta, modified })),
+    put: (disk, f) => asked(store('readwrite').put({ account, disk, ...f })),
+    delete: (disk, name) => asked(store('readwrite').delete([account, disk, name])),
+  };
+}

package/disk/memory.js

@@ -0,0 +1,13 @@
+// A disk's files kept in memory only, for as long as the page: for the tests, which run where there is no
+// IndexedDB, and for a browser that will keep nothing (disk.js says which, `kept`).
+//
+//   memory({ kept })   a backend: { kept, load(disk), put(disk, file), delete(disk, name) }
+export function memory({ kept = true } = {}) {
+  const disks = new Map(), of = d => disks.get(d) ?? disks.set(d, new Map()).get(d);
+  return {
+    kept,
+    load: async d => [...of(d).values()].map(f => ({ ...f, bytes: Uint8Array.from(f.bytes) })),
+    put: async (d, f) => { of(d).set(f.name, { ...f, bytes: Uint8Array.from(f.bytes) }); },
+    delete: async (d, n) => { of(d).delete(n); },
+  };
+}