5ecf1ab | plum | pyrossh

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

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

5ecf1ab — Peter John 2026-11-05T22:33:48+05:30

Simplify the README and rewrite the docs

Files changed (7) hide show

README.md +40 -1285
compiler/lsp/src/main.rs +18 -8
docs/game.md +93 -0
docs/language.md +526 -0
docs/performance.md +51 -0
docs/std.md +166 -0
docs/tools.md +52 -0

README.md CHANGED Viewed

@@ -1,126 +1,56 @@
 # 👾 Plum
-A statically typed, imperative programming language with algebraic data types, inspired by Rust, Zig, Go, Kotlin and Gleam.
+A simple, statically typed programming language with enums, pattern matching and generics. It compiles to WebAssembly.
-- Built on a [tree-sitter](compiler/tooling/tree-sitter-plum) grammar, with syntax highlighting and a language server for Helix and VSCode out of the box (`plum editor helix` / `plum editor vscode`)
-- Compiles to WebAssembly (wasm-gc) and runs under wasmtime; `plum build` embeds the module into a native executable. Native targets (amd64, arm64, riscv64 via QBE, C-ABI compatible) are planned.
-## Language at a glance
 ```plum
-module glance
-import std/Os
+import std/Io
-import std/Str
 import std/Int
 import std/Float
-import std/Slice
+import std/Str
 import std/List
 import std/Option
-import std/Result
-enum ParseError =                          # one error enum per module
-  | BadNum
-  | Negative
-enum Shape =                               # an enum: a Circle or a Rect
+enum Shape =
   | Circle(r: Float)
   | Rect(w: Float, h: Float)
-  fun area(self) -> Float =                # a method
+  fun area(self) -> Float =
     match self
       Circle(r) => r * r * 3.14
       Rect(w, h) => w * h
-  SidesMax = 4                             # associated constant: Shape.SidesMax
-struct Vec2(x: Float, y: Float) =
-  Zero = Vec2(x: 0.0, y: 0.0)              # Vec2.Zero
-  fun add(self, o: Vec2) -> Vec2 =         # `a + b` calls a.add(b)
-    Vec2(x: self.x + o.x, y: self.y + o.y)
-fun parse(s: Str) -> Result[Int, ParseError] =   # an Ok(Int), or an Err(ParseError)
-  n := Int.parse(s).mapErr(|e| BadNum)?    # `?` returns the Err from this function
-  if n < 0
-    return Err(Negative)
-  Ok(n)
-fun double(s: Str) -> Result[Int, ParseError] =
-  n := parse(s)?                           # `?` unwraps an Ok, or propagates the Err
-  Ok(n * 2)
-fun firstEven(xs: List[Int]) -> Option[Int] =   # an Option is None or Some(value)
+fun firstEven(xs: List[Int]) -> Option[Int] =
-  for x := range xs                        # the one loop form
+  for x := range xs
     if x % 2 == 0
       return Some(x)
   None
 fun main(io: Io) =
-  total := 0
-  for i := range 10                        # an Int counts 0..9
-    if i % 2 == 0
-      total = total + i
-  big := [1, 5, 9].filter(|x| x > 2).map(|x| x * 10)   # a list literal
-  e := firstEven([1, 3, 4]).unwrapOr(-1)   # `unwrapOr` supplies a default for None
-  n := parse("42").unwrapOr(0)             # ...and for an Err
-  pos := Vec2.Zero + Vec2(x: 1.0, y: 2.0)
+  shape := Rect(w: 2.0, h: 3.0)
+  even := firstEven([1, 3, 4]).unwrapOr(0)
-  io.printLn("{total} {big.length()} {e} {n} {pos.y} {Shape.SidesMax}")
+  io.printLn("area {shape.area()}, first even {even}")
-test "glance"
+test "shapes"
   assert Rect(w: 2.0, h: 3.0).area() == 6.0
-  assert double("21").unwrapOr(0) == 42
-  assert parse("-1").unwrapOr(7) == 7
   assert firstEven([1, 3]).isNone()
 ```
-| You want | Write |
-|---|---|
-| declare a variable / reassign | `x := 1` / `x = 2` |
-| declare with a type | `s: Shape := Circle(r: 2.0)` (only with `:=`, a value is required) |
-| drop a result on purpose | `_ := stack.pop()!` |
-| a block | indent by 2 spaces, no braces |
-| group an expression | `{1 + 2} * 3` (braces; parentheses are for calls) |
-| a conditional expression | `if c then a else b` (no `c ? a : b` ternary) |
-| loop | `while c`, `for x := range src` (an `Int`, a `Slice`/`Array`, or any type with `next(self) -> Option[Pair[T, Self]]`) |
-| a list / a map | `[1, 2, 3]` (a `List`, `[]` empty), `["a" => 1]` (a `Map`) |
-| an enum of variants | `enum Shape = Circle(r: Float) \| Rect(w: Float, h: Float)` |
-| a product type (the compiler picks flat or boxed) | `struct Vec2(x: Float, y: Float)`, `struct User(name: Str, age: Int)` |
-| a method / static / constant | `fun area(self)` / `fun origin()` / `Name = expr` inside the type body |
-| generics | `fun id[T](x: T) -> T`, `enum Box[T]`, declared lists, duck-typed, one copy per type |
-| operators on your types | define `add`, `sub`, `mul`, `div`, `neg`, `eq`, `lt`, `le`, `gt`, `ge` |
-| an optional | `Option[T]`: `None`, `Some(x)`, `opt.unwrapOr(default)`, `if Some(x) := opt`, `opt.map(f)`, `opt!` |
-| a fallible function | `-> Result[T, E]`, `return Err(MyError)`, `Ok(x)` |
-| propagate / default / crash | `f()?` / `f().unwrapOr(default)` / `f()!` |
-| an iterator | a type with `next(self) -> Option[Pair[T, Self]]`, e.g. `0.until(10).stepBy(3)` |
-| a namespace of constants and functions | `primitive Math =` |
-| a test | `test "name"` with `assert` |
-| a host call | a method of `Io`: `io.printLn(s)` (entry points take `io: Io`) |
-| a function the host calls | `export fun draw(io: Io, g: Game)` |
-Discarding the result of a call is a compile error, so `scores.push(3)` on a type whose `push` returns a new value cannot silently do nothing. Use the result, or drop it explicitly with `_ :=`:
-```plum
-fun main() =
-  list := [1, 2, 3].toSlice()
-  _ := list.pop()!      # evaluate, drop the removed element
-  list.push(4)          # fine: push returns Unit
-```
-A call that returns `Unit` can be a bare statement, and so can the last expression of a function, which is its return value.
-## Installing
-Prebuilt binaries need nothing else. To build from source you need a recent stable Rust toolchain and a C compiler (for the tree-sitter parser). `node` and `npm` are only needed to rebuild the VSCode extension bundle (`npm install && npm run build` in `compiler/tooling/vscode-plum`); without them `plum editor vscode` still installs syntax highlighting.
-```sh
-cargo install --path compiler/cli
-```
+## Features
-Installs a release build as `plum` in `~/.cargo/bin`, which `cargo` puts on your `PATH` for you — no `sudo`/`/usr/local/bin` needed. Re-run this after pulling changes to the compiler; it doesn't auto-update. Use `cargo run -p plum-cli --` instead while actively developing the compiler itself.
+- **Easy to read:** blocks are indentation, and there is one way to loop over anything.
+- **Structs and enums:** `match` checks that you handled every case.
+- **Generics:** write `fun id[T](x: T) -> T`, and each type gets its own fast copy.
+- **No null, no exceptions:** absence is `Option`, failure is `Result`, and `?` passes an error up.
+- **Closures and tail calls:** recursion runs in constant stack.
+- **Tests built in:** add a `test` block next to your code and run `plum test`.
+- **Visible side effects:** printing, files and network go through an `Io` value, so a function without one can't touch the outside world.
+- **Fast by default:** the compiler removes temporary lists and updates values in place when it is safe, with no change to what your code means.
+- **Games:** a built-in engine runs in the browser on WebGPU.
+- **Editor support:** syntax highlighting and a language server for Helix and VSCode.
-### Prebuilt binaries
+Plum compiles to WebAssembly (wasm-gc), and `plum build` wraps the result in a native executable. True native targets are planned.
-No Rust toolchain needed — download the `plum` binary directly (it embeds `plum-lsp`, the tree-sitter grammar, and the VSCode extension bundle; `plum editor helix`/`plum editor vscode` extract them on install):
+## Install
 <!-- prebuilt-binaries:start -->
 | Platform | Download |
@@ -138,1202 +68,27 @@ mv plum ~/.cargo/bin/plum   # or anywhere else already on your PATH
 ```
 <!-- prebuilt-binaries:end -->
-Maintainers: `cargo make release` builds macOS/Linux/Windows binaries (Linux/Windows via [cross](https://github.com/cross-rs/cross), needs Docker), tags `v<version>`, regenerates the links above, and uploads all three to R2 (see `Makefile.toml`; needs [cargo-make](https://github.com/sagiegurari/cargo-make) and the `git` rclone remote configured for R2).
+Or build from source with `cargo install --path compiler/cli`.
-### Using the CLI
+## Use it
-```sh
-plum run file.plum            # compile and run under wasmtime
-plum test file.plum dir/      # run the `test` blocks of files and directories (recursive)
+Run these from a checkout of this repository, so `import std/...` can find the standard library.
-plum compile file.plum        # write file.wasm
-plum build file.plum          # embed the module into a native executable
-plum format file.plum         # rewrite in place (--check, --stdin)
-plum game file.plum           # serve a game and open it in the browser (see Games); -o DIR writes a static build
-plum editor helix|vscode      # install highlighting and the language server
-```
-`import std/Name` resolves to `<lib-path>/std/Name.plum`, and `--lib-path` defaults to the current directory, so run the commands from a checkout of this repository (or pass `--lib-path`).
-### Run the example game
 ```sh
-cargo run -q -p plum-cli -- game examples/games/imperative/game.plum      # or, after `cargo install --path compiler/cli`: plum game examples/games/imperative/game.plum
-```
-This compiles the game, serves it on `http://127.0.0.1:8080/` (any free port if that one is taken) and opens it in your default browser. It needs a browser with WebGPU: Chrome or Edge, Safari 26+ or Firefox. Arrow keys or WASD steer the ship, collect the orbs, dodge the mines; Enter or R restarts after the game is over. Press a key first: browsers start audio only after a user gesture.
-![the example game](docs/game.png)
-## Layout and comments
-Blocks are indentation-sensitive (2 spaces), like Python — there's no `{ }` for grouping statements. `#` starts a line comment.
-```plum
-# this is a comment
-fun main() =
-  x := 1
-  if x > 0
-    x = x + 1
-```
-## Naming conventions
-| Case | Used for |
-|---|---|
-| `PascalCase` | types, enums, error sets, namespaces, associated constants (`Float.Pi`) |
-| `camelCase` | functions, methods, fields |
-| `snake_case` | variables, params |
-| `PascalCase` in a `[..]` list (`T`, `Elem`) | generic type parameters, named where declared |
-## Modules and imports
-A file may start with `module name`, then its imports, then everything else; `test` blocks go last.
-```plum
-module basics
-import std/Os
-```
-Nothing is implicit: `Int`, `Float`, `Str`, `Slice`, ... are available once the file imports `std/Int`, `std/Float`, `std/Str`, `std/Slice`, ...
-## Literals
-```plum
-dec := 42
-hex := 0xFF
-bin := 0b1010
-big := 1_000_000
-flt := 3.14
-flt2 := 12.0f
-exp := 6.022e23
-name := "plum"
-escaped := "line one\nline two\ttabbed \"quoted\""
-yes := true
-no := false
-```
-An integer literal that does not fit in an `Int` is a compile error (`-0x8000_0000_0000_0000` is `Int.Min`).
-### String interpolation
-```plum
-fun greet(name: Str) -> Str =
-  "Hello, {name}!"
-```
-`{expr}` interpolates any expression: a variable, literal, attribute access, method call, `&&`/`||`/comparison or an inline `if`.
-## Operators
-From tightest to loosest binding:
-| Precedence | Operators | Notes |
-|---|---|---|
-| highest | `.` `?` `!` | attribute access / method call, propagation (`f()?`) and crash-unwrap (`f()!`) |
-| | `+` `-` | unary |
-| | `*` `/` `%` | |
-| | `+` `-` | |
-| | `<<` `>>` | |
-| | `^` | |
-| | `&` | |
-| | `\|` | |
-| | `<` `<=` `==` `!=` `>=` `>` `<>` | comparisons (`<>` is another spelling of `!=`) |
-| | `!` | boolean not |
-| | `&&` | |
-| | `\|\|` | |
-| lowest | `if c then a else b` | inline if (the else branch extends as far right as possible) |
-There's no range operator — every `for` is `for <binders> := range <source>` (see [Iteration](#iteration)). `{ }` is used to group a sub-expression (not `( )`, which is reserved for calls):
-```plum
-sum := 3
-bits := 4
-cmp := true
-grouped := {1 + 2} * {3 - 1}
-picked := if cmp then sum else bits
-negated := -sum
-inverted := !cmp
+plum run file.plum       # compile and run
+plum test file.plum      # run its tests
+plum build file.plum     # make an executable
+plum game file.plum      # play a game in the browser
+plum editor helix        # set up your editor (or vscode)
 ```
