9d0ff39 | plum | pyrossh

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

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

9d0ff39 — Peter John 2026-11-03T21:55:51+05:30

Move the pure and functional scene styles into their own folders

Files changed (16) hide show

README.md +7 -7
docs/plans/2026-11-03-state-view-parity.review.md +5 -10
docs/plans/2026-11-03-supercompiler.review.md +1 -1
plum-cli/src/game.rs +31 -4
plum-examples/{game_state_view.plum → games/functional/game_state_view.plum} +2 -2
plum-examples/{game_pure_scene.plum → games/pure/game_pure_scene.plum} +5 -5
plum-game/tests/host_test.rs +2 -2
plum-game/web-test/fixtures/stress_pure_scene.plum +5 -5
plum-game/web-test/fixtures/stress_state_view.plum +1 -1
plum-game/web-test/fixtures/stress_state_view_deep.plum +1 -1
plum-game/web-test/tests/web_check.rs +1 -1
plum-std/game/{Picture.plum → functional/Picture.plum} +0 -0
plum-std/game/{Actions.plum → pure/Actions.plum} +0 -0
plum-std/game/{PureScene.plum → pure/PureScene.plum} +2 -2
plum-std/game/{SceneInput.plum → pure/SceneInput.plum} +3 -3
plum-std/game/{SceneTree.plum → pure/SceneTree.plum} +2 -2

README.md CHANGED Viewed

@@ -1377,13 +1377,13 @@ The page calls `init` once after the assets are loaded, then `update` and `draw`
 ### Pure scene graph
