MoonLive runs on every board: the Xtensa frame fix, and a compiler bounded by memory

docs/MIGRATING.md

@@ -20,6 +20,23 @@ projectMM ships **no migration code**: the persistence layer is robust by defaul
 
 ## Unreleased (`next-iteration`)
 
+### MoonLive scripts move to the filesystem (2026-08-11)
+
+A scripted module used to carry its script as a `source` textarea — a fixed 1 KB array per module, plus a second 1 KB copy to notice edits, **resident whether or not a script was loaded**. Six modules cost 13 KB of a classic ESP32's 320 KB for text that was mostly empty. The script now lives in a file under `/moonlive/`, and the module holds only its **name** (~32 bytes): it is read into a right-sized buffer to compile and freed immediately, so nothing script-sized stays in RAM. A script is bounded by the filesystem instead of by a 1 KB array.
+
+**Action: *re-add a module* — or, to keep your scripts, *update a file* first.**
+
+The `source` control no longer exists, so a persisted `"source"` value is an unknown key and is ignored (the robust-reader rule). A MoonLive module therefore boots with **no script**, reporting `no script — set the script name`, and renders nothing until one is named.
+
+| What | Why | What to do |
+|---|---|---|
+| Your script text | It was persisted under `source`, a control that is gone | **Copy it out before updating** — it is in `/.config/Layouts.json` (or `Effects.json`) as `"N.source"`. Save it as `/moonlive/<name>.mlv` via the File Manager, then set the module's `script` control to `<name>.mlv` |
+| The module's own controls | A script's `@control` sliders exist only once it has compiled, so they are absent until a script is named | Nothing — they reappear with the script, keeping their persisted values |
+
+`/moonlive/` is created on demand: naming a script is enough to make the folder appear, so a fresh device needs no setup.
+
+**Editing today** goes through the File Manager rather than the module's own card. Wiring the card's editor to the same file is a separate change.
+
 ### MoonLive: a script can no longer declare a name the engine supplies (2026-08-10)
 
 `t` (elapsed milliseconds), `width`/`height`/`depth` (the logical grid) and `x`/`y`/`z` (the light a modifier is transforming) are now **system variables** the engine supplies, so a script cannot declare one. Previously each binding faked them by prepending hidden declarations to the script, which meant an effect could declare its own `width` and quietly disagree with the layer it was drawing into.

docs/metrics/repo-health.json

@@ -1,76 +1,76 @@
 {
-  "commit": "9d77ade4",
+  "commit": "38a28dc9",
   "flash": {
     "esp32": 1762368,
-    "esp32p4-eth": 1604272,
+    "esp32p4-eth": 1603952,
     "esp32p4-eth-wifi": 1793760,
-    "esp32s3-n16r8": 1753232,
+    "esp32s3-n16r8": 1752992,
     "esp32s3-n8r8": 1753232,
     "esp32s31": 2025600,
-    "desktop": 1137928,
+    "desktop": 1138184,
     "esp32-16mb": 1714608,
     "esp32-eth": 1324928,
     "esp32-wrover": 1765504
   },
   "perf": {
     "desktop": {
-      "tick_us": 129,
-      "fps": 7751
+      "tick_us": 132,
+      "fps": 7575
     },
     "esp32": {
       "tick_us": 2151,
       "fps": 464
     }
   },
   "loc": {
-    "core": 16980,
-    "light": 24317,
-    "platform": 12860,
+    "core": 17044,
+    "light": 24402,
+    "platform": 12878,
     "ui": 6468,
-    "test": 41246,
-    "moondeck": 20323
+    "test": 41313,
+    "moondeck": 20326
   },
   "comments": {
     "core": {
-      "lines": 6402,
-      "ratio": 0.41
+      "lines": 6433,
+      "ratio": 0.411
     },
     "light": {
-      "lines": 9427,
+      "lines": 9473,
       "ratio": 0.429
     },
     "platform": {
-      "lines": 4365,
+      "lines": 4377,
       "ratio": 0.375
     },
     "ui": {
       "lines": 1670,
       "ratio": 0.274
     },
     "test": {
-      "lines": 7169,
+      "lines": 7193,
       "ratio": 0.201
     },
     "moondeck": {
-      "lines": 3246,
+      "lines": 3248,
       "ratio": 0.183
     }
   },
   "tests": {
-    "cases": 1325,
+    "cases": 1326,
     "scenarios": 23
   },
   "docs": {
     "md_files": 178,
-    "md_lines": 24401,
+    "md_lines": 24421,
     "plans_files": 91,
     "backlog_lines": 3629,
     "lessons_lines": 454,
     "claude_md_lines": 135
   },
   "complexity": {
-    "functions": 2473,
-    "over_threshold": 151,
+    "functions": 2480,
+    "over_threshold": 153,
     "worst_ccn": 93
   }
 }

