machine-readable surfaces
# puck
Apps that travel between tiny computers: portable app bundles (a descriptor
plus recorded input traces, independent of any one implementation) ported
onto self-contained device packs (real firmware, a device.json an emulator
reads at runtime), verified by a shared emulator and differential harness:
pixel-exact frame diffs for a faithful port, stated behavioral invariants
for an adaptation.
This site (puck.sylve.org) is the gallery: every proven combination runs
live in the browser, compiled to WebAssembly, and the reference RP2350
firmware also flashes onto real hardware over WebUSB. The front page is one
card per app; /matrix/ is every app against every device it knows about,
one cell each, computed rather than claimed.
A browser is one of the target devices, not only the thing the others are
shown in. The "web" pack (Web-Touch) is a device pack like any other: it
declares the same 368x448 panel, the same two buttons and a tilt sensor,
it vendors the RP2350 pack's app contract, and its ports are verified by
the same harness. /web/chrono/, /web/fluidbox/ and /web/tinydraw/ are not
previews of those apps: they are those apps, full-viewport, installable to
a phone's home screen, and offline once installed.
## Machine-readable surfaces on this domain
- /matrix/: every app against every device, one cell each, with the mark and the reason behind each one.
- /registry.json: local paths and external URLs for every device pack and app bundle this repo knows about.
- /docs/convention/device-pack.md: what a device pack must contain.
- /docs/convention/app-bundle.md: what an app bundle (descriptor + traces) must contain, including how an affordance carries its intent.
- /apps/<name>/descriptor.md: the portable descriptor for each proven app (chrono, fluidbox, tinydraw, gameos).
- /web/<name>/: the app itself, running on the browser as its target device (chrono, fluidbox, tinydraw).
- https://github.com/s0lness/puck: the repository itself, MIT licensed.
## Consuming a pack or app as an agent
1. git clone https://github.com/s0lness/puck
2. Read docs/convention/device-pack.md and docs/convention/app-bundle.md.
3. Pick a target device pack from registry.json; read its own AGENTS.md and device.json.
4. Pick an app from registry.json; read its descriptor.md and bundle.json (its "ports" array: pack, mode, verification).
5. Give a verdict against the target pack's device.json before writing any code: go, degraded, or refuse, stated plainly.
6. Build: bun install, then bun run <pack>/wasm/build.ts (writes wasm/dist/emu.wasm), then bun run dev for http://127.0.0.1:5340.
7. Verify: bun run verify-bundle <bundle> rebuilds every declared port and replays its traces end to end; bun run harness:selftest proves the differential harness with no hardware; bun run harness/diff.ts <trace.json> --link <yourBoardLink.ts> replays a trace against real hardware and diffs the resulting frames.
## Further reading
- docs/harness.md: how the differential harness proves a port.
- docs/abi.md: the ABI every firmware implements.
- AGENTS.md: conventions and gotchas, repo root.