-The pure scene graph is the same kind of tree as `std/game/Scene`, but a function never changes a value it was only given: updates take an owned actor (`own self`, `own` parameters, see [Own records](#own-records)), change it in place and hand it back, so no `clone()` is needed. `Actor` is an `own trait` and `Group`, `Sprite`, `Label`, `Button` and `Stage` are `own record`s. The graph is split into four modules: `std/game/Actions` (timed actions such as `forever(rotateBy(...))`), `std/game/PureScene` (the `Actor` trait and its leaves, `group`, `sprite`, `button`, and the draw walk), `std/game/SceneTree` (update, hit testing, paths and event routing) and `std/game/SceneInput` (`Stage`, pointer capture and `UiEvent`). A game imports them by name:
+The pure scene graph is the same kind of tree as `std/game/Scene`, but a function never changes a value it was only given: updates take an owned actor (`own self`, `own` parameters, see [Own records](#own-records)), change it in place and hand it back, so no `clone()` is needed. `Actor` is an `own trait` and `Group`, `Sprite`, `Label`, `Button` and `Stage` are `own record`s. The graph is split into four modules: `std/game/pure/Actions` (timed actions such as `forever(rotateBy(...))`), `std/game/pure/PureScene` (the `Actor` trait and its leaves, `group`, `sprite`, `button`, and the draw walk), `std/game/pure/SceneTree` (update, hit testing, paths and event routing) and `std/game/pure/SceneInput` (`Stage`, pointer capture and `UiEvent`). A game imports them by name:
 ```
-import std/game/Actions
+import std/game/pure/Actions
-import std/game/PureScene
+import std/game/pure/PureScene
-import std/game/SceneTree
+import std/game/pure/SceneTree
-import std/game/SceneInput
+import std/game/pure/SceneInput
 ```
 A minimal game holds a `Stage` and replaces it each frame:
@@ -1411,8 +1411,8 @@ export fun draw(w: World) =
 - **Immediate mode** ([`game.plum`](plum-examples/game.plum)): one state record and a `draw` that issues the calls every frame. Use it for flat arcade games with a few kinds of thing.
 - **Scene** ([`game_scene.plum`](plum-examples/game_scene.plum)): a retained tree of mutable actors. Use it when you want objects that change in place and a familiar `act`/`draw` object model.
-- **Pure scene** ([`game_pure_scene.plum`](plum-examples/game_pure_scene.plum)): every update takes an owned value and hands it back, pointer clicks arrive as `UiEvent`s, and the rules can be tested without a host. Use it when you want pure updates and tests that run without a game host.
-- **State/view** ([`game_state_view.plum`](plum-examples/game_state_view.plum)): the game state is plain data and a `view` turns it into `std/game/Picture`, a recursive picture type drawn by recursive functions. Use it when you want to draw from state instead of keeping a tree of actors.
+- **Pure scene** ([`game_pure_scene.plum`](plum-examples/games/pure/game_pure_scene.plum)): every update takes an owned value and hands it back, pointer clicks arrive as `UiEvent`s, and the rules can be tested without a host. Use it when you want pure updates and tests that run without a game host.
+- **State/view** ([`game_state_view.plum`](plum-examples/games/functional/game_state_view.plum)): the game state is plain data and a `view` turns it into `std/game/functional/Picture`, a recursive picture type drawn by recursive functions. Use it when you want to draw from state instead of keeping a tree of actors.
 **Browser check:** `cargo run --manifest-path plum-game/web-test/Cargo.toml -- plum-examples/game.plum --screenshot /tmp/orb-run.png` builds the static web version, serves it and drives headless Chromium (software WebGPU; `--browser webkit` drives Playwright's WebKit, the Safari engine, instead) through [playwright-rs](https://crates.io/crates/playwright-rs): it fails if the canvas stays blank or stops changing, or the page logs an error, and reports whether audio started. It also takes `--assets DIR`, `--require-audio`, `--measure SECS` (with `--json`, `draws` is the GPU draw calls per frame), `--headed`, `--dpr N` (a device pixel ratio of N), `--lose-device` (destroys the GPU device after a few frames and requires rendering to resume) and `--expect-pixel x,y,r,g,b[,tol]` (repeatable; the screenshot pixel at CSS (x, y)), `--expect-unsupported-webgpu` (hides `navigator.gpu` and requires the page's "WebGPU is not supported" message while plum.wasm still loads) and `--no-module-introspection` (makes `WebAssembly.Module.imports/exports/customSections` throw, as Safari does). `plum-game/web-test/fixtures/` has `interleave.plum`, `text_sizes.plum` and `rendertarget.plum` for these. One-time setup: `cargo run --manifest-path plum-game/web-test/Cargo.toml --example install-browsers`. See [`plum-game/web-test/README.md`](plum-game/web-test/README.md); `docs/game.png` above was made with `--screenshot`. [`plum-game/web-test/BENCHMARK.md`](plum-game/web-test/BENCHMARK.md) records the renderer benchmark that led to this design.

docs/plans/2026-11-03-state-view-parity.review.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # Functional state/view at feature parity with PureScene: review plan
-**Builds on:** master after `2026-11-03-pure-scene-enums` (its T1–T6; T7 dropped).
+**Builds on:** master 53de7e3 (pure-scene-enums merged; T7 dropped).
 **Goal (user, 2026-11-03):** the most functional approach, where a frame is a recursive value built from state and walked recursively, with the same features as PureScene. Performance is measured and reported, not chased: matching the mutable scene isn't a goal ("otherwise I would just stick with mutate").
 ## Summary
@@ -28,7 +28,9 @@ The three scene styles currently share `plum-std/game/`, which is confusing. Eac
 | `plum-examples/games/pure/` | `game_pure_scene.plum` | |
 | `plum-examples/games/functional/` | `game_state_view.plum` | |
-The mutable examples (`game.plum`, `game_scene.plum`, `scene.plum`, `trait_scene.plum`) stay at the top of `plum-examples`. Imports in std, examples, web-test fixtures, host tests, web checks and the README are updated in the same part, and an import of an old path is a compile error. This is done first, as one mechanical part, so nothing else moves twice.
+The mutable examples (`game.plum`, `game_scene.plum`, `scene.plum`, `trait_scene.plum`) stay at the top of `plum-examples`.
+**Done before this plan** (user, 2026-11-03: "do that first"), as a separate change on master. This plan builds on the new paths: the new `Anim` and `Ui` go in `plum-std/game/functional/`.
 ## The design
 - **Animations are functions of time, not stepped state.**
@@ -47,11 +49,6 @@ The mutable examples (`game.plum`, `game_scene.plum`, `scene.plum`, `trait_scene
     - capture is dropped when the captured id is no longer in the picture.
   - Button visuals come from the UI state: `Ui.pressed(ui, id)`, `Ui.hovered(ui, id)`. `Ui.button(id, label, rect, ui)` builds the button's `SceneNode`.
   - Events are `UiEvent(id, kind)`, as in PureScene, and the game handles them in `step`.
-- **Static subtree reuse (user, 2026-11-03).** Parts of a picture that never change are built once and returned as the same value every frame. Examples: a starfield's layout, terrain tiles, HUD frames, panel backgrounds.
-  - `view` places them as-is (`Group(.., children: Cons(s.staticBg, ...))`), so they cost no allocation per frame. Only the moving parts are rebuilt.
-  - Anything that varies over time is applied around the shared subtree, not inside it: a twinkle via `Filter(Alpha(..), child: staticStar)`, a scroll via `Group(Translate(..), child: staticMap)`.
-  - Stored in `State` (built in `newState`), or as a module-level constant when it depends on nothing.
-  - Test: a wasmparser/allocation count shows the static part adds no `struct.new` per frame. `game_state_view`'s starfield becomes static (positions fixed, twinkle as a per-frame alpha wrapper).
 - **The game shell stays thin.** `update` reads input into a `Msg`, then calls `step`, then `Ui.step` against `view(state)`, then `step` again for each `UiEvent`. Sound remains the only side effect.
 ## What you will get
@@ -68,12 +65,10 @@ The mutable examples (`game.plum`, `game_scene.plum`, `scene.plum`, `trait_scene
 ## What will be built
 | Part | What it does | Size |
 |---|---|---|
-| Folders | move pure and functional modules and their example games into their folders; update every import and test path | S |
 | Anim | `enum Anim`, `at`, `length`, poses; tests for zero-length, sequences, parallel and forever without drift | M |
 | Picture tags | `Tagged(id, child)`, `hitId`, draw/bounds pass-through; tests | S |
 | Ui | `UiState`, `Ui.step`, events, capture, `pressed`/`hovered`, `button`; PureScene-equivalent tests | M |
 | Orb Run state/view | restart via Ui, Anim for the title and hit flash; tests unchanged plus Ui/Anim cases | M |
-| Static subtrees | starfield built once in `State`, twinkle as an alpha wrapper; allocation test | S |
 | Stress fixture | tags, buttons, animations in `stress_state_view.plum` | S |
 | Benchmark + README | headed table, "Functional scenes" section | S |
@@ -102,10 +97,10 @@ flowchart LR
 ## Risks
 - **R1: allocation.** `view` rebuilds the tree every frame, and the UI adds a hit test per input. Measured and reported; the supercompiler's view-into-draw fusion is the later lever.
 - **R2: hit test against the view.** `Ui.step` needs `view(state)` for `hitId`. Building it twice per frame (once for input, once for draw) is allowed, measured, and may be shared later.
-- **R4: nested std paths.** No std module lives three levels deep yet (`std/game/pure/X`). If the loader, LSP or `plum game` asset/bundle code assumes two levels, the Folders part fixes that in the same part, with a test.
 - **R3: compiler gaps.** Recursive types and generic `List` code have hit gaps before. Each gap is reported as an incident and fixed in the compiler, not worked around.
 ## Out of scope
+- Static subtree reuse: building unchanging parts of a picture (starfield layout, terrain, HUD frames) once and sharing them every frame. Deferred by the user, 2026-11-03, as a later optimisation.
 - Removing PureScene, SceneTree, SceneInput or Actions (a later decision).
 - Fixed timestep and replays (separate queued plan).
 - The supercompiler.

docs/plans/2026-11-03-supercompiler.review.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # Supercompiler: fusing List chains and view-into-draw: review plan
-**Builds on:** master after `2026-11-03-pure-scene-enums` (pure scene on `Node` + `Kind`, `own` kept): closure specialisation, tail calls and TRMC, unboxed variants, std cons `List`, recursive `Picture` and the state/view Orb Run.
+**Builds on:** master after `2026-11-03-pure-scene-enums` (53de7e3) and the folder split (`std/game/pure/`, `std/game/functional/Picture`): closure specialisation, tail calls and TRMC, unboxed variants, std cons `List`, recursive `Picture` and the state/view Orb Run.
 **Added 2026-11-03 (user):** a uniqueness stage. `own` stays for now. If the compiler can prove for itself that nobody else still holds a value, `own` becomes redundant and can be removed in a later plan. See "Uniqueness without `own`" below.

plum-cli/src/game.rs CHANGED Viewed

@@ -20,16 +20,43 @@ fn repoRoot() -> PathBuf {
         .to_path_buf()
 }
-/// The asset root: `--assets`, else `assets` beside the source file.
+/// The asset root: `--assets`, else the nearest `assets` directory beside the source file or in
+/// a parent folder (so games in subfolders share one), else `assets` beside the source file.
 fn assetRoot(file: &Path, cli: Option<PathBuf>) -> PathBuf {
     cli.unwrap_or_else(|| {
+        let dir = file
-        file.parent()
+            .parent()
             .filter(|p| !p.as_os_str().is_empty())
-            .unwrap_or(Path::new("."))
+            .unwrap_or(Path::new("."));
+        let abs = dir.canonicalize().unwrap_or_else(|_| dir.to_path_buf());
+        for up in abs.ancestors() {
+            if up.join("assets").is_dir() {
+                return if up == abs { dir.join("assets") } else { up.join("assets") };
+            }
+        }
-            .join("assets")
+        dir.join("assets")
     })
 }
+#[cfg(test)]
+mod assetRootTests {
+    use super::*;
+    #[test]
+    fn finds_assets_in_a_parent_folder() {
+        let root = std::env::temp_dir().join(format!("plum_assets_{}", std::process::id()));
+        let deep = root.join("games/pure");
+        fs::create_dir_all(&deep).unwrap();
+        fs::create_dir_all(root.join("assets")).unwrap();
+        let found = assetRoot(&deep.join("g.plum"), None);
+        assert_eq!(found.canonicalize().unwrap(), root.join("assets").canonicalize().unwrap());
+        fs::create_dir_all(deep.join("assets")).unwrap();
+        assert_eq!(assetRoot(&deep.join("g.plum"), None), deep.join("assets"));
+        assert_eq!(assetRoot(&deep.join("g.plum"), Some("x".into())), PathBuf::from("x"));
+        fs::remove_dir_all(&root).ok();
+    }
+}
 /// Every file under `dir` (dotfiles skipped), as `/`-separated paths relative to it, sorted.
 fn listFiles(dir: &Path) -> Result<Vec<String>> {
     fn walk(dir: &Path, prefix: &str, out: &mut Vec<String>) -> Result<()> {

plum-examples/{game_state_view.plum → games/functional/game_state_view.plum} RENAMED Viewed

@@ -1,4 +1,4 @@
-# Orb Run as state and view (`plum game plum-examples/game_state_view.plum`): the same
+# Orb Run as state and view (`plum game plum-examples/games/functional/game_state_view.plum`): the same
 # game as game_pure_scene.plum (same arena, rules, sprites, sounds, keys and scoring),
 # written the way a Rust state/view program is. Steer the ship with the arrow keys or
 # WASD, collect the drifting orbs and avoid the mines. Three lives; Enter, R or the
@@ -24,7 +24,7 @@ import std/Math
 import std/game/Vec2
 import std/game/Color
 import std/game/Game
-import std/game/Picture
+import std/game/functional/Picture
 primitive Rules =
   ArenaW = 800.0

plum-examples/{game_pure_scene.plum → games/pure/game_pure_scene.plum} RENAMED Viewed

@@ -1,4 +1,4 @@
-# Orb Run on the pure scene graph (`plum game plum-examples/game_pure_scene.plum`): the same
+# Orb Run on the pure scene graph (`plum game plum-examples/games/pure/game_pure_scene.plum`): the same
 # game as game_scene.plum (same arena, rules, sprites, sounds, keys and scoring), but the
 # scene is made of values. Steer the ship with the arrow keys or WASD, collect the
 # drifting orbs and avoid the mines. Three lives; Enter, R or the "Again" button
@@ -25,10 +25,10 @@ import std/game/Vec2
 import std/game/Color
 import std/game/Affine
 import std/game/Game
-import std/game/Actions
+import std/game/pure/Actions
-import std/game/PureScene
+import std/game/pure/PureScene
-import std/game/SceneTree
+import std/game/pure/SceneTree
-import std/game/SceneInput
+import std/game/pure/SceneInput
 primitive Rules =
   ArenaW = 800.0

plum-game/tests/host_test.rs CHANGED Viewed

@@ -265,7 +265,7 @@ fn sceneExampleRunsFrames() {
 #[test]
 fn pureSceneExampleRunsFrames() {
-    let wasm = compile(&root().join("plum-examples/game_pure_scene.plum"));
+    let wasm = compile(&root().join("plum-examples/games/pure/game_pure_scene.plum"));
     let mut g = PlumGame::load(&wasm, Recorder::with_assets(examples_assets())).expect("load game");
     g.init().expect("init");
     for _ in 0..10 {
@@ -284,7 +284,7 @@ fn pureSceneMatchesSceneDrawCounts() {
         g
     };
     let mut a = load("plum-examples/game_scene.plum");
-    let mut b = load("plum-examples/game_pure_scene.plum");
+    let mut b = load("plum-examples/games/pure/game_pure_scene.plum");
     let tex_ids = |calls: &[String]| {
         let mut v: Vec<String> = calls
             .iter()

plum-game/web-test/fixtures/stress_pure_scene.plum CHANGED Viewed

@@ -1,4 +1,4 @@
-# The stress scene of stress_scene.plum on the PURE scene graph (std/game/PureScene):
+# The stress scene of stress_scene.plum on the PURE scene graph (std/game/pure/PureScene):
 # 5000 sprites in 50 slowly rotating groups, 500 rects and 200 circles (sprites of a
 # 1x1 white texture), 50 texts with a changing number, drawn through a camera. Every
 # node is an own value: each frame changes the tree in place with SceneTree.update. Group and
@@ -13,10 +13,10 @@ import std/game/Vec2
 import std/game/Color
 import std/game/Affine
 import std/game/Game
-import std/game/Actions
+import std/game/pure/Actions
-import std/game/PureScene
+import std/game/pure/PureScene
-import std/game/SceneTree
+import std/game/pure/SceneTree
-import std/game/SceneInput
+import std/game/pure/SceneInput
 primitive Counts =
   Sprites = 5000

plum-game/web-test/fixtures/stress_state_view.plum CHANGED Viewed

@@ -15,7 +15,7 @@ import std/List
 import std/game/Vec2
 import std/game/Color
 import std/game/Game
-import std/game/Picture
+import std/game/functional/Picture
 primitive Counts =
   Sprites = 5000

plum-game/web-test/fixtures/stress_state_view_deep.plum CHANGED Viewed

@@ -17,7 +17,7 @@ import std/List
 import std/game/Vec2
 import std/game/Color
 import std/game/Game
-import std/game/Picture
+import std/game/functional/Picture
 primitive Counts =
   Sprites = 5000

plum-game/web-test/tests/web_check.rs CHANGED Viewed

@@ -12,7 +12,7 @@ fn orb_run_scene_renders_and_animates() {
 #[test]
 fn pure_scene_renders_and_animates() {
-    orb_run("plum-examples/game_pure_scene.plum");
+    orb_run("plum-examples/games/pure/game_pure_scene.plum");
 }
 #[test]

plum-std/game/{Picture.plum → functional/Picture.plum} RENAMED Viewed

File without changes

plum-std/game/{Actions.plum → pure/Actions.plum} RENAMED Viewed

File without changes

plum-std/game/{PureScene.plum → pure/PureScene.plum} RENAMED Viewed

@@ -8,14 +8,14 @@ import std/game/Vec2
 import std/game/Color
 import std/game/Affine
 import std/game/Game
-import std/game/Actions
+import std/game/pure/Actions
 # A pure scene graph: a node is an own record (`Node`) holding a `Transform` and
 # an `enum Kind`. Group, Sprite, Label and Button are built in; games add their
 # own behaviour with `Custom(actor: Actor)`, a behaviour-only trait their records
 # embed (like Rust's `Box<dyn Actor>`). `onPointer` takes the node, changes it in
 # place and hands it back; readers borrow. Only `drawTree` talks to the host,
-# through `std/game/Game`. Actions and tree-wide updates live in std/game/SceneTree.
+# through `std/game/Game`. Actions and tree-wide updates live in std/game/pure/SceneTree.
 enum Touchable =
   | Enabled

plum-std/game/{SceneInput.plum → pure/SceneInput.plum} RENAMED Viewed

@@ -7,9 +7,9 @@ import std/game/Vec2
 import std/game/Color
 import std/game/Affine
 import std/game/Game
-import std/game/Actions
+import std/game/pure/Actions
-import std/game/PureScene
+import std/game/pure/PureScene
-import std/game/SceneTree
+import std/game/pure/SceneTree
 # The root of a pure scene tree, its camera and pointer capture. A Stage is an
 # own value: `input` and `frame` take it, change it in place and hand it back

plum-std/game/{SceneTree.plum → pure/SceneTree.plum} RENAMED Viewed

@@ -5,8 +5,8 @@ import std/Slice
 import std/Str
 import std/game/Vec2
 import std/game/Affine
-import std/game/Actions
+import std/game/pure/Actions
-import std/game/PureScene
+import std/game/pure/PureScene
 fun treeActorOf(n: Node) -> Actor? =
   match n.kind