0ec364b | plum | pyrossh

git clone https://git.pyrossh.dev/plum

A statically typed, imperative programming language inspired by rust, python

0ec364b — Peter John 2026-11-02T14:11:51+05:30

docs(plans): game host milestone 1 plan, progress and incidents

Files changed (3) hide show

docs/plans/2026-11-02-game-host.incidents.jsonl +41 -0
docs/plans/2026-11-02-game-host.md +237 -0
docs/plans/2026-11-02-game-host.progress.md +38 -0

docs/plans/2026-11-02-game-host.incidents.jsonl ADDED Viewed

@@ -0,0 +1,41 @@
+{"file": "-", "line": 0, "context": "exit code 1: For more information, try '--help'.", "agent": "run_tests", "kind": "test-failure", "resolution": "open", "time": "13:42:31"}
+{"file": "-", "line": 0, "context": "exit code 1: For more information, try '--help'.", "agent": "run_tests", "kind": "test-failure", "resolution": "open", "time": "13:42:36"}
+{"file": "plum-std/Game.plum", "line": 1, "context": "Key.W impossible: constants need >=2 chars (single capital is generic). Named KeyA..KeyZ", "agent": "T2", "kind": "spec-ambiguity", "resolution": "Key.KeyW etc", "confidence": "high", "time": "13:42:42"}
+{"file": "plum-core/src/union_lower.rs", "line": 0, "context": "T3: change outside Owns blocked by commit_task; nothing committed", "agent": "commit_task", "kind": "exception", "resolution": "open", "time": "13:43:56"}
+{"file": "plum-game/Cargo.lock", "line": 0, "context": "T3: change outside Owns blocked by commit_task; nothing committed", "agent": "commit_task", "kind": "exception", "resolution": "open", "time": "13:43:56"}
+{"file": "", "line": 0, "context": "verified: seam T1↔T7", "agent": "pt_review", "kind": "verified", "time": "13:49:37"}
+{"file": "", "line": 0, "context": "verified: seam T3↔T7", "agent": "pt_review", "kind": "verified", "time": "13:49:37"}
+{"file": "", "line": 0, "context": "verified: seam T1↔T6", "agent": "pt_review", "kind": "verified", "time": "13:51:37"}
+{"file": "", "line": 0, "context": "verified: seam T2↔T6", "agent": "pt_review", "kind": "verified", "time": "13:51:37"}
+{"file": "", "line": 0, "context": "verified: seam T3↔T4", "agent": "pt_review", "kind": "verified", "time": "13:56:10"}
+{"file": "", "line": 0, "context": "verified: seam T1↔T4", "agent": "pt_review", "kind": "verified", "time": "13:56:10"}
+{"file": "", "line": 0, "context": "verified: seam T2↔T4", "agent": "pt_review", "kind": "verified", "time": "13:56:10"}
+{"file": "plum-game/kam/Main.plum", "line": 128, "context": "T6: mini.push result discarded (Array.push returns a new array); minimap OOB trap on first native draw; compiler accepts unused non-Unit results", "agent": "coordinator", "time": "13:57:47"}
+{"file": "", "line": 0, "context": "verified: seam T3↔T4", "agent": "pt_review", "kind": "verified", "time": "13:57:47"}
+{"file": "", "line": 0, "context": "verified: seam T1↔T4", "agent": "pt_review", "kind": "verified", "time": "13:57:47"}
+{"file": "", "line": 0, "context": "verified: seam T2↔T4", "agent": "pt_review", "kind": "verified", "time": "13:57:47"}
+{"file": "plum-cli/tests/game_web_test.rs", "line": 0, "context": "T5: change outside Owns blocked by commit_task; nothing committed", "agent": "commit_task", "kind": "exception", "resolution": "open", "time": "14:02:14"}
+{"file": "plum-game/web/bridge_check.mjs", "line": 0, "context": "T5: change outside Owns blocked by commit_task; nothing committed", "agent": "commit_task", "kind": "exception", "resolution": "open", "time": "14:02:14"}
+{"file": "", "line": 0, "context": "verified: seam T2↔T5", "agent": "pt_review", "kind": "verified", "time": "14:02:19"}
+{"file": "", "line": 0, "context": "verified: seam T4↔T5", "agent": "pt_review", "kind": "verified", "time": "14:02:19"}
+{"file": "", "line": 0, "context": "verified: seam T1↔T7", "agent": "pt_review", "kind": "verified", "time": "14:02:19"}
+{"file": "", "line": 0, "context": "verified: seam T3↔T7", "agent": "pt_review", "kind": "verified", "time": "14:02:20"}
+{"file": "", "line": 0, "context": "verified: seam T1↔T4", "agent": "pt_review", "kind": "verified", "time": "14:04:34"}
+{"file": "", "line": 0, "context": "verified: seam T4↔T5", "agent": "pt_review", "kind": "verified", "time": "14:04:34"}
+{"file": "", "line": 0, "context": "verified: seam T2↔T4", "agent": "pt_review", "kind": "verified", "time": "14:04:34"}
+{"file": "", "line": 0, "context": "verified: seam T3↔T4", "agent": "pt_review", "kind": "verified", "time": "14:04:34"}
+{"file": "", "line": 0, "context": "verified: seam T2↔T5", "agent": "pt_review", "kind": "verified", "time": "14:04:34"}
+{"file": "", "line": 0, "context": "verified: seam T4↔T5", "agent": "pt_review", "kind": "verified", "time": "14:04:34"}
+{"file": "", "line": 0, "context": "verified: seam T2↔T5", "agent": "pt_review", "kind": "verified", "time": "14:08:36"}
+{"file": "", "line": 0, "context": "verified: seam T4↔T5", "agent": "pt_review", "kind": "verified", "time": "14:08:36"}
+{"file": "", "line": 0, "context": "verified: seam T1↔T7", "agent": "pt_review", "kind": "verified", "time": "14:08:36"}
+{"file": "", "line": 0, "context": "verified: seam T3↔T7", "agent": "pt_review", "kind": "verified", "time": "14:08:36"}
+{"file": "-", "line": 0, "context": "tests::readmeSnippetsHaveNoSyntaxDiagnostics: failed", "agent": "run_tests", "kind": "test-failure", "resolution": "open", "time": "14:08:59"}
+{"kind":"rule-rewrite","agent":"coordinator","tool":"Bash","command":"cargo test --workspace readmeSnippets 21 | grep -B2 -A15  panicked  | head -40"}
+{"file": "-", "line": 0, "context": "tests::readmeSnippetsHaveNoSyntaxDiagnostics: failed", "agent": "run_tests", "kind": "test-failure", "resolution": "open", "time": "14:09:15"}
+{"file": "", "line": 0, "context": "verified: seam T1↔T4", "agent": "pt_review", "kind": "verified", "time": "14:10:32"}
+{"file": "", "line": 0, "context": "verified: seam T3↔T4", "agent": "pt_review", "kind": "verified", "time": "14:10:32"}
+{"file": "", "line": 0, "context": "verified: seam T2↔T4", "agent": "pt_review", "kind": "verified", "time": "14:10:32"}
+{"file": "", "line": 0, "context": "verified: seam T4↔T5", "agent": "pt_review", "kind": "verified", "time": "14:10:32"}
+{"file": "", "line": 0, "context": "verified: seam T1↔T7", "agent": "pt_review", "kind": "verified", "time": "14:10:32"}
+{"file": "", "line": 0, "context": "verified: seam T3↔T7", "agent": "pt_review", "kind": "verified", "time": "14:10:32"}

