diff --git a/README.md b/README.md
index 2464c148..e4b6e573 100644
--- a/README.md
+++ b/README.md
@@ -157,7 +157,8 @@ bus, the deterministic networking stack, scenes, and save/load are all in place
and covered by `bin/x test`. CI gates every push and PR on the build, the test
suites, and that C-free fixpoint. The toolchain is versioned with SemVer
(`ludicc --version`); releases and the `CHANGELOG.md` are cut from changesets by
-`x release`.
+`x release`. Upgrading from 0.2? See the
+[0.2 → 0.3 migration guide](docs/MIGRATION-0.2-to-0.3.md).
Active work and proposals — the standard library, a fuller type system,
rendering/animation/lighting extras, input, filesystem/IO, testing, and
diff --git a/docs/MIGRATION-0.2-to-0.3.md b/docs/MIGRATION-0.2-to-0.3.md
new file mode 100644
index 00000000..cc5e4a2b
--- /dev/null
+++ b/docs/MIGRATION-0.2-to-0.3.md
@@ -0,0 +1,460 @@
+# Migrating from Ludic 0.2 to 0.3
+
+This guide covers everything that changed between **v0.2.0** and **v0.3.0** and how
+to adopt it. It is organised as:
+
+1. [TL;DR](#tldr) — is anything going to break?
+2. [Behaviour changes to be aware of](#behaviour-changes) — the handful of things
+ that behave differently, even though your code still compiles.
+3. [Deprecations](#deprecations)
+4. [New subsystems](#new-subsystems) — packages, controllers, Tiled maps.
+5. [New engine & language features and how to adopt them](#new-features)
+6. [External projects & packaging](#external-projects)
+7. [Full change index](#change-index)
+
+---
+
+
+## 1. TL;DR — is anything going to break?
+
+**No source changes are required. v0.2 programs compile unchanged on v0.3.**
+
+Every addition in this release is additive and feature-gated: a program that does
+not use a new feature compiles to byte-for-byte identical output, the golden
+renders are unchanged, and the C-free bootstrap fixpoint is untouched. There are
+**no removed APIs** and **no changed function signatures**.
+
+There are, however, a few **runtime behaviour changes** (windowed input, and how
+the frame loop drives input) and **one deprecation** (bare `draw_sprite`) that are
+worth a five-minute read before you upgrade. They are covered next.
+
+Upgrade steps:
+
+```
+# rebuild the toolchain from the new sources
+bin/x build
+# (optional) confirm everything still passes
+bin/x test
+# check the version
+bin/x version # -> ludic 0.3.0
+```
+
+---
+
+
+## 2. Behaviour changes to be aware of
+
+These compile without changes but *behave* differently. Most are improvements you
+can lean into; a couple deserve a deliberate look.
+
+### 2.1 Windowed games no longer quit on Esc or 'q' (#88)
+
+In 0.2 the macOS window layer hard-coded **Escape** and the character **'q'** as
+*quit* — handy in the dev loop, fatal in a shipped game (a player pressing Esc to
+pause, or typing 'q', killed the window).
+
+In 0.3:
+
+- **Escape** is delivered to your game as **key 27** (read it and do your own
+ pause), and **'q'** is an ordinary key.
+- A windowed game shuts down via `quit()` or the **window close button** (which
+ still ends the run).
+- The **headless** driver is unchanged: `'q'` still quits scripted / golden runs.
+
+**Action:** if your dev loop relied on pressing Esc/'q' to close the window, use
+**Cmd-Q** or the close button instead, or wire `if Input.key(...) == 27 { quit() }`
+yourself. If you already handle Esc for a pause menu, it now works (it used to be
+swallowed as a quit).
+
+### 2.2 The frame loop now drives input automatically (#83, #87)
+
+In 0.2, a windowed **handler game** had to call `Input.poll()` at the top of its
+Input phase for the multi-key device layer (`Input.key_down`, the mouse, gamepads)
+to update — otherwise those read empty.
+
+In 0.3 the generated frame loop commits the device layer itself once per frame (it
+calls the input driver before your Input handlers). So:
+
+- `Input.key_down` / `Input.mouse_*` / `Input.pad_*` / the new `Input.active` all
+ read live **without** a manual `Input.poll()`.
+- A manual `Input.poll()` you still have in a handler is now **redundant** — and,
+ as of the edge-detection fix (#87), it is a **no-op under the loop** rather than
+ a second commit, so it no longer breaks `Input.key_pressed` / `key_released`
+ edges. You can delete it.
+- **Entry-driven** programs (a `program … { entry { … } }` test harness that calls
+ `Input.poll()` to step input by hand) are **unchanged** — there is no frame loop,
+ so each `Input.poll()` still advances one frame of input exactly as before.
+
+**Action:** in a handler game, remove any `Input.poll()` you were calling by hand;
+it is done for you. Nothing breaks if you leave it.
+
+Before (0.2):
+
+```
+handler Move phase Input {
+ Input.poll() # required in 0.2
+ if Input.key_down('d') { ... }
+}
+```
+
+After (0.3):
+
+```
+handler Move phase Input {
+ if Input.key_down('d') { ... } # the loop already committed input
+}
+```
+
+### 2.3 `Input.key_pressed` / `key_released` now actually fire (#87)
+
+If you had worked around edge detection never triggering (a game-side "previous
+state" flag), you can drop the workaround — `Input.key_pressed` and
+`Input.key_released` now fire on the transition frame. See §2.2 for the cause (a
+double-commit when a game manually polled under the loop).
+
+---
+
+
+## 3. Deprecations
+
+### 3.1 Bare `draw_sprite` / `draw_sprite_scaled` (#85)
+
+The bare global sprite calls are deprecated in favour of the namespaced
+`Screen.sprite` / `Screen.sprite_scaled`. A direct bare call now prints a one-time
+compile-time note; the bare form still compiles (`Screen.sprite` lowers to it), so
+this is a warning, not an error.
+
+```
+# 0.2 (deprecated in 0.3, still compiles with a note)
+draw_sprite(id, x, y)
+draw_sprite_scaled(id, x, y, 2)
+
+# 0.3
+Screen.sprite(id, x, y)
+Screen.sprite_scaled(id, x, y, 2)
+```
+
+**Action:** replace bare `draw_sprite` / `draw_sprite_scaled` with the `Screen.*`
+form. Or, better, adopt the engine sprite-render system (§5.6) and stop calling
+draw per entity at all.
+
+---
+
+
+## 4. New subsystems
+
+These are the large additions in 0.3. They are opt-in — you reach for them, they
+do not change existing programs.
+
+### 4.1 Package manager (#62, #63, #64)
+
+Ludic gains a real package manager with no new infrastructure: dependencies are
+named by their git import path (URL-as-identity — a `git tag vX.Y.Z` publishes,
+there is no registry), resolved by Go-style Minimum Version Selection, fetched into
+a content-addressed global store (`~/.ludic/store`), and linked per project under
+`ludic_modules/`.
+
+```
+x add git.workshopsoft.io/you/pkg # add a dependency (latest tag)
+x add git.workshopsoft.io/you/pkg@1.2.0 # a specific version
+x get # resolve + fetch + link everything
+x update [module] # bump to the latest published version
+x verify # rehash the store against the lock
+x vendor # copy deps into ./vendor for offline builds
+```
+
+A `package.ludic` manifest declares the deps, the `Foo.*` namespace(s) the package
+provides, and its kind; `package.lock.ludic` pins resolved versions + content
+hashes for reproducible builds. A **source** package's Ludic compiles straight into
+your binary (no ABI seam); a **prebuilt** package ships a native dylib whose
+functions/systems/components you use over the reflection C-ABI (`x build-lib`,
+`x link-flags`). Packages register namespaces and engine systems with **no compiler
+edit**, via the `@Namespace(Name)` and `@EngineSystem(Component, Phase)`
+annotations. Full details in [docs/PACKAGES.md](PACKAGES.md).
+
+### 4.2 Gameplay controllers (#57–#61)
+
+Five source packages ship complete, extensible gameplay systems built on the
+engine's `Body`/`Collider` + `esys_move` and on a six-lever extensibility contract
+(see [docs/CONTROLLERS.md](CONTROLLERS.md)):
+
+| Package | What it gives you |
+| --- | --- |
+| **ludic.gameplay** | `Cooldown` timer, `Stats` + a timed modifier stack, a `Faction` table, and a `Combat` damage pipeline (cancellable + mutable amount). |
+| **ludic.platformer** | Jump-feel `Platformer` (apex/coyote/buffer/variable-height/multi-jump), decomposed sub-systems, jump/land/state events, opt-in scaffolding (moving platforms, pickups, springs, hazards, checkpoints). |
+| **ludic.shooter** | `TopDown` decoupled move + aim, a name-keyed `Weapon` registry, a deterministic `Projectile` pool (faction hits, pierce, ring/spiral, homing), a wave `Spawner`. |
+| **ludic.npcai** | Perception → decision (FSM / utility / behaviour tree) → action, writing the *same intent fields the player controllers read*, plus flocking and a `Follower`. |
+| **ludic.rpg** | Seven modules: grid/free/tween movement, inventory + equipment, crafting, quests + flags, an Ink/Yarn dialog graph, Sokoban + a signal graph, and status effects. |
+
+Adopt one by importing it (in-repo the packages live under `packages/`; in a real
+project `x add` them):
+
+```
+program MyGame {
+ import "ludic.platformer/platformer.ludic"
+ model Hero { Platformer, Position, Body, Collider }
+ # ... the engine runs the controller's sub-systems for you
+}
+```
+
+### 4.3 Tiled map support (#66–#74)
+
+Load and draw [Tiled](https://www.mapeditor.org/) maps — both XML (TMX/TSX/TX) and
+JSON (TMJ/TSJ/TJ) — via a new `Tiled.*` runtime, standing on a pure-Ludic `Xml.*`
+reader, `Base64.*`, gzip framing, and a self-contained pure-Ludic **zstd**
+decompressor for base64+zstd layers.
+
+```
+let map = Tiled.load("assets/level.tmx") # reads .tmx or .tmj, resolves tilesets + images
+handler Draw phase Render {
+ Tiled.draw_anim(map, cam_x, cam_y) # animated tiles advance off the fixed frame clock
+}
+```
+
+It covers layers (tile / image / group / object), all object shapes + custom
+properties, templates, animated tiles, isometric/staggered/hexagonal orientations,
+infinite/chunked maps and `.world` stitching, and projects a collision layer that
+`esys_move` / `Grid.*` / `Path.*` read. Deterministic (animations are a pure
+function of the 60/s frame clock).
+
+---
+
+
+## 5. New engine & language features and how to adopt them
+
+### 5.1 Canonical components from `ludic.core` (#77, #84, #85)
+
+The engine-ABI components the movement / sprite / bounds systems read by name are
+now shipped from a base package — import them instead of hand-declaring the
+bundles in every game.
+
+Before (0.2 — every game re-declared these):
+
+```
+property Position { x: int = 0, y: int = 0 }
+property Body { vx: fixed = 0.0, vy: fixed = 0.0, gravity: fixed = 0.0, /* … */ }
+property Collider { w: int = 0, h: int = 0, /* … */ }
+```
+
+After (0.3):
+
+```
+import "ludic.core/components.ludic" # Position, Body, Collider, Solids, Sprite, Bounds
+```
+
+Extend by composition — attach your own components alongside on the same model.
+
+### 5.2 Declarative Render: `@ClearColor` (#86)
+
+Drop the `Screen.clear(...)` / `Screen.show()` boilerplate: annotate a clear colour
+and the Render phase clears to it and presents for you.
+
+```
+@ClearColor(0x101018)
+handler Draw phase Render {
+ # no Screen.clear, no Screen.show — the engine does both
+ Screen.fill_rectangle(10, 10, 4, 4, 0xffcc00)
+}
+```
+
+Opt-in: a program with no `@ClearColor` is byte-identical (it clears/presents
+itself, or the light system owns the present).
+
+### 5.3 Input Manager + ergonomic input (#79, #83)
+
+- **Default, rebindable, device-agnostic actions:**
+ `Input.action(name, key)` ships a default binding (kept if already bound, so a
+ player's `Input.rebind` or a loaded key-map isn't clobbered);
+ `Input.bind_pad(name, button)` makes an action fire from keyboard *or* gamepad.
+- **Held + edges over the whole device layer:** `Input.active(name)`,
+ `Input.just_pressed(name)`, `Input.just_released(name)` — the deterministic,
+ dispatch-free on-press / on-release (poll the edge; a replay fires it identically).
+- **Directional intent without glue:** `Input.axis_i(neg, pos) -> int` returns a
+ -1/0/1 movement intent, replacing the `ki(key_down('d')) - ki(key_down('a'))`
+ boilerplate.
+
+```
+@OnStart handler Boot {
+ Input.action("jump", ' ')
+ Input.bind_pad("jump", 0)
+}
+handler Move phase Update {
+ let dx = Input.axis_i('a', 'd')
+ let dy = Input.axis_i('w', 's')
+ if Input.just_pressed("jump") { ... }
+}
+```
+
+### 5.4 `Camera.zoom` (#78)
+
+A deterministic Q16.16 render-time zoom about the screen centre, composing with
+`Camera.set`/`follow`/`shake`:
+
+```
+Camera.zoom(2.0) # 2x in; 1.0 = none (turns the zoom path back off); 0.5 = out
+```
+
+The world coordinate types stay integer px + Q16.16 velocity (hardware floats were
+rejected to preserve lockstep/replay/save — see
+[docs/RFC-POSITION-TYPES.md](RFC-POSITION-TYPES.md)). Byte-identical when unused.
+
+### 5.5 Spritesheet / atlas API + async preload (#81, #82)
+
+Load one sheet and address cells by grid coords or name — including sprites that
+span more than one cell — instead of one `png_load` per file:
+
+```
+let sheet = Sprite.sheet("assets/tiles.png", 16, 16)
+let floor = Sprite.cell(sheet, 0, 0)
+let boss = Sprite.cell_span(sheet, 4, 2, 2, 2) # a 32x32 sprite spanning 2x2 cells
+Sprite.define("hero", sheet, 1, 3) # name a cell
+# ... later
+Sprite.draw(Sprite.named("hero"), x, y) # through camera / zoom / clip
+```
+
+And preload incrementally so the first frame doesn't stall — the loading-scene
+pattern:
+
+```
+Assets.enqueue("hero", "assets/hero.png")
+# in a loading scene, each frame:
+Assets.pump(4) # load up to 4 this frame
+# draw Assets.progress() (0..100) as a bar; become the play scene when Assets.ready()
+```
+
+### 5.6 Engine sprite-render system (#85)
+
+The engine already auto-*ticks* SpriteAnim/Motion; it now auto-*draws* too. Declare
+a `Sprite` component (from `ludic.core`) and the engine draws it each Render frame
+from the entity's `Position` — no hand-written Render handler:
+
+```
+import "ludic.core/components.ludic"
+spawn Player { Position { x: 40, y: 40 }, Sprite { id: hero } }
+# ... no per-entity draw_sprite; the engine draws Sprite entities (adds the
+# SpriteAnim frame when present). Opt out by omitting Sprite / `disable system esys_sprite`.
+```
+
+### 5.7 World bounds (#84)
+
+Keep entities in a play area without hand-clamping `Position` — declare one
+`Bounds` config entity:
+
+```
+import "ludic.core/components.ludic"
+spawn Arena { Bounds { x: 0, y: 0, w: 320, h: 240, policy: 0 } }
+# policy 0 clamp, 1 wrap, 2 bounce (flip velocity), 3 kill (despawn when fully outside)
+```
+
+Runs in LateUpdate (after movement). Off by default (no `Bounds` = open world). Also
+adds `World.despawn(entity)` — the by-id reflective form of the `despawn` statement.
+
+### 5.8 Entity-pool stats (#80)
+
+The ECS already recycles freed entity slots through a freelist (spawn/despawn does
+no per-spawn allocation and cannot fragment). `Pool.*` exposes the counters:
+
+```
+Pool.live() # entities alive now
+Pool.free() # freed slots waiting to be reused
+Pool.reserved() # high-water — flat across a steady spawn/despawn loop (proves reuse)
+Pool.capacity() # the fixed entity cap
+```
+
+### 5.9 `namespace` block form (#76)
+
+Declare a namespace once and control its public surface, instead of the
+per-function `@Namespace(Name)`:
+
+```
+namespace Combat {
+ export function amount() -> int { return base() + 5 } # callable as Combat.amount()
+ internal function base() -> int { return 10 } # private helper (Combat.base() is a compile error)
+}
+```
+
+`export` (the default) is the public surface; `internal` is a private helper
+(emitted, callable by short name from siblings, but not part of `Name.*`). It is
+sugar for `@Namespace`, so namespaces declared the old way are unchanged.
+
+### 5.10 Cursor capture (#89)
+
+A windowed action game can hide/lock/confine the OS cursor:
+
+```
+Input.cursor_mode(2) # 0 normal, 1 hidden, 2 locked (relative aim), 3 confined
+```
+
+Mode 2 (locked) hides the cursor and feeds relative motion through
+`Input.mouse_dx/dy` with `Input.mouse_x/y` as a clamped virtual cursor. Auto-releases
+on focus loss (Cmd-Tab) and on close. No-op headless.
+
+---
+
+
+## 6. External projects & packaging
+
+### 6.1 The engine runtime ships with the toolchain now (#75)
+
+In 0.2, an external game that consumed the `ludic.*` packages had to copy or
+symlink the engine runtime (`runtime/native/*`) into its `ludic_modules/`, because
+the compiler resolved the auto-spliced runtime through the module root.
+
+In 0.3 the compiler resolves a `runtime/…` import it can't find locally from
+**`$LUDIC_HOME`** (the toolchain install — where `cocoa.ll` already comes from),
+*before* the module root. So:
+
+- **Remove** any copy/symlink of `runtime/` from your project's `ludic_modules/`.
+- **Set `LUDIC_HOME`** to the toolchain install (the repo root, or wherever `bin/`
+ and `runtime/` live) when you build. `ludic_modules/` now holds only third-party
+ packages.
+
+In-repo builds are unaffected (the runtime resolves locally there).
+
+### 6.2 Building against packages
+
+Use `x add` to fetch packages, then `x get`. For an in-repo build against
+`packages/`, point `LUDIC_MODULES` at it and `LUDIC_HOME` at the toolchain, e.g.:
+
+```
+LUDIC_HOME=/path/to/ludic LUDIC_MODULES=/path/to/ludic/packages \
+ ludicc mygame.ludic -o mygame
+```
+
+Prebuilt (dylib) packages link via `x link-flags` (or `x app` in-repo).
+
+---
+
+
+## 7. Full change index
+
+Everything in v0.3.0, by area. See `CHANGELOG.md` for the per-change detail.
+
+**Packaging** — package manager (#63), prebuilt binary packages (#64),
+package-declarable `@Namespace` / `@EngineSystem` registries (#62).
+
+**Controllers** — ludic.gameplay (#57), ludic.platformer (#58), ludic.shooter
+(#60), ludic.npcai (#61), ludic.rpg (#59).
+
+**Tiled maps** — the full TMX/TSX/TMJ pipeline (#66–#74): XML/base64/gzip/zstd
+primitives, readers, render, collision, animated tiles, objects/properties/
+templates/spawning, image/group layers, iso/stagger/hex, infinite maps + worlds.
+
+**Engine & rendering** — `Camera.zoom` (#78), `@ClearColor` auto-clear/present
+(#86), the engine sprite-render system + `draw_sprite` deprecation (#85), world
+bounds + `World.despawn` (#84), entity-pool stats (#80), the spritesheet/atlas API
+(#81), async asset preload (#82), canonical `ludic.core` components (#77).
+
+**Input** — the Input Manager + automatic device-layer drive (#83),
+`Input.axis_i` (#79), the `key_pressed`/`key_released` edge fix (#87), cursor
+capture (#89), and the windowed quit-key change (#88).
+
+**Language** — the `namespace` block form (#76).
+
+**Compiler / toolchain** — runtime resolves from `$LUDIC_HOME` (#75), and the
+`emit_index_addr` element-type fix for `slice[obj.field]`.
+
+---
+
+*Questions or a migration snag? Open an issue at
+.*