@raskell/wasm-ad 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 raskell.io
+
+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,98 @@
-# Temporary Holding Version
+# WASM-AD for AssemblyScript
 
-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.
+An AssemblyScript SDK for [WASM-AD](https://github.com/raskell-io/wasm-ad) carts: register
+addresses, typed builders for backgrounds, sprites and affine matrices, input, save RAM and
+`trace`, with no runtime allocation and no mutable globals.
+
+## The starter cart
+
+```sh
+npm install
+npm run build            # build/starter.wasm
+node ../../tools/wasmad.mjs check build/starter.wasm
+```
+
+[`examples/starter.ts`](examples/starter.ts) is the same cart as every other SDK's starter
+and renders bit-identical frames. Drop `build/starter.wasm` into the player.
+
+## A new cart
+
+```sh
+npm install @raskell/wasm-ad assemblyscript@0.28
+echo '{ "extends": "./node_modules/@raskell/wasm-ad/cart.asconfig.json" }' > asconfig.json
+```
+
+```ts
+import { write16, reg, dispcnt, keys, key } from "@raskell/wasm-ad/assembly";
+```
+
+```sh
+npx asc cart.ts --config asconfig.json -o cart.wasm
+npx wasmad meta cart.wasm title="My Cart" author=you
+npx wasmad check cart.wasm
+```
+
+`cart.asconfig.json` is the configuration below with `abort` pointing into the
+installed package; extend it rather than copying it. `wasmad` is the cart
+checker from `tools/wasmad.mjs`, shipped with this package.
+
+`asconfig.json` sets what the spec requires:
+
+| Option | Why |
+|---|---|
+| `memoryBase: 163840` | Static data starts at 0x28000, above the hardware region (SPEC.md §4). |
+| `initialMemory: 4` | At least 3 pages; 4 leaves room above the data. |
+| `runtime: "stub"` | No garbage collector; carts do not allocate. |
+| `use: abort=assembly/index/abort` | Traps instead of importing `env.abort`; a cart may only import `env.trace`. |
+
+AssemblyScript cannot write custom sections, so `wasmad meta` adds the `wasm-ad` metadata
+(`spec` is filled in). Run `wasmad check` before sharing a cart.
+
+## Rules
+
+A cart exports `update()`, and optionally `start()` and `scanline(y: i32)`. Do the setup in
+`start`, not at the top level of a module, which would run before the host clears the hardware.
+
+**Keep state in linear memory.** AssemblyScript compiles a module-level `let` or `var` to a
+mutable WebAssembly global, which SPEC.md §12 forbids (hosts snapshot linear memory for save
+states and netplay), and `wasmad check` rejects it. Put the cart's state in an
+`@unmanaged` class placed in a static block of memory:
+
+```ts
+@unmanaged
+class State {
+  x: i32;
+  y: i32;
+}
+const state = changetype<State>(memory.data(offsetof<State>()));
+
+export function start(): void {
+  state.x = 112; // memory starts zeroed; set initial values here
+}
+```
+
+`const` values are fine. Avoid `new`, string concatenation, arrays and anything else that
+allocates; use `memory.data` for static buffers.
+
+## API
+
+All values are plain integers; builders take a value and return a new one.
+
+| | |
+|---|---|
+| `read16`, `write16`, `read32`, `write32` | Raw register access, e.g. `write16(reg.DISPCNT, dispcnt.MODE0 \| dispcnt.BG0)` |
+| `reg.*`, `reg.BGCNT(i)`, `reg.BGHOFS(i)`, `reg.BGVOFS(i)` | Register addresses by their SPEC.md names |
+| `dispcnt`, `layer`, `blend`, `key` | Bit constants; `blend.cnt(effect, first, second)`, `blend.alpha(eva, evb)` |
+| `bgcnt.priority/charBlock/screenBlock/size/bpp8/mosaic` | `BGxCNT` builders |
+| `rgb(r, g, b)` | 8-bit channels to RGB555 |
+| `setBgColor(i, c)`, `setObjColor(i, c)` | Palette RAM |
+| `bgTile(block, i)`, `objTile(i)`, `fillTile(addr, byte)` | Addresses of 32-byte 4bpp tiles |
+| `screenBlock(b)`, `setScreenEntry(b, i, e)`, `screenEntry.make/hflip/vflip` | Background maps |
+| `sprite.make(x, y, SpriteSize.S16x16, tile)` then `.bank/.priority/.hflip/.vflip/.semiTransparent/.window/.mosaic/.bpp8/.affine` | Sprites, packed in a `u64` |
+| `oam.set(i, s)`, `oam.hide(i)`, `oam.hideAll()`, `oam.setAffine(slot, m)` | OAM |
+| `affine.rotateScaleFixed(angle, sx, sy)`, `affine.IDENTITY`, `affine.make` | Affine matrices; angle in 1/256 turns, scale in 8.8 |
+| `fixed.sin(a)`, `fixed.cos(a)` | Q14 trigonometry, identical in every SDK |
+| `buttons.update()`, `buttons.held(k)`, `buttons.pressed(k)`, `keys()` | Input |
+| `frame()`, `seed()` | Time and the only entropy source |
+| `saveRam()`, `saveRestored()`, `requestSave()` | 32 KB of save RAM at 0x19000 |
+| `trace(msg)` | UTF-8 to the host's debug log (at most 1 KB) |

package/asconfig.json

@@ -0,0 +1,12 @@
+{
+  "options": {
+    "runtime": "stub",
+    "memoryBase": 163840,
+    "initialMemory": 4,
+    "use": ["abort=assembly/index/abort"],
+    "optimizeLevel": 3,
+    "shrinkLevel": 1,
+    "noAssert": true,
+    "exportRuntime": false
+  }
+}

package/assembly/index.ts

@@ -0,0 +1,549 @@
+// AssemblyScript SDK for WASM-AD carts.
+//
+// A cart exports `update` (and optionally `start` and `scanline`) and drives
+// the console by writing its memory-mapped hardware, which this module wraps
+// in typed helpers. See SPEC.md for the hardware.
+//
+// AssemblyScript keeps module-level `let`/`var` in WebAssembly globals, but a
+// cart's state must live in linear memory (SPEC.md §12). So this SDK has no
+// mutable globals, its values are plain integers (no allocation), and carts
+// keep their own state in a `@unmanaged` class placed with `memory.data`:
+//
+//   @unmanaged class State { x: i32; y: i32 }
+//   const state = changetype<State>(memory.data(offsetof<State>()));
+
+// ---- Memory map (SPEC.md §4) ------------------------------------------------
+
+export const SCREEN_W: i32 = 240;
+export const SCREEN_H: i32 = 160;
+
+export const IO: usize = 0x00400;
+export const PAL_BG: usize = 0x00800;
+export const PAL_OBJ: usize = 0x00a00;
+export const OAM: usize = 0x00c00;
+export const VRAM: usize = 0x01000;
+export const VRAM_SIZE: usize = 0x18000;
+/** Sprite tile 0. */
+export const OBJ_VRAM: usize = VRAM + 0x10000;
+export const SAVE: usize = 0x19000;
+export const SAVE_SIZE: usize = 0x8000;
+/** First address the cart may use for its own data, stack and heap. */
+export const CART: usize = 0x28000;
+/** OAM attribute 0 that hides a sprite. */
+export const OBJ_HIDDEN: u16 = 0x0200;
+export const SPEC_VERSION: u16 = 0x0001;
+
+// ---- Registers (SPEC.md §5, §6) ---------------------------------------------
+
+/** Every register address, by its SPEC.md name. Use with `read16`/`write16`. */
+export namespace reg {
+  export const DISPCNT: usize = 0x400;
+  export const VCOUNT: usize = 0x406;
+  export const WIN0H: usize = 0x440;
+  export const WIN1H: usize = 0x442;
+  export const WIN0V: usize = 0x444;
+  export const WIN1V: usize = 0x446;
+  export const WININ: usize = 0x448;
+  export const WINOUT: usize = 0x44a;
+  export const MOSAIC: usize = 0x44c;
+  export const BLDCNT: usize = 0x450;
+  export const BLDALPHA: usize = 0x452;
+  export const BLDY: usize = 0x454;
+  export const KEYS: usize = 0x700;
+  export const FRAME: usize = 0x704; // u32
+  export const SEED: usize = 0x708; // u32
+  export const SAVECNT: usize = 0x70c;
+  export const SAVESTAT: usize = 0x70e;
+  export const SPEC: usize = 0x710;
+
+  /** `BGxCNT` for background 0–3. */
+  // @ts-ignore: decorator
+  @inline export function BGCNT(bg: i32): usize {
+    return 0x408 + (<usize>bg << 1);
+  }
+  /** `BGxHOFS` for background 0–3. */
+  // @ts-ignore: decorator
+  @inline export function BGHOFS(bg: i32): usize {
+    return 0x410 + (<usize>bg << 2);
+  }
+  /** `BGxVOFS` for background 0–3. */
+  // @ts-ignore: decorator
+  @inline export function BGVOFS(bg: i32): usize {
+    return 0x412 + (<usize>bg << 2);
+  }
+}
+
+// @ts-ignore: decorator
+@inline export function read16(addr: usize): u16 {
+  return load<u16>(addr);
+}
+// @ts-ignore: decorator
+@inline export function write16(addr: usize, v: u16): void {
+  store<u16>(addr, v);
+}
+// @ts-ignore: decorator
+@inline export function read32(addr: usize): u32 {
+  return load<u32>(addr);
+}
+// @ts-ignore: decorator
+@inline export function write32(addr: usize, v: u32): void {
+  store<u32>(addr, v);
+}
+
+/** `DISPCNT` bits (SPEC.md §6.1). */
+export namespace dispcnt {
+  export const MODE0: u16 = 0;
+  export const MODE3: u16 = 3;
+  export const MODE4: u16 = 4;
+  export const MODE5: u16 = 5;
+  export const PAGE1: u16 = 1 << 4;
+  export const OBJ_1D: u16 = 1 << 6;
+  export const FORCED_BLANK: u16 = 1 << 7;
+  export const BG0: u16 = 1 << 8;
+  export const BG1: u16 = 1 << 9;
+  export const BG2: u16 = 1 << 10;
+  export const BG3: u16 = 1 << 11;
+  export const OBJ: u16 = 1 << 12;
+  export const WIN0: u16 = 1 << 13;
+  export const WIN1: u16 = 1 << 14;
+  export const OBJ_WIN: u16 = 1 << 15;
+}
+
+/** Layer bits for `BLDCNT` targets and window masks. */
+export namespace layer {
+  export const BG0: u16 = 1 << 0;
+  export const BG1: u16 = 1 << 1;
+  export const BG2: u16 = 1 << 2;
+  export const BG3: u16 = 1 << 3;
+  export const OBJ: u16 = 1 << 4;
+  export const BACKDROP: u16 = 1 << 5;
+  /** In window masks: color effects enabled. */
+  export const EFFECTS: u16 = 1 << 5;
+  export const ALL: u16 = 0x3f;
+}
+
+/** `BLDCNT` effects (SPEC.md §6.5). */
+export namespace blend {
+  export const NONE: u16 = 0;
+  export const ALPHA: u16 = 1 << 6;
+  export const BRIGHTEN: u16 = 2 << 6;
+  export const DARKEN: u16 = 3 << 6;
+
+  /** `BLDCNT` value: `effect` on `first` targets, blending onto `second`. */
+  // @ts-ignore: decorator
+  @inline export function cnt(effect: u16, first: u16, second: u16): u16 {
+    return effect | first | (second << 8);
+  }
+  /** `BLDALPHA` value; coefficients 0–16. */
+  // @ts-ignore: decorator
+  @inline export function alpha(eva: u16, evb: u16): u16 {
+    return eva | (evb << 8);
+  }
+}
+
+/** `KEYS` bits (SPEC.md §5). */
+export namespace key {
+  export const A: u16 = 1 << 0;
+  export const B: u16 = 1 << 1;
+  export const SELECT: u16 = 1 << 2;
+  export const START: u16 = 1 << 3;
+  export const RIGHT: u16 = 1 << 4;
+  export const LEFT: u16 = 1 << 5;
+  export const UP: u16 = 1 << 6;
+  export const DOWN: u16 = 1 << 7;
+  export const R: u16 = 1 << 8;
+  export const L: u16 = 1 << 9;
+}
+
+// ---- Backgrounds (SPEC.md §6.2, §8) -----------------------------------------
+
+/** Background map sizes, in tiles. */
+export enum MapSize {
+  S32x32 = 0,
+  S64x32 = 1,
+  S32x64 = 2,
+  S64x64 = 3,
+}
+
+/** Builders for a `BGxCNT` value (SPEC.md §6.2), e.g. `bgcnt.priority(bgcnt.screenBlock(0, 31), 1)`. */
+export namespace bgcnt {
+  // @ts-ignore: decorator
+  @inline export function priority(c: u16, p: u16): u16 {
+    return (c & ~3) | (p & 3);
+  }
+  // @ts-ignore: decorator
+  @inline export function charBlock(c: u16, b: u16): u16 {
+    return (c & ~0xc) | ((b & 3) << 2);
+  }
+  // @ts-ignore: decorator
+  @inline export function screenBlock(c: u16, b: u16): u16 {
+    return (c & ~0x1f00) | ((b & 31) << 8);
+  }
+  // @ts-ignore: decorator
+  @inline export function size(c: u16, s: MapSize): u16 {
+    return (c & 0x3fff) | (<u16>s << 14);
+  }
+  // @ts-ignore: decorator
+  @inline export function bpp8(c: u16): u16 {
+    return c | 0x80;
+  }
+  // @ts-ignore: decorator
+  @inline export function mosaic(c: u16): u16 {
+    return c | 0x40;
+  }
+}
+
+/** Packs 8-bit channels into RGB555. */
+// @ts-ignore: decorator
+@inline export function rgb(r: i32, g: i32, b: i32): u16 {
+  return <u16>(((r & 255) >> 3) | (((g & 255) >> 3) << 5) | (((b & 255) >> 3) << 10));
+}
+
+/** Sets background color `i` (0–255; 16 banks of 16 for 4bpp graphics). */
+// @ts-ignore: decorator
+@inline export function setBgColor(i: i32, c: u16): void {
+  store<u16>(PAL_BG + (<usize>i << 1), c);
+}
+/** Sets sprite color `i` (0–255). */
+// @ts-ignore: decorator
+@inline export function setObjColor(i: i32, c: u16): void {
+  store<u16>(PAL_OBJ + (<usize>i << 1), c);
+}
+
+/** Address of 4bpp background tile `index` counted from character block `block` (0–3). Tiles are 32 bytes. */
+// @ts-ignore: decorator
+@inline export function bgTile(block: i32, index: i32): usize {
+  return VRAM + <usize>block * 0x4000 + (<usize>index << 5);
+}
+/** Address of 4bpp sprite tile `index` (0–1023). */
+// @ts-ignore: decorator
+@inline export function objTile(index: i32): usize {
+  return OBJ_VRAM + (<usize>index << 5);
+}
+/** Fills a 32-byte 4bpp tile with one byte value, e.g. 0x11 for solid color 1. */
+// @ts-ignore: decorator
+@inline export function fillTile(tile: usize, byte: u8): void {
+  memory.fill(tile, byte, 32);
+}
+
+/** Address of screen block `block` (0–31): a 32×32 map of u16 entries, row-major. */
+// @ts-ignore: decorator
+@inline export function screenBlock(block: i32): usize {
+  return VRAM + <usize>block * 0x800;
+}
+/** Sets entry `i` (0–1023) of screen block `block`. */
+// @ts-ignore: decorator
+@inline export function setScreenEntry(block: i32, i: i32, e: u16): void {
+  store<u16>(screenBlock(block) + (<usize>i << 1), e);
+}
+
+/** Background map entries (SPEC.md §8.2). */
+export namespace screenEntry {
+  // @ts-ignore: decorator
+  @inline export function make(tile: u16, bank: u16): u16 {
+    return (tile & 0x3ff) | ((bank & 0xf) << 12);
+  }
+  // @ts-ignore: decorator
+  @inline export function hflip(e: u16): u16 {
+    return e | (1 << 10);
+  }
+  // @ts-ignore: decorator
+  @inline export function vflip(e: u16): u16 {
+    return e | (1 << 11);
+  }
+}
+
+// ---- Sprites (SPEC.md §9) ------------------------------------------------------
+
+/** Sprite sizes as shape × 4 + size (SPEC.md §9.2). */
+export enum SpriteSize {
+  S8x8 = 0,
+  S16x16 = 1,
+  S32x32 = 2,
+  S64x64 = 3,
+  W16x8 = 4,
+  W32x8 = 5,
+  W32x16 = 6,
+  W64x32 = 7,
+  T8x16 = 8,
+  T8x32 = 9,
+  T16x32 = 10,
+  T32x64 = 11,
+}
+
+/** Width in pixels of a sprite size. */
+export function spriteWidth(s: SpriteSize): i32 {
+  const shape = <i32>s >> 2, size = <i32>s & 3;
+  if (shape == 0) return 8 << size;
+  if (shape == 1) return size == 0 ? 16 : size == 3 ? 64 : 32;
+  return size == 3 ? 32 : size == 2 ? 16 : 8;
+}
+/** Height in pixels of a sprite size. */
+export function spriteHeight(s: SpriteSize): i32 {
+  const shape = <i32>s >> 2, size = <i32>s & 3;
+  if (shape == 0) return 8 << size;
+  if (shape == 1) return size == 3 ? 32 : size == 2 ? 16 : 8;
+  return size == 0 ? 16 : size == 3 ? 64 : 32;
+}
+
+/** One OAM entry's three attributes, packed as attr0 | attr1 << 16 | attr2 << 32. */
+export type Sprite = u64;
+
+/** Builders for sprites (SPEC.md §9.1), e.g. `sprite.affine(sprite.make(x, y, SpriteSize.S16x16, 0), 0, true)`. */
+export namespace sprite {
+  export const HIDDEN: Sprite = <u64>OBJ_HIDDEN;
+
+  // @ts-ignore: decorator
+  @inline export function attr0(s: Sprite): u16 {
+    return <u16>s;
+  }
+  // @ts-ignore: decorator
+  @inline export function attr1(s: Sprite): u16 {
+    return <u16>(s >> 16);
+  }
+  // @ts-ignore: decorator
+  @inline export function attr2(s: Sprite): u16 {
+    return <u16>(s >> 32);
+  }
+  // @ts-ignore: decorator
+  @inline export function pack(a0: u16, a1: u16, a2: u16): Sprite {
+    return <u64>a0 | (<u64>a1 << 16) | (<u64>a2 << 32);
+  }
+
+  /** A sprite with its top-left at screen (x, y), using `tile` and bank 0. */
+  export function make(x: i32, y: i32, size: SpriteSize, tile: u16): Sprite {
+    const shape = <u16>(<i32>size >> 2), sz = <u16>(<i32>size & 3);
+    return pack(<u16>(y & 0xff) | (shape << 14), <u16>(x & 0x1ff) | (sz << 14), tile & 0x3ff);
+  }
+  export function bank(s: Sprite, b: u16): Sprite {
+    return pack(attr0(s), attr1(s), (attr2(s) & 0x0fff) | ((b & 0xf) << 12));
+  }
+  export function priority(s: Sprite, p: u16): Sprite {
+    return pack(attr0(s), attr1(s), (attr2(s) & ~0x0c00) | ((p & 3) << 10));
+  }
+  export function hflip(s: Sprite, on: bool): Sprite {
+    return pack(attr0(s), on ? attr1(s) | 0x1000 : attr1(s) & ~0x1000, attr2(s));
+  }
+  export function vflip(s: Sprite, on: bool): Sprite {
+    return pack(attr0(s), on ? attr1(s) | 0x2000 : attr1(s) & ~0x2000, attr2(s));
+  }
+  export function semiTransparent(s: Sprite): Sprite {
+    return pack((attr0(s) & ~0x0c00) | 0x0400, attr1(s), attr2(s));
+  }
+  export function window(s: Sprite): Sprite {
+    return pack((attr0(s) & ~0x0c00) | 0x0800, attr1(s), attr2(s));
+  }
+  export function mosaic(s: Sprite): Sprite {
+    return pack(attr0(s) | 0x1000, attr1(s), attr2(s));
+  }
+  export function bpp8(s: Sprite): Sprite {
+    return pack(attr0(s) | 0x2000, attr1(s), attr2(s));
+  }
+  /** Uses affine matrix `slot` (0–31). With `doubleSize` the bounding box
+   *  doubles so rotated or enlarged pixels are not clipped. */
+  export function affine(s: Sprite, slot: u16, doubleSize: bool): Sprite {
+    const a0 = attr0(s) | 0x0100 | (doubleSize ? 0x0200 : 0);
+    const a1 = (attr1(s) & ~0x3e00) | ((slot & 31) << 9);
+    return pack(<u16>a0, a1, attr2(s));
+  }
+}
+
+/** An affine matrix in 8.8 fixed point, mapping screen to texture space,
+ *  packed as pa | pb << 16 | pc << 32 | pd << 48. */
+export type AffineMatrix = u64;
+
+export namespace affine {
+  export const IDENTITY: AffineMatrix = 256 | (<u64>256 << 48);
+
+  // @ts-ignore: decorator
+  @inline export function make(pa: i16, pb: i16, pc: i16, pd: i16): AffineMatrix {
+    return <u64><u16>pa | (<u64><u16>pb << 16) | (<u64><u16>pc << 32) | (<u64><u16>pd << 48);
+  }
+  // @ts-ignore: decorator
+  @inline export function pa(m: AffineMatrix): i16 {
+    return <i16>m;
+  }
+  // @ts-ignore: decorator
+  @inline export function pb(m: AffineMatrix): i16 {
+    return <i16>(m >> 16);
+  }
+  // @ts-ignore: decorator
+  @inline export function pc(m: AffineMatrix): i16 {
+    return <i16>(m >> 32);
+  }
+  // @ts-ignore: decorator
+  @inline export function pd(m: AffineMatrix): i16 {
+    return <i16>(m >> 48);
+  }
+
+  function clamp16(v: i32): i16 {
+    return <i16>(v < -32768 ? -32768 : v > 32767 ? 32767 : v);
+  }
+
+  /** Rotates counter-clockwise by `angle` 1/256 turns and scales by (sx, sy)
+   *  in 8.8 fixed point (256 = 1×, nonzero). Integer math, identical in
+   *  every WASM-AD SDK. */
+  export function rotateScaleFixed(angle: i32, sx: i32, sy: i32): AffineMatrix {
+    const s = fixed.sin(angle), c = fixed.cos(angle);
+    return make(clamp16((c * 4) / sx), clamp16((-s * 4) / sx), clamp16((s * 4) / sy), clamp16((c * 4) / sy));
+  }
+}
+
+/** OAM: 128 sprites, plus affine matrices stored in the gaps. */
+export namespace oam {
+  export function set(i: i32, s: Sprite): void {
+    const at = OAM + (<usize>i << 3);
+    store<u16>(at, sprite.attr0(s));
+    store<u16>(at + 2, sprite.attr1(s));
+    store<u16>(at + 4, sprite.attr2(s));
+  }
+  export function hide(i: i32): void {
+    set(i, sprite.HIDDEN);
+  }
+  export function hideAll(): void {
+    for (let i = 0; i < 128; i++) hide(i);
+  }
+  export function setAffine(slot: i32, m: AffineMatrix): void {
+    const at = OAM + <usize>slot * 32 + 6;
+    store<u16>(at, <u16>affine.pa(m));
+    store<u16>(at + 8, <u16>affine.pb(m));
+    store<u16>(at + 16, <u16>affine.pc(m));
+    store<u16>(at + 24, <u16>affine.pd(m));
+  }
+}
+
+// ---- Fixed-point trigonometry --------------------------------------------------
+
+/** Fixed-point trigonometry shared by all WASM-AD SDKs, so carts in any
+ *  language compute bit-identical results (SPEC.md §12). */
+export namespace fixed {
+  /** sin over a quarter turn in 1/256-turn steps, scaled by 16384 (Q14). */
+  export const SIN_Q14: usize = memory.data<i32>([
+    0, 402, 804, 1205, 1606, 2006, 2404, 2801, 3196, 3590, 3981, 4370, 4756, 5139, 5520, 5897, 6270, 6639, 7005,
+    7366, 7723, 8076, 8423, 8765, 9102, 9434, 9760, 10080, 10394, 10702, 11003, 11297, 11585, 11866, 12140, 12406,
+    12665, 12916, 13160, 13395, 13623, 13842, 14053, 14256, 14449, 14635, 14811, 14978, 15137, 15286, 15426, 15557,
+    15679, 15791, 15893, 15986, 16069, 16143, 16207, 16261, 16305, 16340, 16364, 16379, 16384,
+  ]);
+
+  // @ts-ignore: decorator
+  @inline function q(i: i32): i32 {
+    return load<i32>(SIN_Q14 + (<usize>i << 2));
+  }
+
+  /** sin of `angle` 1/256 turns (only the low 8 bits count), in Q14. */
+  export function sin(angle: i32): i32 {
+    const a = angle & 255;
+    if (a < 64) return q(a);
+    if (a < 128) return q(128 - a);
+    if (a < 192) return -q(a - 128);
+    return -q(256 - a);
+  }
+
+  /** cos of `angle` 1/256 turns, in Q14. */
+  export function cos(angle: i32): i32 {
+    return sin(angle + 64);
+  }
+}
+
+// ---- Input, time, save RAM -------------------------------------------------------
+
+/** Buttons held this frame. */
+// @ts-ignore: decorator
+@inline export function keys(): u16 {
+  return load<u16>(reg.KEYS);
+}
+
+/** Edge detection over `KEYS`: call `buttons.update()` at the start of every
+ *  frame. Its two words of state live in linear memory. */
+export namespace buttons {
+  const STATE: usize = memory.data(4); // held: u16, prev: u16
+
+  export function update(): void {
+    store<u16>(STATE + 2, load<u16>(STATE));
+    store<u16>(STATE, keys());
+  }
+  export function held(k: u16): bool {
+    return (load<u16>(STATE) & k) != 0;
+  }
+  /** True only on the frame the button went down. */
+  export function pressed(k: u16): bool {
+    return (load<u16>(STATE) & ~load<u16>(STATE + 2) & k) != 0;
+  }
+}
+
+/** Frames since boot. */
+// @ts-ignore: decorator
+@inline export function frame(): u32 {
+  return load<u32>(reg.FRAME);
+}
+
+/** The boot-time random seed, the cart's only entropy (SPEC.md §12). */
+// @ts-ignore: decorator
+@inline export function seed(): u32 {
+  return load<u32>(reg.SEED);
+}
+
+/** Address of the 32 KB battery-backed save RAM. */
+// @ts-ignore: decorator
+@inline export function saveRam(): usize {
+  return SAVE;
+}
+
+/** Whether the host restored save RAM from storage at boot. */
+// @ts-ignore: decorator
+@inline export function saveRestored(): bool {
+  return (load<u16>(reg.SAVESTAT) & 1) != 0;
+}
+
+/** Asks the host to persist save RAM after this frame. */
+// @ts-ignore: decorator
+@inline export function requestSave(): void {
+  store<u16>(reg.SAVECNT, load<u16>(reg.SAVECNT) | 1);
+}
+
+// ---- Debug log -------------------------------------------------------------------
+
+// @ts-ignore: decorator
+@external("env", "trace")
+declare function hostTrace(ptr: usize, len: i32): void;
+
+/** Writes a message to the host's debug log, as UTF-8 (at most 1 KB). */
+export function trace(msg: string): void {
+  const buf = memory.data(1024);
+  let n: usize = 0;
+  const len = msg.length;
+  for (let i = 0; i < len; i++) {
+    let c = <u32>msg.charCodeAt(i);
+    if (c >= 0xd800 && c < 0xdc00 && i + 1 < len) {
+      const lo = <u32>msg.charCodeAt(i + 1);
+      if (lo >= 0xdc00 && lo < 0xe000) {
+        c = 0x10000 + ((c - 0xd800) << 10) + (lo - 0xdc00);
+        i++;
+      }
+    }
+    const need: usize = c < 0x80 ? 1 : c < 0x800 ? 2 : c < 0x10000 ? 3 : 4;
+    if (n + need > 1024) break;
+    if (need == 1) store<u8>(buf + n, c);
+    else if (need == 2) {
+      store<u8>(buf + n, 0xc0 | (c >> 6));
+      store<u8>(buf + n + 1, 0x80 | (c & 63));
+    } else if (need == 3) {
+      store<u8>(buf + n, 0xe0 | (c >> 12));
+      store<u8>(buf + n + 1, 0x80 | ((c >> 6) & 63));
+      store<u8>(buf + n + 2, 0x80 | (c & 63));
+    } else {
+      store<u8>(buf + n, 0xf0 | (c >> 18));
+      store<u8>(buf + n + 1, 0x80 | ((c >> 12) & 63));
+      store<u8>(buf + n + 2, 0x80 | ((c >> 6) & 63));
+      store<u8>(buf + n + 3, 0x80 | (c & 63));
+    }
+    n += need;
+  }
+  hostTrace(buf, <i32>n);
+}
+
+/** Replaces AssemblyScript's `env.abort` import (`--use abort=...` in asconfig.json):
+ *  a failed assertion or bounds check traps. */
+export function abort(message: string | null, file: string | null, line: u32, column: u32): void {
+  unreachable();
+}

package/bin/wasmad.mjs

@@ -0,0 +1,428 @@
+#!/usr/bin/env node
+// Command-line tools for WASM-AD carts, in any language. Needs Node 18+ and
+// nothing else.
+//
+//   wasmad check <cart.wasm>                  validate a cart against SPEC.md
+//   wasmad meta <cart.wasm> key=value...      set the `wasm-ad` metadata section
+//   wasmad run <cart.wasm> [options]          run frames headlessly
+//
+// `meta` replaces the metadata section in place (or writes `-o <file>`); `spec`
+// defaults to the version this tool implements. It is for toolchains that
+// cannot emit custom sections themselves (AssemblyScript, TinyGo).
+//
+// `run` boots the cart like a host does (SPEC.md §3) and renders with the
+// reference renderer, player/web/core.wasm (`make player`). Options:
+//   --frames N        frames to run (default 1)
+//   --keys SCRIPT     held buttons per frame, e.g. "0-29:right,30-59:down+b,60:a"
+//   --seed N          value for SEED (default 1)
+//   --hash F,F,...    print a hash of the frame rendered at each listed frame
+//   --ppm FILE        write the last rendered frame as a PPM image
+//   --core FILE       a different core.wasm
+
+import { readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+const SPEC = '0.1';
+const SPEC_VERSION = 0x0001;
+const W = 240, H = 160;
+const A = {
+  IO: 0x400, PAL_END: 0xC00, OAM: 0xC00, VIDEO_END: 0x19000, SAVE: 0x19000, SAVE_SIZE: 0x8000, CART: 0x28000,
+  VCOUNT: 0x406, KEYS: 0x700, FRAME: 0x704, SEED: 0x708, SAVECNT: 0x70C, SAVESTAT: 0x70E, SPEC: 0x710,
+};
+const KEY = { a: 1, b: 2, select: 4, start: 8, right: 16, left: 32, up: 64, down: 128, r: 256, l: 512 };
+const MAX_CART = 32 * 1024 * 1024;
+
+// ---- WebAssembly binary reading -------------------------------------------
+
+class Reader {
+  constructor(bytes, pos = 0, end = bytes.length) {
+    Object.assign(this, { bytes, pos, end });
+  }
+  byte() {
+    if (this.pos >= this.end) throw new Error('unexpected end of module');
+    return this.bytes[this.pos++];
+  }
+  u32() {
+    let result = 0, shift = 0, b;
+    do {
+      b = this.byte();
+      result |= (b & 0x7F) << shift;
+      shift += 7;
+    } while (b & 0x80);
+    return result >>> 0;
+  }
+  i32() {
+    let result = 0, shift = 0, b;
+    do {
+      b = this.byte();
+      result |= (b & 0x7F) << shift;
+      shift += 7;
+    } while (b & 0x80);
+    return shift < 32 && b & 0x40 ? result | (-1 << shift) : result | 0;
+  }
+  skip(n) { this.pos += n; }
+  name() {
+    const n = this.u32();
+    const s = new TextDecoder().decode(this.bytes.subarray(this.pos, this.pos + n));
+    this.pos += n;
+    return s;
+  }
+  limits() {
+    const flags = this.byte();
+    const min = this.u32();
+    const max = flags & 1 ? this.u32() : null;
+    return { flags, min, max };
+  }
+  // A constant expression; returns its value if it is a single i32.const.
+  constExpr() {
+    let value = null, first = true;
+    for (;;) {
+      const op = this.byte();
+      if (op === 0x0B) return value;
+      if (op === 0x41) value = first ? this.i32() : (this.i32(), null);
+      else if (op === 0x23) { this.u32(); value = null; } // global.get
+      else if (op === 0x42) { while (this.byte() & 0x80); value = null; }
+      else if (op === 0x43) { this.skip(4); value = null; }
+      else if (op === 0x44) { this.skip(8); value = null; }
+      else value = null;
+      first = false;
+    }
+  }
+}
+
+const VALTYPE = { 0x7F: 'i32', 0x7E: 'i64', 0x7D: 'f32', 0x7C: 'f64', 0x7B: 'v128', 0x70: 'funcref', 0x6F: 'externref' };
+
+function sections(bytes) {
+  if (bytes.length < 8 || bytes[0] !== 0 || bytes[1] !== 0x61 || bytes[2] !== 0x73 || bytes[3] !== 0x6D) {
+    throw new Error('not a WebAssembly module');
+  }
+  const out = [];
+  const r = new Reader(bytes, 8);
+  while (r.pos < bytes.length) {
+    const start = r.pos;
+    const id = r.byte();
+    const size = r.u32();
+    const body = r.pos;
+    out.push({ id, start, body, end: body + size });
+    r.pos = body + size;
+  }
+  return out;
+}
+
+/** Parses the parts of a module that SPEC.md constrains. */
+export function inspect(bytes) {
+  const m = { types: [], imports: [], funcs: [], memories: [], globals: [], exports: [], data: [], custom: [], start: null };
+  let importedFuncs = 0, importedGlobals = 0;
+  for (const s of sections(bytes)) {
+    const r = new Reader(bytes, s.body, s.end);
+    switch (s.id) {
+      case 0: m.custom.push({ name: r.name(), data: bytes.subarray(r.pos, s.end), start: s.start, end: s.end }); break;
+      case 1:
+        for (let n = r.u32(); n--;) {
+          if (r.byte() !== 0x60) throw new Error('unsupported type form');
+          const params = Array.from({ length: r.u32() }, () => VALTYPE[r.byte()]);
+          const results = Array.from({ length: r.u32() }, () => VALTYPE[r.byte()]);
+          m.types.push({ params, results });
+        }
+        break;
+      case 2:
+        for (let n = r.u32(); n--;) {
+          const imp = { module: r.name(), name: r.name(), kind: r.byte() };
+          if (imp.kind === 0) { imp.type = r.u32(); importedFuncs++; m.funcs.push(imp.type); }
+          else if (imp.kind === 1) { r.byte(); r.limits(); }
+          else if (imp.kind === 2) { imp.limits = r.limits(); m.memories.push(imp.limits); }
+          else if (imp.kind === 3) { r.byte(); imp.mutable = r.byte() === 1; importedGlobals++; m.globals.push({ imported: true, mutable: imp.mutable }); }
+          m.imports.push(imp);
+        }
+        break;
+      case 3: for (let n = r.u32(); n--;) m.funcs.push(r.u32()); break;
+      case 5: for (let n = r.u32(); n--;) m.memories.push(r.limits()); break;
+      case 6:
+        for (let n = r.u32(); n--;) {
+          const type = VALTYPE[r.byte()];
+          const mutable = r.byte() === 1;
+          m.globals.push({ type, mutable, init: r.constExpr() });
+        }
+        break;
+      case 7:
+        for (let n = r.u32(); n--;) m.exports.push({ name: r.name(), kind: r.byte(), index: r.u32() });
+        break;
+      case 8: m.start = r.u32(); break;
+      case 11:
+        for (let n = r.u32(); n--;) {
+          const flags = r.u32();
+          let offset = null, active = flags !== 1;
+          if (flags === 2) r.u32();
+          if (active) offset = r.constExpr();
+          const size = r.u32();
+          r.skip(size);
+          m.data.push({ active, offset, size });
+        }
+        break;
+    }
+  }
+  m.importedFuncs = importedFuncs;
+  m.importedGlobals = importedGlobals;
+  return m;
+}
+
+/** Validates a cart against SPEC.md. Returns { errors, warnings, meta, info }. */
+export function check(bytes) {
+  const errors = [], warnings = [], info = [];
+  if (bytes.length > MAX_CART) errors.push(`cart is ${bytes.length} bytes; the limit is 32 MiB (§2.4)`);
+  let m;
+  try {
+    m = inspect(bytes);
+    new WebAssembly.Module(bytes);
+  } catch (e) {
+    return { errors: [`invalid module: ${e.message}`], warnings, meta: null, info };
+  }
+
+  // §2.2 imports
+  for (const imp of m.imports) {
+    if (imp.module === 'env' && imp.name === 'trace' && imp.kind === 0) {
+      const t = m.types[imp.type];
+      if (t.params.join() !== 'i32,i32' || t.results.length) errors.push('env.trace must have type (i32, i32) -> () (§2.2)');
+    } else {
+      errors.push(`imports ${imp.module}.${imp.name}; a cart may only import env.trace (§2.2)`);
+    }
+  }
+
+  // §2.1 exports
+  const exp = Object.fromEntries(m.exports.map((e) => [e.name, e]));
+  const funcType = (name) => m.types[m.funcs[exp[name].index]];
+  const sig = (t) => `(${t.params.join(', ')}) -> (${t.results.join(', ')})`;
+  const want = { update: '() -> ()', start: '() -> ()', scanline: '(i32) -> ()' };
+  if (!exp.memory || exp.memory.kind !== 2) errors.push('does not export memory (§2.1)');
+  else {
+    const mem = m.memories[exp.memory.index];
+    if (mem.min < 3) errors.push(`memory starts at ${mem.min} pages; at least 3 are required (§2.1)`);
+    if (mem.max !== null && mem.max < 256) warnings.push(`memory is capped at ${mem.max} pages; hosts allow growth to 16 MiB (§2.4)`);
+    info.push(`memory: ${mem.min} pages${mem.max !== null ? `, max ${mem.max}` : ''}`);
+  }
+  for (const [name, want_] of Object.entries(want)) {
+    if (!exp[name]) {
+      if (name === 'update') errors.push('does not export update (§2.1)');
+      continue;
+    }
+    if (exp[name].kind !== 0) { errors.push(`export ${name} is not a function (§2.1)`); continue; }
+    const got = sig(funcType(name));
+    if (got !== want_) errors.push(`${name} has type ${got}; expected ${want_} (§2.1)`);
+  }
+  info.push(`exports: ${['update', 'start', 'scanline'].filter((n) => exp[n]).join(', ')}`);
+  if (m.start !== null) errors.push('uses the WebAssembly start section; export `start` instead (§2.1)');
+
+  // §4 memory layout
+  for (const d of m.data) {
+    if (!d.active) continue;
+    if (d.offset === null) warnings.push('a data segment has a non-constant offset; cannot check it is above 0x28000');
+    else if ((d.offset >>> 0) < A.CART && d.size > 0) {
+      errors.push(`data segment at 0x${(d.offset >>> 0).toString(16)} lies below 0x28000 (§4, §13)`);
+    }
+  }
+  // Only the stack pointer may be a mutable global; we can't see names in a
+  // stripped module, so a lone i32 starting in the cart region is taken as it.
+  const mutable = m.globals.filter((g) => !g.imported && g.mutable);
+  if (mutable.length > 1) {
+    errors.push(`${mutable.length} mutable globals; cart state must live in linear memory, only the stack pointer may be a global (§12)`);
+  } else if (mutable.length === 1) {
+    const [g] = mutable;
+    if (g.type !== 'i32') errors.push(`a mutable ${g.type} global holds cart state; it must live in linear memory (§12)`);
+    else if (g.init !== null && (g.init >>> 0) < A.CART) {
+      errors.push(`a mutable global starts at 0x${(g.init >>> 0).toString(16)}: as the stack pointer it would be inside the hardware region (§4, §13), and anything else is cart state that must live in linear memory (§12)`);
+    } else if (g.init !== null) info.push(`stack pointer: 0x${(g.init >>> 0).toString(16)}`);
+  }
+
+  // §2.3 metadata
+  let meta = null;
+  const sections_ = m.custom.filter((c) => c.name === 'wasm-ad');
+  if (!sections_.length) errors.push('missing the "wasm-ad" metadata section (§2.3)');
+  else {
+    if (sections_.length > 1) warnings.push('more than one "wasm-ad" section; hosts read the first');
+    meta = parseMeta(sections_[0].data);
+    if (!meta.spec) errors.push('metadata has no spec key (§2.3)');
+    else if (!/^\d+\.\d+$/.test(meta.spec)) errors.push(`metadata spec "${meta.spec}" is not major.minor (§2.3)`);
+    if (!meta.title) errors.push('metadata has no title (§2.3)');
+  }
+  return { errors, warnings, meta, info };
+}
+
+export function parseMeta(data) {
+  const meta = {};
+  for (const line of new TextDecoder().decode(data).split('\n')) {
+    const i = line.indexOf('=');
+    if (i > 0) meta[line.slice(0, i).trim().toLowerCase()] = line.slice(i + 1).trim();
+  }
+  return meta;
+}
+
+function leb(n) {
+  const out = [];
+  do {
+    let b = n & 0x7F;
+    n >>>= 7;
+    if (n) b |= 0x80;
+    out.push(b);
+  } while (n);
+  return out;
+}
+
+/** Returns `bytes` with its `wasm-ad` sections replaced by one holding `meta`. */
+export function setMeta(bytes, meta) {
+  const text = Object.entries(meta).map(([k, v]) => `${k}=${v}\n`).join('');
+  const name = new TextEncoder().encode('wasm-ad');
+  const payload = [...leb(name.length), ...name, ...new TextEncoder().encode(text)];
+  const section = Uint8Array.from([0, ...leb(payload.length), ...payload]);
+  const parts = [bytes.subarray(0, 8)];
+  for (const s of sections(bytes)) {
+    if (s.id === 0 && new Reader(bytes, s.body, s.end).name() === 'wasm-ad') continue;
+    parts.push(bytes.subarray(s.start, s.end));
+  }
+  parts.push(section);
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+  let at = 0;
+  for (const p of parts) { out.set(p, at); at += p.length; }
+  return out;
+}
+
+// ---- Headless host ----------------------------------------------------------
+
+/** Parses "0-29:right,30-59:down+b,60:a" into a frame -> KEYS function. */
+export function parseKeys(script) {
+  const spans = (script ?? '').split(',').filter(Boolean).map((part) => {
+    const [range, buttons] = part.split(':');
+    const [from, to = from] = range.split('-').map(Number);
+    let mask = 0;
+    for (const b of (buttons ?? '').split('+').filter(Boolean)) {
+      if (!(b in KEY)) throw new Error(`unknown button "${b}"; use ${Object.keys(KEY).join(', ')}`);
+      mask |= KEY[b];
+    }
+    return { from, to, mask };
+  });
+  return (frame) => spans.reduce((k, s) => (frame >= s.from && frame <= s.to ? k | s.mask : k), 0);
+}
+
+/** Boots a cart and returns a host that runs frames (SPEC.md §3). */
+export async function boot(bytes, { core: corePath, seed = 1, onTrace = () => {} } = {}) {
+  const core = (await WebAssembly.instantiate(readFileSync(corePath))).instance.exports;
+  let instance;
+  const decoder = new TextDecoder();
+  const imports = { env: { trace: (ptr, len) => onTrace(decoder.decode(new Uint8Array(instance.exports.memory.buffer, ptr, len))) } };
+  instance = (await WebAssembly.instantiate(bytes, imports)).instance;
+  const ex = instance.exports;
+  const mem = () => new Uint8Array(ex.memory.buffer);
+  const dv = () => new DataView(ex.memory.buffer);
+  mem().fill(0, 0, A.CART);
+  for (let i = 0; i < 128; i++) dv().setUint16(A.OAM + i * 8, 0x0200, true);
+  dv().setUint32(A.SEED, seed >>> 0, true);
+  dv().setUint16(A.SPEC, SPEC_VERSION, true);
+  ex.start?.();
+
+  let frame = 0;
+  return {
+    exports: ex,
+    /** Runs one frame with `keys` held and returns the rendered RGBA8 pixels. */
+    frame(keys = 0) {
+      dv().setUint16(A.KEYS, keys & 0x3FF, true);
+      dv().setUint32(A.FRAME, frame >>> 0, true);
+      dv().setUint16(A.VCOUNT, 160, true);
+      ex.update();
+      const coreMem = new Uint8Array(core.memory.buffer, core.ad_mem(), core.ad_mem_len());
+      coreMem.set(mem().subarray(0, A.VIDEO_END));
+      for (let y = 0; y < H; y++) {
+        if (ex.scanline) {
+          dv().setUint16(A.VCOUNT, y, true);
+          ex.scanline(y);
+          coreMem.set(mem().subarray(A.IO, A.PAL_END), A.IO);
+        }
+        core.ad_render_line(y);
+      }
+      if (dv().getUint16(A.SAVECNT, true) & 1) dv().setUint16(A.SAVECNT, dv().getUint16(A.SAVECNT, true) & ~1, true);
+      frame++;
+      return new Uint8Array(core.memory.buffer, core.ad_framebuffer(), W * H * 4).slice();
+    },
+  };
+}
+
+export function hash(pixels) {
+  return createHash('sha256').update(pixels).digest('hex').slice(0, 16);
+}
+
+function ppm(pixels) {
+  const head = new TextEncoder().encode(`P6 ${W} ${H} 255\n`);
+  const out = new Uint8Array(head.length + W * H * 3);
+  out.set(head);
+  for (let i = 0; i < W * H; i++) out.set(pixels.subarray(i * 4, i * 4 + 3), head.length + i * 3);
+  return out;
+}
+
+// ---- CLI ----------------------------------------------------------------------
+
+function options(args) {
+  const opts = { _: [] };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '-o') opts.o = args[++i];
+    else if (args[i].startsWith('--')) opts[args[i].slice(2)] = args[++i];
+    else opts._.push(args[i]);
+  }
+  return opts;
+}
+
+async function main([cmd, ...args]) {
+  const opts = options(args);
+  const [file, ...rest] = opts._;
+  if (!cmd || !file || !['check', 'meta', 'run'].includes(cmd)) {
+    console.error('usage: wasmad check <cart.wasm>\n       wasmad meta <cart.wasm> [-o out.wasm] key=value...\n       wasmad run <cart.wasm> [--frames N] [--keys SCRIPT] [--seed N] [--hash F,F] [--ppm FILE]');
+    return 2;
+  }
+  const bytes = new Uint8Array(readFileSync(file));
+
+  if (cmd === 'meta') {
+    const meta = { spec: SPEC };
+    for (const kv of rest) {
+      const i = kv.indexOf('=');
+      if (i <= 0) throw new Error(`expected key=value, got "${kv}"`);
+      meta[kv.slice(0, i).toLowerCase()] = kv.slice(i + 1);
+    }
+    if (!meta.title) throw new Error('title=... is required');
+    writeFileSync(opts.o ?? file, setMeta(bytes, meta));
+    return 0;
+  }
+
+  if (cmd === 'check') {
+    const { errors, warnings, meta, info } = check(bytes);
+    if (meta) console.log(`${meta.title}${meta.author ? ` by ${meta.author}` : ''} (spec ${meta.spec}), ${bytes.length} bytes`);
+    for (const line of info) console.log(`  ${line}`);
+    for (const w of warnings) console.log(`warning: ${w}`);
+    for (const e of errors) console.log(`error: ${e}`);
+    if (!errors.length) console.log('ok');
+    return errors.length ? 1 : 0;
+  }
+
+  const { errors } = check(bytes);
+  if (errors.length) {
+    for (const e of errors) console.error(`error: ${e}`);
+    return 1;
+  }
+  const core = opts.core ?? fileURLToPath(new URL('../player/web/core.wasm', import.meta.url));
+  const host = await boot(bytes, { core, seed: Number(opts.seed ?? 1), onTrace: (m) => console.log(`trace: ${m}`) });
+  const keys = parseKeys(opts.keys);
+  const frames = Number(opts.frames ?? 1);
+  const marks = new Set((opts.hash ?? '').split(',').filter(Boolean).map(Number));
+  let pixels;
+  for (let f = 0; f < frames; f++) {
+    pixels = host.frame(keys(f));
+    if (marks.has(f)) console.log(`frame ${f}: ${hash(pixels)}`);
+  }
+  if (opts.ppm) writeFileSync(opts.ppm, ppm(pixels));
+  return 0;
+}
+
+// Run as a command, also through a symlink such as node_modules/.bin/wasmad.
+if (process.argv[1] && realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1])) {
+  main(process.argv.slice(2)).then((code) => process.exit(code), (e) => {
+    console.error(`error: ${e.message}`);
+    process.exit(1);
+  });
+}

package/cart.asconfig.json

@@ -0,0 +1,12 @@
+{
+  "options": {
+    "runtime": "stub",
+    "memoryBase": 163840,
+    "initialMemory": 4,
+    "use": ["abort=~lib/@raskell/wasm-ad/assembly/index/abort"],
+    "optimizeLevel": 3,
+    "shrinkLevel": 1,
+    "noAssert": true,
+    "exportRuntime": false
+  }
+}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@raskell/wasm-ad",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "AssemblyScript SDK for writing WASM-AD carts",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/raskell-io/wasm-ad.git",
+    "directory": "sdk/assemblyscript"
+  },
+  "type": "module",
+  "main": "assembly/index.ts",
+  "types": "assembly/index.ts",
+  "files": [
+    "assembly",
+    "bin",
+    "asconfig.json",
+    "cart.asconfig.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "asc examples/starter.ts --config asconfig.json -o build/starter.wasm && node ../../tools/wasmad.mjs meta build/starter.wasm title=Starter author=raskell.io \"description=The WASM-AD starter cart, in AssemblyScript\"",
+    "prepack": "mkdir -p bin && cp ../../tools/wasmad.mjs bin/wasmad.mjs && cp ../../LICENSE LICENSE"
+  },
+  "devDependencies": {
+    "assemblyscript": "0.28.20"
+  },
+  "keywords": [
+    "wasm-ad",
+    "assemblyscript",
+    "webassembly",
+    "fantasy-console",
+    "gba"
+  ],
+  "homepage": "https://wasmad.raskell.io",
+  "peerDependencies": {
+    "assemblyscript": ">=0.28.0 <0.29.0"
+  },
+  "bin": {
+    "wasmad": "bin/wasmad.mjs"
+  }
+}