docs/plans/2026-11-02-game-host.md ADDED Viewed

@@ -0,0 +1,237 @@
+# Game host, milestone 1: native + browser host and a KaM map viewer
+**Goal:** a Plum program declares `export fun init/update/draw`, and a macroquad host runs it natively (wasmtime) and in the browser (a miniquad JS plugin), drawing a real Knights and Merchants map with camera pan/zoom and a minimap. This covers tasks H1, H2 and P1 of `2026-10-26-game-engine.md`. P2–P5 (units, pathfinding, economy, combat/AI) are later milestones.
+**Architecture:** the compiler gains `export fun` (same boundary ABI as `extern fun`) and always exports four Str bridge helpers. `plum-std/Game.plum` declares the host API as externs. The standalone crate `plum-game/` (macroquad) decodes KaM assets and implements those externs over a `Backend` trait: wasmtime binds them natively, and on wasm32 a `plum_bridge.js` miniquad plugin binds them through JS. `plum game <file> [--web]` compiles and runs or packages.
+**Tech stack:** Rust workspace (plum-core, plum-checker, plum-wasm-codegen, plum-cli), tree-sitter grammar, Plum std, new standalone crate plum-game (macroquad 0.4, wasmtime 47, flate2), JS.
+**Spec:** docs/plans/2026-11-02-game-host.md
+**Detail:** contracts
+**Target-min:** 25
+## Design (rulings)
+- **`export fun`** (top level only, not a method, not generic) is a normal Plum function that is also exported as a wasm function with the function's name. Its boundary ABI is exactly the `extern fun` ABI: `Int` narrowed to i32, `Float` f64, `Bool` i32, a struct flattened into its fields' values (params and multi-value results), `Str` and records as GC refs. Errors: `export fun can't be a method`, `export fun can't be generic`, `export fun can't return an error union` (same check `extern` has). `export` and `extern` on one fun is a parse error.
+- **Str bridge exports**, always present in every module (JS can't read GC structs): `strLen(s: Str) -> i32`, `strByte(s: Str, i: i32) -> i32` (0..255), `strNew(n: i32) -> Str` (n zero bytes), `strSetByte(s: Str, i: i32, b: i32)` (only used by hosts on a fresh `strNew` result).
+- **Game entry contract:** `export fun init() -> G`, `export fun update(g: G, dt: Float)`, `export fun draw(g: G)` where `G` is any record. The host calls `init` once after the window exists, then `update` then `draw` every frame. Game state lives in `G`; no globals.
+- **Host API (`plum-std/Game.plum`, all `extern fun`)** — the exact contract between Plum and every backend. Coordinates are world units (camera applied) unless noted; `Int` handles are `-1` on failure.
+  - `screenWidth() -> Float`, `screenHeight() -> Float`, `frameTime() -> Float`
+  - `clear(c: Color)`; `drawRect(x: Float, y: Float, w: Float, h: Float, c: Color)`; `drawLine(x1: Float, y1: Float, x2: Float, y2: Float, thickness: Float, c: Color)`; `drawText(s: Str, x: Float, y: Float, size: Float, c: Color)`
+  - `setCamera(x: Float, y: Float, scale: Float)` — world point `(x, y)` maps to the screen's top-left, one world unit is `scale` pixels; `resetCamera()` returns to screen pixels.
+  - `atlasLoad(name: Str) -> Int` — loads `<assets>/sprites/<name>.rxx` (e.g. `"Tileset"`, `"Trees_a"`); `spriteCount(atlas: Int) -> Int`; `spriteW(atlas: Int, idx: Int) -> Int`, `spriteH`, `spritePivotX`, `spritePivotY` (0 for a missing sprite); `spriteColor(atlas: Int, idx: Int) -> Color` (average of opaque pixels, for minimaps)
+  - `drawSprite(atlas: Int, idx: Int, x: Float, y: Float, flipX: Bool, tint: Color)` — top-left at `(x + pivotX, y + pivotY)`, natural size; `drawTile(atlas: Int, idx: Int, x: Float, y: Float, size: Float, quarterTurns: Int, tint: Color)` — stretched to a `size`×`size` square at top-left `(x, y)`, rotated `quarterTurns`×90° clockwise about its centre.
+  - `isKeyDown(k: Int) -> Bool`, `isKeyPressed(k: Int) -> Bool`, `mousePos() -> Vec2` (screen pixels, multi-value), `isMouseDown(b: Int) -> Bool`, `isMousePressed(b: Int) -> Bool`, `mouseWheel() -> Float` (notches this frame, + = up)
+  - `mapLoad(path: Str) -> Int` — a KaM `.map` relative to `<assets>`; `mapWidth(m: Int) -> Int`, `mapHeight(m: Int) -> Int`; `mapTerrain(m: Int, x: Int, y: Int) -> Int` (tileset id; Tileset sprite is id + 1), `mapRotation(m, x, y) -> Int` (0..3), `mapElevation(m, x, y) -> Int`, `mapObject(m, x, y) -> Int` (Trees_a sprite index, 0 = none). Row 0 is the map's first (north) row; no y flip.
+- **Keys** (`primitive Key` constants, GLFW numbering, the host maps them to macroquad `KeyCode`): `Space 32`, `A`..`Z` 65..90, `Num0`..`Num9` 48..57, `Escape 256`, `Enter 257`, `Tab 258`, `Backspace 259`, `Right 262`, `Left 263`, `Down 264`, `Up 265`, `LeftShift 340`, `LeftControl 341`. **Mouse** (`primitive Mouse`): `Left 0`, `Right 1`, `Middle 2`.
+- **Std value types:** `plum-std/Vec2.plum`: `struct Vec2(x: Float, y: Float)` with `add`, `sub`, `mul(s: Float)`, `neg`, `eq`, `length`, `distance`, `Vec2.Zero`. `plum-std/Color.plum`: `struct Color(r: Float, g: Float, b: Float, a: Float)` (0..1) with consts `White`, `Black`, `Red`, `Green`, `Blue`, `Yellow`, `Transparent` and `Color.rgb(r, g, b)`, `withAlpha(a)`. Game.plum imports both; they're separate so pure logic can import them without pulling in externs.
+- **`plum test` and `plum run` stub unknown `plum` imports** with a function that traps `host function 'X' is not available here`, so a game file's `test` blocks run as long as they don't call the host.
+- **Assets** are never copied into the repo. The host's asset root is `--assets <dir>` (default `$PLUM_GAME_ASSETS`, else `../kam_macroquad/assets` beside the repo). plum-game vendors a minimal decoder: `.rxx` (from kam_macroquad `src/rxx.rs`, with a source note) and `.map` (from `src/rules/map_file.rs` `parse_map`). Tests that need real assets skip with a printed note when the directory is missing.
+- **Audio** is deferred to P2 (KaM sfx decoding); no audio externs in this milestone.
+- **Web:** the macroquad host compiles to `wasm32-unknown-unknown`. Before the first frame it fetches every file listed in `preload.txt` (sprites and maps) with macroquad's `load_file`, and polls `plum_bridge_ready()` until the plugin has instantiated `plum.wasm`; then it calls `plum_bridge_init/update/draw`, which call the Plum exports. Plum's externs call back into `pg_*` exports of the host wasm (re-entrant calls are fine: no borrow is held across them). Str crosses through `strLen/strByte` (Plum → host, bytes copied into host memory from `pg_alloc(n)`) and `strNew/strSetByte` (host → Plum).
+- **`plum game <file>`** compiles, then runs the native host (`cargo run --release --manifest-path <repo>/plum-game/Cargo.toml -- <wasm> --assets <dir>`). **`plum game --web <file> [-o dist] [--preload path]...`** writes `index.html`, `mq_js_bundle.js`, `plum_bridge.js`, `plum-game.wasm`, `plum.wasm`, `preload.txt` and an `assets/` copy of the preloaded files (the six `sprites/*.rxx` are always preloaded) into `dist` (default `<file dir>/dist`, gitignored).
+- **P1 viewer** (`plum-game/kam/Main.plum`): loads `Maps/A new Beginning/A new Beginning.map` into `Grid[Int]`s once at `init`; draws only visible tiles with `drawTile` (Tileset, id + 1, rotation) and map objects with `drawSprite` (Trees_a) at 32 world units per tile; camera pans with arrows/WASD (speed independent of zoom on screen), zooms with the wheel about the mouse (scale clamped 0.25..4), and is clamped to the map; a minimap (one rect per tile, colours from `spriteColor`, computed once) in the bottom-right corner, with the view rectangle outlined; clicking it centres the camera; FPS in the top-left. No elevation relief in this milestone.
+## Global constraints
+- Regenerate tree-sitter only with `cd plum-tooling/tree-sitter-plum && npx --yes tree-sitter-cli generate --disable-optimizations`, then `npx --yes tree-sitter-cli test`.
+- `touch` an edited `.rs` file before trusting a build. Plum tests: `cargo build --quiet && ./target/debug/plum test <file-or-dir>`.
+- Never run `plum format` on repo files.
+- `plum-game/` is its own cargo workspace (`[workspace]` in its Cargo.toml, like `plum-runtime/`), never a member of the root workspace. It may path-depend on `../plum-core` and `../plum-wasm-codegen` as dev-dependencies to compile Plum fixtures in tests.
+- wasmtime is `cfg(not(target_arch = "wasm32"))` only. `cargo build --target wasm32-unknown-unknown` in `plum-game/` must succeed.
+- Never copy files from `../kam_macroquad/assets` into this repo. `dist/` and `plum-game/target/` are gitignored.
+- Comments and docs describe the final behaviour only, no history.
+```mermaid
+flowchart LR
+  P["Main.plum (export init/update/draw)"] -->|"externs (Game.plum)"| B["Backend trait"]
+  B --> N["native: wasmtime linker + macroquad"]
+  B --> W["web: plum_bridge.js -> pg_* exports"]
+  N & W --> A["assets.rs: .rxx + .map"]
+```
+## File structure
+- `plum-tooling/tree-sitter-plum/*`, `plum-core/src/{ast,parser}.rs`, `plum-checker/src/lib.rs`, `plum-wasm-codegen/src/lib.rs`, `plum-lsp/src/completion.rs`: `export fun`, Str bridge.
+- `plum-std/{Vec2,Color,Game}.plum`, `plum-cli/src/main.rs` (import stubs): the Plum side of the API.
+- `plum-game/`: `Cargo.toml`, `src/lib.rs`, `src/assets.rs`, `src/api.rs`, `src/recorder.rs`, `src/native.rs`, `src/mq.rs`, `src/main.rs`, `src/web.rs`, `web/{plum_bridge.js,index.html}`, `tests/`, `kam/Main.plum`.
+- `plum-cli/src/game.rs`: `plum game`.
+## Task graph
+```mermaid
+flowchart LR
+  T1[export fun + Str bridge]
+  T2[std Game API + import stubs]
+  T3[plum-game assets]
+  T4[native host]
+  T5[web bridge + plum game + docs]
+  T6[KaM map viewer]
+  T7[incidental files]
+  %% taskgraph
+  T1 --> T4
+  T2 --> T4
+  T3 --> T4
+  T4 --> T5
+  T2 --> T5
+  T1 --> T6
+  T2 --> T6
+  T1 --> T7
+  T3 --> T7
+```
+```mermaid
+%% schedule
+gantt
+  title Predicted schedule (mm:ss)
+  dateFormat X
+  axisFormat %M:%S
+  section lane 1
+  T1 export fun + Str bridge :t1, 0, 208s
+  T4 native host  Backend  wasmtime bindin :t4, 208, 283s
+  T5 web bridge + `plum game` + README :t5, 492, 246s
+  section lane 2
+  T2 std Game API + import stubs :t2, 0, 142s
+  T6 KaM map viewer (P1) :t6, 208, 150s
+  section lane 3
+  T3 plum-game crate + KaM asset decoders :t3, 0, 128s
+```
+critical path: T1 → T4 → T5 (12.3 min) · peak width 3 · predicted build 12.3 min · predicted total ≈ 15.8 min (target ✓)
+## Predicted schedule
+## Package: compiler
+**Probe entry:** run=cargo test -p plum-wasm-codegen
+### T1 export fun + Str bridge · Complexity 6 (O-1) · Est. context 60k
+**Owns:** plum-tooling/tree-sitter-plum/grammar.js, plum-tooling/tree-sitter-plum/src/parser.c, plum-tooling/tree-sitter-plum/src/grammar.json, plum-tooling/tree-sitter-plum/src/node-types.json, plum-tooling/tree-sitter-plum/test/corpus/export.txt, plum-tooling/tree-sitter-plum/queries/plum/highlights.scm, plum-tooling/vscode-plum/syntaxes/plum.tmLanguage.json, plum-core/src/ast.rs, plum-core/src/parser.rs, plum-core/tests/parser_test.rs, plum-checker/src/lib.rs, plum-checker/tests/checker_tests.rs, plum-wasm-codegen/src/lib.rs, plum-wasm-codegen/tests/codegen_tests.rs, plum-lsp/src/completion.rs
+**Components:** 3
+**LOC owned:** 260
+**Tests:** slow
+**Kind:** design
+**Model:** sonnet
+**Est. time:** 6 min
+**Consumes:** none
+**Produces:** wasm exports of a compiled module
+  e.g. `struct V(x: Float, y: Float)\nexport fun step(n: Int, v: V) -> V =\n  V(x: v.x + 1.0, y: v.y * 2.0)\n` -> export `step` with type `(func (param i32 f64 f64) (result f64 f64))`; calling it with (3, 1.0, 2.0) returns (2.0, 4.0)
+  e.g. `record G(n: Int)\nexport fun init() -> G =\n  G(n: 1)\nexport fun bump(g: G) =\n  g.n = g.n + 1\n` -> exports `init` (result is a GC ref) and `bump`; host calls init, bump twice on the same ref, reads nothing back but no trap
+  e.g. any module -> exports `strLen`, `strByte`, `strNew`, `strSetByte`; `strNew(3)` then `strSetByte` 104,105,33 then passing it to a Plum `export fun echo(s: Str) -> Str = s` and reading back with `strLen`/`strByte` gives "hi!"
+**Review Focus:** `export_abi_matches_extern`: Int param is i32 and is sign-extended to i64 inside; Int result narrowed with wrap; Bool param/result i32; `export_struct_flattened`: nested struct (struct with a struct field) flattens depth-first; `export_errors`: method / generic / error-union return / `extern export` each give their error; `export_still_callable`: Plum code calling an `export fun` directly works and uses the normal internal ABI (an i32 wrapper may be emitted separately); `str_bridge_on_view`: `strByte` on a substring view (`"hello".sub(1,3)`) indexes from `start`; `main_unchanged`: modules with `main` still export it as before.
+**Test code:** parser_test.rs `exportFunParses`; checker_tests.rs one test per error; codegen_tests.rs `exportFlattensStructsAndNarrowsInt`, `exportRecordRefRoundTrip`, `strBridgeRoundTrip`, `strBridgeOnView` (wasmtime calls, the e.g. lines); corpus `export.txt`.
+**Steps:** 1 failing tests, 2 grammar: optional `exportKw` beside `externKw` (mutually exclusive), regenerate, corpus, highlights `"export" @keyword`, tmLanguage keyword, 3 ast `is_export: bool`, parser sets it, 4 checker errors, 5 codegen: for each export fun emit a boundary wrapper with the extern ABI that converts and calls the real function, export it under the fun's name; emit and export the four Str helpers, 6 lsp keyword completion `export`, 7 `cargo test --workspace` and `./target/debug/plum test plum-std plum-examples` green.
+**Notes:** reuse the existing extern lowering (flattening, i32 narrowing) for the wrapper rather than writing a second one. Don't touch README (T5 documents `export`).
+## Package: std
+**Probe entry:** run=./target/debug/plum test plum-std
+### T2 std Game API + import stubs · Complexity 4 (O-1) · Est. context 40k
+**Owns:** plum-std/Vec2.plum, plum-std/Color.plum, plum-std/Game.plum, plum-cli/src/main.rs, plum-cli/tests/host_stub_test.rs
+**Components:** 2
+**LOC owned:** 220
+**Tests:** fast
+**Kind:** design
+**Model:** sonnet
+**Est. time:** 4 min
+**Consumes:** none
+**Produces:** std/Game, std/Vec2, std/Color modules
+  e.g. `import std/Vec2\n... Vec2(x: 1.0, y: 2.0) + Vec2(x: 3.0, y: 4.0) * 2.0` == `Vec2(x: 7.0, y: 10.0)`
+  e.g. `Color.rgb(1.0, 0.5, 0.0)` == `Color(r: 1.0, g: 0.5, b: 0.0, a: 1.0)`; `Key.W == 87`, `Key.Left == 263`, `Mouse.Right == 1`
+  e.g. a file importing std/Game whose test block doesn't call any extern passes under `plum test`; one that calls `screenWidth()` fails that test with `host function 'screenWidth' is not available here`
+**Review Focus:** `extern_list_exact`: every extern in the Design's Host API list, exact names, parameter order and types; `stub_only_plum_module`: real host functions (printLn, crash, clock, files) keep working; the stub covers only names the host doesn't define; `stub_traps_not_panics`: the stub returns a wasm trap that the test runner reports as that test's failure; `vec2_ops`: operators work through `add`/`sub`/`mul`/`neg`/`eq`.
+**Test code:** `test` blocks in Vec2.plum and Color.plum (the e.g. lines); host_stub_test.rs runs `plum test` on a scratch file importing std/Game: one passing test, one calling `screenWidth()` that fails with the message.
+**Steps:** 1 write Vec2.plum, Color.plum with tests, 2 Game.plum: externs exactly per the Design, `primitive Key` and `primitive Mouse` constants, 3 plum-cli hostImports: for each module import with no host definition, a func of its type that traps with the message, 4 host_stub_test, 5 `./target/debug/plum test plum-std plum-examples` and `cargo test -p plum-cli` green.
+**Notes:** keep Game.plum to declarations and constants; no logic. Don't touch plum-cli's command list (T5 adds `plum game` in `plum-cli/src/game.rs`).
+## Package: host
+**Probe entry:** run=cargo test --manifest-path plum-game/Cargo.toml
+### T3 plum-game crate + KaM asset decoders · Complexity 4 (O-1) · Est. context 45k
+**Owns:** plum-game/Cargo.toml, plum-game/src/lib.rs, plum-game/src/assets.rs, plum-game/tests/assets_test.rs, plum-game/.gitignore
+**Components:** 1
+**LOC owned:** 300
+**Tests:** fast
+**Kind:** design
+**Model:** sonnet
+**Est. time:** 4 min
+**Consumes:** none
+**Produces:** assets::Atlas::parse(bytes: &[u8]) -> io::Result<Atlas>; Atlas { sprites: Vec<Option<Sprite>> } with Sprite { w: u16, h: u16, px: i32, py: i32, rgba: Vec<u8> } and avg_color(idx) -> [f32; 4]; assets::MapData::parse(bytes: &[u8]) -> Result<MapData, String> with MapData { w: i32, h: i32, terrain: Vec<u16>, rotation: Vec<u8>, elevation: Vec<u8>, object: Vec<u16> } indexed y * w + x; assets::AssetRoot::resolve(cli: Option<&Path>) -> PathBuf
+  e.g. `Atlas::parse(read("sprites/Tileset.rxx"))` -> sprite 1 is 32×32
+  e.g. `MapData::parse(read("Maps/A new Beginning/A new Beginning.map"))` -> w, h both in 32..=256 and terrain.len() == w*h; every terrain id < 512
+**Review Focus:** `rxx_header_variants`: RXX1, RXX2 and plain-zlib inputs; `map_object_mapping`: map object ids converted to Trees_a sprite indices the way kam_macroquad's `kamdat::map_object_sprite` does (0 = none), including its mapelem.dat lookup if needed (read from `<assets>/data/defines/mapelem.dat`); `bounds`: truncated input returns an error, never panics; `no_macroquad_in_assets`: assets.rs is plain Rust (macroquad-free) so it tests fast.
+**Test code:** assets_test.rs: `tilesetSprite1Is32`, `mapParsesANewBeginning`, `truncatedRxxIsError`, `truncatedMapIsError`; real-asset tests skip with a printed note when the asset root is missing.
+**Steps:** 1 Cargo.toml (own `[workspace]`; deps macroquad 0.4 default-features=false, flate2; wasmtime 47 under `cfg(not(target_arch = "wasm32"))`; dev-deps plum-core, plum-wasm-codegen by path) and .gitignore (`target/`, `dist/`), 2 failing tests, 3 assets.rs from kam_macroquad's rxx.rs and map_file.rs parse_map (with a one-line source note each), 4 lib.rs `pub mod assets;`, 5 `cargo test --manifest-path plum-game/Cargo.toml` green.
+**Notes:** read `../kam_macroquad/src/rxx.rs`, `src/rules/map_file.rs` and `src/kamdat.rs` (map_object_sprite) for the formats; copy only what's needed.
+### T4 native host: Backend, wasmtime binding, macroquad, recorder · Complexity 7 (O-1) · Est. context 70k
+**Owns:** plum-game/src/lib.rs, plum-game/src/api.rs, plum-game/src/recorder.rs, plum-game/src/native.rs, plum-game/src/mq.rs, plum-game/src/main.rs, plum-game/tests/host_test.rs, plum-game/tests/fixtures/host_fixture.plum
+**Components:** 4
+**LOC owned:** 650
+**Tests:** slow
+**Kind:** design
+**Model:** sonnet
+**Est. time:** 8 min
+**Consumes:** T1 export ABI; T2 Game.plum externs; T3 assets
+**Produces:** api::Backend trait (one method per Host API extern, Rust types: f32 for Float, i32 for Int, bool, String for Str, [f32;4] Color, (f32,f32) Vec2); native::PlumGame::load(wasm: &[u8], backend: B) -> Result<PlumGame<B>>, .init(), .update(dt: f32), .draw(); recorder::Recorder (records calls as strings, scripted input); binary `plum-game <module.wasm> [--assets DIR]`
+  e.g. fixture `export fun draw(g: G) = clear(Color.Black); drawRect(1.0, 2.0, 3.0, 4.0, Color.Red); p := mousePos(); drawText("hi", p.x, p.y, 16.0, Color.White)` with Recorder mouse (5, 6) -> calls `["clear(0,0,0,1)", "drawRect(1,2,3,4,1,0,0,1)", "mousePos()", "drawText(\"hi\",5,6,16,1,1,1,1)"]`
+**Review Focus:** `color_flattened`: Color arrives as four f64 and becomes [f32;4]; `mousePos_multi_value`: host returns two f64 results; `str_args`: drawText/atlasLoad/mapLoad read the Plum Str through the GC struct (reuse plum-cli's Str reading approach); `state_ref_held`: the `init` result is kept rooted across frames (wasmtime `ManuallyRooted`/`OwnedRooted`) and passed to every update/draw; `missing_export`: a module without `init`/`update`/`draw` errors with which one is missing; `int_handles`: atlas/map handles are indices into host Vecs, -1 on failure; `draw_tile_rotation`: quarterTurns rotate about the centre; `key_mapping`: the Design's key numbers map to the right macroquad KeyCode.
+**Test code:** host_test.rs compiles `tests/fixtures/host_fixture.plum` with plum-core + plum-wasm-codegen (lib path = repo root) and drives it with Recorder: `callOrderAndArgs`, `colorFlattened`, `mousePosMultiValue`, `stateSurvivesFrames` (update increments a counter 3 times, draw reports it via drawText), `missingExportErrors`, `atlasAndMapThroughHost` (skips without assets).
+**Steps:** 1 failing tests, 2 api.rs Backend, 3 recorder.rs, 4 native.rs: wasmtime engine (gc, function references, multi-value), linker binding every extern to Backend, plus `printLn`/`crash`, PlumGame, 5 mq.rs: macroquad Backend (textures per sprite uploaded lazily on first draw, Camera2D from setCamera, KeyCode mapping, wheel), 6 main.rs: `#[macroquad::main]` loop calling init once then update/draw, native only, 7 lib.rs modules, 8 `cargo test --manifest-path plum-game/Cargo.toml` green and `cargo build --manifest-path plum-game/Cargo.toml --release` succeeds.
+**Notes:** macroquad's main loop is async; wasmtime calls are sync, fine inside it. Keep native.rs and mq.rs behind `cfg(not(target_arch = "wasm32"))`; api.rs and recorder.rs build on every target.
+### T5 web bridge + `plum game` + README · Complexity 7 (O-1) · Est. context 65k
+**Owns:** plum-game/src/web.rs, plum-game/src/lib.rs, plum-game/src/main.rs, plum-game/web/plum_bridge.js, plum-game/web/index.html, plum-cli/src/game.rs, plum-cli/src/main.rs, plum-cli/Cargo.toml, README.md, .gitignore
+**Components:** 3
+**LOC owned:** 550
+**Tests:** slow
+**Kind:** design
+**Model:** sonnet
+**Est. time:** 8 min
+**Consumes:** T4 Backend + mq backend; T2 Game.plum
+**Produces:** `plum game <file> [--assets DIR]` and `plum game --web <file> [-o DIR] [--preload PATH]... [--assets DIR]`
+  e.g. `plum game --web plum-game/tests/fixtures/host_fixture.plum -o $SCRATCH/dist` -> the dir holds index.html, mq_js_bundle.js, plum_bridge.js, plum-game.wasm, plum.wasm, preload.txt listing the six `sprites/*.rxx`
+**Review Focus:** `reentrancy`: Rust → JS → Plum → JS → Rust `pg_*` calls hold no RefCell borrow or `&mut` context across the JS call; `str_marshalling`: Plum Str → host memory via `pg_alloc` + strLen/strByte, host → Plum via strNew/strSetByte; `ready_poll`: nothing calls Plum before `plum_bridge_ready()`; `preload`: every listed file is fetched before init and served from memory to atlasLoad/mapLoad; `wasm32_build`: `cargo build --target wasm32-unknown-unknown --release` in plum-game passes; `cli_paths`: `plum game` finds plum-game via the plum-cli crate's compile-time repo path; `bridge_imports_complete`: plum_bridge.js defines every Game.plum extern plus printLn/crash.
+**Test code:** a plum-cli integration test `game_web_test.rs` (may live in plum-cli/tests/) checking the dist file list for the e.g.; a node script `plum-game/web/bridge_check.mjs` that loads `plum.wasm` with stub `pg_*` functions and asserts every module import is satisfied (run with `node`).
+**Steps:** 1 web.rs: `pg_*` exports per Backend method + `pg_alloc`, imports `plum_bridge_ready/init/update/draw`, preload via `load_file`, 2 main.rs: wasm32 loop variant, 3 plum_bridge.js miniquad plugin + index.html (based on kam_macroquad/web/index.html), 4 plum-cli game.rs + wiring in main.rs (command only), 5 README: `export fun` section (next to `extern`) and a "Games" section (`plum game`, `--web`, the entry contract, the Host API table, assets path), 6 root .gitignore `dist/`, 7 tests green; `./target/debug/plum game --web` on the fixture produces the dist.
+**Notes:** copy `mq_js_bundle.js` from the macroquad crate in cargo's registry (find it via `cargo metadata` like kam_macroquad/web/build.sh). Don't edit plum-cli's hostImports (T2's).
+## Package: viewer
+**Probe entry:** run=./target/debug/plum test plum-game/kam
+### T6 KaM map viewer (P1) · Complexity 5 (O-1) · Est. context 50k
+**Owns:** plum-game/kam/Main.plum
+**Components:** 2
+**LOC owned:** 280
+**Tests:** fast
+**Kind:** design
+**Model:** sonnet
+**Est. time:** 5 min
+**Consumes:** T1 export fun; T2 Game.plum, Vec2, Color
+**Produces:** `export fun init() -> Viewer`, `export fun update(v: Viewer, dt: Float)`, `export fun draw(v: Viewer)`; pure helpers `Camera` record with `screenToWorld(p: Vec2) -> Vec2`, `worldToScreen(p: Vec2) -> Vec2`, `clampTo(w: Float, h: Float, sw: Float, sh: Float)`, `zoomAt(screen: Vec2, factor: Float)`, `visibleTiles(sw, sh) -> TileRange`
+  e.g. Camera(x: 100.0, y: 50.0, scale: 2.0).screenToWorld(Vec2(x: 20.0, y: 10.0)) == Vec2(x: 110.0, y: 55.0) and worldToScreen inverts it
+  e.g. zoomAt keeps the world point under the mouse fixed; scale stays in 0.25..4
+  e.g. visibleTiles for a 64×64 map at x=0,y=0,scale 1 on an 800×600 screen covers columns 0..25 and rows 0..18 (inclusive of the partial tile), clamped to the map
+**Review Focus:** `only_visible_drawn`: draw loops over visibleTiles, not the whole map; `minimap_cached`: minimap colours computed once in init; `pan_speed_screen_space`: pan per second is constant on screen across zoom; `clamp`: the view never shows outside the map unless the map is smaller than the screen (then centred); `tests_dont_call_host`: test blocks use only pure helpers.
+**Test code:** `test` blocks in Main.plum for the three e.g. lines, clamp, and minimap click → camera centre.
+**Steps:** 1 failing tests, 2 Camera + TileRange + helpers, 3 init (atlasLoad Tileset/Trees_a, mapLoad, copy into Grid[Int]s, minimap colours), update (keys, wheel, minimap click), draw (setCamera, tiles, objects, resetCamera, minimap, FPS), 4 `./target/debug/plum test plum-game/kam` green and `./target/debug/plum compile plum-game/kam/Main.plum` succeeds.
+**Notes:** 32 world units per tile. A missing atlas/map (-1) draws a "assets not found" message instead of crashing.
+## Package: incidental
+**Probe entry:** run=cargo test --workspace
+### T7 incidental files · Complexity 1 (O-1) · Est. context 5k
+**Owns:** plum-game/Cargo.lock, plum-core/src/union_lower.rs, plum-cli/tests/game_web_test.rs, plum-game/web/bridge_check.mjs, plum-game/web/screenshot.mjs, plum-lsp/src/main.rs
+**Components:** 1
+**LOC owned:** 10
+**Tests:** fast
+**Kind:** mechanical
+**Model:** haiku
+**Est. time:** 1 min
+**Consumes:** none
+**Produces:** none
+**Review Focus:** `lockfile`: plum-game/Cargo.lock is committed (binary crate); `union_lower`: T1's edit to union_lower.rs is the `is_export` field threading only.
+**Test code:** none.
+**Steps:** 1 coordinator commits these files once T1 and T3 are in.
+**Notes:** bookkeeping for files T1 and T3 touch outside their Owns.
+## Review Focus
+- compiler (T1): encoding, seam. Risks: export wrapper ABI drift from extern's; Str helpers on views. Cases in T1.
+- std (T2): contract. Risks: extern list drifting from the Design; stub masking real host fns.
+- host (T3, T4, T5): seam, state, protocol. Risks: GC ref rooting across frames; JS re-entrancy; Str marshalling; wasm32 build breaking on wasmtime deps.
+- viewer (T6): logic. Risks: off-by-one in visible range; zoom anchor math.
+## Self-review
+Design → tasks: export fun + Str bridge → T1; Host API, Key/Mouse, Vec2/Color, import stubs → T2; assets → T3; Backend/native/recorder/macroquad → T4; web, `plum game`, README → T5; P1 viewer → T6. Shared files: plum-game/src/lib.rs (T3 → T4 → T5, sequential edges), plum-game/src/main.rs (T4 → T5), plum-cli/src/main.rs (T2 → T5, T5 only adds the command wiring). Audio deferred (Design ruling). Playwright isn't installed: the browser check is the coordinator's manual Chrome run, plus T5's node import check.

docs/plans/2026-11-02-game-host.progress.md ADDED Viewed

@@ -0,0 +1,38 @@
+- start eb0d1281d0f034394e5f8c60796c2b253c7a947a
+Ruling: AI orchestrator - user said "go ahead with the game plan" - user wanted to approve first
+Ruling: this run = milestone 1 (H1 host, H2 browser, P1 map viewer); P2-P5 later - each later task needs this host layer working - user expected full port
+Ruling: export fun keyword instead of hardcoded init/update/draw exports - user rejects hardcoded special cases - one more keyword
+Ruling: plum-game vendors minimal rxx/map decoders rather than path-depending on kam_macroquad (a bin crate with crate:: paths) - decoders are small - drift from KaM format fixes
+Ruling: audio deferred to P2 - needs KaM sfx decoding - milestone without sound
+Ruling: no Playwright (not installed); browser check done manually in Chrome + node import check - avoids a download - weaker automated coverage
+- unblocked: dispatched T0 T1 T2 T3 at 13:40:07; waiting on fixes: none
+- tests fast passed=0 failed=1 skipped=0 seconds=0.0
+- tests full passed=1 failed=0 skipped=0 seconds=62.4
+- tests fast passed=0 failed=1 skipped=0 seconds=0.1
+Ruling: no T0 commit; plum-game Cargo.toml/lib.rs belong to T3, test-cmd.json widened to workspace + plum test + plum-game - T0 had no stubs to write - none
+- commit T3 010dcc3b9a plum-game crate + KaM asset decoders
+Ruling: plan over the 15000-char cap left as is - every Design ruling is a cross-task contract; trimming risks drift - larger prime per agent
+Ruling: letter keys are Key.KeyA..Key.KeyZ (single-capital consts parse as generics) - avoids a grammar change mid-run - one naming wart in Game.plum
+- commit T2 1e951682d8 std Game API + import stubs
+- commit T1 7cf0f18a66 export fun + Str bridge
+- commit T7 8dc69a552c incidental files
+- unblocked: dispatched T4 T6 at 13:50:10; waiting on fixes: none
+Ruling: T6 sent to the T2 agent without a relevance poll - it wrote Game.plum, the clear best fit - none
+- commit T6 f689ac73a7 KaM map viewer (P1)
+- commit T4 43b65ab9b2 native host: Backend, wasmtime binding, macroquad, recorder
+- unblocked: dispatched T5 at 13:56:40; waiting on fixes: none
+- commit T4 b8586116a7 native host: Backend, wasmtime binding, macroquad, recorder
+Ruling: mapLoad/atlasLoad path '..' escape left open - Plum programs are trusted local code reading local assets - a hostile .wasm could read files under the user's account
+- commit T5 8ffa113b8b web bridge + `plum game` + README
+- commit T7 5617070cbb incidental files
+- commit T4 f77dbeaa4b native host: Backend, wasmtime binding, macroquad, recorder
+- commit T5 79646b4c71 web bridge + `plum game` + README
+- commit T5 63a5080979 web bridge + `plum game` + README
+- commit T7 908c08de12 incidental files
+- tests full passed=222 failed=1 skipped=0 seconds=16.3
+- tests full passed=222 failed=1 skipped=0 seconds=12.3
+Ruling: checker warning/error for discarded non-Unit results deferred to the user - it's a language-design change (affects every chained/builder call) - another silent-discard bug could slip in meanwhile
+Ruling: final-review finding "run_tests bad args" is stale - those were agents' malformed sl invocations; the full suite ran after and surfaced one real failure (readme snippet test), fixed - none
+- commit T4 1163e3e7e8 native host: Backend, wasmtime binding, macroquad, recorder
+- commit T7 f82e1e2e52 incidental files
+- tests full passed=1129 failed=0 skipped=0 seconds=67.3