docs/metrics/repo-health.md

@@ -1,63 +1,63 @@
 # Repo health
 
-Measured at `9d77ade4`. Generated by [`moondeck/check/repo_health.py`](../../moondeck/check/repo_health.py) on every KPI-gate run. **Do not edit by hand.**
+Measured at `38a28dc9`. Generated by [`moondeck/check/repo_health.py`](../../moondeck/check/repo_health.py) on every KPI-gate run. **Do not edit by hand.**
 
 Current state only; the trend is this file's git history (`git log -p docs/metrics/repo-health.md`). Nothing here fails a build: the numbers make growth visible, the judgment stays human.
 
 ## Firmware size
 
 | Target | Flash |
 |---|---:|
-| desktop | 1,111 KB (+0 KB) ⚠ |
+| desktop | 1,112 KB (+0 KB) ⚠ |
 | esp32 | 1,721 KB |
 | esp32-16mb | 1,674 KB |
 | esp32-eth | 1,294 KB |
 | esp32-wrover | 1,724 KB |
-| esp32p4-eth | 1,567 KB (+0 KB) ⚠ |
+| esp32p4-eth | 1,566 KB (−0 KB) ✓ |
 | esp32p4-eth-wifi | 1,752 KB |
-| esp32s3-n16r8 | 1,712 KB |
-| esp32s3-n8r8 | 1,712 KB (+84 KB) ⚠ |
+| esp32s3-n16r8 | 1,712 KB (−0 KB) ✓ |
+| esp32s3-n8r8 | 1,712 KB |
 | esp32s31 | 1,978 KB |
 
 ## Render performance
 
 | Target | Tick | FPS |
 |---|---:|---:|
-| desktop | 129 µs (+1 µs) ⚠ | 7,751 (−61) ⚠ |
+| desktop | 132 µs (+3 µs) ⚠ | 7,575 (−176) ⚠ |
 | esp32 | 2,151 µs | 464 |
 
 ## Code
 
 | Area | Lines | Comments | Comment share |
 |---|---:|---:|---:|
-| core | 16,980 | 6,402 | 41.0 % |
-| light | 24,317 (+5) ⚠ | 9,427 | 42.9 % |
-| platform | 12,860 | 4,365 | 37.5 % |
+| core | 17,044 (+64) ⚠ | 6,433 | 41.1 % (+0.1 %) ⚠ |
+| light | 24,402 (+85) ⚠ | 9,473 | 42.9 % |
+| platform | 12,878 (+18) ⚠ | 4,377 | 37.5 % |
 | ui | 6,468 | 1,670 | 27.4 % |
-| test | 41,246 | 7,169 | 20.1 % |
-| moondeck | 20,323 | 3,246 | 18.3 % |
+| test | 41,313 (+67) ⚠ | 7,193 | 20.1 % |
+| moondeck | 20,326 (+3) ⚠ | 3,248 | 18.3 % |
 
 ## Tests
 
 | Kind | Count |
 |---|---:|
-| unit cases | 1,325 |
+| unit cases | 1,326 (+1) ✓ |
 | scenarios | 23 |
 
 ## Complexity
 
 | Metric | Value |
 |---|---:|
-| functions | 2,473 (+1) ✓ |
-| over threshold | 151 |
+| functions | 2,480 (+7) ✓ |
+| over threshold | 153 (+2) ⚠ |
 | worst CCN | 93 |
 
 ## Documentation
 
 | Metric | Value |
 |---|---:|
 | markdown files | 178 |
