@moonbase-machines/player 0.9.1 → 0.11.0

package/README.md

@@ -1,24 +1,35 @@
 # @moonbase-machines/player
 
-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.
+The player for Mark Wharton's titles of 1985 to 1995, one way in for every title and every way to play it (`play.js`):
+
+- **Original** (`way: 'original'`, `engines/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** (`way: 'remake'`): the game's scenes, lifted from its code and compiled to JavaScript, on the remake's
+  engine (`engines/scenes.js`, a title of `card` or `vector` scenes), or the title's own engine, a module in its folder.
+
+The player makes its part of the page and owns it, the same for every title: the section (classes `player`, the way,
+the title's slug), the stage sized a whole number of the device's pixels to each of the screen's dots, the options
+line and the status, the keys (one listener, each machine's codes, `keys.js`), the sound, a Commodore 64's printer,
+the saves (`saves.js`), the settings the player and its engine act on, each declared where it acts and shown only
+there (`settings.js`), and what the page asks of it (`watch`, `claim`, `pace`, keys and a route). An engine plays
+the game on the stage and returns its handle (`play.js` says what it may have). The page tells the player everything
+and the player reads no address and keeps nothing itself: the page gives the title's disk, a virtual disk of files
+(`disk/disk.js` `openDisk`), and the person's settings, a typed store (`settings.js`: a setting is a declared name,
+type, default and owner; only a declared setting can be read or kept, its value checked). Both come from a
+**provider** (`provider.js`), which chooses once a visit where files and settings live, the backend (this browser's,
+IndexedDB; an account's, a site's own); a site makes one a page from a module of its own, giving its policy of
+settings (hidden, fixed, or a value for the visit) and the player never chooses. Nothing in the package knows of an
+address: a page that lets its address set anything reads it itself, each input by its type. The disk has 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`);
+- `title.js`, what the title is: its engine (`'card'`, `'vector'` or a module of its own), its screen where it is not
+  its machine's (`screen`, in its own dots), 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`).
@@ -28,10 +39,13 @@ Beside it the game's data, `<name>.json` (its disks' files, its kind, and where
 <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' } } });
+  import { play } from '@moonbase-machines/player/play.js';
+  import { titleDisk } from '@moonbase-machines/player/disk/disk.js';
+  import { provider } from '@moonbase-machines/player/provider.js';
+  const { disk, settings } = await provider();   // (this browser's)
+  await play({ way: 'remake', slug: 'game', title: new URL('title/', location).href, data: new URL('game.json', location).href,
+    root: document.getElementById('player'), disk: await disk(titleDisk('game')), settings,
+    words: { printer: { line: '', print: 'Print', tear: 'Tear off' } } });
 </script>
 ```
 

package/bin/moonbase-play.mjs

@@ -1,7 +1,9 @@
 #!/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
+// each game's data beside it (/?way=original, or with more than one /?game=<name>); its disk and settings from the
+// package's own provider (provider.js), this browser's, as the page has no site to give them; the page's own inputs
+// its own, each checked: ?way and ?game one of the ways it has, ?keys=space,return keys to press at the start; 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.
@@ -30,9 +32,10 @@ async function page() {
   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 }))];
+  // (the ways: the remake, its data the title's own or, for a title of its own engine, data/; an original for each
+  // game, by the game's name where there are several; each with its address)
+  const ways = [...(title ? [{ label: 'Remake', search: '', way: 'remake', game: null, 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', way: 'original', game: games.length > 1 ? g.name : null, data: g.data }))];
   const map = { imports: Object.fromEntries(PACKAGES.map(p => [`@moonbase-machines/${p}/`, `/packages/${p}/`])) };
   return `<!doctype html>
 <html lang="en">
@@ -52,11 +55,19 @@ ${ways.length > 1 ? `<nav>${ways.map(w => `<a href="/${w.search}">${esc(w.label)
 </main>
 <script type="module">
 const ways = ${JSON.stringify(ways)};
-const way = ways.find(w => w.search === location.search) ?? ways[0];
+const [{ play }, { titleDisk }, { provider }] = await Promise.all(['play.js', 'disk/disk.js', 'provider.js'].map(m => import('@moonbase-machines/player/' + m)));
+// (the page's own inputs, each checked: the way or a game by its name, one of those it has, else the first; the keys
+// to press, names of letters, digits and dashes; anything else refused and said)
+const q = new URLSearchParams(location.search), refused = (n, what) => { console.warn('?' + n + '=' + q.get(n) + ' refused: not ' + what); return null; };
+const one = (n, of) => !q.has(n) ? null : of.includes(q.get(n)) ? q.get(n) : refused(n, 'one of ' + of.join(', '));
+const askedGame = one('game', ways.map(w => w.game).filter(Boolean)), askedWay = one('way', [...new Set(ways.map(w => w.way))]);
+const way = ways.find(w => askedGame ? w.game === askedGame : askedWay ? w.way === askedWay : true) ?? 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 keys = !q.has('keys') ? undefined : /^[\\w-]+(,[\\w-]+)*$/.test(q.get('keys')) ? q.get('keys').split(',') : refused('keys', 'names separated by commas') ?? undefined;
 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)})),
+const { disk, settings } = await provider();
+await play({ way: way.way, slug: ${JSON.stringify(slug)}, title: ${title ? "at('title/')" : 'null'}, data: at(way.data), root: document.getElementById('player'),
+  disk: await disk(titleDisk(${JSON.stringify(slug)})), settings, keys,
   words: { printer: { line: 'What the printer has printed.', print: 'Print', tear: 'Tear off' } } });
 </script>
 </body>

package/disk/disk.js

@@ -8,32 +8,34 @@
 // @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)
+//   const disk = await openDisk(name, { backend })   backend: where its files are kept, the provider's choice
+//                                                     (provider.js), never the disk's: local() (local.js, this
+//                                                     browser's) 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.failed = err => ...    told of a write or remove the backend could not store (the queue goes on)
 //   disk.name, disk.kept        the disk's name; whether its files outlast the page
+//   disk.where                  where they are kept, as the backend says ('this browser'), for the dialogs
 //
 // 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) },
+// The backend is where a disk's files are kept: { kept, where, 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 }); } }
+export async function openDisk(name, { backend }) {
+  if (!backend) throw new Error('openDisk: a backend is the provider\'s to give (provider.js)');
   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 {
+  // (each job stored in turn; one that fails is said (`failed`) and the next goes on, its own promise rejected for a
+  // caller that waits for it)
+  const later = job => { const p = queue.then(job); queue = p.catch(err => disk.failed?.(err)); p.catch(() => {}); return p; };
+  const disk = {
     name,
-    kept: backend.kept,
+    kept: backend.kept, where: backend.where ?? null, failed: null,
     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 = {}) {
@@ -47,6 +49,7 @@ export async function openDisk(name, { backend } = {}) {
     },
     written: () => queue,
   };
+  return disk;
 }
 
 export const titleDisk = slug => `title/${slug}`;

package/disk/local.js

@@ -2,7 +2,7 @@
 // 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) }
+//   await local({ account })   a backend: { kept, where, 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';
 
@@ -18,7 +18,7 @@ export async function local({ account = ACCOUNT } = {}) {
   const db = await opened();
   const store = mode => db.transaction(STORE, mode).objectStore(STORE);
   return {
-    kept: true,
+    kept: true, where: 'this browser',
     // (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 })),