@wasm-gaming/fbneo-wasm 0.1.1 → 0.2.0

package/README.md

@@ -1,44 +1,82 @@
 # @wasm-gaming/fbneo-wasm
 
-FinalBurn Neo (FBNeo) — the multi-system arcade emulator (Capcom CPS-1/2/3, SNK
-Neo Geo, Sega System 16, Cave, PGM, and many more) — compiled to WebAssembly via
-Emscripten and packaged as a wasm-gaming engine SDK.
+FinalBurn Neo (FBNeo), the multi-system arcade emulator (Capcom CPS-1/2/3, SNK Neo Geo,
+Sega System 16, Cave, PGM and many more), compiled to WebAssembly and wrapped in a small JS
+SDK that implements the [wasm-gaming engine contract](https://github.com/wasm-gaming/engine-specs)
+1.0. It ships no games: the player brings the ROM sets, and they never leave the browser.
 
-This subproject follows the same engine-package approach used by jgenesis-wasm,
-blastem-wasm, rsdkv3, and rsdkv4:
+## Install
 
-- typed `manifest`
-- typed `options`
-- `load(config)` engine SDK surface
-- Makefile-driven build (`build-sdk`, `build-wasm`, `preview`)
+```sh
+npm install @wasm-gaming/fbneo-wasm
+```
+
+The SDK is self-contained: the contract's runtime ships beside it in `dist/fbneo/` and is
+imported relatively, so it loads from any static server with no bundler and no import map.
+The wasm and its glue sit next to it (`fbneo.js`, `fbneo.wasm`).
+
+## Use
+
+```js
+import FbneoSDK from '@wasm-gaming/fbneo-wasm';
+
+FbneoSDK.id;   // 'fbneo' — also this engine's folder in OPFS
+
+const play = await new FbneoSDK()
+  .options({ driver: 'mslug' })                       // or romFileName: 'mslug.zip'
+  .assets({ rom: () => zip.arrayBuffer(), bios: () => neogeo.arrayBuffer() })
+  .storage({ namespace: 'mslug' })                    // → OPFS fbneo/mslug/
+  .on('saves', ({ detail }) => console.log('saved', detail.files))
+  .mount(document.querySelector('#stage'))            // a <canvas> is used as is; anything else gets one
+  .start();
+
+play.pause('menu');            // the first caller owns the pause…
+play.resume('menu');           // …and only it lifts it; sound stops too
+await play.restart();          // soft reset
+await play.states.save(0);     // save states: slots 0-3, plus 9 (the suspend point)
+play.states.load(0);
+await play.destroy();          // saves flushed, loop stopped, audio closed
+```
+
+| payload | keys |
+| --- | --- |
+| `config` | `renderFilter` (`pixelated` \| `smooth`, live), `jsUrl`, `wasmUrl` |
+| `options` | `driver` (FBNeo short name), `romFileName` (its stem is the driver when `driver` is empty) |
+| `assets` | `rom` (`.zip`/`.7z`, required), `bios` (`.zip`, e.g. `neogeo.zip`) |
+| `storage` | `namespace` (default `default`), `persist` (`'opfs'` \| `null`) |
+
+FBNeo boots a game by its ROM-set short name (the *driver*, `mslug`) and finds `<driver>.zip`
+in its ROM path; the SDK writes the bytes there under that name, so the player's file name
+never matters once the driver is known.
 
-It conforms to the [`@wasm-gaming/engine-specs`](https://github.com/wasm-gaming/engine-specs)
-contract (`EngineSDK` = `{ manifest, load }`).
+Events: the contract's `start`, `error`, `exit`, `pause`, `resume`, plus `saves`.
 
-## Contract surface
+## The engine's own app
+
+A host that would rather not draw menus mounts the app shipped next to the SDK
+(engine-specs `EngineApp`, `UX.md`):
 
 ```js
-import { manifest, load } from '@wasm-gaming/fbneo-wasm';
-
-const engine = await load({
-  canvas,                         // per engine-specs EngineConfig
-  assets: {
-    rom: romZipBytes,             // arcade ROM set (zip)
-    bios: neogeoZipBytes,         // optional: e.g. neogeo.zip for Neo Geo sets
-  },
-  options: { driver: 'mslug', renderFilter: 'pixelated' },
-  onEvent: (e) => console.log(e),
-});
-engine.start();
+const app = await import('@wasm-gaming/fbneo-wasm/app'); // dist/fbneo/app/app.js
+const handle = await app.mount(element, { game, storage, assets, input, exit });
+await handle.unmount();
 ```
 
-FBNeo identifies a game by the ROM zip **filename** (without extension). Pass the
-game short name explicitly via `options.driver` (e.g. `"mslug"`, `"sf2"`,
-`"kof98"`), or let it be inferred from `options.romFileName` / the picked file's
-name. (The bytes are always written to MEMFS as `<driver>.zip`, so the source
-file itself never needs renaming — only its *name* has to resolve to a driver.)
+The same app as blastem-wasm's: suspend points the way the Nintendo Classic Mini does them
+(leaving keeps an unsaved point with its frame; coming back offers it, four slots and "from
+the beginning"), and a pause menu on Select + Start or Escape (*Continuar*, *Puntos de
+suspensión*, *Reiniciar*, *Volver al lanzador*). The host hands over bytes, not a driver
+name, so the app identifies the set by its contents (the datasets below, Neo Geo and Capcom
+first), rebuilds a `.neo` image, and falls back to `game.slug`.
+
+## Saves live in the engine's own folder
+
+FBNeo's NVRAM/EEPROM (`<driver>.fs`), hiscores (`<driver>.hi`) and save states
+(`slot_N.fs`, with an optional `slot_N.png` frame and `slot_N.lock`) are written to MEMFS
+`/save`, which the SDK seeds from OPFS `fbneo/<namespace>/` before boot and mirrors back
+every 10 s, on pause, when the page is hidden and on destroy. `persist: null` keeps nothing.
 
-### Identifying a ROM set from its contents
+## Identifying a ROM set from its contents
 
 When the filename is unreliable (a browser-mangled `mslug (1).zip`) but the ROM
 files inside must keep their canonical names, recover the driver from the zip's
@@ -55,16 +93,21 @@ const neogeo = await fetch('/romsets/neogeo.json').then((r) => r.json());
 const index = new RomsetIndex([neogeo]);
 
 const match = resolveDriver(romZipBytes, index); // { driver: 'mslug', coverage: 1, ... } | null
-const engine = await load({
-  canvas,
-  assets: { rom: romZipBytes },
-  options: { driver: match?.driver }, // fall back to your own logic when null
-});
+const play = await new FbneoSDK()
+  .options({ driver: match?.driver ?? '' })   // fall back to your own logic when null
+  .assets({ rom: romZipBytes })
+  .mount(stage)
+  .start();
 ```
 
-The dataset ships as `data/romsets/<system>.json` (also served at `/romsets/…`
-from the built `dist/`); `data/romsets/index.json` lists the systems and game
-counts. Regenerate it from a pinned FBNeo checkout with `make romsets`.
+The dataset is `data/romsets/<system>.json` in the repo and ships next to the SDK as
+`fbneo/romsets/<system>.json` (package export `./romsets/*`); `index.json` lists the
+systems and game counts. Regenerate it from a pinned FBNeo checkout with `make romsets`.
+
+Each ROM entry carries its internal name (`n`) and CRC-32 (`c`). `neogeo.json`
+additionally carries each chip's size (`s`) and hardware region (`r`) — the chip
+*layout* — which is what lets the `neo` helper below rebuild a ROM set from a
+flash-cart image.
 
 Because the match is by CRC-32 — and FBNeo itself looks ROM chips up by CRC
 before falling back to their names — a set is usually accepted as downloaded:
@@ -72,60 +115,74 @@ extra files, subdirectories, and non-canonical chip filenames inside the zip do
 not matter. Only the zip's *name* has to resolve to a driver, which is exactly
 what this helper supplies.
 
-### Neo Geo `.neo` files (NeoSD / Terraonion)
+## Neo Geo `.neo` files (NeoSD / Terraonion)
 
 FBNeo reads `.zip` and `.7z` ROM sets only. A `.neo` — the single-file format for
 NeoSD/Terraonion flash carts, and how most Neo Geo homebrew is distributed — is a
 4 KiB header followed by each ROM region as one contiguous blob (with the sprite
 region byte-interleaved as the cartridge wires it), so it cannot be handed to the
-engine as-is. Convert it to a bootable ROM set first:
+engine as-is. The opt-in `@wasm-gaming/fbneo-wasm/neo` helper rebuilds the chip
+split FBNeo expects, in the browser and with no dependencies:
+
+```js
+import { isNeoFile, neoToRomset } from '@wasm-gaming/fbneo-wasm/neo';
+
+const neogeo = await fetch('/romsets/neogeo.json').then((r) => r.json());
+
+if (isNeoFile(bytes)) {
+  const { driver, zip } = neoToRomset(bytes, neogeo); // throws if it cannot be rebuilt
+  await new FbneoSDK().options({ driver }).assets({ rom: zip }).mount(stage).start();
+}
+```
+
+It identifies the driver by matching the `.neo`'s region sizes against the chip
+layouts in `data/romsets/neogeo.json`, rebuilds the individual chip dumps
+(de-interleaving sprites, undoing the `HARDWARE_SNK_SWAPP` program-ROM swap), and
+CRC-32 verifies every chip before returning — so it throws loudly rather than
+handing the engine a broken set. The zip it returns is *stored*, not deflated:
+FBNeo decompresses each chip immediately, so compressing would only be undone.
+
+The same conversion is available offline, which is handy for preparing a set once
+rather than on every page load:
 
 ```sh
-node scripts/neo2romset.mjs mygame.neo --out ./roms
+node scripts/neo2romset.mjs mygame.neo --out ./roms   # needs `make build-lib`
 ```
 
-It identifies the driver by matching the `.neo`'s region sizes against FBNeo's own
-chip tables, rebuilds the individual chip dumps (de-interleaving sprites, undoing
-the `HARDWARE_SNK_SWAPP` program-ROM swap), and CRC-verifies every chip before
-writing `<driver>.zip` — so it fails loudly rather than emitting a broken set. It
-reads the chip tables from a FBNeo checkout (`.tmp/fbneo-build/…` by default, as
-left by `make build-wasm-ci`; override with `--src`).
-
-### Options
-
-| Option | Default | Description |
-|--------|---------|-------------|
-| `romFileName` | `game.zip` | Filename used when writing ROM bytes to MEMFS. |
-| `driver` | *(inferred)* | FBNeo ROM set short name to boot. |
-| `renderFilter` | `pixelated` | `pixelated` (crisp) or `smooth` (linear). |
-| `audioSampleRate` | `44100` | Target audio sample rate in Hz. |
-| `vsync` | `true` | Enable vertical sync. |
-| `integerScale` | `false` | Integer scaling only. |
-| `windowScale` | `2` | Internal render-resolution multiplier. |
+Sets whose program ROM lives inside the SMA custom chip cannot be reproduced by a
+straight carve; those fail CRC verification and are reported rather than written.
 
 ## Build
 
 ```sh
-make build        # Full build: WASM (Docker/Emscripten) + TypeScript SDK
-make build-sdk    # TypeScript only (SDK + manifest + demo shell)
-make build-wasm   # FBNeo WASM only (via Docker)
-make preview      # Serve dist/ with COOP/COEP headers
+make build-sdk    # TypeScript → dist/fbneo/ (no WASM), with the app and the datasets
+make build-wasm   # FBNeo → WebAssembly in the pinned emscripten/emsdk:6.0.2 (Docker)
+make demo         # the no-build demo page → dist/index.html
+make test         # type-check, then the tests against the built package
+make preview      # serve dist/ with COOP/COEP
+make romsets      # regenerate data/romsets/*.json from the pinned FBNeo checkout
 ```
 
-WebAssembly threads/SharedArrayBuffer require the COOP/COEP headers that
-`make preview` sets — serve the built `dist/` with those headers in production too.
+`scripts/build-fbneo.sh` fetches FBNeo at a pinned commit and ports its SDL2 burner to
+Emscripten: every source patch checks it applied, so a moved upstream fails the build
+instead of producing a broken engine. FBNeo's own blocking loop runs under ASYNCIFY and
+paces itself to the driver's frame rate on the real-time clock (not the monitor's refresh);
+`scripts/web_bridge.cpp` adds the SDK's handles (pause, reset, NVRAM flush, save states).
+
+## Project Specs
+
+- Contract: engine-specs 1.0 (`FbneoSDK` / `FbneoPlay`), self-contained ESM.
+- Engine: FBNeo pinned (see `FBNEO_REV` in `scripts/build-fbneo.sh`), Emscripten 6.0.2, ASYNCIFY.
+- Storage: OPFS `fbneo/<namespace>/` (NVRAM, hiscores, save states).
+- App: `dist/fbneo/app/app.js` (EngineApp), driver identified by content.
+- Records: [RECORD/](RECORD/).
 
-## WASM artifacts
+## Todos
 
-| File | Description |
-|------|-------------|
-| `fbneo.js` | Emscripten-generated module loader (`createFbneoModule`). |
-| `fbneo.wasm` | Compiled FBNeo runtime. |
+- Verify game-level behaviour with real ROM sets (pause, reset, states, NVRAM round trip).
+- Move the FBNeo pin forward (later upstream changed the audio code the build patches).
 
-FBNeo uses Emscripten SDL2. The JS loader expects a `<canvas id="canvas">` in the
-DOM (the SDK sets this id automatically). ROM zips are written to the in-memory
-MEMFS under `/roms/` before the emulator boots, and FBNeo is launched with the
-driver short name.
+## License
 
-See [CORE.md](CORE.md) for the mapping between upstream FBNeo capabilities and the
-options currently exposed by this wrapper.
+MIT for this wrapper. FBNeo has its own non-commercial license; ROM sets and BIOS images
+belong to their owners and are never shipped.

package/dist/fbneo/app/app.css

@@ -0,0 +1,112 @@
+/* FBNeo app — suspend points (Classic Mini style) and the pause menu.
+   engine-specs `--wg-*` tokens when the host sets them; same values as fallbacks. */
+
+.fbn-app {
+  --ring: var(--wg-focus-ring, 0 0 0 3px #fff);
+  --surface: var(--wg-surface, rgb(18 20 28 / 0.78));
+  --line: var(--wg-line, rgb(255 255 255 / 0.12));
+  --text: var(--wg-text, #f4f6fb);
+  --muted: var(--wg-muted, #8e97a9);
+  --danger: var(--wg-danger, #f87171);
+  --ui: var(--wg-font-ui, 'Inter Variable', 'Inter', system-ui, sans-serif);
+  --display: var(--wg-font-display, 'Unbounded Variable', 'Unbounded', system-ui, sans-serif);
+  --ease: var(--wg-ease, cubic-bezier(0.2, 0.8, 0.2, 1));
+  position: absolute; inset: 0; overflow: hidden; background: #000; color: var(--text);
+  font-family: var(--ui); user-select: none; -webkit-tap-highlight-color: transparent;
+}
+.fbn-app * { box-sizing: border-box; }
+.fbn-stage { position: absolute; inset: 0; display: grid; place-items: center; }
+.fbn-stage canvas { outline: none; }
+.fbn-overlay { position: absolute; inset: 0; display: grid; place-items: center; pointer-events: none; }
+.fbn-overlay > * { pointer-events: auto; }
+.fbn-app:not([data-screen='game']) .fbn-overlay {
+  background:
+    radial-gradient(120% 80% at 50% 0%, color-mix(in srgb, var(--accent) 34%, transparent), transparent 70%),
+    rgb(4 6 12 / 0.74);
+  backdrop-filter: blur(14px) saturate(1.2);
+  -webkit-backdrop-filter: blur(14px) saturate(1.2);
+}
+.fbn-app[data-screen='boot'] .fbn-overlay,
+.fbn-app[data-screen='points'] .fbn-overlay { background-color: rgb(4 6 12 / 0.9); }
+
+.kicker { margin: 0; font: 600 0.72rem var(--ui); letter-spacing: 0.22em; text-transform: uppercase; color: var(--muted); }
+.fbn-app h2 { margin: 0; font: 700 clamp(1.3rem, 3vw, 2rem) var(--display); letter-spacing: -0.02em; }
+
+/* boot */
+.fbn-boot { display: grid; justify-items: center; gap: 22px; }
+.fbn-boot img { width: min(240px, 46vw); border-radius: 22px; box-shadow: 0 30px 80px -30px #000; animation: fbn-breathe 2.4s var(--ease) infinite alternate; }
+.fbn-boot p { margin: 0; color: var(--muted); font-weight: 500; }
+@keyframes fbn-breathe { from { opacity: 0.55; transform: scale(0.98); } to { opacity: 1; transform: none; } }
+
+/* suspend points: a row of frames, like the Classic Mini's */
+.fbn-points { width: min(1180px, 100%); padding: 0 clamp(16px, 4vw, 48px); display: grid; gap: clamp(20px, 4vh, 36px); }
+.fbn-points header { display: grid; gap: 6px; }
+.points { display: flex; justify-content: center; gap: clamp(10px, 1.4vw, 18px); padding: 12px 4px; }
+.point {
+  all: unset; box-sizing: border-box; flex: 0 1 196px; min-width: 0; display: grid; gap: 8px; cursor: pointer;
+  transition: transform 0.22s var(--ease), opacity 0.2s;
+}
+.point-frame {
+  position: relative; display: grid; place-items: center; aspect-ratio: 320 / 224; border-radius: 10px; overflow: hidden;
+  background: rgb(255 255 255 / 0.04); border: 2px solid rgb(255 255 255 / 0.16);
+  transition: box-shadow 0.22s var(--ease), border-color 0.2s;
+}
+.point-frame img { width: 100%; height: 100%; object-fit: cover; image-rendering: pixelated; }
+.point-frame svg { width: 30%; color: var(--muted); }
+.point.is-empty .point-frame { border-style: dashed; background: transparent; }
+.point.is-auto .point-frame { border-color: color-mix(in srgb, var(--accent) 70%, #fff); }
+.point-label { font: 700 0.9rem var(--ui); text-align: center; }
+.point.is-auto .point-label { color: #fda4af; }
+.point-date { font: 500 0.74rem var(--ui); color: var(--muted); text-align: center; font-variant-numeric: tabular-nums; }
+.point-lock {
+  position: absolute; top: 6px; right: 6px; display: grid; place-items: center; width: 24px; height: 24px; border-radius: 50%;
+  background: rgb(0 0 0 / 0.72); color: #fbbf24;
+}
+.point-lock svg { width: 13px; color: inherit; }
+.point.is-start .point-frame { border-style: solid; }
+.point.is-focused { transform: translateY(-6px) scale(1.04); }
+.point.is-focused .point-frame { box-shadow: var(--ring), 0 26px 60px -24px #000; border-color: transparent; }
+.point.is-dim { opacity: 0.32; }
+.point.is-target.is-focused .point-frame { box-shadow: 0 0 0 3px #fbbf24, 0 26px 60px -24px #000; }
+
+/* pause, sheets, confirms */
+.fbn-panel {
+  width: min(440px, 92vw); display: grid; gap: 10px; padding: 26px; border-radius: 28px;
+  background: rgb(20 22 31 / 0.92); border: 1px solid var(--line); box-shadow: 0 40px 100px -30px #000;
+}
+.fbn-panel.is-small { width: min(380px, 92vw); }
+.fbn-panel h2 { margin-bottom: 8px; }
+.fbn-panel .text { margin: 0 0 8px; color: var(--muted); line-height: 1.5; }
+.item {
+  all: unset; box-sizing: border-box; display: grid; gap: 2px; padding: 13px 16px; border-radius: 14px;
+  background: rgb(255 255 255 / 0.05); font-weight: 600; cursor: pointer; transition: background 0.15s, box-shadow 0.15s;
+}
+.item small { font-weight: 500; font-size: 0.78rem; color: var(--muted); }
+.item[disabled] { opacity: 0.45; cursor: default; }
+.item.is-focused { background: #fff; color: #0b0d12; box-shadow: var(--ring); }
+.item.is-focused small { color: #4b5563; }
+.item.is-danger.is-focused { background: var(--danger); color: #1a0505; box-shadow: 0 0 0 3px var(--danger); }
+.item.is-danger.is-focused small { color: #450a0a; }
+.fbn-panel .row { display: grid; grid-template-columns: 1fr 1fr; gap: 10px; }
+.fbn-panel .row .item { text-align: center; }
+.fbn-layer { position: absolute; inset: 0; display: grid; place-items: center; background: rgb(0 0 0 / 0.55); }
+
+.fbn-hints { display: flex; flex-wrap: wrap; gap: 8px 18px; justify-content: center; color: var(--muted); font-size: 0.78rem; font-weight: 500; }
+.fbn-hints span { display: inline-flex; align-items: center; gap: 7px; }
+.fbn-hints kbd { display: inline-grid; place-items: center; min-width: 22px; height: 22px; padding: 0 6px; border-radius: 11px; background: rgb(255 255 255 / 0.12); color: var(--text); font: 700 0.68rem var(--ui); }
+.fbn-panel .fbn-hints { justify-content: flex-start; margin-top: 6px; }
+
+.fbn-toast {
+  position: absolute; left: 50%; bottom: calc(28px + var(--wg-safe-bottom, 0px)); transform: translateX(-50%); margin: 0;
+  padding: 10px 18px; border-radius: 999px; background: rgb(20 22 31 / 0.94); border: 1px solid var(--line);
+  font-weight: 600; font-size: 0.85rem; white-space: nowrap; animation: fbn-toast 0.3s var(--ease);
+}
+@keyframes fbn-toast { from { opacity: 0; transform: translate(-50%, 8px); } }
+
+@media (max-width: 960px) {
+  .points { justify-content: flex-start; overflow-x: auto; scrollbar-width: none; padding: 14px 6px 18px; }
+  .point { flex: 0 0 min(42vw, 180px); }
+}
+@media (prefers-reduced-motion: reduce) {
+  .point, .point-frame, .fbn-boot img, .fbn-toast { transition: none; animation: none; }
+}