-| markdown lines | 24,401 |
+| markdown lines | 24,421 (+20) ⚠ |
 | plan files | 91 |
 | backlog lines | 3,629 |
 | lessons lines | 454 |

docs/moonmodules/light/MoonLiveEffect.md

@@ -4,7 +4,7 @@ MoonLive is projectMM's **live-script engine** — author an effect as text and
 
 Scripts call the same [power functions](power-functions.md) compiled effects use, reached through the builtin table — so the vocabulary is shared, in its flat scalar form.
 
-A scripted effect carries its **script source** as an editable, persisted multi-line text control (a resizable `textarea` in the UI), and a front-end (lexer → parser → IR → per-ISA assembler) compiles it to native code on the next tick. The grammar is a sequence of **statements** — a function call, or a `for` loop over them — with **expression arguments**, so any argument may be a literal or a nested call:
+A scripted effect names a **script file** under `/moonlive/`; the UI loads, edits and saves that file, and the module holds only the name (~32 bytes) — the text is read into a right-sized buffer to compile and freed immediately, so nothing script-sized stays resident. A front-end (lexer → parser → IR → per-ISA assembler) compiles it to native code on the next tick. The grammar is a sequence of **statements** — a function call, or a `for` loop over them — with **expression arguments**, so any argument may be a literal or a nested call:
 
 ```
 setRGB(random16(256), 0, 0, 255);   // a random pixel, blue
@@ -16,7 +16,7 @@ The functions are **not built into the compiler** — `setRGB`, `fill`, `random1
 
 ## Controls
 
-- `source` — the script text (default: random pixels — `setRGB(random16(256), random16(256), random16(256), random16(256));`, one random light in a random color each tick). Editing it recompiles live: a valid script swaps in on the next tick; a failed compile frees the old code, shows the diagnostic in the module status, and renders dark until fixed (the script-editor loop, robust + no reboot).
+- `script` — the file name under `/moonlive/`, e.g. `lines.mlv`. A fresh module has none: it reports `no script — set the script name` and renders nothing, rather than every new module compiling the same default. Naming one (or re-naming it after an edit) recompiles live: a valid script swaps in on the next tick; a failed compile frees the old code, shows the diagnostic in the module status, and renders dark until fixed (the script-editor loop, robust + no reboot). The directory is created on demand.
 - **Scripted controls** — a script declares a tunable variable with a range annotation, and the engine surfaces it as a real `uint8` MoonModule control (slider + UI + persistence), bound to a live value the running native code reads each tick:
 
   ```c
@@ -25,7 +25,7 @@ The functions are **not built into the compiler** — `setRGB`, `fill`, `random1
   setRGB(speed, hue, 0, 255);
   ```
 
-  Declaring the variable is what **creates** the control: `uint8_t <name> = <default>;` becomes a `<name>` slider (default `<default>`, range `0..255`). The trailing `// @control <min>..<max>` only **adjusts that control's range**; it's optional. A declared name used in a statement reads the control's **current** value. Editing a control's slider does **not** recompile — the value lands in the engine's control-values arena and the next render tick reads it (the live-edit guarantee, the *no-reboot* principle). Editing the `source` recompiles and re-derives the control set; a control kept across the edit keeps its slider value, a removed control's saved value drops. Stage 1 is `uint8` only.
+  Declaring the variable is what **creates** the control: `uint8_t <name> = <default>;` becomes a `<name>` slider (default `<default>`, range `0..255`). The trailing `// @control <min>..<max>` only **adjusts that control's range**; it's optional. A declared name used in a statement reads the control's **current** value. Editing a control's slider does **not** recompile — the value lands in the engine's control-values arena and the next render tick reads it (the live-edit guarantee, the *no-reboot* principle). Saving the script file and re-naming it recompiles and re-derives the control set; a control kept across the edit keeps its slider value, a removed control's saved value drops. Stage 1 is `uint8` only.
 
 ### System variables — what the engine hands a script
 
