chore(repo): DX cleanup — categorise examples, text-diffable golden, build/ output (#27 #28 #30)

Repository-cleanup / DX pass folding three tracker items into one coherent
change, verified green end to end (`bin/x test` 49/0, `bin/x selfhost-test`
29/0, `bin/x test-tools` 29/0).

#28 — curate & categorise examples/
- 42 flat entries regrouped into intent-revealing subdirs: games/, rendering/,
  ecs/, events/, networking/, lang/, library/ (was lib/).
- chronorift dir-vs-file duplication resolved: the entry file and its import
  modules now live together under games/chronorift(.ludic).
- Every path reference updated repo-wide (test runner, editor-tool drivers,
  docs/site, design docs).
- New examples/README.md indexes the whole set with run commands.
- Showcase examples without a self-asserting entry (hello, events, net_rt) now
  get a compile-only rot guard in `bin/x test`, so nothing here rots silently.

#30 — text-diffable golden baseline
- The 4 binary selfhost/golden/*.ppm blobs are replaced by a single
  selfhost/golden/renders.sha256 manifest (SHA-256 per render). Hashes are
  byte-identical to the old PPMs, so the baseline is unchanged — only its form.
- game_case now compares framebuffer hashes; a regression shows as a changed
  hex line in review, not "binary files differ".
- New `bin/x golden` regenerates the manifest deliberately (review with
  `git diff selfhost/golden/renders.sha256`).

#27 — PPM & asset handling
- Headless renders now write build/out.ppm, never the repo root; `x app`,
  `x clean`, messaging and .gitignore updated to match. Nothing is written to
  the working root any more.
- Redundant local Kenney .zip archives removed (the art ships extracted;
  .gitignore already excludes *.zip). CC0 License.txt files retained.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

examples/events/cancel.ludic

@@ -0,0 +1,27 @@
+# cancel.ludic — EV3: cancellable (decision) events.
+#
+# A `cancellable` event is fired BEFORE an action so a listener can veto it. The
+# listener calls `cancel`; the caller reads the verdict back — `emit E(…)` used as
+# an expression yields the cancelled flag (1 = vetoed, 0 = allowed). A foreign mod
+# vetoes the same way, by setting the payload's trailing `cancelled` field over
+# the ABI. This is the modding headline: observation becomes control.
+#
+# Running it prints:  0 1 92
+program Cancel {
+  event cancellable BeforeHurt { amount: int = 0 }
+
+  @On(BeforeHurt) handler Armor { if amount > 10 { cancel } }   # veto any hit over 10
+
+  entry {
+    let v1 = emit BeforeHurt(amount: 5)      # 5 <= 10 -> allowed
+    print(v1)                                 # 0
+    let v2 = emit BeforeHurt(amount: 15)     # 15 > 10 -> vetoed
+    print(v2)                                 # 1
+
+    # the realistic shape: only apply the effect when the decision isn't vetoed
+    var hp = 100
+    if emit BeforeHurt(amount: 8)  == 0 { hp = hp - 8 }    # allowed  -> 92
+    if emit BeforeHurt(amount: 50) == 0 { hp = hp - 50 }   # vetoed   -> unchanged
+    print(hp)                                 # 92
+  }
+}

examples/events/events.ludic

@@ -0,0 +1,25 @@
+# events.ludic — EV0: the event bus core.
+#
+# `event E { fields }` declares a public event carrying a POD payload. `@On(E)
+# handler …` registers a listener whose body reads the payload fields by name.
+# `emit E(field: v, …)` fires the event: it calls every @On(E) listener, in
+# declaration order, as a direct call — the whole thing desugars to code, with no
+# runtime and no dispatch table. A program that declares no `event` is compiled
+# byte-for-byte as before (the subsystem is gated on `g_events`).
+#
+# Running it prints:  5 8 20 30 999 42 42
+program Events {
+  event Hurt    { entity: int = 0, amount: int = 0 }   # a payload with fields + defaults
+  event Cleared { }                                    # an empty payload is allowed
+
+  @On(Hurt) handler Flash { print(amount) }            # listeners bind payload fields by name
+  @On(Hurt) handler Guard { print(entity + amount) }   # a second listener, run after the first
+  @On(Cleared) handler Cheer { print(999) }
+
+  entry {
+    emit Hurt(entity: 3, amount: 5)       # -> Flash 5, Guard 3+5=8
+    emit Hurt(entity: 10, amount: 20)     # -> Flash 20, Guard 10+20=30
+    emit Cleared()                        # -> Cheer 999
+    emit Hurt(amount: 42)                 # entity defaults to 0 -> Flash 42, Guard 0+42=42
+  }
+}

examples/events/layer_events.ludic

@@ -0,0 +1,27 @@
+# layer_events.ludic — EV1 for layers + SCENES E2 (layer toggle). A `public` layer
+# promotes its show/hide to events; `enable layer L` / `disable layer L` flips the
+# layer on and off (its handlers stop running while hidden) and fires
+# layer_<L>_show / layer_<L>_hide. This closes the last scope of "events across the
+# whole architecture" — properties, models, scenes, program, and now layers.
+#
+# Running it prints:  50 2 1 50
+program LayerEvents {
+  var step: int = 0
+
+  @On(layer_Hud_show) handler Shown  { print(1) }   # a mod reacts when the HUD returns
+  @On(layer_Hud_hide) handler Hidden { print(2) }   # ...and when it's hidden
+
+  scene Main start {
+    layer Hud public {
+      handler Draw phase Update { print(50) }        # only runs while Hud is enabled
+    }
+    layer Ctrl {
+      handler Drive phase LateUpdate {
+        step = step + 1
+        if step == 1 { disable layer Hud }           # frame 1: hide -> Hidden 2, Draw stops
+        if step == 2 { enable layer Hud }            # frame 2: show -> Shown 1, Draw resumes
+        if step == 3 { quit() }                      # frame 3: after Draw ran again
+      }
+    }
+  }
+}

examples/events/mod_events.ludic

@@ -0,0 +1,16 @@
+# mod_events.ludic — the event bus with two listeners on one event, driven from
+# Ludic (replaces the former tests/mod_c/mod.c foreign-mod host). A public event
+# `Damage` has two @On listeners: one prints the amount, one accumulates a total.
+# Emitting it twice runs both listeners each time. Prints 10 / 32 / 42.
+program ModEvents {
+  var total: int = 0
+  event Damage { amount: int = 0 }
+  @On(Damage) handler Native { print(amount) }        # prints each hit
+  @On(Damage) handler Accum  { total = total + amount }   # sums them
+
+  entry {
+    emit Damage(amount: 10)     # Native prints 10
+    emit Damage(amount: 32)     # Native prints 32
+    print(total)                # 42
+  }
+}

examples/events/program_events.ludic

@@ -0,0 +1,18 @@
+# program_events.ludic — EV1 for the program ("game") scope: @Public on @OnStart
+# and @OnQuit promotes them to program_start / program_quit events, so a mod runs
+# its own setup after the game boots and its own teardown as the game exits — the
+# top-level modding entry points (Blender's app handlers, Minetest's on_shutdown).
+#
+# Running it prints:  1 100 2 200
+program ProgramEvents {
+  property Health { hp: int = 0 }
+  model Dummy { Health }
+
+  @Public @OnStart handler Boot { print(1) }        # -> program_start
+  @Public @OnQuit  handler Bye  { print(2) }        # -> program_quit
+
+  @On(program_start) handler ModInit { print(100) } # mod boots after the game
+  @On(program_quit)  handler ModDone { print(200) } # mod tears down as the game exits
+
+  handler Run phase Update { quit() }
+}

examples/events/promote.ludic

@@ -0,0 +1,32 @@
+# promote.ludic — EV1: `@Public` promotes a lifecycle hook to a public event.
+#
+# Marking a lifecycle hook `@Public` makes its fire site ALSO emit an event named
+# for the moment — `model_<M>_spawn`, `model_<M>_despawn` — carrying the entity
+# (and, for despawn, the EndReason). Anything can then subscribe: a native
+# listener with `@On(model_Enemy_spawn)`, or a foreign mod binding
+# `ludic_on_model_Enemy_spawn` over the C ABI. The game's own lifecycle becomes
+# the modding surface, with no hand-written `emit` in the hook body.
+#
+# Running it prints:  100 101 200 201
+program Promote {
+  property Health { hp: int = 0, max: int = 100 }
+  model Enemy { Health }
+
+  @Public @OnSpawn(Enemy)   handler Init  { Health.hp = Health.max }   # -> model_Enemy_spawn
+  @Public @OnDespawn(Enemy) handler Clean { }                          # -> model_Enemy_despawn
+
+  # Listeners on the promoted events. These read the generated payload (entity,
+  # and reason for despawn) by name — exactly what a foreign mod receives.
+  @On(model_Enemy_spawn)   handler Spawned { print(entity + 100) }
+  @On(model_Enemy_despawn) handler Died    { print(entity + reason + 200) }
+
+  handler Seed phase Start {
+    spawn Enemy { Health { max: 50 } }     # entity 0 -> Spawned 100
+    spawn Enemy { Health { max: 60 } }     # entity 1 -> Spawned 101
+  }
+
+  handler Run phase Update {
+    for (h) in query [Health] { despawn self() }   # despawn 0 -> Died 200, despawn 1 -> Died 201
+    quit()
+  }
+}

examples/events/prop_events.ludic

@@ -0,0 +1,26 @@
+# prop_events.ludic — EV1 for properties: @Public promotes the structural
+# attach/detach hooks to public events, so a mod sees a property appear or vanish
+# on a live entity (the same shape works for @OnEnable/@OnDisable → enable/disable
+# events). This extends the public-event surface past models to properties —
+# "events for properties, models, scenes, layers" in the architecture.
+#
+# Running it prints:  300 400
+program PropEvents {
+  property Tag    { v: int = 0 }
+  property Shield { amount: int = 0 }
+  model Unit { Tag }
+
+  @Public @OnAttach(Shield) handler Up   { }   # -> prop_Shield_attach
+  @Public @OnDetach(Shield) handler Down { }   # -> prop_Shield_detach
+
+  @On(prop_Shield_attach) handler Gained { print(entity + 300) }   # entity 0 -> 300
+  @On(prop_Shield_detach) handler Lost   { print(entity + 400) }   # entity 0 -> 400
+
+  handler Seed phase Start { spawn Unit { Tag { v: 1 } } }         # entity 0
+
+  handler Run phase Render {
+    for (u) in query [Unit]   { attach Shield on self() { amount: 5 } }   # -> prop_Shield_attach -> 300
+    for (s) in query [Shield] { detach Shield on self() }                # -> prop_Shield_detach -> 400
+    quit()
+  }
+}

examples/events/recurse.ludic

@@ -0,0 +1,21 @@
+# recurse.ludic — EV6: re-entrant emit is bounded. Ping's listener emits Pong,
+# Pong's listener emits Ping — an event cycle that would hang the frame forever.
+# The depth bound (EV_DEPTH_CAP) makes the nesting trap as an early return, so the
+# program terminates with a bounded count instead of spinning. This is the "no
+# runaway event cycle" guarantee.
+#
+# Running it prints:  16   (the cycle bottoms out at the depth cap, deterministically)
+program Recurse {
+  var n: int = 0
+
+  event Ping { }
+  event Pong { }
+
+  @On(Ping) handler A { n = n + 1; emit Pong() }   # each Ping deepens by one Pong
+  @On(Pong) handler B { emit Ping() }              # ...and each Pong by one Ping
+
+  entry {
+    emit Ping()
+    print(n)
+  }
+}

examples/events/scene_events.ludic

@@ -0,0 +1,22 @@
+# scene_events.ludic — EV1 for scenes: a `public` scene promotes its on-enter /
+# on-exit to public events scene_<S>_enter / scene_<S>_exit, extending the modding
+# surface to the game's scene structure. A mod (native @On here, or foreign over
+# the ABI) reacts as the game moves between scenes.
+#
+# Running it prints:  10 1 20 2 30 3
+program SceneEvents {
+  @On(scene_Menu_enter) handler Greet { print(1) }
+  @On(scene_Menu_exit)  handler Bye   { print(2) }
+  @On(scene_Game_enter) handler Begin { print(3) }
+
+  scene Menu start public {
+    on enter { print(10) }        # boot enters Menu: 10, then scene_Menu_enter -> 1
+    on exit  { print(20) }        # become leaves Menu: 20, then scene_Menu_exit -> 2
+    layer L { handler Go phase Update { become Game } }
+  }
+
+  scene Game public {
+    on enter { print(30) }        # become enters Game: 30, then scene_Game_enter -> 3
+    layer M { handler Stop phase Update { quit() } }
+  }
+}

examples/events/scoped.ludic

@@ -0,0 +1,21 @@
+# scoped.ludic — a despawned entity drops out of subsequent event-driven work
+# (replaces tests/mod_c/scoped_mod.c, which tested entity-scoped foreign callbacks
+# swept on despawn). Here a @On(Tick) listener counts live Units each tick; after
+# the Unit is despawned, a further tick finds none. Fires twice before the kill,
+# not the third time. Prints 2.
+program Scoped {
+  property Health { hp: int = 0 }
+  model Unit { Health }
+  var fires: int = 0
+  event Tick { }
+  @On(Tick) handler OnTick { for (Health) in query [Health, {Unit}] { fires = fires + 1 } }
+
+  entry {
+    spawn Unit { Health { hp: 1 } }
+    emit Tick()     # 1 live Unit -> fires = 1
+    emit Tick()     # fires = 2
+    for (Health) in query [Health, {Unit}] { despawn self() }   # kill the Unit
+    emit Tick()     # no live Units -> fires stays 2
+    print(fires)    # 2
+  }
+}