-### Operators on your own types
-On `Int`, `Float`, `Byte` and `Str` operators are built in. On any other (declared) type, an operator calls a method on the left operand, resolved statically per instantiation:
-| Operator | Method |
-|---|---|
-| `a + b`, `a - b`, `a * b`, `a / b` | `a.add(b)`, `sub`, `mul`, `div` |
-| `-a` | `a.neg()` |
-| `a == b`, `a != b` | `a.eq(b)`, `!a.eq(b)` |
-| `a < b`, `a <= b`, `a > b`, `a >= b` | `a.lt(b)`, `a.le(b)`, `a.gt(b)`, `a.ge(b)` |
-Each operator needs its own method (no derivation from `lt`/`eq`). The right operand may have a different type: `v * 2.0` calls `mul(self, s: Float)`. Using an operator without the method is an error such as `Vec2 has no operator '+' (define add)`, with the instantiation chain when it happens inside a generic. `==`/`!=` on a type with no `eq` keep their built-in meaning (variant identity).
-```plum
-struct Vec2(x: Float, y: Float) =
-  fun add(self, o: Vec2) -> Vec2 =
-    Vec2(x: self.x + o.x, y: self.y + o.y)
-  fun mul(self, s: Float) -> Vec2 =
-    Vec2(x: self.x * s, y: self.y * s)
-```
-See [`examples/numbers.plum`](examples/numbers.plum).
-## Variables and assignment
-```plum
-x := 1
-# declares a new binding — errors if `x` is already in scope
-a, b := 1, 2
-# multiple targets, positionally paired with multiple values
-x = 2
-# reassigns an existing binding — type-checked against x's declared type
-```
-### Annotated declarations
-`name: Type := value` fixes the local's type instead of inferring it from the value. The value is checked against the annotation exactly like an argument for a parameter of that type, so `Some(3)` fits an `Option[Int]` annotation; a later `name = value` converts the same way. Only `:=` takes an annotation (`s: Shape = v` is an error), a value is required (`total: Float` alone is an error), and there is a single target (`a, b: T := ...` is not allowed). `fn(..) -> T` types and a generic parameter in scope (`T`) work as annotations. It adds no numeric conversion: `n: Float := 3` is rejected just as `take(3)` is for a `Float` parameter.
-```plum
-s: Shape := Circle(r: 2.0)
-xs: Slice[Shape] := Slice[Shape]()
-o: Option[Int] := None
-s = Rect(w: 1.0, h: 2.0)       # checked, and converted, against Shape
-```
-See [`examples/structs_records.plum`](examples/structs_records.plum).
-## Control flow
-`if` is also an expression: `if c then a else b` (both branches are required and must have the same type; it chains, `if a then x else if b then y else z`). The block form below, with indented bodies and no `then`, is a statement.
-```plum
-fun sign(n: Int) -> Int =
-  if n < 0 then -1 else if n == 0 then 0 else 1
-```
-```plum
-if n < 0
-  return "negative"
-else if n == 0
-  return "zero"
-else
-  return "positive"
-i := start
-while i > 0
-  i = i - 1
-for i := range limit
-  if i == 3
-    continue
-  if i == 8
-    break
-  total = total + i
-assert n > 0    # traps at runtime if false
-todo            # traps at runtime — marks a body as not yet implemented
-```
-`match` is covered under [Types](#match). To test a single case instead, see [Pattern `if`](#pattern-if) below.
-### Pattern `if`
-`if Pattern := expr` tests one case and binds the pattern's names for that branch only. It uses the same patterns as `match` (constructor patterns with nested fields, literals, `_`, bare member, tag or error names), and reads like any other `if`/`else if`/`else` chain. A `, cond` after the value adds more conditions that already see the bindings. It works in `else if`, inline (`if Circle(r) := s then r else 0.0`) and in `while`:
-```plum
-fun draw(shape: Shape) =
-  if Circle(r) := shape
-    drawCircle(r)
-  else if Rect(w, h) := shape, w > h
-    drawWide(w, h)
-  else
-    drawOther(shape)
-```
-A bare member name narrows the value inside the branch (see [Enums](#enums)):
-```plum
-fun width(s: Shape) -> Float =
-  if Rect := s
-    s.w
-  else
-    0.0
-```
-```plum
-while Busy(task) := worker.state      # loops while the pattern matches
-  task.step()
-```
-Use pattern `if` when only one or two cases need code and the rest are "do nothing" or one shared fallback, especially for early exits and guard-style checks. Use [`match`](#match) when every case needs handling: it is checked for exhaustiveness, so adding a variant later is a compile error until each `match` covers it, and pattern `if` is never checked that way. The same job both ways:
-```plum
-# pattern if: one interesting case, early exit
-fun attack(unit: Unit) =
-  if Soldier(hp, Weapon(dmg)) := unit, hp > 0
-    enemy.hurt(dmg)
-```
-```plum
-# match: every job is handled, the compiler checks it
-match job
-  Idle => rest()
-  Busy(task) => task.step()
-  Done(loot) => collect(loot)
-```
-Details:
-- The bindings exist only in that branch's block (and in the `, cond`s after the pattern); using them after the `if`, or in a later `else` branch, is an error.
-- A pattern that cannot fail on its type (`Vec2(x, y) := v` on a struct) is allowed and always takes the branch.
-- `else if` chains can mix plain conditions, `Some(x) := opt` bindings (see [Option and Result](#option-and-result)) and patterns.
-- It works on results too: `if Err(TooBig) := r` tests one error variant.
-See [`examples/match.plum`](examples/match.plum).
-## Functions
-```plum
-fun addInts(a: Int, b: Int) -> Int =
-  a + b
-fun greet() = # no return type => Unit
-  todo
-fun withDefault(a: Int, step: Int = 1) -> Int =
-  a + step
-fun sumAll(nums: List[Int]) -> Int = # no variadics: take a List, call as sumAll([1, 2])
-  total := 0
-  for v := range nums
-    total = total + v
-  total
-```
-A body that is a single `match` can start on the signature line: `= match x` followed by the arms indented one level. It is the same as putting the `match` on the next line, for functions and methods alike:
-```plum
-fun sign(n: Int) -> Int = match n
-  0 => 0
-  _ => if n < 0 then -1 else 1
-```
-A function without a return type returns `Unit`; the last expression of a body is its value. Functions take positional arguments; only constructors can name them (see [Constructing values](#constructing-values)).
-## Types: struct and enum
+## Learn more
-`struct` is the one product type with named fields; an `enum` is a set of variants, each with its own named fields. The other declaration form is `primitive Name =` ([Constants, statics and `primitive`](#constants-statics-and-primitive)).
+- [The language](docs/language.md): the full guide
+- [The standard library](docs/std.md): strings, lists, maps, JSON, files and more
+- [The game engine](docs/game.md): drawing, input, sound and scene graphs
+- [Tools](docs/tools.md): every command and option, editors, building from source
+- [Performance](docs/performance.md): how the compiler optimises your code
+- [Examples](examples): a runnable file per feature, and example games
-### `struct`
-A `struct` is declared with named fields. It may be generic, embed one other struct (its base), have `mut` fields, have no fields, and have a body of methods and constants:
-```plum
-struct Vec2(x: Float, y: Float)
-struct Body(pos: Vec2, size: Vec2)  # a field may be another struct
-struct User(name: Str, mut age: Int)
-struct Pair[K, V](key: K, val: V)   # generic
-struct Marker()                     # no fields
-```
-The header ends with `=` only when an indented body follows (methods, constants: see [Methods](#methods-self-and-field-access) and [Constants](#constants-statics-and-primitive)); `struct Vec2(x: Float, y: Float)` with no body has no `=`.
-The compiler chooses each struct's layout in one place (`plum_core::layout`; `plum run --explain` prints `layout <Name>: flat|boxed`). A struct is **flat** when it has at least one field, no generics, no embedding, no `mut` field and no `fun init(self)`, is not recursive, and every field is `Int`, `Float`, `Bool`, `Byte` or another flat struct. Every other struct is **boxed**: a heap object.
-```plum
-a := Vec2(x: 1.0, y: 2.0)
-b := a
-b.x = 9.0          # a.x is still 1.0: a flat struct is copied
-u := User(name: "ann", age: 3)
-u2 := u
-u2.age = 4         # u.age is now 4: a boxed struct is shared on assignment
-```
-A flat struct is copied on assignment and when passed, compares field by field with `==`, and is boxed inside `Option[T]` and other generic slots. Its fields can be assigned, since it is copied. Arrays of flat structs (`Array[Vec2]`, and so `Slice[Vec2]` and `Grid[Tile]`) are stored field by field, one native array per field, with no per-element allocation. A boxed struct's fields are immutable unless declared `mut` (`u.name = "x"` is an error), and its `==` is identity. To change an immutable field, build an updated value with a spread (`User(..u, name: "bob")`, see [In-place updates](#in-place-updates)). Methods and `match` work as for any enum. See [`examples/structs_records.plum`](examples/structs_records.plum).
-### Enums
-An `enum` lists its variants. A variant is a payload-less tag (`Red`) or declares named fields inline (`Circle(r: Float)`). A short list fits on one line; a longer one, or one with methods, goes on indented `|` lines. A variant is a constructor and a pattern only, not a type: `Shape` is the only type, so there is no `Circle` to name in a signature or a field:
-```plum
-enum Shape = Circle(r: Float) | Rect(w: Float, h: Float)
-enum Color =
-  | Red
-  | Green
-  | Blue
-enum Json =
-  | JsonNull
-  | JsonBool(value: Bool)
-  | JsonNum(value: Float)
-  | JsonStr(value: Str)
-  | JsonArr(items: Slice[Json])
-  | JsonObj(fields: Map[Str, Json])
-```
-Construct a variant with named arguments; the value has the enum's type (generics are inferred from the arguments or the expected type):
-```plum
-fun make(big: Bool) -> Shape =
-  if big
-    Rect(w: 10.0, h: 10.0)
-  else
-    Circle(r: 1.0)
-fun label(j: Json) -> Str =
-  "json"
-fun use() -> Str =
-  label(JsonNum(value: 2.5))
-```
-Read the fields with a pattern, since an inline variant has no `.field`. A `match` over an enum must be exhaustive:
-```plum
-fun show(j: Json) -> Str =
-  match j
-    JsonNull => "null"
-    JsonBool(value) => if value then "true" else "false"
-    JsonNum(value) => value.toStr()
-    JsonStr(value) => "\"{value}\""
-    JsonArr(_) => "list"
-    JsonObj(_) => "map"
-```
-An enum defines methods with a `match self` body, one per operation:
-```plum
-enum Shape =
-  | Circle(r: Float)
-  | Rect(w: Float, h: Float)
-  fun area(self) -> Float =
-    match self
-      Circle(r) => r * r * 3.14
-      Rect(w, h) => w * h
-fun areaOf(s: Shape) -> Float =
-  s.area()
-```
-See [`examples/unions.plum`](examples/unions.plum). Open-ended dispatch (new kinds added elsewhere) is done with [struct subtyping](#embedding-structs-and-override) instead.
-Variants can hold the enum recursively, which is how recursive data is written:
-```plum
-enum Link[T] = Nil | Cons(head: T, tail: Link[T])
-enum Node =
-  | Leaf(id: Int)
-  | Group(id: Int, kids: Link[Node])
-```
-Generics are inferred from the arguments or the expected type:
-```plum
-fun length[T](xs: Link[T]) -> Int = match xs
-  Nil => 0
-  Cons(_, t) => 1 + length(t)
-fun twoLinks() -> Link[Int] =
-  Cons(head: 1, tail: Cons(head: 2, tail: Nil))
-```
-Using a variant as a type is an error, as are unnamed fields and reading a field with `.`:
-- `Cons is a variant of Link, not a type; use Link[...]`
-- `variant Some(T) needs named fields: Some(value: T)`
-- `read Cons's fields with a pattern: Cons(...)`
-### Embedding structs and override
-A struct whose header lists exactly one other struct, first, embeds it as its base and is its subtype. It gains the base's fields, `init` and instance methods, converts to the base wherever the base is expected, and `override fun` picks the subtype's method at runtime (dispatch on the concrete type). The header names the base fields a caller passes (`Stage(camScale)`); the rest are set by the base `init`, which runs before the struct's own, or by the struct's `init`. Statics are not copied. A base method written without a body, `abstract fun m(self) -> T`, must be overridden by every subtype, and such a base cannot be constructed. See [`examples/subtyping.plum`](examples/subtyping.plum).
-```plum
-struct Stage(camScale: Float) =
-  fun init(self) =
-    self.camX: Float = 0.0
-  fun act(self, dt: Float) =
-    self.camX = self.camX + dt
-  fun draw(self, io: Io) =
-    io.printLn("stage")
-struct World(Stage(camScale), score: Int) =
-  override fun draw(self, io: Io) =
-    self.Stage.draw(io)             # the original, from Stage
-    io.printLn("world")
-```
-```plum
-w := World(camScale: 2.0, score: 0)
-w.act(1.0)                          # inherited from Stage
-w.draw()                            # World.draw: prints "stage" then "world"
-```
-Every method that implements an abstract method or replaces the base's method must be `override fun`; defining one without it is an error (`World.draw hides Stage.draw; mark it override`), and so is an `override fun` that overrides nothing. Inside a struct, `self.Owner.method(args)` calls the original from the base struct `Owner`.
-### In-place updates
-A spread `T(..x, f: v)` is written into `x` in place when the compiler proves `x` unique (dead after the update, no other holder); `--explain-fusion` shows each such site as `unique spread at fn:line`. No keyword is needed:
-```plum
-struct Cell(x: Float)
-fun bump(s: Cell) -> Cell = Cell(..s, x: s.x + 1.0)
-```
-### Methods, `self` and field access
-A `fun` declared indented directly inside an `enum` or `struct` body whose first parameter is `self` is a method, called on a value (`c.getAge()`). One without `self` is a static function, called on the type (`Cat.named("Tom")`), and can't use `self`. Calling a static on a value, or a method on the type, is an error:
-```plum
-struct Cat(name: Str, age: Int) =
-  fun getAge(self) -> Int =
-    self.age
-  fun birthday(self) -> Int =
-    self.age + 1
-  fun named(name: Str) -> Cat =   # static: Cat.named("Tom")
-    Cat(name: name, age: 0)
-struct Wrapper(inner: Cat, tag: Int)
-fun main() -> Int =
-  c := Cat(name: "Whiskers", age: 3)
-  a := c.getAge()
-  w := Wrapper(inner: c, tag: 1)
-  a + w.inner.age # chained field access
-```
-A field of a `struct` is read with `.field`. On an enum, variant fields are read with a pattern (see [Enums](#enums)).
-### Constructing values
-Construct a `struct` by calling its name with `field: value` pairs (any order; every field required), or positionally. This is the only call that can name its arguments:
-```plum
-cat := Cat(name: "Whiskers", age: 3)
-```
-Fields are immutable unless declared `mut` (`mut age: Int` allows `cat.age = cat.age + 1`), and a Gleam-style spread builds an updated value from an existing one, overriding just the fields you name:
-```plum
-older := Cat(..cat, age: cat.age + 1)
-```
-### Constructors and init
-A struct's header is its constructor: the parameters a caller passes. A struct that embeds a base struct lists the base fields it exposes, `Actor(x, y)`; a bare `Actor` exposes none. Everything else is set in `fun init(self)`, which runs once per construction (the base's `init` first, then the struct's own):
-```plum
-struct Bag(n: Int) =
-  fun init(self) =
-    self.label = "bag"
-    self.items: Slice[Int] = Slice[Int]()
-    self.cap: Int = self.n * 2
-```
-```plum
-bag := Bag(n: 9)      # label "bag", items a fresh empty list, cap 18
-```
-In a struct's `init`, a top-level `self.f = expr` that names no header or base field declares an internal field: its type comes from the literal, a constructor call or an annotation (`self.f: T = expr`), and it is not a constructor parameter. Naming anything but a parameter in a call is an error (`Bag has no constructor parameter cap`), every field must be passed or set in some `init`, and `self.method()` is allowed in `init` only after every field has a value. A fresh list per construction therefore comes from `init`, never from a shared default. Field defaults (`name: Type = expr`) do not exist.
-### `match`
-```plum
-match n
-  0 => 1
-  x =>
-    if x < 0
-      -1
-    else
-      2
-match shape
-  Circle(r) => r
-  Rect(w, h) => w * h
-match book
-  FantasyBook(title, _, hasMythicalCreatures) when hasMythicalCreatures =>
-    "Fantasy book \"{title}\" features mythical creatures"
-  FantasyBook(title, _, _) => "Fantasy book \"{title}\" has no mythical creatures"
-```
-Pattern names follow a casing rule: a lowercase name always binds, a Capitalised name must be a known member or tag (`unknown tag Foo` otherwise), and a lowercase name equal to a tag is an error (`did you mean Foo?`). Patterns can be literals, a bare identifier (binds), a bare capitalized name (a member or tag of an enum; compared), a constructor pattern (`Circle(r)`, binding its fields, possibly nested), a bare member name (`Float`, which narrows the subject to that type, see [Enums](#enums)), or `_` (wildcard). `match a, b, ...` supports multiple subjects, and a case can carry a `when <expr>` guard. A `match` over an enum must be exhaustive. See [`examples/match.plum`](examples/match.plum).
-### Enum `init`
-`TypeName(args)` on an enum calls its static `init`, the same call syntax as a struct. The result is any member of the enum:
-```plum
-module shapes
-import std/Int
-import std/Str
-enum Shape =
-  | Dot
-  | Line(len: Int)
-  fun init(n: Int) -> Shape = if n == 0 then Dot else Line(len: n)
-  fun size(self) -> Int = match self
-    Dot => 0
-    Line(len) => len
-test "enum init"
-  assert Shape(0).size() == 0
-  assert Shape(7).size() == 7
-```
-## Lists, slices and arrays
-Three sequence types, from `std/List`, `std/Slice` and `std/Array`.
-**`List[T]`** is the std cons list: `Nil` or `Cons(head, tail)`. It is the default for recursive code, with pattern matching and the list literal `[1, 2, 3]` (`[]` is `Nil`). Each cell is one allocation. Self tail calls run as loops and a constructor-wrapped self call (`map`) is rewritten to a loop (tail modulo cons), so recursion over a million cells uses constant stack. `for x := range xs` works, but `at(i)` is O(i), so a plain index loop is quadratic.
-```plum
-module lists
-import std/Int
-import std/Str
-import std/List
-fun sum(xs: List[Int], acc: Int) -> Int = match xs
-  Nil => acc
-  Cons(h, t) => sum(t, acc + h)
-test "list"
-  xs := [1, 2, 3, 4]
-  assert sum(xs, 0) == 10
-  assert xs.map(|x| x * 2).length() == 4
-  total := 0
-  for x := range xs
-    total = total + x
-  assert total == 10
-```
-**`Slice[T]`** is the growable view over an `Array` (the type formerly called `List`): indexed access, `push`; `Slice[T]()` is empty and `[1, 2, 3].toSlice()` copies a list literal.
-```plum
-module slices
-import std/Int
-import std/Slice
-test "slice"
-  s := [1, 2, 3].toSlice()
-  s.push(4)
-  assert s.length() == 4
-  assert s.at(3) == 4
-```
-**`Array[T]`** is the fixed-length array, unchanged: arrays of structs are stored field by field. See [`examples/arrays.plum`](examples/arrays.plum).
-## Generics
-```plum
-struct Box[T](value: T) =
-  fun map[B](self, f: fn(T) -> B) -> Box[B] =
-    Box(value: f(self.value))
-fun wrap[T](value: T) -> Bool =
-  true
-fun firstOr[Elem](xs: List[Elem], d: Elem) -> Elem = match xs
-  Nil => d
-  Cons(h, _) => h
-```
-Generics are declared, never guessed from spelling. A type declares its own with `struct Box[T]`; a function declares its own after its name, `fun wrap[T](..)`, `fun map[B](..)`. A method sees its owner's generics (`T` in `Box.map`) without redeclaring them, and redeclaring one is an error (`T is already a generic of Box`). A generic name can be any type name (`Elem`, `Key`); an undeclared name is an ordinary type, so using one that does not exist is an error. Single letters are not special: `struct P(x: Int)` and `enum Two = A | B` are fine. Generic types, methods, and free functions are duck-typed: see [How generics compile](#how-generics-compile).
-A generic call whose type parameters stay unknown is an error at the call, before codegen: `len(Nil)` gives `cannot infer T for len(Nil); annotate, e.g. empty: Link[Int] := Nil`. Annotate the value (`empty: Link[Int] := Nil`) so `T` is known.
-### How generics compile
-Generics are duck-typed and compiled per type, as in Zig. A generic body is type-checked once per concrete instantiation, and each instantiation gets its own compiled copy with unboxed values (an array of its own element type, no boxing at generic edges): `Slice[Int]` and `Slice[Str]` are different code, and a `Slice[Float]` stores raw `f64`s.
-- **No bounds.** `[T]` carries no constraint. `fun show[T](x: T) -> Str = x.toStr()` works for every type that has a `toStr` method and fails at the use site otherwise.
-- **Errors point at the use site.** A missing method is reported against the concrete type, with the chain of instantiations that led there:
-```
-in outer[Plain] (called at main.plum:9:3):
-  in maxOf[Plain] (called at main.plum:5:3):
-    Plain has no method 'lt'
-```
-- **Unreachable generics are not emitted.** A generic that no root (a non-generic fn or a test) reaches is neither checked per type nor compiled.
-- **Bare generic types need type arguments.** `p: Parcel` is an error when `Parcel` is generic; write `p: Parcel[Int]` (or `Parcel[T]` inside a generic).
-- **Explicit behavior values.** When a generic needs behavior that is not a method on `T`, pass it explicitly, like a Zig comptime parameter or a Haskell dictionary:
-```plum
-struct Num[T](add: fn(T, T) -> T, zero: T)
-fun sumWith[T](xs: Slice[T], num: Num[T]) -> T =
-  acc := num.zero
-  for x := range xs
-    acc = num.add(acc, x)
-  acc
-```
-```plum
-intNum := Num(add: |a, b| a + b, zero: 0)
-floatNum := Num(add: |a, b| a + b, zero: 0.0)
-sumWith([1, 2, 3].toSlice(), intNum)      # 6
-sumWith([1.5, 2.5].toSlice(), floatNum)   # 4.0
-```
-  `num.add(a, b)` calls the closure stored in the fn-typed field `add`; if the type also declares a method named `add`, the method wins. See `num_record_passed_explicitly` in [`examples/generics.plum`](examples/generics.plum).
-## How fusion works
-After type checking and closure specialisation, `typedSource` runs a supercompiler stage over the checked program, before lowering (`purity`, `simplify`, `drive`, `uniqueness`, `reuse` in `plum-core`), before tail-call rewriting. The result is re-checked; if the rewritten program does not check, the original is kept, so fusion can only change speed, never meaning.
-What it does:
-- **Fuses a pure producer into its consumer.** A function is a candidate only when it is expression-bodied: bindings plus one tail expression (`= match`, `= if`, `= Ctor(..)`, `= call`); block bodies with early returns are skipped (`--explain-fusion` says `not expression-bodied`). When a candidate is pure (no `Io` reachable, no writes outside its own fresh values) and its result is used once, by a function that is one `match` on that parameter, the call is specialised on the producer's constructors and the intermediate value is never built. `sumL(mapCells(xs))` becomes one loop.
-- **List chains.** `xs.map(f).filter(g).reduce(...)`-style chains on `List` fuse the same way, so the intermediate lists disappear (the reason `List.filter` is written in direct recursive style).
-- **View to draw.** `view(state).draw(io)` fuses the scene built by a pure `view` into the draw walk, so the frame's picture tree is not allocated.
-- **Uniqueness to in-place spreads.** `markUnique` proves that a spread source (`T(..x, f: v)`) is not used afterwards and not shared, and marks the construction `unique`: codegen then writes the fields into `x` instead of copying it.
-- **Reuse.** A same-shape rebuild of a value that is dead afterwards (a `match` arm that rebuilds the constructor it matched) reuses the old cell.
-Switches: `plum build|run|test|game --no-fusion` skips the whole stage; `--explain-fusion` prints each decision to stderr (`fusion: ...`, `unique spread at fn:line`, and why a call was not specialised).
-Limits:
-- A result that is shared (used twice, stored in a field, captured by a closure) is not fused.
-- Uniqueness is proved for locals and fields of fresh values only; field assignments are not yet marked.
-- Reuse does not go through tail-recursion-modulo-cons, which runs after it.
-## Constants, statics and `primitive`
-There are no top-level constants and no free-standing statics. A constant lives inside a type's body (`enum`, `struct`) or a `primitive`; `Name = expr` declares an associated constant, and a `fun` without `self` is a static function. A constant's name is PascalCase, at least two characters, with no underscores and no two capitals in a row (`MaxRetries`, `Ln2`, `Log10E`). A constant is always read as `Type.Name`, from anywhere including inside the same body; a static is called as `Type.f(args)`, or by its bare name inside the same body. A constant is evaluated lazily, once (a heap value such as a `Slice` is cached and shared), and names are unique per type, so `Alpha.Flag` and `Beta.Flag` coexist. A constant may not share its name with a variant of its own type.
-```plum
-enum Level =
-  | Low
-  | High
-  Limit = 10                      # Level.Limit
-  fun cap(self, n: Int) -> Int =
-    if n > Level.Limit then Level.Limit else n
-struct Vec2(x: Float, y: Float) =
-  Zero = Vec2(x: 0.0, y: 0.0)     # Vec2.Zero
-  fun unit() -> Vec2 =            # a static: Vec2.unit()
-    Vec2(x: 1.0, y: 1.0)
-```
-The built-in types carry theirs: `Int.Min`, `Int.Max`, `Float.Pi`, `Float.Tau`, `Float.E`, `Float.Epsilon`, `Float.Max`, ... and the statics `Int.parse(s)` and `Float.parse(s)`.
-### `primitive`
-`primitive Name =` has two meanings, by name:
-- **a namespace**: any name that is not a built-in type declares a stateless namespace of constants and static functions, usable anywhere. It has no `self`, no values and no fields, so `Name` is not a type and can't be constructed or used as a value; it only appears as `Name.Const` or `Name.f()`. Use an `enum` when you need markers or a set of cases.
-- **a built-in's API**: `primitive Int =`, `primitive Float =`, `primitive Bool =`, `primitive Str =`, `primitive Byte =`, and `primitive Array[T] =` declare the methods, statics and constants of a compiler built-in, without declaring a dummy `enum X = | X` just to hang them on. This is only allowed in `std`; anywhere else it is an error (`primitive Int declares a built-in type and is only allowed in std`).
-```plum
-primitive Config =
-  MaxRetries = 3
-  Greeting = "hello"
-  fun doubled() -> Int =
-    Config.MaxRetries * 2
-fun main() =
-  n := Config.MaxRetries + Config.doubled()
-```
-```plum
-primitive Byte =                  # in std/Byte.plum
-  fun toInt(self) -> Int =
-    Int(self)
-```
-The std library has no free functions: each function is a static of its type or of a `primitive` namespace, so `Math.sqrt(x)`, `Os.readFile(io, path)`, `Base64.encode(s)`, `Http.get(url)` and `Testing.expectEq(a, b)` (see [Standard library highlights](#standard-library-highlights)). `Time.now(io)`, `Uuid.v4(rng)`, `Uuid.fromStr(s)`, `Random.seeded(seed)` are statics of their types. `Random` is a plain value: `r.nextInt()`, `r.nextIntBelow(n)` and `r.nextFloat()` return a `Rolled` (the `value` and the next `rng`), so the same seed gives the same sequence; `io.randomSeed()` supplies a wall-clock seed. See [`examples/constants.plum`](examples/constants.plum) and [`examples/numbers.plum`](examples/numbers.plum).
-## Closures
-```plum
-fun each(cb: fn(Int) -> Int) -> Int =
-  cb(5)
-fun useCapturingClosure() -> Int =
-  offset := 100
-  cb := |v|
-    v + offset
-  cb(5)
-fun main() -> Int =
-  each(|v| v * 3) + useCapturingClosure()
-```
-A closure literal is `|params| body`. Capture is snapshot-by-value: a closure copies the outer variables it references at creation time, not re-read live later. A `fn(...) -> T` type annotates a closure-typed parameter or field, and a named function can be passed wherever a `fn` value is expected. `Slice` and `Map` have no closure-taking iteration methods (use `for`, below); closures are for passing behavior around as values (see `Num` under [Generics](#how-generics-compile)). See [`examples/closures.plum`](examples/closures.plum).
-A closure parameter may carry a type, `|b: Box| b.get()`, and then it has that type (a mismatch with an expected `fn(..)` is a type error). An untyped closure stored in a local takes its parameter types from the first call of that local; if there is none, the error is `cannot infer the type of b; write |b: Box|`.
-A function may return a function; write the return type as `fn(A) -> B`. Bind the result and call it:
-```plum
-fun adder(n: Int) -> fn(Int) -> Int =
-  |x| x + n
-fun main() -> Int =
-  add1 := adder(1)
-  add1(2)
-```
-Calling the result of a call directly (`adder(1)(2)`) is not supported yet.
-### Automatic specialisation
-A closure literal or a function name passed directly to a `fn` parameter that the callee only calls (never stores, returns, captures or passes on) is specialised automatically: the compiler emits a copy of the callee with the closure body inlined, so there is no closure allocation and no indirect call. Captured variables become extra parameters of the copy. Escaping closures behave as before, and a callee gets at most 8 specialised copies before further call sites fall back to ordinary closure calls.
-```plum
-fun twice(f: fn(Int) -> Int, x: Int) -> Int =
-  f(f(x))
-test "specialised"
-  k := 3
-  assert twice(|v| v + k, 1) == 7
-```
-### Tail calls
-A call in tail position (the last thing a function does: the value of its body, of an `if`/`match` arm in tail position, or of a `return`) compiles to a real tail call, for direct calls, methods and closure calls, so tail-recursive loops run in constant stack and a 200000-step recursion is fine:
-```plum
-fun countUp(n: Int, acc: Int) -> Int =
-  if n <= 0 then acc else countUp(n - 1, acc + 1)
-```
-A call whose result is then used (`1 + f(x)`) or converted on return (for example a plain value wrapped in `Some`, or an `Int` widened) is not a tail call and uses stack.
-## Iteration
-`while` and `for` are the only loops, and `for x := range v` is the only `for` form (`_` ignores the value):
-```plum
-for u := range units              # a Slice or Array, by position
-  total = total + u.hp
-for i := range 10                 # an Int: 0, 1, ... 9
-  total = total + i
-for i := range 2.until(10)        # a Range (also to, downTo, stepBy)
-  total = total + i
-for x := range [1, 2, 3]          # a List
-  total = total + x
-for e := range scores.entries()   # a Map's entries: Pair(first: key, second: value)
-  total = total + e.second
-for k := range scores.keys()      # also values()
-  io.printLn(k)
-```
-Beyond `range n` (0 to n-1), the `Int` methods `a.until(b)` (a to b-1), `a.to(b)` (inclusive) and `a.downTo(b)` return a `Range`, and `r.stepBy(n)` changes its step (`for i := range 0.until(10).stepBy(3)`).
-### The iteration protocol
-The source of a `for` is one of:
-- an `Int` n: the value counts 0, 1, ... n - 1;
-- a `Slice` or `Array`: by position;
-- any value whose type has `next(self) -> Option[Pair[T, Self]]`: `None` means done, otherwise `Some(Pair(first: value, second: rest))` binds the value and the loop continues with the rest. `List`, `Range` and your own types use this.
-A user-defined iterator is an ordinary type with `next`:
-```plum
-struct Countdown(n: Int) =
-  fun next(self) -> Option[Pair[Int, Countdown]] =
-    if self.n <= 0 then None else Some(Pair(first: self.n, second: Countdown(n: self.n - 1)))
-```
-There are no generators, no sequence chains and no `for` clauses: filter with an `if` in the body, bind with `name := expr` inside the body, and build a result with a `Slice` or with `List.map`/`filter`/`fold`:
-```plum
-alive := Slice[Soldier]()
-for u := range units
-  if u.team == me.team && u.hp > 0.0
-    alive.push(u)
-```
-See [`examples/sequences.plum`](examples/sequences.plum) and [`examples/control_flow.plum`](examples/control_flow.plum).
-### Iteration cheat sheet
-| Go / Rust / streams | Plum |
-|---|---|
-| `for _, u := range units` / `for u in &units` | `for u := range units` |
-| `for i, u := range units` / `.iter().enumerate()` | `for i := range units.length()` then `u := units.at(i)` |
-| `for k, v := range m` / `for (k, v) in &m` | `for e := range m.entries()` then `e.first`, `e.second` |
-| `for i := 0; i < n; i++` / `for i in 0..n` | `for i := range n` or `range a.until(b)` |
-| `for i := n; i >= 0; i--` / `for i in (0..=n).rev()` | `for i := range n.downTo(0)` |
-| `for i := 0; i < n; i += 2` | `for i := range 0.until(n).stepBy(2)` |
-| `.iter().filter(p).collect()` | `xs.filter(p)` on a `List`, or a loop with an `if` that pushes to a `Slice` |
-| `.iter().map(f).collect()` | `xs.map(f)` on a `List` |
-| `.iter().fold(0, f)` | `xs.fold(0, f)` on a `List` |
-| `if p(x) { continue }` | `if` in the body, or `continue` |
-| generator / `yield` | a type with `next(self) -> Pair[T, Self]?` |
-## Option and Result
-There is no `null`, no optional type syntax and no exceptions. Absence is `Option[T]` (`None` or `Some(value)`) and failure is `Result[T, E]` (`Ok(value)` or `Err(error)`). Both are ordinary enums from `std/Option` and `std/Result`, so they are matched, constructed and extended like any other enum. A plain `T` is never implicitly an `Option[T]`: write `Some(x)`.
-```plum
-struct Person(name: Str, age: Int)
-fun find(n: Int) -> Option[Person] =
-  if n > 0
-    return Some(Person(name: "a", age: n))
-  return None
-```
-`Slice.get`, `head`, `last`, `first`, `pop`, `findValue`, `sample` and `Map.get` return an `Option`, because a missing element is not an error. Functions that fail for a reason return a `Result` with one error enum per module: `Int.parse`/`Float.parse` give `Result[Int, NumError]`, the `Os` file functions `Result[Str, IoError]` (`IoFailed`, `NoSuchPath`), `Json.fromStr` and `fromJson` `Result[T, JsonError]` (`InvalidJson`, `WrongJsonType`, `MissingField`).
-| Form | Meaning |
-|---|---|
-| `Some(x) := opt` + block | runs the block with `x` bound when `opt` is `Some`; an optional `else` block runs otherwise. Also inline: `if Some(x) := opt then f(x) else 0`. See [Pattern `if`](#pattern-if) |
-| `while Some(x) := opt` + block | loops while the expression is `Some`, re-evaluated each iteration |
-| `match opt` | `Some(v) => ...`, `None => ...` (exhaustive); for a result, `Ok(v)` / `Err(e)` |
-| `opt.unwrapOr(default)` | the value, or `default` when `None` (or `Err`) |
-| `opt.map(f)`, `opt.andThen(f)` | map over a present value; `andThen` takes a function that itself returns an `Option` (or `Result`) |
-| `res.mapErr(f)` | change the error value, e.g. into the calling module's error enum |
-| `opt.okOr(err)`, `res.ok()` | convert between `Option` and `Result` |
-| `x?` | propagate: the value of an `Ok`/`Some`, or return the `Err`/`None` from the enclosing function |
-| `x!` | unwrap: the value, or crash with the source position (`file:line`) |
-```plum
-fun total(xs: Slice[Option[Int]]) -> Int =
-  sum := 0
-  for x := range xs
-    if Some(n) := x
-      sum = sum + n
-  sum
-fun firstOrZero(xs: List[Int]) -> Int =
-  xs.head().unwrapOr(0)
-```
-### Propagating: `x?`
-`x?` is a postfix operator. On a `Result` it evaluates to the `Ok` value, or returns the `Err` from the enclosing function, which must itself return a `Result` with the same error type. On an `Option` it evaluates to the `Some` value, or returns `None` from a function returning an `Option`. Postfix operators and calls bind tighter than anything else, so `a.b()?.c()` is `{a.b()?}.c()`. To mix error types, convert with `mapErr` first.
-```plum
-enum ParseError =
-  | BadNumber
-  | Negative
-fun parsePositive(s: Str) -> Result[Int, ParseError] =
-  n := Int.parse(s).mapErr(|e| BadNumber)?
-  if n < 0
-    return Err(Negative)
-  Ok(n)
-fun sumTwo(a: Str, b: Str) -> Result[Int, ParseError] =
-  x := parsePositive(a)?
-  y := parsePositive(b)?
-  Ok(x + y)
-fun firstOf(xs: Slice[Int]) -> Option[Int] =
-  h := xs.head()?
-  Some(h * 2)
-```
-A function that has an `Option` in hand and wants an error uses `okOr`: `xs.head().okOr(Empty)?`.
-### Handling in place
-`match` handles each case, with a default or a recovery per arm; `unwrapOr` supplies a plain default:
-```plum
-fun sumOrZero(a: Str, b: Str) -> Int =
-  x := parsePositive(a).unwrapOr(0)
-  y := parsePositive(b).unwrapOr(0)
-  x + y
-fun describeAge(s: Str) -> Str =
-  match parsePositive(s)
-    Ok(n) => "age {n}"
-    Err(BadNumber) => "not a number"
-    Err(Negative) => "can't be negative"
-```
-The patterns are positional, so a `match` over a `Result[T, ParseError]` is exhaustive once every variant of `ParseError` is covered; adding a variant points you at every `match` that has to deal with it. Cases in an error enum carry data like any other variant, and `name()`-style helpers are ordinary methods.
-### Crashing: `x!` and `crash`
-`x!` unwraps an `Option` or `Result`, or crashes with a message that shows the source position (`file:line`). `!=` wins by maximal munch, so write `{f()!} == x`. `crash "msg"` aborts the same way. Use both for bugs (a broken invariant), not for expected failures; `unwrap()` is the method form.
-See [`examples/errors.plum`](examples/errors.plum) and [`examples/error_propagation.plum`](examples/error_propagation.plum).
-## Testing
-Zig-style `test` blocks are a native language feature, compiled and run only by `plum test`. `plum test` takes files and directories (searched recursively) and runs only the tests declared in those files, not the ones in their imports:
-```plum
-fun add(a: Int, b: Int) -> Int =
-  a + b
-test "add works"
-  assert add(1, 2) == 3
-```
-```sh
-$ plum test examples/basics.plum
-└─ add works ✔
-1 passed, 0 failed
-```
-A failing `assert` prints the actual and expected values for `==` comparisons. `import std/Testing` adds small assertion helpers (`Testing.expectEq`, `Testing.expectTrue`, `Testing.expectSuccess`, ...). The `std` library and every file in `examples` carry their own tests: `plum test std examples`.
-## `extern` functions and hosts
-```plum
-import std/Io
-fun main(io: Io) =
-  io.printLn("hello")
-```
-Every call that leaves the program (printing, files, clock, randomness, network, drawing, input, sound) is a method of the built-in `Io` capability, declared once as `extern fun` methods in `primitive Io` (`std/Io.plum`); an `Io` cannot be constructed in user code, so no host import is reachable without one. An entry point (`main`, an `export fun`, a `test`) may take it as its first parameter (a `test` gets `io` implicitly), and code passes it down only to the functions that do I/O, so a function with no `Io` reachable cannot touch the host. That is all purity is: there is no function colouring and no `pure` keyword. An `extern fun` method declares a function backed by a host-provided wasm import (module `plum`, the function's name), with no Plum body. At the boundary `Int` is narrowed to a wasm `i32` (the rest of the language uses 64-bit `Int`), so extern parameters and results are 32-bit, and an extern can't return an error union. The `io` parameter is not part of the wasm ABI. `plum run`, `plum test` and `plum build` provide the standard host functions (printing, `crash`, clock and random, files, HTTP).
-```sh
-$ plum run examples/basics.plum
-hello from plum
-hello, world!
-```
-## `export fun`
-```plum
-export fun step(n: Int, v: Vec2) -> Vec2 =
-  Vec2(x: v.x + 1.0, y: v.y * 2.0)
-```
-`export fun` (top level only: not a method, not generic, no error-union result) is an ordinary Plum function that is also exported from the wasm module under its own name. Its boundary uses the `extern fun` ABI: `Int` is narrowed to `i32`, `Float` is `f64`, `Bool` is `i32`, a struct is flattened into its fields' values, and `Str` and structs are GC references. Plum code can still call it directly with the normal internal ABI. A function can't be both `extern` and `export`.
-Every module that imports `std/Str` also exports four helpers for hosts that can't read GC structs: `strLen(s) -> i32`, `strByte(s, i) -> i32`, `strNew(n) -> Str` (n zero bytes) and `strSetByte(s, i, b)` (for a fresh `strNew` result only).
-## Games
-Games run in the browser on Plum's own WebGPU renderer (`compiler/game/web/plum_bridge.js`): the Plum module calls the bridge directly, one extern call per draw, and the bridge batches everything into one buffer upload per frame. A draw call binds up to 16 textures (each vertex carries its texture slot), so mixing atlases in y-sorted scenes costs a handful of draw calls; the canvas is `CSS size x devicePixelRatio` while every game coordinate (`screenWidth`, `mousePos`, the camera) stays in CSS pixels; text is drawn from a signed-distance-field glyph atlas, so it stays crisp at any size or zoom; and if the GPU device is lost the renderer requests a new one, re-uploads the textures and logs `GPU device lost (<reason>); restored` (render-target contents start transparent again). WebGPU is required (Chrome or Edge, Safari 26+, Firefox); there is no fallback. The bridge reads nothing from the wasm module's import or export lists (`WebAssembly.Module.imports` throws in Safari for typed GC references), so it loads the same way in Safari; `plum-web-test --browser webkit` checks that against Playwright's WebKit.
-`plum game file.plum [--assets DIR] [--port N] [--no-open]` compiles the game, serves it on 127.0.0.1 (port 8080, else any free port; `--port` picks one), prints the URL and opens the default browser unless `--no-open` is given. Ctrl-C stops it. `plum game file.plum -o dist [--assets DIR]` writes a static build instead and exits: `index.html`, `plum_bridge.js`, `plum.wasm`, `preload.txt` and an `assets/` copy of the whole asset directory (every file in it is listed in `preload.txt` and fetched before the first frame). Host that directory on any static file server; the browser needs wasm GC support. The asset root defaults to `assets` beside the source file.
-`examples/games/imperative/game.plum` is a small arcade game: steer a ship with the arrow keys or WASD, collect orbs, dodge mines (Enter restarts). It draws shapes, text, additive orb glow (`io.blendMode(Blend.Add)`) and an animated sprite sheet (`examples/games/assets/sprites.png`, generated by `examples/games/tools/make_sprites.py`) and plays music and sound effects (`examples/games/assets/*.wav`, generated by `examples/games/tools/make_sounds.py`); both generators live outside the asset dir so they are not shipped. For a bigger game built on this engine see the Knights and Merchants port in the sibling repo `../kam_plum` (`./run.sh` there). Its rules are plain functions with `test` blocks, so `plum test examples` covers them without a browser.
-**`std/game/imperative/Scene`** is a scene-graph library written in Plum (see [`examples/games/imperative/scene.plum`](examples/games/imperative/scene.plum)): a tree of actors under a `Stage`, with parent-relative position, rotation, scale and colour, per-actor `act`, `draw` and `hit` behaviour, a camera and hit testing; its demo renders a minimap into a texture with `textureCreate` and `renderTarget`. Use it for UI and other hierarchical scenes, where moving a parent should move everything in it. It is libGDX Scene2D-style subclassing on a base struct (a game's own world can embed the `Stage` struct to get its root, camera and `act`/`draw`, see [Embedding structs and override](#embedding-structs-and-override)): `Actor` is a base struct holding the position, size, origin, scale, rotation, colour, visibility, children and culling fields, and `Group`, `Sprite`, `Rect`, `Circle` and `Text` are structs embedding it. `Actor.init` sets every field (position and size 0.0, scale 1.0, white, visible, a fresh `children` list), so a struct exposes only what a caller passes (`struct Rect(Actor(width, height, color))`) and its own `init` sets the rest. A game adds its own kinds the same way and overrides what it needs:
-```plum
-struct Walker(Actor(x, y), speed: Float) =
-  fun init(self) =
-    self.width = 8.0
-    self.height = 8.0
-    self.color = Color.Red
-  override fun act(self, dt: Float) =
-    self.x = self.x + self.speed * dt
-  override fun draw(self, m: Affine, alpha: Float) =
-    drawRectBox(m, alpha, self.width, self.height, self.color)
-```
-```plum
-stage.root.add(Walker(x: 0.0, y: 40.0, speed: 30.0))
-```
-The default `act` acts the children (an override that keeps children calls `self.actChildren(dt)`), the default `draw` paints nothing and the default `hit(p)` tests the width by height box. Compare actors with `same(a, b)`, not `==` (actors are compared by identity). For a large world, keep the game objects in flat structs and lists instead (for example `enum Entity = Unit | House`) and draw them directly through `std/game/Game`.
-`std/game/imperative/Scene` follows libGDX Scene2D for draw order and culling. An actor's z-index is its position in its parent's child list (draw order is list order, hit testing goes in reverse):
-```plum
-a.zIndex()                              # index among its siblings, -1 without a parent
-a.setZIndex(0)                          # move within the parent (clamped to 0..length-1)
-a.toFront()                             # last child: drawn on top, hit first
-a.toBack()                              # first child: drawn first
-world.sortChildren(|a, b| a.y < b.y)    # stable, in place, no allocation once warm
-world.setCullingArea(cam.x, cam.y, viewW, viewH)   # in world's own coordinates
-world.clearCullingArea()
-```
-`sortChildren(before)` is a natural merge sort with a scratch list kept on the actor: a list that is already sorted costs n - 1 comparisons and a nearly sorted one (a y-sorted layer re-sorted every frame) about 2n, with O(n log n) as the worst case; equal keys keep their order, so ties do not flicker. `setCullingArea` makes a group skip each direct child whose box (position and size, scaled about its origin; rotation ignored) lies outside the rectangle, in both `draw` and `hit`, with the child's whole subtree; children with no size (plain groups) are never culled. In [`compiler/game/web-test/BENCHMARK.md`](compiler/game/web-test/BENCHMARK.md) a 20,000-sprite y-sorted layer costs 1.15 ms per frame with culling and 4.20 ms without on the earlier closure-based `Node` (2.09 ms with culling on the `Actor` base struct).
-A layered world (a layer recipe for a large map) is a few groups under the stage root, drawn in order: `terrain` (static, culled), `world` (y-sorted every frame, culled), `effects` (culled) and `ui` (not culled, in screen space with a second `Stage` or camera). Each frame: `world.sortChildren(|a, b| a.y < b.y)`, then `setCullingArea` on `terrain`, `world` and `effects` from the camera view.
-A game declares three exports. `G` is any struct and holds all game state (there are no globals):
-```plum
-export fun init(io: Io) -> G
-export fun update(io: Io, g: G, dt: Float)
-export fun draw(io: Io, g: G)
-```
-The page calls `init` once after the assets are loaded, then `update` and `draw` every frame. A game imports `std/Io`, `std/game/Game`, `std/game/Vec2` and `std/game/Color`; pure logic can import `std/game/Vec2` and `std/game/Color` alone. Under `plum test` and `plum run` the host functions are stubs that trap with `host function 'X' is not available here`, so `test` blocks work as long as they don't call the host.
-**Headless tests:** the `plum-game` crate (a standalone crate, wasmtime only) runs a compiled game with no browser against a `Recorder` backend that logs every host call as a string and answers input from scripted values, so `cargo test --manifest-path compiler/game/Cargo.toml` checks games' draw-call sequences (`compiler/game/tests/host_test.rs`). `plum-game <wasm> [--assets DIR] [--frames N]` does the same from the command line and prints the host calls of the last frame.
-**Immediate mode or Scene?** [`examples/games/imperative/game.plum`](examples/games/imperative/game.plum) is immediate mode: one state struct, a pure `update`, and `draw` issues the calls each frame; it suits flat arcade games with a few kinds of thing. [`examples/games/imperative/scene.plum`](examples/games/imperative/scene.plum) and [`examples/games/imperative/game_scene.plum`](examples/games/imperative/game_scene.plum) are retained mode on the `Actor` base struct: a tree with transforms, z-order, culling, hit-testing and per-kind `act`/`draw`, which suits UI, layered worlds and unit crowds. `game_scene.plum` is the same Orb Run as `game.plum` rebuilt on the scene graph, so you can compare the two styles on identical rules.
-### Pure scene graph
-The pure scene graph is the same kind of tree as `std/game/imperative/Scene`, but a function never changes a value it was only given: updates take a node, change it in place when it is proved unique (see [In-place updates](#in-place-updates)) and hand it back, so no `clone()` is needed. Every node is a `Node` struct (a `Transform`, an id, colour, visibility, its running `actions` and a `Kind`: `Group`, `Sprite`, `Label`, `Button` or `Custom(actor)`); game behaviour is an `Actor` struct in a `Custom` node. The graph is three modules: `std/game/pure/Actions` (timed `Action`s such as `Action.forever(Action.rotateBy(..))`), `std/game/pure/PureScene` (`Node` and its methods: `Node.group`/`sprite`/`label`/`button`/`custom`, `update`, `drawTree`, `findHit`, `findPath`, `modify` and `route`) and `std/game/pure/SceneInput` (`Stage`, pointer capture, `Input.poll`). A game imports them by name:
-```
-import std/game/pure/Actions
-import std/game/pure/PureScene
-import std/game/pure/SceneInput
-```
-A minimal game holds a `Stage` and replaces it each frame:
-```
-struct World(mut stage: Stage, mut wasDown: Bool)
-export fun init(io: Io) -> World =
-  spr := Node.sprite(2, 0, 100.0, 100.0, 48.0, 48.0)
-  spinning := Node(..spr, actions: [Action.forever(Action.rotateBy(1.0, 1.0))].toSlice())
-  root := Node.group(1, 0.0, 0.0, 800.0, 600.0, [spinning].toSlice())
-  World(stage: Stage.create(root), wasDown: false)
-export fun update(io: Io, w: World, dt: Float) =
-  inputs := Input.poll(io, w.wasDown)
-  w.wasDown = io.isMouseDown(0)
-  w.stage = w.stage.frame(dt, inputs).intoStage()
-export fun draw(io: Io, w: World) =
-  w.stage.draw(io)
-```
-- **Immediate mode** ([`game.plum`](examples/games/imperative/game.plum)): one state struct 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`](examples/games/imperative/game_scene.plum)): a retained tree of actors with `mut` fields. Use it when you want objects that change in place and a familiar `act`/`draw` object model.
-- **Pure scene** ([`game_pure_scene.plum`](examples/games/pure/game_pure_scene.plum)): every update takes an actor and hands back an updated one (written in place when uniqueness proves it), 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`](examples/games/functional/game_state_view.plum)): the game state is plain data and a `view` turns it into a `SceneNode` (`std/game/functional/FunctionalScene`), a recursive data type whose methods draw, measure and hit-test it. Use it when you want to draw from state instead of keeping a tree of actors.
-### Functional scenes (state/view)
-Three scene styles ship, each in its own folder: `std/game/imperative/Scene` (actors with `mut` fields, in `examples/games/imperative`), `std/game/pure/*` (pure-update actors, in `examples/games/pure`) and `std/game/functional/*` (plain state plus a `view`, in `examples/games/functional`); the shared assets and generators are in `examples/games/assets` and `examples/games/tools`. The functional style is a loop of `State -> view -> draw`: the game state is plain data, `view(state)` builds a `SceneNode` (`std/game/functional/FunctionalScene`) and `draw` walks it. Nothing is retained between frames.
-The functional game is written in a component style: each kind of thing is a struct with an `update(self, ..)` that returns the next value and a `render(self, ..)` that returns its `SceneNode` (`Ship.update`/`Ship.render`, `Orb`, `Mine`, `Star`), and `State.render` composes them. `update` never changes a value it was given.
-- **`Anim`** describes motion as a function of time: `MoveBy`, `RotateBy`, `ScaleTo`, `Delay`, `Seq`, `Par` and `Forever`. `Anim.at(anim, t)` returns an `AnimPose` (dx, dy, rotation, scaleX, scaleY) for any `t`, so a view just applies the pose for `state.clock`.
-- **`Ui`** is pure pointer state. `view.hitId(x, y)` finds the `Clickable(id, msg, child)` node under the pointer; `Ui.step(ui, input, hit)` returns a `UiStep` with the new `UiState` and the `UiEvent`s raised (`Press`, `Release`, `Click`, `Enter`, `Exit`, with pointer capture), and `Ui.messages(view, events)` turns the clicks into the game's own messages. `Ui.button(id, msg, label, x, y, w, h, ui)` builds a button that shows hover and pressed looks and sends `msg` when clicked. The picture is a `SceneNode[Msg]`, generic over the game's message type.
-From [`game_state_view.plum`](examples/games/functional/game_state_view.plum) (a method of `State`): `feed` runs `Ui.step` against the picture the player sees, then hands each event to `update`.
-```
-fun feed(self, input: Input) -> State =
-  pos := input.position()?
-  view := self.render()
-  r := Ui.step(self.ui, input, view.hitId(pos.x, pos.y))
-  Ui.messages(view, r.events).fold(State(..self, ui: r.ui), |s, m| s.update(m))
-```
-The button's id only identifies it for hover and press state (a boxed struct's `==` is identity today, structural `==` is a deferred item); what a click means is its message.
-**Browser check:** `cargo run --manifest-path compiler/game/web-test/Cargo.toml -- examples/games/imperative/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). `compiler/game/web-test/fixtures/` has `interleave.plum`, `text_sizes.plum` and `rendertarget.plum` for these. One-time setup: `cargo run --manifest-path compiler/game/web-test/Cargo.toml --example install-browsers`. See [`compiler/game/web-test/README.md`](compiler/game/web-test/README.md); `docs/game.png` above was made with `--screenshot`. [`compiler/game/web-test/BENCHMARK.md`](compiler/game/web-test/BENCHMARK.md) records the renderer benchmark that led to this design.
-**Asset root:** textures and files are read relative to the asset root. A path that escapes the root (`..` or absolute) fails like a missing file: `-1`, `""` or `false`. The headless runner's root is `--assets` or `assets` beside the wasm; it reads image headers for `textureWidth`/`textureHeight` and structs sounds without decoding them.
-**Sounds:** the browser decodes every `.wav` and `.ogg` file of the asset root before `init`, and `soundLoad` looks the decoded sound up by path with the same path rules as `textureLoad`. Browsers only start audio after a user gesture (a key press or click); sounds played before that are silent, and the music of the example begins once you press a key.
-**Host API** (methods of `Io`, called `io.drawRect(..)` etc.; `Key`, `Mouse` and `Blend` are in `std/game/Game`; texture and sound handles are `-1` on failure; coordinates are world units once a camera is set):
-| function | meaning |
-|---|---|
-| `screenWidth()`, `screenHeight()`, `frameTime()` | canvas size in CSS pixels (the unit of game coordinates, independent of the device pixel ratio), last frame time in seconds |
-| `clear(c)` | fill the screen |
-| `drawRect(x, y, w, h, c)`, `drawCircle(x, y, r, c)`, `drawLine(x1, y1, x2, y2, thickness, c)`, `drawText(s, x, y, size, c)` | shapes and text (`x, y` is the text's top-left, a circle's centre) |
-| `setCamera(x, y, scale)`, `resetCamera()` | world point `(x, y)` maps to the screen's top-left, one world unit is `scale` pixels |
-| `textureLoad(path)` | load an image (PNG at least) relative to the asset root |
-| `textureWidth(t)`, `textureHeight(t)` | size in pixels (0 for a bad handle) |
-| `textureCreate(w, h)` | a blank, transparent texture to draw into (`-1` if a side is below 1 or above 8192) |
-| `renderTarget(t)` | following draws and `clear` go into texture `t`, or to the screen for `-1`; each target has its own camera (reset to its pixels when selected, the screen's is restored on return); contents persist across frames |
-| `blendMode(m)` | `Blend.Normal`, `Blend.Add`, `Blend.Multiply` or `Blend.Screen` for the following draws; every frame starts with Normal |
-| `textureSetSmooth(t, smooth)` | linear (`true`) or nearest (`false`, the default) filtering |
-| `drawTexture(t, x, y, tint)` | the texture at its natural size, top-left at `(x, y)` |
-| `drawTextureEx(t, sx, sy, sw, sh, x, y, w, h, rotation, flipX, tint)` | source rect `(sx, sy, sw, sh)` in texture pixels drawn into dest rect `(x, y, w, h)`, rotated `rotation` radians clockwise about the dest centre |
-| `soundLoad(path)` | a handle for a WAV or OGG file relative to the asset root (`-1` on failure) |
-| `soundPlay(s, volume)`, `soundLoop(s, volume)` | one-shot play (plays may overlap) and start looping; `volume` is 0..1 |
-| `soundStop(s)`, `soundSetVolume(s, volume)` | stop every play of the sound; change its volume. A bad handle is a no-op |
-| `fileExists(path)`, `fileLoad(path)` | whole file as a `Str` (`""` if missing), relative to the asset root |
-| `isKeyDown(k)`, `isKeyPressed(k)`, `isMouseDown(b)`, `isMousePressed(b)` | input; `k` is a `Key` constant, `b` a `Mouse` constant |
-| `mousePos()`, `mouseWheel()` | pointer in CSS pixels; wheel direction this frame (+ is up) |
-`Key` constants use GLFW numbering: `Key.Space`, `Key.KeyA` to `Key.KeyZ`, `Key.Num0` to `Key.Num9`, `Key.Escape`, `Key.Enter`, `Key.Tab`, `Key.Backspace`, `Key.Right`, `Key.Left`, `Key.Down`, `Key.Up`, `Key.LeftShift`, `Key.LeftControl`. `Mouse` has `Mouse.Left`, `Mouse.Right` and `Mouse.Middle`; `Blend` has `Blend.Normal`, `Blend.Add`, `Blend.Multiply` and `Blend.Screen`. `Color` holds RGBA channels in 0..1 with the constants `White`, `Black`, `Red`, `Green`, `Blue`, `Yellow` and `Transparent`, plus `Color.rgb(r, g, b)` and `withAlpha(a)`.
-## Standard library highlights
-- **`Bool`** — `true`/`false`, `if`, `&&`/`||`/`!` and `==` are built in (no import); `toStr` (also used by `"{b}"` interpolation) and `Bool.parse("true")` need `import std/Bool`
-- **`Int`** / **`Float`** (`import std/Int`, `import std/Float`) — built-in numbers with their API in `primitive Int` / `primitive Float`: `abs`, `sign`, `min`, `max`, `sqrt`, `pow`, `floor`, `round`, `toStr`, ... (constants and `parse`: see [Constants](#constants-statics-and-primitive))
-- **`Math`** (`import std/Math`) — a `primitive` namespace of floating-point functions: `Math.sqrt`, `Math.sin`, `Math.exp`, `Math.ln`, ...
-- **`Str`** (`import std/Str`) — an immutable view of a packed byte array, with a codepoint-aware layer for Unicode correctness (`runeLength`, `runeAt`, `codePointAt`, `Str.codePointToStr(cp)`). Substrings (`sub`, `slice`, `trim*`, `split` parts) share their source's bytes instead of copying; `s.clone()` detaches one
-- **`Byte`** (`import std/Byte`) — a scalar unsigned 8-bit value; `Array[Byte]` stores one byte per element
-- **`Buffer`** (`import std/Buffer`) — a growable, mutable byte sequence for building up a `Str`, amortized O(n) writes
-- **`Array[T]`** (`import std/Array`) — the compiler-intrinsic fixed-length array that `Slice`, `Map` and `Str` are written on, with `Array.copy` and `Array.equal` for scalar ranges; `Grid[T]` is a flat 2D array
-- **`Slice[T]`** (`import std/Slice`) — a growable list built on `Array`, with `get`/`add`/`set`/`removeAt`/`remove`/`sort`/`join`/`chunk` (iteration and transformation via `for`). `xs.slice(i, j)` returns a view: a `Slice` over the same storage, with no copy. `set` on a view changes the original and a `push` on a view moves it to its own storage first; reordering the original in place (`removeAt`, `reverse`) is visible through its views, so use `sublist(i, j)` for a copy
-- **`Map[K, V]`** (`import std/Map`) — `["a" => 1, "b" => 2]` builds a `Map[Str, Int]` (it is `Map.empty().with("a", 1).with("b", 2)`); `m: Map[K, V] := Map.empty()` is empty. A key can be any expression (`[n + 1 => x]`). A later duplicate key wins, as with `set`. See [`examples/maps.plum`](examples/maps.plum)
-- **`Set[T]`**, **`Deque[T]`**, **`Heap[T]`** — a set over `Map`'s bucketed hash table, a ring-buffer double-ended queue and a key-ordered min-heap
-- **`Json`**, **`Base64`**, **`Uuid`**, **`Time`**, **`Random`** — parsing, encoding, ids, wall-clock time and a seeded deterministic generator value (`Random.seeded(n)`; the wall-clock seed comes from `io.randomSeed()`)
-- **`Os`**, **`Http`** — printing and the file system (`Os.readFile`, `Os.writeFile`, ...); HTTP requests through the host (`Http.get`, `Http.post`, ...)
-- **`Testing`** (`import std/Testing`) — assertion helpers for `test` blocks
-See [`examples/`](examples) for a runnable file per feature above, and [`std/`](std) for the standard library source.
-### JSON
-`import std/Json` adds `Json.encode(x)` and `Json.decode(s)`. A type encodes when it has `toJson(self) -> Json` and decodes when it has a static `fromJson(j: Json) -> Result[T, JsonError]`. `Int`, `Float`, `Bool`, `Str`, `Slice[T]` and `Map[K, V]` get both methods from `std/Json`, so they exist only in programs that import it. `Int.fromJson` rejects fractions and magnitudes of 2^53 or more. `decode` takes `T` from the annotation, and `JsonError` is `InvalidJson | WrongJsonType | MissingField`.
-```plum
-struct Point(x: Int, y: Int) =
-  fun toJson(self) -> Json =
-    Json.object(["x" => self.x.toJson(), "y" => self.y.toJson()])
-  fun fromJson(j: Json) -> Result[Point, JsonError] =
-    x := Int.fromJson(j.field("x")?)?
-    y := Int.fromJson(j.field("y")?)?
-    return Ok(Point(x: x, y: y))
-```
-Using it:
-```plum
-text := Json.encode(Point(x: 1, y: 2))
-p: Result[Point, JsonError] := Json.decode(text)
-```
-Also available: `Json.decodeWith(s, fn)`, `j.field(name)`, `j.optField(name)`, `Json.object(...)`, `Json.array(...)` and `j.into()` (which is `T.fromJson(j)`). Limits:
-- There are no explicit call-site type arguments: `Json.decode[House](s)` does not parse, so annotate the result instead.
-- `Option[T]` has no built-in `toJson`/`fromJson` yet; write them by hand.
-- `Slice[Int].fromJson(j)` does not parse; use `j.into()` or `Json.decode`.
-- There is no derive: structs write `toJson`/`fromJson` by hand.
-See [`examples/json.plum`](examples/json.plum).
-## Planned performance work
-These are compiler optimizations, not language changes; none of them changes what a program means or how it is written.
-- **No allocation for local lists and views.** A `Slice`, a `Slice.slice` view or a `Str` substring that never leaves its function (isn't stored, passed on or returned) could keep its fields in locals instead of allocating its small struct (escape analysis).
-- **Loops read a list once.** `for x := range xs` could read `xs`'s storage, start and size once before the loop instead of on every step, and `xs.get(i)` loops could do the same when the body can't change `xs`.
-- **Inlined `get`, `set` and `push`.** These small `Slice` and `Array` methods are function calls today. Inlining them removes the call and lets the wasm engine keep values in registers.
-- **No placeholder `self` for statics.** A static such as `Vec2.zero()` still receives an unused `self` slot (one per field for a struct), which could be dropped from its signature.
-- **Fewer boxed structs.** A flat struct stored in a boxed struct field, or carried in an error union is boxed (one allocation); it could be stored inline instead.
-- **Host string reads.** When the host prints or writes a `Str`, it copies the whole backing array and then takes the `[start, start + len)` part; it could copy only that range.
-## Editor support
-```sh
-plum editor helix     # tree-sitter grammar, queries and plum-lsp for Helix
-plum editor vscode    # the VSCode extension (add --insiders for VSCode Insiders)
-```
-Both install syntax highlighting and the `plum-lsp` language server (syntax and type diagnostics, keyword and member completion). The grammar, queries and VSCode extension live in [`compiler/tooling/`](compiler/tooling); everything is embedded in the `plum` binary, so the commands work from any directory. Reload the editor window afterwards.
+![the example game](docs/game.png)

compiler/lsp/src/main.rs CHANGED Viewed

@@ -1085,13 +1085,22 @@ mod tests {
         assert!(n > 10, "found only {n} examples");
     }
-    /// Every ```plum block in the README parses without a syntax diagnostic
+    /// Every ```plum block in the README and docs parses without a syntax diagnostic
     /// (statement fragments are wrapped in a function first).
     #[test]
-    fn readmeSnippetsHaveNoSyntaxDiagnostics() {
+    fn docSnippetsHaveNoSyntaxDiagnostics() {
+        let files = [
+            "README.md",
+            "docs/language.md",
+            "docs/std.md",
+            "docs/game.md",
+            "docs/tools.md",
-        let readme = std::fs::read_to_string(repoRoot().join("README.md")).unwrap();
+            "docs/performance.md",
+        ];
         let mut n = 0;
+        for file in files {
+        let text = std::fs::read_to_string(repoRoot().join(file)).unwrap();
-        let mut rest = readme.as_str();
+        let mut rest = text.as_str();
         while let Some(i) = rest.find("```plum\n") {
             let body = &rest[i + 8..];
             let end = body.find("```").unwrap();
@@ -1137,7 +1146,7 @@ mod tests {
                 let (items, stmts) = block.split_at(block.find("\nintNum").unwrap() + 1);
                 assert!(
                     Backend::syntaxDiagnostics(&Backend::parseTree(items), items).is_empty(),
-                    "items:\n{items}"
+                    "{file} items:\n{items}"
                 );
                 let wrapped = format!(
                     "fun frag() =\n{}",
@@ -1148,14 +1157,15 @@ mod tests {
                 );
                 assert!(
                     Backend::syntaxDiagnostics(&Backend::parseTree(&wrapped), &wrapped).is_empty(),
-                    "stmts:\n{stmts}"
+                    "{file} stmts:\n{stmts}"
                 );
             } else {
-                assert!(d.is_empty(), "README snippet has syntax errors:\n{block}");
+                assert!(d.is_empty(), "{file} snippet has syntax errors:\n{block}");
             }
             n += 1;
         }
+        }
-        assert!(n > 20, "found only {n} README snippets");
+        assert!(n > 20, "found only {n} doc snippets");
     }
     /// A type error is published at the position its `Diagnostic` reports (1-based there,

docs/game.md ADDED Viewed

@@ -0,0 +1,93 @@
+# The game engine
+Write a game in Plum and run it in the browser on Plum's own WebGPU renderer. It needs a browser with WebGPU: Chrome, Edge, Firefox or Safari 26+.
+![the example game](game.png)
+## Try it
+```sh
+plum game examples/games/imperative/game.plum
+```
+This builds the game, starts a local server and opens your browser. Steer with the arrow keys or WASD, collect the orbs and dodge the mines. Press a key first, because browsers only start sound after you interact with the page.
+## A minimal game
+A game exports three functions. Your state goes in a struct of your choice, as there are no globals.
+```plum
+import std/Int
+import std/Float
+import std/Str
+import std/Io
+import std/game/Game
+import std/game/Vec2
+import std/game/Color
+struct World(mut x: Float)
+export fun init(io: Io) -> World =
+  World(x: 0.0)
+export fun update(io: Io, w: World, dt: Float) =
+  if io.isKeyDown(Key.Right)
+    w.x = w.x + 100.0 * dt
+export fun draw(io: Io, w: World) =
+  io.clear(Color.Black)
+  io.drawRect(w.x, 100.0, 40.0, 40.0, Color.Red)
+```
+`init` runs once after the assets load. `update` and `draw` then run every frame.
+## Drawing and input
+These are methods on `io`, for example `io.drawRect(..)`.
+| Group | Functions |
+|---|---|
+| Screen | `screenWidth()`, `screenHeight()`, `frameTime()`, `clear(color)` |
+| Shapes | `drawRect(x, y, w, h, c)`, `drawCircle(x, y, r, c)`, `drawLine(x1, y1, x2, y2, thickness, c)` |
+| Text | `drawText(s, x, y, size, c)` |
+| Camera | `setCamera(x, y, scale)`, `resetCamera()` |
+| Images | `textureLoad(path)`, `drawTexture(t, x, y, tint)`, `drawTextureEx(t, sx, sy, sw, sh, x, y, w, h, rotation, flipX, tint)`, `textureWidth(t)`, `textureHeight(t)`, `textureSetSmooth(t, smooth)` |
+| Draw to an image | `textureCreate(w, h)`, `renderTarget(t)` (`-1` goes back to the screen) |
+| Blending | `blendMode(m)` with `Blend.Normal`, `Blend.Add`, `Blend.Multiply`, `Blend.Screen` |
+| Sound | `soundLoad(path)`, `soundPlay(s, volume)`, `soundLoop(s, volume)`, `soundStop(s)`, `soundSetVolume(s, volume)` |
+| Keyboard | `isKeyDown(k)`, `isKeyPressed(k)` with `Key.Space`, `Key.KeyA`, `Key.Up`, `Key.Enter`, ... |
+| Mouse | `mousePos()`, `mouseWheel()`, `isMouseDown(b)`, `isMousePressed(b)` with `Mouse.Left`, `Mouse.Right`, `Mouse.Middle` |
+| Files | `fileExists(path)`, `fileLoad(path)` |
+Colors come from `Color.White`, `Color.Red` and so on, or `Color.rgb(r, g, b)`. `textureLoad` and `soundLoad` return `-1` if the file can't be loaded.
+## Assets
+Images and sounds are loaded from an `assets` folder next to your game, or from the folder you pass with `--assets`. WAV and OGG sounds are supported. Paths are relative to that folder and can't leave it.
+## Ways to structure a game
+Drawing directly is enough for small games. For bigger ones, Plum includes three scene libraries. All of them are in [`std/game`](../std/game), and each has an example game.
+| Style | How it works | Good for | Example |
+|---|---|---|---|
+| **Direct drawing** | One state struct, and `draw` makes the calls each frame | small arcade games | [`game.plum`](../examples/games/imperative/game.plum) |
+| **Imperative scene** | A tree of objects that you change in place | UI, and objects with their own behaviour | [`game_scene.plum`](../examples/games/imperative/game_scene.plum) |
+| **Pure scene** | A tree where each update returns the next version | rules you can test without a browser | [`game_pure_scene.plum`](../examples/games/pure/game_pure_scene.plum) |
+| **State and view** | Plain data, and a `view` function draws it each frame | games that are simple to reason about | [`game_state_view.plum`](../examples/games/functional/game_state_view.plum) |
+These four examples play the same kind of game, so you can compare them side by side. [Game scene styles](game-scene-styles.md) goes deeper into the differences, and [imperative vs functional](imperative-vs-functional.md) compares the code.
+## Testing a game
+Put your rules in plain functions with `test` blocks, and `plum test` runs them with no browser. Calling a drawing function under `plum test` stops with an error, so keep those calls out of the code you test.
+To check a game actually renders, the browser test tool runs it in headless Chromium. See [its README](../compiler/game/web-test/README.md).
+## Publishing
+```sh
+plum game game.plum -o dist
+```
+This writes a static site to `dist`, ready for any static file host.

docs/language.md ADDED Viewed

@@ -0,0 +1,526 @@
+# The Plum language
+A tour of the language, one idea at a time. Every feature also has a runnable file in [`examples/`](../examples).
+- [First program](#first-program)
+- [Basics](#basics)
+- [Functions](#functions)
+- [Control flow](#control-flow)
+- [Structs](#structs)
+- [Enums](#enums)
+- [Pattern matching](#pattern-matching)
+- [Option and Result](#option-and-result)
+- [Lists, slices and maps](#lists-slices-and-maps)
+- [Loops](#loops)
+- [Closures](#closures)
+- [Generics](#generics)
+- [Methods, statics and constants](#methods-statics-and-constants)
+- [Operators on your own types](#operators-on-your-own-types)
+- [Inheritance](#inheritance)
+- [Modules](#modules)
+- [Tests](#tests)
+- [Talking to the outside world](#talking-to-the-outside-world)
+## First program
+```plum
+import std/Io
+import std/Str
+fun main(io: Io) =
+  io.printLn("Hello, Plum!")
+```
+```sh
+plum run hello.plum
+```
+## Basics
+**Blocks** use indentation (2 spaces), with no braces or semicolons. **Comments** start with `#`.
+**Variables:** `:=` declares a new name and `=` changes an existing one.
+```plum
+fun main() =
+  count := 1
+  count = count + 1
+  a, b := 1, 2
+  ratio: Float := 0.5    # with an explicit type
+```
+**Values:**
+| Type | Examples |
+|---|---|
+| `Int` | `42`, `0xFF`, `0b1010`, `1_000_000` |
+| `Float` | `3.14`, `6.022e23` |
+| `Bool` | `true`, `false` |
+| `Str` | `"hello"`, `"line one\nline two"` |
+**Strings** can hold any expression inside `{ }`:
+```plum
+fun greet(name: Str) -> Str =
+  "Hello, {name}! Your name has {name.length()} letters."
+```
+**Grouping** uses `{ }`, because `( )` is only for calls:
+```plum
+fun total() -> Int =
+  {1 + 2} * 3
+```
+**Names:**
+| Style | Used for |
+|---|---|
+| `PascalCase` | types, enums, variants, constants |
+| `camelCase` | functions, methods, fields |
+| `snake_case` | variables, parameters |
+**Unused results are an error.** This stops a call like `scores.push(3)` from silently doing nothing on a type where `push` returns a new value. To drop a result on purpose, write `_ := list.pop()!`.
+## Functions
+The last expression is the return value. With no return type, a function returns `Unit`.
+```plum
+fun add(a: Int, b: Int) -> Int =
+  a + b
+fun step(a: Int, by: Int = 1) -> Int =   # a default value
+  a + by
+fun sign(n: Int) -> Int = match n        # a body can be one match
+  0 => 0
+  _ => if n < 0 then -1 else 1
+```
+Calls in tail position run in constant stack, so deep recursion is safe:
+```plum
+fun countUp(n: Int, acc: Int) -> Int =
+  if n <= 0 then acc else countUp(n - 1, acc + 1)
+```
+## Control flow
+`if` comes in two forms. The block form is a statement, and the `then` form is an expression:
+```plum
+fun describe(n: Int) -> Str =
+  if n < 0
+    return "negative"
+  else if n == 0
+    return "zero"
+  if n > 100 then "big" else "small"
+```
+`while` loops as long as a condition holds, and `for` is covered under [Loops](#loops). `break` and `continue` work in both.
+```plum
+fun halve(start: Int) -> Int =
+  i := start
+  while i > 1
+    i = i / 2
+  i
+```
+`assert n > 0` stops the program if the condition is false. `todo` marks a body you haven't written yet, and stops the program if it is reached.
+## Structs
+A struct is a set of named fields.
+```plum
+struct User(name: Str, mut age: Int)
+fun main() =
+  ann := User(name: "Ann", age: 30)
+  ann.age = 31                          # allowed, because age is `mut`
+  older := User(..ann, age: 32)         # a copy with one field changed
+```
+Fields can't change unless they are marked `mut`. A spread, `User(..ann, age: 32)`, makes an updated value, and the compiler writes it in place when the old value isn't used again.
+**Copied or shared?** A small struct made only of numbers, like `Vec2` below, is copied when assigned. Any other struct is shared: two names point at the same value.
+```plum
+struct Vec2(x: Float, y: Float)
+fun main() =
+  a := Vec2(x: 1.0, y: 2.0)
+  b := a
+  b.x = 9.0        # a.x is still 1.0
+```
+**Setting up extra fields:** the header lists what callers pass. Anything else is set in `init`, which runs on construction.
+```plum
+import std/Int
+import std/Slice
+struct Bag(size: Int) =
+  fun init(self) =
+    self.items: Slice[Int] = Slice[Int]()
+    self.capacity: Int = self.size * 2
+```
+## Enums
+An enum is a value that is one of several variants. A variant can carry its own fields.
+```plum
+enum Color = Red | Green | Blue
+enum Shape =
+  | Circle(r: Float)
+  | Rect(w: Float, h: Float)
+  fun area(self) -> Float =
+    match self
+      Circle(r) => r * r * 3.14
+      Rect(w, h) => w * h
+fun main() =
+  s := Rect(w: 2.0, h: 3.0)
+  a := s.area()
+```
+`Shape` is the type. `Circle` and `Rect` are ways to build and match it, not types of their own, so you read a variant's fields with a pattern rather than with `.field`.
+Enums can be recursive and generic:
+```plum
+enum Tree[T] =
+  | Leaf
+  | Node(left: Tree[T], value: T, right: Tree[T])
+```
+## Pattern matching
+`match` handles every case, and the compiler checks that none is missing. Add a variant later and each `match` that doesn't handle it becomes an error.
+```plum
+enum Job =
+  | Idle
+  | Busy(task: Str)
+  | Done(score: Int)
+fun describe(job: Job) -> Str =
+  match job
+    Idle => "resting"
+    Busy(task) => "working on {task}"
+    Done(score) when score > 90 => "great work"
+    Done(_) => "finished"
+```
+Patterns can be literals, names that bind a value, variants with nested patterns, or `_` to ignore. A case can add a `when` condition. `match a, b` matches several values at once.
+**Checking one case** is easier with `if`. The names it binds exist only inside that branch, and `, cond` adds a condition:
+```plum
+enum Job =
+  | Idle
+  | Busy(task: Str, urgent: Bool)
+fun urgentTask(job: Job) -> Str =
+  if Busy(task, urgent) := job, urgent
+    task
+  else
+    "none"
+```
+The same form works as `while Pattern := value`.
+Use `match` when every case needs handling, and `if` when only one or two do. Only `match` is checked for missing cases.
+## Option and Result
+Plum has no `null` and no exceptions.
+- `Option[T]` is a value that may be missing: `None` or `Some(x)`.
+- `Result[T, E]` is an operation that may fail: `Ok(x)` or `Err(e)`.
+Both are ordinary enums from `std/Option` and `std/Result`.
+```plum
+import std/Int
+import std/Str
+import std/Option
+import std/Result
+enum AgeError =
+  | NotANumber
+  | Negative
+fun parseAge(s: Str) -> Result[Int, AgeError] =
+  n := Int.parse(s).mapErr(|e| NotANumber)?
+  if n < 0
+    return Err(Negative)
+  Ok(n)
+fun describe(s: Str) -> Str =
+  match parseAge(s)
+    Ok(n) => "age {n}"
+    Err(NotANumber) => "not a number"
+    Err(Negative) => "can't be negative"
+```
+Each way of handling them:
+| You write | It means |
+|---|---|
+| `x?` | Use the value, or return the `Err`/`None` from this function |
+| `x!` | Use the value, or crash and report the file and line |
+| `x.unwrapOr(d)` | Use the value, or the default `d` |
+| `if Some(v) := x` | Run a block only when there is a value |
+| `match x` | Handle each case |
+| `x.map(f)`, `x.andThen(f)` | Transform a value that is present |
+| `r.mapErr(f)` | Change the error, usually into your own error enum |
+| `o.okOr(e)`, `r.ok()` | Convert between `Option` and `Result` |
+A good habit is one error enum per module. Use `?` and `mapErr` for failures you expect. Save `!` and `crash "message"` for bugs.
+## Lists, slices and maps
+| Type | Use it for | Build one |
+|---|---|---|
+| `List[T]` | recursion and pattern matching | `[1, 2, 3]` |
+| `Slice[T]` | a growable array with fast indexing | `[1, 2, 3].toSlice()`, `Slice[Int]()` |
+| `Array[T]` | a fixed-size array | `Array.filled(10, 0)` |
+| `Map[K, V]` | key and value lookup | `["a" => 1, "b" => 2]` |
+```plum
+import std/Int
+import std/List
+import std/Slice
+fun main() =
+  big := [1, 5, 9].filter(|x| x > 2).map(|x| x * 10)
+  scores := Slice[Int]()
+  scores.push(4)
+  last := scores.last().unwrapOr(0)
+```
+A `List` is `Nil` or `Cons(head, tail)`, so you can match on it. Indexing a `List` is slow, so reach for a `Slice` when you need it.
+## Loops
+`for x := range source` is the only `for`.
+```plum
+import std/Int
+import std/Str
+import std/List
+import std/Map
+import std/Slice
+fun main() =
+  total := 0
+  for i := range 10                    # 0, 1, ... 9
+    total = total + i
+  for i := range 2.until(10)           # 2 to 9; also to, downTo, stepBy
+    total = total + i
+  for x := range [1, 2, 3]             # a List, Slice or Array
+    total = total + x
+  for e := range ["a" => 1].entries()  # a Map: e.first and e.second
+    total = total + e.second
+```
+Make your own type loopable by giving it `next`. Return `None` when done, or `Some` of the value and the remaining sequence:
+```plum
+import std/Int
+import std/Str
+import std/Option
+import std/Pair
+struct Countdown(n: Int) =
+  fun next(self) -> Option[Pair[Int, Countdown]] =
+    if self.n <= 0 then None else Some(Pair(first: self.n, second: Countdown(n: self.n - 1)))
+```
+## Closures
+A closure is written `|params| body`. It copies the variables it uses when it is created.
+```plum
+fun apply(f: fn(Int) -> Int, x: Int) -> Int =
+  f(x)
+fun adder(n: Int) -> fn(Int) -> Int =
+  |x| x + n
+fun main() -> Int =
+  offset := 100
+  a := apply(|v| v + offset, 5)
+  add1 := adder(1)
+  a + add1(2)
+```
+Add a type when the compiler can't work one out: `|b: Box| b.get()`. Passing a closure straight to a function that just calls it costs nothing, because the compiler inlines it.
+`adder(1)(2)` isn't supported yet, so bind the result to a name first.
+## Generics
+Declare type parameters in `[ ]`. The name can be anything.
+```plum
+struct Box[T](value: T) =
+  fun map[B](self, f: fn(T) -> B) -> Box[B] =
+    Box(value: f(self.value))
+fun first[Elem](xs: List[Elem], fallback: Elem) -> Elem = match xs
+  Nil => fallback
+  Cons(h, _) => h
+```
+Parameters have no constraints. If `show[T]` calls `x.toStr()`, it works for any type that has `toStr`, and any other type gets an error showing how the call got there:
+```
+in outer[Plain] (called at main.plum:9:3):
+  in maxOf[Plain] (called at main.plum:5:3):
+    Plain has no method 'lt'
+```
+Each type gets its own compiled copy, so a `Slice[Float]` stores plain floats with no boxing.
+If the compiler can't work out a type parameter, annotate the value: `empty: List[Int] := Nil`.
+## Methods, statics and constants
+Inside a type's body:
+- a `fun` with `self` is a **method**, called on a value: `cat.age()`
+- a `fun` without `self` is a **static**, called on the type: `Cat.named("Tom")`
+- `Name = value` is a **constant**, read as `Type.Name`
+```plum
+struct Vec2(x: Float, y: Float) =
+  Zero = Vec2(x: 0.0, y: 0.0)
+  fun unit() -> Vec2 =
+    Vec2(x: 1.0, y: 1.0)
+  fun sum(self) -> Float =
+    self.x + self.y
+```
+There are no top-level constants. For a group of constants and helper functions with no data, use `primitive`:
+```plum
+primitive Config =
+  MaxRetries = 3
+  fun doubled() -> Int =
+    Config.MaxRetries * 2
+```
+## Operators on your own types
+Define the matching method and the operator works:
+| Operator | Method |
+|---|---|
+| `a + b`, `a - b`, `a * b`, `a / b` | `add`, `sub`, `mul`, `div` |
+| `-a` | `neg` |
+| `a == b`, `a != b` | `eq` |
+| `a < b`, `a <= b`, `a > b`, `a >= b` | `lt`, `le`, `gt`, `ge` |
+```plum
+struct Vec2(x: Float, y: Float) =
+  fun add(self, o: Vec2) -> Vec2 =
+    Vec2(x: self.x + o.x, y: self.y + o.y)
+  fun mul(self, s: Float) -> Vec2 =
+    Vec2(x: self.x * s, y: self.y * s)
+```
+## Inheritance
+A struct can embed one other struct by listing it first. It gets the base's fields and methods, and can be used anywhere the base is expected.
+```plum
+import std/Io
+import std/Int
+import std/Str
+struct Animal(name: Str) =
+  fun speak(self, io: Io) =
+    io.printLn("...")
+struct Dog(Animal(name), tricks: Int) =
+  override fun speak(self, io: Io) =
+    io.printLn("Woof")
+```
+The header names which base fields callers pass. `override fun` replaces a base method, and the right version is picked at run time. `self.Animal.speak(io)` calls the base's version.
+`abstract fun` declares a method with no body. Every subtype must override it, and the base can't be constructed:
+```plum
+struct Shape() =
+  abstract fun area(self) -> Float
+struct Square(Shape, side: Float) =
+  override fun area(self) -> Float =
+    self.side * self.side
+```
+## Modules
+A file starts with its imports. Nothing is implicit, not even `Int` or `Str` methods, and each file imports what it uses.
+```plum
+module shapes
+import std/Int
+import std/Str
+```
+`test` blocks go at the end of the file.
+## Tests
+Tests live next to the code and run with `plum test`:
+```plum
+fun add(a: Int, b: Int) -> Int =
+  a + b
+test "add works"
+  assert add(1, 2) == 3
+```
+```sh
+$ plum test math.plum
+└─ add works ✔
+1 passed, 0 failed
+```
+A failing `assert` on `==` prints both values. `plum test` accepts files and folders, and `std/Testing` adds helpers like `Testing.expectEq`.
+## Talking to the outside world
+Everything that leaves your program goes through an `Io` value: printing, files, the clock, the network, drawing. You can't make an `Io` yourself. It is given to `main`, and you pass it to whatever needs it.
+```plum
+import std/Io
+import std/Str
+import std/Os
+fun main(io: Io) =
+  match Os.readFile(io, "notes.txt")
+    Ok(text) => io.printLn(text)
+    Err(e) => io.printLn("could not read the file")
+```
+This means a function that doesn't receive an `Io` can't have outside effects, which makes it easy to test and lets the compiler optimise it.
+`export fun` makes a top-level function callable from the host, such as a browser. See [the game engine](game.md) for how a game uses this.

docs/performance.md ADDED Viewed

@@ -0,0 +1,51 @@
+# Performance
+You can write clear code and let the compiler make it fast. These optimisations never change what your program does: if a rewritten program doesn't type-check, the compiler keeps the original.
+## What the compiler does
+**Removes temporary lists.** This builds no intermediate lists, and runs as one loop:
+```plum
+import std/Int
+import std/List
+fun total(xs: List[Int]) -> Int =
+  xs.map(|x| x * 2).filter(|x| x > 2).fold(0, |a, x| a + x)
+```
+**Updates in place.** If a value isn't used again, a spread writes into it instead of copying:
+```plum
+struct Cell(x: Float)
+fun bump(s: Cell) -> Cell =
+  Cell(..s, x: s.x + 1.0)
+```
+**Reuses memory.** Rebuilding a value of the same shape can reuse the old one.
+**Inlines closures.** A closure passed straight to a function that only calls it becomes a direct copy of the code, with no allocation.
+**Skips the picture tree.** In a game, `view(state).draw(io)` draws without building the scene in memory.
+**Runs tail calls as loops.** Recursion in tail position uses no extra stack.
+## When it can't help
+The first three need pure code, which means no `Io`, and a value that has one use. If a value is used twice, stored in a field or captured by a closure, it stays as written.
+To see each decision, or turn the optimisations off:
+```sh
+plum run --explain-fusion file.plum
+plum run --no-fusion file.plum
+```
+## Planned
+- Keep lists and substrings that stay inside one function out of the heap
+- Read a list's storage once per loop, rather than on every step
+- Inline `get`, `set` and `push`
+- Store small structs inside other structs instead of separately
+- Copy only the needed part of a string when printing it

docs/std.md ADDED Viewed

@@ -0,0 +1,166 @@
+# The standard library
+Import what you use: `import std/Str`, `import std/Slice`, and so on. The source is in [`std/`](../std), and it is plain Plum, so it's a good place to read how things work.
+The [game engine](game.md) has its own page.
+| Module | What it's for |
+|---|---|
+| [`Int`, `Float`, `Bool`, `Byte`](#numbers) | numbers and booleans |
+| [`Math`](#numbers) | `sqrt`, `sin`, `exp` and friends |
+| [`Str`, `Buffer`](#text) | text |
+| [`List`, `Slice`, `Array`, `Grid`](#sequences) | sequences |
+| [`Map`, `Set`, `Deque`, `Heap`](#collections) | other collections |
+| [`Option`, `Result`](#option-and-result) | missing values and failures |
+| [`Json`](#json) | reading and writing JSON |
+| [`Os`, `Http`](#files-and-network) | files and the network |
+| [`Time`, `Random`, `Uuid`, `Base64`](#utilities) | utilities |
+| [`Testing`](#testing) | helpers for tests |
+## Numbers
+```plum
+import std/Int
+import std/Float
+import std/Str
+import std/Math
+fun main() =
+  a := 5.max(3)
+  b := Float.Pi * 2.0
+  c := Math.sqrt(2.0)
+  d := Int.parse("42").unwrapOr(0)
+```
+- `Int`: `abs`, `sign`, `min`, `max`, `pow`, `toStr`, `Int.parse`, `Int.Min`, `Int.Max`
+- `Float`: `abs`, `sqrt`, `pow`, `floor`, `ceil`, `round`, `trunc`, `isNaN`, `toStr`, `Float.parse`, `Float.Pi`, `Float.Tau`, `Float.E`
+- `Math`: `sqrt`, `sin`, `cos`, `tan`, `asin`, `acos`, `atan`, `atan2`, `exp`, `ln`, `hypot`, `cbrt`
+- `Bool`: `toStr`, `Bool.parse`
+## Text
+A `Str` can't be changed. Taking part of one shares the original's memory rather than copying it.
+```plum
+import std/Int
+import std/Str
+fun main() =
+  name := "  plum  ".trim()
+  shout := name.upperCase()
+  twice := name.repeat(2)
+  yes := name.startsWith("pl")
+```
+- **Search:** `contains`, `startsWith`, `endsWith`, `indexOf`
+- **Cut:** `sub`, `slice`, `split(separator, limit)`, `trim`, `trimStart`, `trimEnd`, `truncate`
+- **Change:** `replace`, `replaceAll`, `repeat`, `reverse`, `padStart`, `padEnd`
+- **Case:** `upperCase`, `lowerCase`, `capitalize`, `camelCase`, `snakeCase`, `kebabCase`
+- **Unicode:** `length` counts bytes; `runeLength` and `runeAt` count characters
+To build a string in steps, use `Buffer`: `write`, `writeByte`, `toStr`.
+## Sequences
+**`List`** suits recursion: `map`, `filter`, `fold`, `append`, `reverse`, `length`, `isEmpty`, `get`, `toSlice`.
+**`Slice`** is a growable array:
+```plum
+import std/Int
+import std/List
+import std/Slice
+fun main() =
+  xs := [3, 1, 2].toSlice()
+  xs.push(4)
+  first := xs.get(0).unwrapOr(0)    # Some(value), or None when out of range
+  second := xs.at(1)                # the value, or crash when out of range
+```
+- **Read:** `get`, `at`, `first`, `last`, `head`, `length`, `contains`, `findValue`
+- **Change:** `push`, `pop`, `set`, `add`, `remove`, `removeAt`, `clear`, `sort`, `reverse`, `shuffle`
+- **Other:** `slice` (a view that shares storage), `sublist` (a copy), `chunk`, `join`, `drop`
+**`Array`** has a fixed size: `Array.filled(n, value)`, `get`, `set`, `length`. **`Grid`** is a 2D array: `Grid.filled(w, h, value)`, `get(x, y)`, `set(x, y, value)`.
+## Collections
+```plum
+import std/Int
+import std/Str
+import std/Map
+fun main() =
+  ages := ["ann" => 30, "bob" => 25]
+  ages.set("cy", 40)
+  ann := ages.get("ann").unwrapOr(0)
+```
+- **`Map`:** `get`, `set`, `has`, `remove`, `keys`, `values`, `entries`, `length`. `Map.empty()` makes an empty one, but needs a type: `m: Map[Str, Int] := Map.empty()`
+- **`Set`:** `add`, `has`, `remove`, `length`, `toList`
+- **`Deque`:** a queue you can use from both ends: `pushBack`, `pushFront`, `popBack`, `popFront`
+- **`Heap`:** always gives back the smallest item first: `push`, `pop`, `peek`
+## Option and Result
+See [the language guide](language.md#option-and-result).
+- **`Option`:** `isSome`, `isNone`, `unwrap`, `unwrapOr`, `map`, `andThen`, `okOr`
+- **`Result`:** `isOk`, `isErr`, `unwrap`, `unwrapOr`, `map`, `andThen`, `mapErr`, `ok`
+## JSON
+`Json.encode` and `Json.decode` convert your types. Numbers, `Bool`, `Str`, `Slice` and `Map` work already, and your own types need `toJson` and `fromJson`:
+```plum
+import std/Int
+import std/Str
+import std/Map
+import std/Json
+struct Point(x: Int, y: Int) =
+  fun toJson(self) -> Json =
+    Json.object(["x" => self.x.toJson(), "y" => self.y.toJson()])
+  fun fromJson(j: Json) -> Result[Point, JsonError] =
+    x := Int.fromJson(j.field("x")?)?
+    y := Int.fromJson(j.field("y")?)?
+    Ok(Point(x: x, y: y))
+fun main() =
+  text := Json.encode(Point(x: 1, y: 2))
+  p: Result[Point, JsonError] := Json.decode(text)
+```
+The result's annotation tells `decode` which type to build. `Option` doesn't have JSON support yet, so write those conversions by hand.
+## Files and network
+All of these need an `Io` and return a `Result`.
+```plum
+import std/Io
+import std/Str
+import std/Os
+import std/Http
+fun main(io: Io) =
+  _ := Os.writeFile(io, "note.txt", "hello")
+  text := Os.readFile(io, "note.txt").unwrapOr("")
+  io.printLn(text)
+```
+- **`Os`:** `readFile`, `writeFile`, `appendFile`, `exists`, `mkdir`, `remove`, `rename`, `copyFile`, `readdir`
+- **`Http`:** `get`, `post`, `put`, `patch`, `delete`, `head`, `postJson`. A `Response` has `status`, `headers`, `body`, `ok()` and `json()`
+## Utilities
+- **`Time`:** `Time.now(io)` and `Duration` values such as `Duration.seconds(5)`
+- **`Random`:** `Random.seeded(n)`. Each call returns the value and the next generator, so the same seed always gives the same sequence. `io.randomSeed()` gives a seed from the clock
+- **`Uuid`:** `Uuid.v4(rng)`, `Uuid.fromStr`, `Uuid.isValid`
+- **`Base64`:** `Base64.encode`, `Base64.decode`, `Base64.encodeURL`
+## Testing
+`assert` covers most tests. `std/Testing` adds `Testing.expectEq`, `expectNotEq`, `expectTrue`, `expectFalse`, `expectSuccess` and `expectFailure`.

docs/tools.md ADDED Viewed

@@ -0,0 +1,52 @@
+# Tools
+## Commands
+Run these from a checkout of this repository, or pass `--lib-path`, so `import std/...` can find the standard library.
+| Command | What it does |
+|---|---|
+| `plum run file.plum` | Compile and run |
+| `plum test file.plum dir/` | Run the `test` blocks in files and folders |
+| `plum compile file.plum` | Write `file.wasm` |
+| `plum build file.plum` | Make a native executable |
+| `plum format file.plum` | Format the file in place (`--check` only checks, `--stdin` reads standard input) |
+| `plum game file.plum` | Serve a game and open it in the browser |
+| `plum editor helix` | Set up Helix |
+| `plum editor vscode` | Set up VSCode (`--insiders` for VSCode Insiders) |
+**Options for `plum game`:**
+| Option | What it does |
+|---|---|
+| `--assets DIR` | Load assets from `DIR` |
+| `--port N` | Use port `N` (default 8080, or any free port) |
+| `--no-open` | Don't open the browser |
+| `-o DIR` | Write a static site to `DIR` and exit |
+**Options for looking at the compiler's work:**
+| Option | What it does |
+|---|---|
+| `--no-fusion` | Turn off the optimisations described in [Performance](performance.md) |
+| `--explain-fusion` | Print each optimisation decision and how each struct is stored |
+## Editors
+`plum editor helix` and `plum editor vscode` install syntax highlighting and the language server, which gives you errors as you type and completion. Everything is built into the `plum` binary, so they work from any folder. Reload your editor afterwards.
+## Building from source
+You need a recent stable Rust toolchain and a C compiler.
+```sh
+cargo install --path compiler/cli
+```
+This installs `plum` to `~/.cargo/bin`. Run it again after pulling changes. While working on the compiler, use `cargo run -p plum-cli --` instead.
+To rebuild the VSCode extension, you also need `node` and `npm`: run `npm install && npm run build` in `compiler/tooling/vscode-plum`.
+## Releases
+For maintainers: `cargo make release` builds the macOS, Linux and Windows binaries, tags the version, updates the download links in the README and uploads the binaries. It needs [cargo-make](https://github.com/sagiegurari/cargo-make), [cross](https://github.com/cross-rs/cross) with Docker, and the `git` rclone remote. See `Makefile.toml`.