@@ -70,7 +70,7 @@ Registered by the light domain, not built into the compiler (the core owns only
 
 ### Wire contract — control declaration
 
-The controls are **derived from `source`** (one per declared `uint8` control; the optional `@control` annotation only refines a control's range), then **surfaced in `/api/state`** — the device JSON view the integrator consumes — as regular `uint8` controls alongside `source`. So an integrator sees and writes them exactly like any other control — e.g. `POST /api/control` with `{"module": "ML", "control": "speed", "value": 80}`; they're fully present in the device JSON, just authored in the script rather than fixed in the module. The script's `\n` line breaks are standard JSON string escapes the device decodes, so a multi-line `source` round-trips.
+The controls are **derived from the script** (one per declared `uint8` control; the optional `@control` annotation only refines a control's range), then **surfaced in `/api/state`** — the device JSON view the integrator consumes — as regular `uint8` controls alongside `script`. So an integrator sees and writes them exactly like any other control — e.g. `POST /api/control` with `{"module": "ML", "control": "speed", "value": 80}`; they're fully present in the device JSON, just authored in the script rather than fixed in the module. The script's `\n` line breaks are standard JSON string escapes the device decodes, so a multi-line script round-trips through `/api/file`.
 
 ## Pieces
 
@@ -79,7 +79,7 @@ The controls are **derived from `source`** (one per declared `uint8` control; th
 - **`MoonLiveCompiler`** (`src/core/moonlive/MoonLiveCompiler.h/.cpp`) — the **platform-independent front-end**: a recursive-descent lexer + expression parser that lowers each statement to the typed IR (`MoonLiveIr.h`). Pure (source + table in, IR out, deterministic). Knows the *language*, never an ISA and never a domain.
 - **`MoonLiveBuiltins_light`** (`src/light/moonlive/MoonLiveBuiltins_light.h`) — the **light-domain registration**: the only place the LED vocabulary lives. Registers the whole vocabulary above — Inline ops lowering to stores, and Calls into host helpers — plus the system variables each binding supplies. A different host (display, sensor) writes its own table; the core is unchanged.
 - **per-ISA assembler + lowering** (`src/platform/<target>/moonlive_asm_*` + `moonlive_lower_*`) — a tiny named-instruction MacroAssembler with label back-patching, and the IR→bytes lowering that drives it. Xtensa for the classic/S3 (`__XTENSA__`), the host ISA on desktop (arm64/x86-64). Adding an ISA is a new assembler + lowering; the front-end and IR are unchanged. (`emitFill`/`emitAnimatedFill` remain as the hand-encoded `fill` references the assembler's output is checked against.)
-- **`MoonLiveEffect`** (`src/light/moonlive/MoonLiveEffect.h`) — the **thin binding**: a first-class `EffectBase` carrying the `source` control, whose `tick()` delegates to the engine over its own `buffer()`. `compile(source, table, sysvars)` takes both host tables: the shared `lightBuiltins()`, and the system variables THIS binding supplies — `effectSysVars()` here, `modifierSysVars()` for a modifier, `layoutSysVars()` for a layout, which is what decides the names each kind of script can read and cannot declare. The engine is projectMM-agnostic; the binding is the only coupled layer.
+- **`MoonLiveEffect`** (`src/light/moonlive/MoonLiveEffect.h`) — the **thin binding**: a first-class `EffectBase` carrying the `script` control, whose `tick()` delegates to the engine over its own `buffer()`. `compile(source, table, sysvars)` takes both host tables: the shared `lightBuiltins()`, and the system variables THIS binding supplies — `effectSysVars()` here, `modifierSysVars()` for a modifier, `layoutSysVars()` for a layout, which is what decides the names each kind of script can read and cannot declare. The engine is projectMM-agnostic; the binding is the only coupled layer.
 
 ## Cross-domain wiring
 
@@ -95,9 +95,9 @@ MoonLive's native-codegen approach — compile a small C-like language straight
 
 [unit_moonlive_fill](../../../test/unit/core/unit_moonlive_fill.cpp) runs the engine path in-process on the desktop host backend (`compile`/`run`, the animated routine, zero-lights, recompile, `free`, the `allocExec`/`writeExec`/`freeExec` round-trip, the buffer-shape guards). [unit_moonlive_ir](../../../test/unit/core/unit_moonlive_ir.cpp) pins the **behavioral golden** — a compiled `fill` and the hand-encoded reference render an identical buffer — plus setRGB's single-pixel write and the runtime bounds guard. [unit_moonlive_compiler](../../../test/unit/core/unit_moonlive_compiler.cpp) pins the expression grammar (`random16` in any/every argument slot, uint16 bounds), the parser diagnostics (no crash on malformed input), live recompile, and the **domain-neutral** property: with an empty builtin table the core knows *no* functions, and a host can register an arbitrary name against the same machinery.
 
-The grammar + bounds guard are verified live on the S3/Olimex (Xtensa) by editing the `source` control — the device compiles the expression on-chip and renders it.
+The grammar + bounds guard are verified live on the S3/Olimex (Xtensa) by saving a script file and naming it — the device compiles the expression on-chip and renders it.
 
-[scenario_MoonLiveEffect_livescript](../../../test/scenarios/light/scenario_MoonLiveEffect_livescript.json) exercises the effect **as a wired MoonModule** — what the unit tests can't reach: add it, live-edit the `source` to recolor (recompile), push a broken script (`MoonLive::compile` fails, frees the previous code, `MoonLiveEffect` reports the parse error in the status and renders dark — no crash), recover, resize the grid to 1×1 and back while rendering (the every-grid-size hard rule), then remove and re-add (exec memory re-acquired clean). It runs in-process on the desktop backend each commit, and the same JSON runs live over REST against the device backends. The Xtensa/RISC-V backends are validated by the live S3/P4 runs (a `MoonLiveEffect` on a Layer lights the grid from its `source`), which the desktop tests can't reach.
+[scenario_MoonLiveEffect_livescript](../../../test/scenarios/light/scenario_MoonLiveEffect_livescript.json) exercises the effect **as a wired MoonModule** — what the unit tests can't reach: add it, live-edit the script file to recolor (recompile), push a broken script (`MoonLive::compile` fails, frees the previous code, `MoonLiveEffect` reports the parse error in the status and renders dark — no crash), recover, resize the grid to 1×1 and back while rendering (the every-grid-size hard rule), then remove and re-add (exec memory re-acquired clean). It runs in-process on the desktop backend each commit, and the same JSON runs live over REST against the device backends. The Xtensa/RISC-V backends are validated by the live S3/P4 runs (a `MoonLiveEffect` on a Layer lights the grid from its script file), which the desktop tests can't reach.
 
 ## Source
 

docs/moonmodules/light/MoonLiveLayout.md

@@ -77,7 +77,7 @@ So it runs twice. On the first pass `addLight` counts; on the second it emits ea
 
 | control | what it does |
 |---|---|
-| `source` | the script; editing it recompiles and re-places the lights live |
+| `script` | the file name under `/moonlive/`; naming it (or re-naming it after an edit) recompiles and re-places the lights live |
 
 Plus one control per `@control` the script declares.
 

docs/moonmodules/light/MoonLiveModifier.md

@@ -42,7 +42,7 @@ It is for debugging and comes back out again — [what print costs](../../../moo
 
 | control | what it does |
 |---|---|
-| `source` | the script; editing it recompiles and re-maps live |
+| `script` | the file name under `/moonlive/`; naming it (or re-naming it after an edit) recompiles and re-maps live |
 
 Plus one control per `@control` the script declares — `uint8_t amount = 4; // @control 0..64`
 becomes a slider, and moving it rebuilds the mapping just as editing the script does.

moondeck/moonlive/disasm.py

@@ -43,6 +43,9 @@ def main() -> int:
             ["c++", "-std=c++20", "-O0", "-I", os.path.join(ROOT, "src"),
              "-I", os.path.join(ROOT, "src", "platform", "desktop"),
              TOOL_SRC, os.path.join(ROOT, "src", "core", "moonlive", "MoonLiveCompiler.cpp"),
+             # The IR sizes its op array with platform::alloc, so the platform implementation has
+             # to come along — the compiler is no longer self-contained.
+             os.path.join(ROOT, "src", "platform", "desktop", "platform_desktop.cpp"),
              "-o", emitter],
             capture_output=True, text=True)
         if build.returncode != 0: