Scenario Tests

Auto-generated from test/scenarios/{core,light}/scenario_*.json by moondeck/docs/generate_test_docs.py. Do not edit by hand — update the JSON file's top-level fields and per-step description / bounds / contract / observed instead, then regenerate.

Scenario tests are the integration tier in the test strategy: each one is a JSON script that drives the full pipeline (desktop or live ESP32) and captures tick / heap per step against per-target contracts. Run them with moondeck/scenario/run_scenario.py (desktop) or moondeck/scenario/run_live_scenario.py (live device). See testing.md § Performance contracts for the contract semantics.

AudioService

scenario_Audio_mutation

test/scenarios/light/scenario_Audio_mutation.json — Add / configure / remove the AudioService (a Service module) and an audio-reactive effect while the render pipeline runs, proving the robustness rule for the audio producer/consumer pair. AudioService is a Service (it sits beside the pipeline, publishing an AudioFrame), and the audio effects read it through the static AudioService::latestFrame() accessor, NOT a boot-time pointer, so add/remove can happen in any order at runtime. The checks assert the pipeline keeps RENDERING (buffer non-null, fps measurable) through each mutation: adding the mic, configuring it one control write at a time (device / sampleRate / gain, the install fan-out's exact add-then-configure sequence from a catalog entry's modules+controls), adding a consumer effect, and crucially REMOVING the mic while a consumer is still live (the consumer must fall back to a silent frame, never deref a dangling pointer, the bug the boot-loop fix and the unit lifecycle tests pin, here proven end-to-end through the Scheduler). The sequential writes include a REAL live capture reinit on capture hosts; the pipeline never stalls through any of it. On a capture-capable host the device write triggers a REAL OS-capture reinit mid-render (silence-tolerant: a locked-down host degrades to a status line); the I2S pin path is proven on hardware. Grid is 64x64 so the tick stays above the host microsecond clock at every step.

Mode: mutate · Also touches: SystemModule, Services, Layouts, GridLayout, Layer, RainbowEffect, AudioVolumeEffect, AudioSpectrumEffect, Drivers, PreviewDriver

measure-pipeline-only (measure) 📏

Baseline: the render pipeline runs with no audio module present.

Bounds: - FPS ≥ 1 (absolute)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 21,739-50,000	— / —	— / —
desktop-windows	— / 27,778	— / —	— / —
esp32	— / 76.9-4,115	— / 49KB-95KB	— / 38KB-48KB
esp32s3-n16r8	— / 29,412	— / 7402KB	— / 84KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-21
• esp32: observed 2026-09-01
• esp32s3-n16r8: observed 2026-07-24

measure-audio-added (measure) 📏

Pipeline still renders with the (idle, unconfigured) mic added.

Setup (preceding non-measured steps): - add-audio-module (add_module) — Add the AudioService under the Services container (where the user adds a capability module). Pins default unset, so it stays idle; the pipeline must keep rendering.

Bounds: - FPS ≥ 1 (absolute)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 14,286-38,462	— / —	— / —
desktop-windows	— / 27,778	— / —	— / —
esp32	— / 77.0-4,237	— / 51KB-89KB	— / 38KB-72KB
esp32s3-n16r8	— / 26,316	— / 7467KB	— / 84KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-21
• esp32: observed 2026-09-01
• esp32s3-n16r8: observed 2026-07-24

measure-capture-configured (measure) 📏

Audio input configured via the sequential install-fan-out order: pipeline still renders through the full add-then-configure flow (add AudioService, then device/sampleRate/gain one write at a time, a live capture reinit among them on capture hosts).

Setup (preceding non-measured steps): - configure-device (set_control) — Pick the capture device (index 0, the OS default). On a capture-capable host this triggers a REAL live reinit: the OS device opens (or fails cleanly on a locked-down host) while the pipeline renders, the desktop equivalent of the install fan-out's pin writes. The pipeline must keep rendering through it. Optional: the control exists only where hasAudioCapture is true, so board targets record a clean skip. - configure-rate (set_control) — Change the sample rate (44100). Rebuilds the capture (or I2S) channel live, mid-render, the second config write of the sequence. - configure-gain (set_control) — Set the analysis gain. A plain (non-prepare) control write completing the add-then-configure flow a catalog inject performs; the prepareTree rebuilds before it must not have disturbed the running pipeline.

Bounds: - FPS ≥ 1 (absolute)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 15,873-38,462	— / —	— / —
desktop-windows	— / 27,778	— / —	— / —
esp32	— / 77.4-90.6	— / 48KB-92KB	— / 26KB-88KB
esp32s3-n16r8	— / 21,277	— / 7402KB	— / 76KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-23
• esp32: observed 2026-09-01
• esp32s3-n16r8: observed 2026-07-24

measure-consumer-live (measure) 📏

Pipeline renders with the producer + consumer both wired.

Setup (preceding non-measured steps): - add-audio-consumer (add_module) — Add an AudioVolumeEffect consumer under the Layer. It reads the mic via the static accessor; with the mic present it gets the live (silent, on host) frame.

Bounds: - FPS ≥ 1 (absolute)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 14,706-38,462	— / —	— / —
desktop-windows	— / 25,000	— / —	— / —
esp32	— / 73.8-85.8	— / 48KB-91KB	— / 26KB-88KB
esp32s3-n16r8	— / 21,739	— / 7379KB	— / 60KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-23
• esp32: observed 2026-09-01
• esp32s3-n16r8: observed 2026-07-24

measure-after-mic-removed (measure) 📏

Mic gone, consumer remains: pipeline keeps rendering on silent audio (buffer non-null, fps measurable). No crash from the orphaned consumer.

Setup (preceding non-measured steps): - remove-audio-module (remove_module) — Remove the mic while the consumer is STILL live. The consumer must fall back to AudioService::latestFrame()'s static silence — no dangling pointer, no crash. This is the robustness rule's hardest case for this pair.

Bounds: - FPS ≥ 1 (absolute)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 14,493-43,478	— / —	— / —
desktop-windows	— / 25,000	— / —	— / —
esp32	— / 70.5-81.9	— / 54KB-97KB	— / 26KB-92KB
esp32s3-n16r8	— / 27,027	— / 7480KB	— / 84KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-22
• esp32: observed 2026-09-01
• esp32s3-n16r8: observed 2026-07-24

measure-back-to-baseline (measure) 📏

Both audio modules gone: back to the pipeline-only baseline, still rendering.

Setup (preceding non-measured steps): - remove-audio-consumer (remove_module) — Remove the orphaned consumer too — clean teardown, pipeline still live.

Bounds: - FPS ≥ 1 (absolute)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 12,658-50,000	— / —	— / —
desktop-windows	— / 28,571	— / —	— / —
esp32	— / 65.2-76.0	— / 54KB-96KB	— / 26KB-92KB
esp32s3-n16r8	— / 29,412	— / 7482KB	— / 84KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-07-08
• esp32: observed 2026-09-01
• esp32s3-n16r8: observed 2026-07-24

AuroraEffect

scenario_Aurora_fps

test/scenarios/light/scenario_Aurora_fps.json — What a layered shader costs, one control at a time. Aurora samples a warped noise field once per layer per pixel, so its frame time is set by three knobs that multiply: how many layers, how many octaves inside each, and whether the field warps at all. The steps walk them from the cheapest configuration to the most expensive on one grid, so the ratios between the observed numbers are what an author reads to choose settings for a fixture, and a jump in any one of them between commits is a regression with a name. The grid is deliberately 64x64: large enough that per-pixel cost dominates, small enough to run on every target the contracts name.

Mode: mutate · Also touches: OscillatorBank, PolarLut, GridLayout, Layer

aurora-defaults (add_module) 📏

Aurora as it ships: 3 layers, 2 octaves, warp on. This is the number a catalog card promises, and the one every step below is read against.

Setup (preceding non-measured steps): - canvas-clear-layers (clear_children) — Self-canvas: clear and rebuild the pipeline this scenario assumes, so it runs from any device state. - canvas-clear-layouts (clear_children) - canvas-grid (add_module) - canvas-layer (add_module)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	≥ 333 / 719-1,170	unlimited / —	— / —

• desktop-macos: contract set 2026-09-04 "initial contract: Aurora at 64x64, 3 layers, 2 octaves, warp on" · observed 2026-09-06

one-layer (set_control) 📏

The cost knob at its cheapest. Layers are the outer multiplier: each one is a full warped field sample per pixel, so this should land near a third of the step above.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	≥ 667 / 2,227-3,145	unlimited / —	— / —

• desktop-macos: contract set 2026-09-04 "initial contract: one layer, roughly a third of the three-layer cost" · observed 2026-09-06

one-layer-no-warp (set_control) 📏

Warp off: the field is sampled where it lies rather than where the field displaced it, which is two fewer noise samples per pixel. The cheapest Aurora that still reads as Aurora, and the configuration a large wall runs.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	≥ 1,111 / 4,082-5,348	unlimited / —	— / —

• desktop-macos: contract set 2026-09-04 "initial contract: one layer without domain warping" · observed 2026-09-06

four-layers-no-warp (set_control) 📏

Four unwarped layers: the same total field samples as roughly one warped layer, arranged as more structure instead of more folding. Reading this against one-layer-no-warp is how an author trades detail for depth at a fixed budget.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	≥ 294 / 1,425-1,815	unlimited / —	— / —

• desktop-macos: contract set 2026-09-04 "initial contract: four layers, warp off" · observed 2026-09-06

four-layers-four-octaves (set_control) 📏

Four unwarped layers at four octaves: the octave knob at its top, with warp still off from the step above. Read against four-layers-no-warp, this is what octaves alone cost.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	≥ 143 / 864-1,053	unlimited / —	— / —

• desktop-macos: contract set 2026-09-04 "initial contract: four layers, four octaves, warp still off" · observed 2026-09-06

warp-back-on (set_control) 📏

Warp back on, so the two steps below measure the configuration Aurora actually ships. Setting it explicitly rather than relying on the default is what keeps each number readable on its own.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	≥ 111 / 534-679	unlimited / —	— / —

• desktop-macos: contract set 2026-09-04 "initial contract: four layers, four octaves, warp on: the true ceiling" · observed 2026-09-06

kaleidoscope (set_control) 📏

Fold the composition into six wedges, at the ceiling settings above. The symmetry is applied to the angle before the field is ever sampled, so it costs one modulo per pixel and not a second pass over the field: the small step from warp-back-on is what pins that claim.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	≥ 105 / 547-661	unlimited / —	— / —

• desktop-macos: contract set 2026-09-04 "initial contract: the fold adds one modulo per pixel, not a pass" · observed 2026-09-06

back-to-defaults (set_control) 📏

Octaves back to the shipped 2, with four layers and the fold still on. Returning near the four-layers steps above is what shows the effect carries no state that accumulates across reconfiguration.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	≥ 238 / 826-895	unlimited / —	— / —

• desktop-macos: contract set 2026-09-04 "initial contract: four layers, two octaves, folded" · observed 2026-09-06

Effects

scenario_Effects_composition

test/scenarios/light/scenario_Effects_composition.json — Multi-layer composition end-to-end: Layouts→Grid, TWO Layers under one Effects container (bottom Spiral, top Rainbow), Drivers→NetworkSendDriver. Proves the Drivers composite loop builds, allocates its output buffer, blends both enabled layers and feeds the result to the driver without crashing, and gates the bounded FPS so the N-pass composite cost is tracked. The exact alpha/additive blend math and the disable-drops-to-single-layer path are pinned by the unit tests (unit_BlendMap, unit_Effects_container); construct-mode set_control can't apply controls (built post-scheduler), so this scenario uses each Layer's default blend (additive, full opacity) and asserts wired liveness + tick, not per-byte blend output.

Mode: construct · Also touches: Layer, GridLayout, RainbowEffect, SpiralEffect, Drivers, NetworkSendDriver

add-artnet (add_module) 📏

Add NetworkSendDriver and run the bounded FPS measurement over the two-layer composite (min_pct gates on hardware; skipped with a WARN in the desktop runner).

Setup (preceding non-measured steps): - add-layout-group (add_module) — Top-level Layouts container. - add-grid (add_module) — 128x128 GridLayout under Layouts (above host clock resolution so the composite tick is measurable). - add-layers-group (add_module) — Top-level Effects container — the multi-layer composition host. - add-bottom-layer (add_module) — Bottom Layer (composited first — clears + overwrites the output buffer). RGB. - add-bottom-effect (add_module) — A Spiral base as the bottom layer's effect. - add-top-layer (add_module) — Top Layer (composited second — blends onto the bottom with its default blend). RGB. - add-top-effect (add_module) — Rainbow as the top layer's effect — composited over the Spiral base. - add-driver-group (add_module) — Top-level Drivers container wired to the Effects container (composites all enabled layers into its output buffer).

Bounds: - FPS ≥ 80% of baseline - FPS × lights ≥ 294,912

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 1,302-5,917	— / —	— / —
desktop-windows	— / 1,821	— / —	— / —

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-07-08

FluidEffect

scenario_Fluid_solver

test/scenarios/light/scenario_Fluid_solver.json — What a stable-fluid solver costs, and that it survives being reshaped underneath itself. Unlike every other flow in the library the velocity here is STATE: six grids the solver owns, reallocated whenever the fixture changes, which is what makes the resize steps a real contract rather than a formality. A stale grid would address cells that no longer exist. The cost knob is iterations, the pressure solve that keeps the flow divergence-free: each one is another Gauss-Seidel sweep over the whole grid, so the ladder from 1 to 20 is close to linear and it is what an author reads to pick a value for their fixture. On a cube every slice is its own medium, with nothing carried between slices, so the cost is depth times one panel. The frame times are a TREND per target rather than a pass mark; the solver is several passes over the grid per frame, so this is a desktop and P4 effect and the device numbers are the ones that decide where it can run.

Mode: mutate · Also touches: Fluid, draw, OscillatorBank, GridLayout, Layer

add-fluid (add_module) 📏

The solver on the layer. prepare() allocates six velocity and pressure grids plus two dye planes, so the allocation happens here rather than on the first rendered frame.

Setup (preceding non-measured steps): - canvas-clear-layers (clear_children) — Self-canvas: rebuild the pipeline this scenario assumes, so it runs from any device state. - canvas-clear-layouts (clear_children) - canvas-grid (add_module) — A 32x32 panel to start: small enough that the six solver grids are cheap while the shape of the cost is already visible. - canvas-layer (add_module)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 13,699-33,333	— / —	— / —

• desktop-macos: observed 2026-09-06

iterations-1 (set_control) 📏

The pressure solve at its cheapest. At one sweep the flow is not properly divergence-free and reads springy, which is the visible cost of the cheap setting.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 27,027-52,632	— / —	— / —

• desktop-macos: observed 2026-09-06

iterations-20 (set_control) 📏

And at its most expensive. The ratio against the step above is the pressure solve's share of the frame, which is what an author trades against grid size.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 9,901-14,706	— / —	— / —

• desktop-macos: observed 2026-09-06

iterations-5 (set_control) 📏

Back to the default, confirming the knob moves in both directions rather than one way.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 27,027-34,483	— / —	— / —

• desktop-macos: observed 2026-09-06

grid-64 (set_control) 📏

Widen to 64 under a running solver, height still 32: one dimension doubled, so twice the cells, and every one of the six grids is reallocated in prepare(). A solver that carried its old grid over would be addressing cells that no longer exist.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 13,514-15,625	— / —	— / —

• desktop-macos: observed 2026-09-06

grid-64-h (set_control) 📏

And the height, making it 64x64: four times the cells of the 32x32 the pair started from. Reallocating on each axis separately is the shape a UI resize actually takes.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 6,897-7,576	— / —	— / —

• desktop-macos: observed 2026-09-06

all-jets (set_control) 📏

Every jet pouring at once. The jets are forcing rather than per-pixel work, so this should barely move the frame time: the solver dominates, which is the point.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 6,897-7,576	— / —	— / —

• desktop-macos: observed 2026-09-06

long-persistence (set_control) 📏

Dye held at its longest half-life, the setting the 16-bit plane exists for: a value multiplied by slightly less than one many times a second has nowhere to go at 8 bits.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 6,803-7,634	— / —	— / —

• desktop-macos: observed 2026-09-06

cube-20 (set_control) 📏

A 20x20x20 cube, the largest volumetric fixture in practice: twenty independent slices, each its own medium, with the jets drifting through them in z. The cost is twenty small solves, close to one 90x90 panel, and it is what decides whether the effect belongs on a cube at all.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 25,000-27,778	— / —	— / —

• desktop-macos: observed 2026-09-06

cube-20-h (set_control) 📏

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 83,333-90,909	— / —	— / —

• desktop-macos: observed 2026-09-06

cube-20-d (set_control) 📏

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 4,016-4,545	— / —	— / —

• desktop-macos: observed 2026-09-06

back-to-panel (set_control) 📏

Depth back to 1: the slices are freed and the panel path is exactly the 2D one again.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 83,333-90,909	— / —	— / —

• desktop-macos: observed 2026-09-06

grid-16 (set_control) 📏

Shrink it again, the direction that frees rather than allocates, and the one where a solver holding a stale pointer shows up immediately.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 34,483-111,111	— / —	— / —

• desktop-macos: observed 2026-09-06

grid-16-h (set_control) 📏

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 125,000-142,857	— / —	— / —

• desktop-macos: observed 2026-09-06

GridBlacksLayout

scenario_GridBlacks_blackpixel

test/scenarios/light/scenario_GridBlacks_blackpixel.json — Toggle a mid-strand dark-gap (black column) run on a GridBlacks layout live and verify the full Layouts->Layer->Drivers pipeline keeps rendering. A gap is a physical wire slot held black: it forces the layer off the dense identity fast path onto the folded LUT (which drops the gap slots), while the SpiralEffect fill keeps the lit cells non-zero. Steps: build a 16x16 grid with a moving fill (dense, identity path), then set blackCount live (gap engaged, folded LUT, still renders non-zero because lit cells remain), then clear blackCount back (returns to the identity path). A crash, a wedge, or an all-black buffer on the gapped step would fail the measure. The exact 'gap cells carry no color' correctness is pinned by unit_GridBlacksLayout / unit_Layer_sparse_mapping; this is the live wired-pipeline gate.

Mode: mutate · Also touches: Layer, SpiralEffect

dense-no-gap (set_control) 📏

Baseline: a plain 16x16 moving fill, no gap. Dense identity fast path (no LUT). Buffer is fully non-zero.

Setup (preceding non-measured steps): - canvas-clear-layers (clear_children) — Self-canvas: clear+rebuild the pipeline this scenario assumes, so it runs from any device state. - canvas-clear-layouts (clear_children) - canvas-clear-drivers (clear_children) - canvas-grid (add_module) - canvas-layer (add_module) - canvas-effect (add_module) — A moving fill: every lit cell is a known non-zero color, so an all-black buffer would mean the gap wrongly blanked the whole grid.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 83,333-500,000	— / —	— / —
desktop-windows	— / 142,857	— / —	— / —
esp32	— / 4,115	— / 120KB	— / 92KB
esp32s3-n16r8	— / 5,682	— / 8326KB	— / 80KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-22
• esp32: observed 2026-07-24
• esp32s3-n16r8: observed 2026-07-24

gap-engaged (set_control) 📏

Set a dark column run live (blackStart 6, blackCount 4 -> columns 6..9 dark) as the FINAL state. Forces the folded LUT (drops the 4x16 gap slots). The pipeline must keep rendering: the lit cells of the moving fill stay non-zero (buffer non-zero holds), the physical light count is unchanged at 256 (gaps are real wire slots the driver still clocks), no crash. Ending on the gapped state means the buffer-non-zero check asserts the gap did NOT blank the grid.

Setup (preceding non-measured steps): - gap-start (set_control) — Position the dark run at column 6 (before engaging it). Still no gap until blackCount is set. - gap-cleared-again (set_control) — Clear the run back to 0 (from the earlier gap-start position set): confirms the toggle is reversible with no reboot before the gap is engaged for the final measured state. Returns to the dense identity fast path.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 62,500-500,000	— / —	— / —
desktop-windows	— / 125,000	— / —	— / —
esp32	— / 3,717	— / 119KB	— / 92KB
esp32s3-n16r8	— / 3,745	— / 8320KB	— / 80KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-23
• esp32: observed 2026-07-24
• esp32s3-n16r8: observed 2026-07-24

GridLayout

scenario_GridLayout_resize

test/scenarios/light/scenario_GridLayout_resize.json — Resize the grid while the pipeline is running and verify it reallocates cleanly under memory pressure. Lowers to 128x64 (release memory), increases to 128x128 (heaviest config: mirror + LUT). Each measured step captures tick/FPS/heap so the runner reports the degrade behaviour.

Mode: mutate · Also touches: MultiplyModifier, Layer

size-128x128 (set_control) 📏

Set grid height to 128 (alongside default width 128). Measures the heaviest config as the baseline for the next two steps.

Setup (preceding non-measured steps): - canvas-clear-layers (clear_children) — Self-canvas: clear+rebuild the pipeline this scenario assumes, so it runs from any device state (the perf scenarios' pattern). Pre-wired apparatus (Preview/Board) survives clear_children. On the in-process runner the fixture already built the tree; clearing then rebuilding is harmless there and makes the live run order-independent. - canvas-clear-layouts (clear_children) - canvas-clear-drivers (clear_children) - canvas-grid (add_module) - canvas-layer (add_module) - canvas-noise (add_module) - canvas-mirror (add_module) - canvas-artnet (add_module)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	≥ 8,333 / 3,215-7,874	unlimited / —	— / —
desktop-windows	— / 4,566	— / —	— / —
esp32	— / 740	— / 83KB	— / 48KB
esp32-eth	— / 10.8	— / 132KB	— / 48KB
esp32-eth-wifi	≥ 10.0 / 12.4	≥ 103KB / 93KB	— / 48KB
esp32p4rev1-eth	— / 880	— / 33206KB	— / 376KB
esp32s3-n16r8	— / 989	— / 8293KB	— / 76KB

• desktop-macos: contract set 2026-06-02 "initial contract" · observed 2026-09-06
• desktop-windows: observed 2026-07-08
• esp32: observed 2026-07-24
• esp32-eth: observed 2026-06-02
• esp32-eth-wifi: contract set 2026-06-02 "initial contract" · observed 2026-06-02
• esp32p4rev1-eth: observed 2026-06-22
• esp32s3-n16r8: observed 2026-07-24

shrink-to-128x64 (set_control) 📏

Shrink to 128x64. Measured: tick/heap captured so the runner reports the realloc behaviour against each target's contract. (The old relative-to-baseline FPS bound was removed — it compared against the runner's idle pre-scenario baseline, not the prior render step, so it false-failed on fast boards like the P4 where idle FPS dwarfs render FPS.)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	≥ 16,667 / 6,897-15,152	unlimited / —	— / —
desktop-windows	— / 10,638	— / —	— / —
esp32	— / 1,745	— / 63KB	— / 17KB
esp32-eth	— / 26.5	— / 114KB	— / 48KB
esp32-eth-wifi	≥ 22.2 / 31.8	≥ 83KB / 75KB	— / 24KB
esp32p4rev1-eth	— / 1,739	— / 33214KB	— / 376KB
esp32s3-n16r8	— / 2,092	— / 8310KB	— / 84KB

• desktop-macos: contract set 2026-06-02 "initial contract" · observed 2026-09-06
• desktop-windows: observed 2026-08-21
• esp32: observed 2026-07-24
• esp32-eth: observed 2026-06-02
• esp32-eth-wifi: contract set 2026-06-02 "initial contract" · observed 2026-06-02
• esp32p4rev1-eth: observed 2026-06-22
• esp32s3-n16r8: observed 2026-07-24

grow-to-128x128 (set_control) 📏

Grow back to 128x128. Measured: confirms the heap can return to the heavy baseline after a shrink.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	≥ 8,333 / 3,356-7,937	unlimited / —	— / —
desktop-windows	— / 4,608	— / —	— / —
esp32	— / 839	— / 83KB	— / 52KB
esp32-eth	— / 10.4	— / 132KB	— / 48KB
esp32-eth-wifi	≥ 10.0 / 12.2	≥ 103KB / 93KB	— / 52KB
esp32p4rev1-eth	— / 875	— / 33206KB	— / 376KB
esp32s3-n16r8	— / 1,106	— / 8292KB	— / 76KB

• desktop-macos: contract set 2026-06-02 "initial contract" · observed 2026-09-06
• desktop-windows: observed 2026-07-08
• esp32: observed 2026-07-24
• esp32-eth: observed 2026-06-02
• esp32-eth-wifi: contract set 2026-06-02 "initial contract" · observed 2026-06-02
• esp32p4rev1-eth: observed 2026-06-22
• esp32s3-n16r8: observed 2026-07-24

Layer

scenario_Layer_base_pipeline

test/scenarios/light/scenario_Layer_base_pipeline.json — Core pipeline: build Layouts→Grid→Layer→RainbowEffect→Drivers→NetworkSendDriver from scratch and verify each module wires correctly. Drives the bounded FPS check at the end so a render-path regression is caught.

Mode: construct · Also touches: GridLayout, RainbowEffect, Drivers, NetworkSendDriver

add-artnet (add_module) 📏

Add NetworkSendDriver and run the bounded FPS measurement (expected to stay at >=80% of the rated FPS for the 128x128 grid this scenario builds; min_pct needs a live baseline, so it gates only on hardware and is skipped with a WARN in the desktop runner).

Setup (preceding non-measured steps): - add-layout-group (add_module) — Create the top-level Layouts container. - add-grid (add_module) — Add a 128x128 GridLayout child to Layouts. Set explicitly (the module default is 16x16x1) so the tick is above the host's microsecond clock resolution — a 16x16 grid renders in <1us on desktop, flooring tick to 0. - add-layer (add_module) — Add a top-level Layer wired to the Layouts container, RGB (3 channels per light). - add-rainbow (add_module) — Add RainbowEffect as the Layer's only effect. - add-driver-group (add_module) — Add a top-level Drivers container wired to the Layer's output buffer.

Bounds: - FPS ≥ 80% of baseline - FPS × lights ≥ 294,912

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	≥ 20,000 / 5,587-14,085	unlimited / —	— / —
desktop-windows	— / 8,475	— / —	— / —

• desktop-macos: contract set 2026-06-02 "initial contract" · observed 2026-09-06
• desktop-windows: observed 2026-07-08

scenario_Layer_memory_1to1

test/scenarios/light/scenario_Layer_memory_1to1.json — Verify that an unshuffled 1:1 mapping (no modifier) uses no LUT and no driver buffer. Catches a regression where Layer would allocate a passthrough LUT for the identity case.

Mode: construct · Also touches: MappingLUT, BlendMap

add-artnet (add_module) 📏

Add NetworkSendDriver and run the bounded FPS measurement on the no-LUT path.

Setup (preceding non-measured steps): - add-layout-group (add_module) — Create the top-level Layouts container. - add-grid (add_module) — Add a 16x16 GridLayout. - add-layer (add_module) — Add a Layer wired to Layouts (RGB). - add-rainbow (add_module) — Add RainbowEffect as the Layer's effect. - add-driver-group (add_module) — Add a Drivers container wired to the Layer.

Bounds: - FPS ≥ 80% of baseline

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	≥ 20,000 / 25,000-200,000	unlimited / —	— / —
desktop-windows	— / 1,000,000	— / —	— / —

• desktop-macos: contract set 2026-06-02 "initial contract" · observed 2026-09-06
• desktop-windows: observed 2026-08-22

scenario_modifier_chain

test/scenarios/light/scenario_modifier_chain.json — Stack TWO modifiers on one Layer (Region then Multiply) and verify the chain composes live end-to-end — the capability the old single-modifier engine couldn't do. Prepares its own canvas: Layout(Grid 32x32) + Layer + NoiseEffect + Region(0..50) + Multiply(2x), measures the composite, then adds a third (Checkerboard mask) and measures again, then removes the middle modifier and measures — exercising add/remove on a multi-modifier chain. A broken fold (null buffer, wrong light count, crash on a disabled/removed stage) shows up as a failed measure. The fold composition + order semantics are pinned by unit_Layer_modifier_chain; this is the live end-to-end gate.

Mode: mutate · Also touches: RegionModifier, MultiplyModifier, CheckerboardModifier, RotateModifier, NoiseEffect, Layouts, GridLayout, Drivers, NetworkSendDriver

add-mask (add_module) 📏

Add a third modifier (Checkerboard mask) on top of the chain — a 3-deep fold. Measure that the deeper chain still renders.

Setup (preceding non-measured steps): - region-then-multiply (measure) — Two stacked modifiers: Region(top-left quarter) then Multiply(2x mirror) compose into one mapping. Measure the live composite.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 27,778-111,111	— / —	— / —
desktop-windows	— / 83,333	— / —	— / —
esp32	— / 64.7-82.2	— / 46KB-47KB	— / 26KB-38KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-21
• esp32: observed 2026-09-01

remove-middle (remove_module) 📏

Remove the middle modifier (Multiply) — the chain re-folds with Region then Checkerboard, no stale state. Measure.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 13,889-38,462	— / —	— / —
desktop-windows	— / 23,810	— / —	— / —

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-22

add-live-rotate (add_module) 📏

Add a DYNAMIC Rotate on top of the static chain — its modifyLive runs the per-frame remap pass over the composed buffer. Verifies a static chain + a live modifier coexist (the buffer is remapped each frame on top of the baked Region/Checkerboard mapping) without a crash or null buffer.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 8,130-21,277	— / —	— / —
desktop-windows	— / 14,493	— / —	— / —
esp32	— / 69.8-75.0	— / 43KB-46KB	— / 26KB-38KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-23
• esp32: observed 2026-09-01

scenario_modifier_swap

test/scenarios/light/scenario_modifier_swap.json — Swap the Layer's modifier between Multiply and Checkerboard and verify the pipeline stays live across each replace. Prepares its own canvas (clear + rebuild) so it runs from any device state: one Layout(Grid 32x32) + one Layer + one effect + one modifier, then replace_module cycles the modifier MOD slot Multiply -> Checkerboard -> Multiply, measuring after each so a broken swap (null buffer / wrong light count) shows up. Exercises the modifier-replace path the UI's drag-replace uses.

Mode: mutate · Also touches: MultiplyModifier, CheckerboardModifier, NoiseEffect, Layouts, GridLayout, Drivers, NetworkSendDriver, PreviewDriver

multiply-1 (measure) 📏

Multiply modifier active — pipeline live, LUT folds the grid.

Setup (preceding non-measured steps): - shrink-w (set_control) - shrink-h (set_control) - clear-layers (clear_children) - clear-layouts (clear_children) - build-grid (add_module) - build-layer (add_module) - build-fx (add_module) - build-mod (add_module)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 14,085-111,111	— / —	— / —
desktop-windows	— / 71,429	— / —	— / —
esp32	— / 71.3-81.6	— / 35KB-93KB	— / 26KB-68KB
esp32-eth	— / 7,752	— / 172KB	— / 76KB
esp32p4rev1-eth	— / 6,061	— / 33243KB	— / 376KB
esp32s3-n16r8	— / 13,158	— / 7533KB	— / 76KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-22
• esp32: observed 2026-09-01
• esp32-eth: observed 2026-06-08
• esp32p4rev1-eth: observed 2026-06-25
• esp32s3-n16r8: observed 2026-07-24

checkerboard (measure) 📏

Checkerboard modifier active — masks half the lights; pipeline stays live (driver buffer non-null).

Setup (preceding non-measured steps): - swap-to-checker (replace_module)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 11,494-41,667	— / —	— / —
desktop-windows	— / 24,390	— / —	— / —
esp32	— / 81.5-89.2	— / 34KB-93KB	— / 26KB-68KB
esp32-eth	— / 990	— / 170KB	— / 76KB
esp32p4rev1-eth	— / 2,762	— / 33242KB	— / 376KB
esp32s3-n16r8	— / 2,825	— / 7533KB	— / 72KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-22
• esp32: observed 2026-09-01
• esp32-eth: observed 2026-06-08
• esp32p4rev1-eth: observed 2026-06-25
• esp32s3-n16r8: observed 2026-07-24

multiply-2 (measure) 📏

Back to Multiply — replace round-trips cleanly, pipeline live again.

Setup (preceding non-measured steps): - swap-to-multiply (replace_module)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 20,408-100,000	— / —	— / —
desktop-windows	— / 76,923	— / —	— / —
esp32	— / 72.9-85.6	— / 37KB-95KB	— / 26KB-68KB
esp32-eth	— / 2,278	— / 169KB	— / 76KB
esp32p4rev1-eth	— / 6,410	— / 33243KB	— / 376KB
esp32s3-n16r8	— / 6,803	— / 7534KB	— / 76KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-22
• esp32: observed 2026-09-01
• esp32-eth: observed 2026-06-08
• esp32p4rev1-eth: observed 2026-06-25
• esp32s3-n16r8: observed 2026-07-24

scenario_perf_full

test/scenarios/light/scenario_perf_full.json — Comprehensive incremental performance check (the SLOW, on-device companion to scenario_perf_light). Mutate mode + canvas-preparing: clear_children whatever the device already had (pre-wired apparatus like PreviewDriver/Board survives — clear_children only drops user-editable children), rebuild a known minimal tree, then add one subsystem at a time — audio, device discovery, a modifier, then EVERY output driver this board has (each optional + capped to 64 output LEDs so its per-frame cost is comparable, not its transmit-all-16K time), then a network driver — measuring the tick/heap delta after each so each subsystem's cost is isolated. Then sweep the grid 16²→32²→64²→128² (16K) for both a LIGHT effect (Spiral) and a HEAVY one (Noise) to bracket the compute range across sizes. LED drivers are platform-gated (RMT on classic/S3, LCD on S3, Parlio on P4; none on desktop) so each driver step is optional:true and skipped where absent — the all-drivers comparison is assembled across boards (S3 gives RMT vs LCD, P4 gives RMT vs Parlio). Subsumes the old scenario_Layer_buildup (incremental module cost), scenario_GridLayout_grid_sizes (grid sweep), and scenario_AllEffects_grid_sizes (per-effect size sweep, here reduced to a light/heavy bracket). Runs minutes on a device; not a per-commit gate.

Mode: mutate · Also touches: Layouts, GridLayout, Drivers, PreviewDriver, NetworkSendDriver, RmtLedDriver, ParallelLedDriver, MultiplyModifier, SpiralEffect, NoiseEffect

measure-minimal (measure) 📏

Bare minimum at 16²: Grid + Layer + Spiral, no output driver, audio/discovery still on as the device ships. The floor for the subsystem-cost diffs below.

Setup (preceding non-measured steps): - clear-layers (clear_children) — Start clean: drop whatever effects/modifiers/layouts/drivers the device had (pre-wired Preview survives). - clear-layouts (clear_children) - clear-drivers (clear_children) - build-grid (add_module) - build-layer (add_module) - build-fx (add_module)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 111,111-1,000,000	— / —	— / —
desktop-windows	— / 333,333	— / —	— / —
esp32	— / 758-1,098	— / 75KB-108KB	— / 38KB-92KB
esp32p4rev1-eth	— / 17,544	— / 33226KB	— / 376KB
esp32s3-n16r8	— / 9,009	— / 8323KB	— / 80KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-21
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-06-25
• esp32s3-n16r8: observed 2026-07-24

measure-no-audio (measure) 📏

Setup (preceding non-measured steps): - disable-audio (set_control) — Disable the mic (stops I2S sampling in tick()). Diff vs measure-minimal = the audio subsystem's per-tick cost (device only; optional). Targets it by its runtime name 'Audio' (displayNameFor strips the 'Service' suffix).

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 142,857-1,000,000	— / —	— / —
desktop-windows	— / 333,333	— / —	— / —
esp32	— / 1,142-1,513	— / 82KB-118KB	— / 38KB-92KB
esp32p4rev1-eth	— / 18,868	— / 33228KB	— / 376KB
esp32s3-n16r8	— / 9,901	— / 8330KB	— / 84KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-23
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-06-25
• esp32s3-n16r8: observed 2026-07-24

measure-quiet (measure) 📏

Quiet baseline: render-only, audio + discovery off. The cleanest render floor; the per-driver costs below diff against this.

Setup (preceding non-measured steps): - disable-devices (set_control) — Disable the Devices module (stops the blocking HTTP discovery sweep in tick1s()). Diff = the discovery cost (device only; optional).

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 125,000-1,000,000	— / —	— / —
desktop-windows	— / 333,333	— / —	— / —
esp32	— / 1,117-1,403	— / 84KB-118KB	— / 38KB-92KB
esp32p4rev1-eth	— / 18,519	— / 33226KB	— / 376KB
esp32s3-n16r8	— / 9,901	— / 8331KB	— / 84KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-22
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-06-25
• esp32s3-n16r8: observed 2026-07-24

measure-modifier (measure) 📏

Setup (preceding non-measured steps): - add-modifier (add_module) — +MultiplyModifier: allocates the mapping LUT. Diff = modifier + LUT cost.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 250,000-1,000,000	— / —	— / —
desktop-windows	— / 1,000,000	— / —	— / —
esp32	— / 2,336-3,367	— / 83KB-119KB	— / 38KB-92KB
esp32p4rev1-eth	— / 10,638	— / 33224KB	— / 376KB
esp32s3-n16r8	— / 8,264	— / 8331KB	— / 84KB

• desktop-macos: observed 2026-09-03
• desktop-windows: observed 2026-08-22
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-06-25
• esp32s3-n16r8: observed 2026-07-24

measure-preview (measure) 📏

Setup (preceding non-measured steps): - remove-modifier (remove_module) — Drop the modifier so the driver-cost measurements below are on the plain 1:1 pipeline (drivers, not the LUT, are what we compare here). - add-preview (add_module) — +PreviewDriver. Optional: on a device the pre-wired Preview survives clear_children so it's already present (the add is skipped); on the in-process desktop runner there's no apparatus, so this adds it. Either way the next measure includes Preview.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 125,000-1,000,000	— / —	— / —
desktop-windows	— / 333,333	— / —	— / —
esp32	— / 1,080-1,458	— / 83KB-119KB	— / 38KB-92KB
esp32p4rev1-eth	— / 18,182	— / 33228KB	— / 376KB
esp32s3-n16r8	— / 9,434	— / 8330KB	— / 84KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-23
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-06-25
• esp32s3-n16r8: observed 2026-07-24

measure-network (measure) 📏

Setup (preceding non-measured steps): - add-network-driver (add_module) — +NetworkSendDriver (ArtNet/DDP — works on every platform). Diff = the network output cost (capped by the 16² grid here).

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 111,111-500,000	— / —	— / —
desktop-windows	— / 333,333	— / —	— / —
esp32	— / 1,021-1,372	— / 80KB-117KB	— / 38KB-92KB
esp32p4rev1-eth	— / 17,544	— / 33226KB	— / 376KB
esp32s3-n16r8	— / 8,065	— / 8331KB	— / 84KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-22
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-06-25
• esp32s3-n16r8: observed 2026-07-24

measure-rmt (measure) 📏

Setup (preceding non-measured steps): - remove-network-driver (remove_module) - add-rmt-driver (add_module) — +RmtLedDriver capped to 64 output LEDs (one pin, ledsPerPin=64). Optional — classic + S3. Diff = the RMT per-frame cost at a fixed 64-LED output.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 125,000-1,000,000	— / —	— / —
desktop-windows	— / 333,333	— / —	— / —
esp32	— / 1,072-1,406	— / 57KB-91KB	— / 38KB-68KB
esp32p4rev1-eth	— / 17,857	— / 33200KB	— / 376KB
esp32s3-n16r8	— / 9,346	— / 8307KB	— / 84KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-23
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-06-25
• esp32s3-n16r8: observed 2026-07-24

measure-i80 (measure) 📏

The i80 per-frame cost. Only meaningful where add-i80-driver's pins are valid (S3; desktop is inert but exercises the code path) — the classic/P4 blocks were removed: they recorded a driver that had failed to init, so the tiny tick was the bail-out path, not an encode.

Setup (preceding non-measured steps): - remove-rmt-driver (remove_module) - add-i80-driver (add_module) — +ParallelLedDriver (peripheral=i80) capped to 64 LEDs on lane 0 (i80 needs all 8 data pins; unused lanes get 0 LEDs). S3 ONLY — the pins below are the S3's clean set. The i80 peripheral also runs on the classic ESP32 (I2S backend) and the P4 (LCD_CAM), but NO 8-pin set is safe on all three (only GPIO 21 is common: the classic's 6-11 are the SPI flash bus, the P4 exposes a different range), so one shared step cannot measure them. On a non-S3 target the driver fails to init and the measure below is meaningless — the observed blocks are therefore S3/desktop only. Diff = the i80 per-frame cost.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 125,000-1,000,000	— / —	— / —
desktop-windows	— / 333,333	— / —	— / —
esp32	— / 969-1,208	— / 80KB-93KB	— / 38KB-46KB
esp32s3-n16r8	— / 9,259	— / 8330KB	— / 84KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-23
• esp32: observed 2026-09-01
• esp32s3-n16r8: observed 2026-07-24

measure-parlio (measure) 📏

Setup (preceding non-measured steps): - remove-i80-driver (remove_module) - add-parlio-driver (add_module) — +ParallelLedDriver (peripheral=Parlio) capped to 64 LEDs on lane 0. Optional — P4 only. Diff = the Parlio per-frame cost.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 83,333-1,000,000	— / —	— / —
desktop-windows	— / 333,333	— / —	— / —
esp32	— / 1,115-1,372	— / 80KB-92KB	— / 38KB-46KB
esp32p4rev1-eth	— / 17,857	— / 33225KB	— / 376KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-23
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-06-25

measure-light-16 (measure) 📏

Setup (preceding non-measured steps): - remove-parlio-driver (remove_module) - add-preview-for-sweep (add_module) — Re-add PreviewDriver as the output for the grid sweep (the per-driver adds above each removed their driver; Preview is the cheap, every-board output for a pure-render size curve). - light-16-w (set_control) — Grid sweep, LIGHT effect (Spiral is already FX). - light-16-h (set_control)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 111,111-1,000,000	— / —	— / —
desktop-windows	— / 333,333	— / —	— / —
esp32	— / 1,218-1,513	— / 83KB-115KB	— / 38KB-92KB
esp32p4rev1-eth	— / 18,868	— / 33226KB	— / 376KB
esp32s3-n16r8	— / 9,901	— / 8333KB	— / 84KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-22
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-06-25
• esp32s3-n16r8: observed 2026-07-24

measure-light-32 (measure) 📏

Setup (preceding non-measured steps): - light-32-w (set_control) - light-32-h (set_control)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 28,571-166,667	— / —	— / —
desktop-windows	— / 83,333	— / —	— / —
esp32	— / 309-396	— / 78KB-114KB	— / 38KB-92KB
esp32p4rev1-eth	— / 7,576	— / 33225KB	— / 376KB
esp32s3-n16r8	— / 3,597	— / 8323KB	— / 84KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-07-08
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-06-25
• esp32s3-n16r8: observed 2026-07-24

measure-light-64 (measure) 📏

Setup (preceding non-measured steps): - light-64-w (set_control) - light-64-h (set_control)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 5,747-43,478	— / —	— / —
desktop-windows	— / 20,408	— / —	— / —
esp32	— / 67.2-96.2	— / 61KB-97KB	— / 38KB-64KB
esp32p4rev1-eth	— / 2,232	— / 33218KB	— / 376KB
esp32s3-n16r8	— / 1,011	— / 8296KB	— / 80KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-22
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-06-25
• esp32s3-n16r8: observed 2026-07-24

measure-light-128 (measure) 📏

Setup (preceding non-measured steps): - light-128-w (set_control) - light-128-h (set_control)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 978-8,850	— / —	— / —
desktop-windows	— / 5,102	— / —	— / —
esp32	— / 91.8-385	— / 84KB-90KB	— / 34KB-38KB
esp32p4rev1-eth	— / 573	— / 33182KB	— / 376KB
esp32s3-n16r8	— / 134	— / 8283KB	— / 80KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-23
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-06-25
• esp32s3-n16r8: observed 2026-07-24

measure-heavy-16 (measure) 📏

Setup (preceding non-measured steps): - swap-heavy (replace_module) — Swap to the HEAVY effect (Noise) and repeat the sweep — the upper bracket of per-pixel compute. - heavy-16-w (set_control) - heavy-16-h (set_control)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 66,667-250,000	— / —	— / —
desktop-windows	— / 111,111	— / —	— / —
esp32	— / 2,342-2,924	— / 83KB-120KB	— / 38KB-92KB
esp32p4rev1-eth	— / 3,367	— / 33229KB	— / 376KB
esp32s3-n16r8	— / 3,472	— / 8329KB	— / 84KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-23
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-06-25
• esp32s3-n16r8: observed 2026-07-24

measure-heavy-32 (measure) 📏

Setup (preceding non-measured steps): - heavy-32-w (set_control) - heavy-32-h (set_control)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 13,889-58,824	— / —	— / —
desktop-windows	— / 27,778	— / —	— / —
esp32	— / 584-853	— / 79KB-113KB	— / 38KB-92KB
esp32p4rev1-eth	— / 898	— / 33227KB	— / 376KB
esp32s3-n16r8	— / 973	— / 8331KB	— / 84KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-22
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-06-25
• esp32s3-n16r8: observed 2026-07-24

measure-heavy-64 (measure) 📏

Setup (preceding non-measured steps): - heavy-64-w (set_control) - heavy-64-h (set_control)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 2,778-14,493	— / —	— / —
desktop-windows	— / 6,897	— / —	— / —
esp32	— / 189-234	— / 61KB-90KB	— / 25KB-64KB
esp32p4rev1-eth	— / 229	— / 33218KB	— / 376KB
esp32s3-n16r8	— / 251	— / 8320KB	— / 84KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-22
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-06-25
• esp32s3-n16r8: observed 2026-07-24

measure-heavy-128 (measure) 📏

Setup (preceding non-measured steps): - heavy-128-w (set_control) - heavy-128-h (set_control)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 898-3,584	— / —	— / —
desktop-windows	— / 1,689	— / —	— / —
esp32	— / 178-238	— / 74KB-84KB	— / 38KB
esp32p4rev1-eth	— / 57.4	— / 33182KB	— / 376KB
esp32s3-n16r8	— / 59.1	— / 8273KB	— / 76KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-23
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-06-25
• esp32s3-n16r8: observed 2026-07-24

measure-mod-16 (measure) 📏

Setup (preceding non-measured steps): - add-modifier-for-sweep (add_module) — Re-add the MultiplyModifier on the HEAVY effect and sweep grid sizes — the diff vs the matching measure-heavy-N step (no modifier) is the modifier's PER-FRAME cost at each grid, answering whether the ~180µs seen at 16² scales with pixel count or is fixed overhead. - mod-16-w (set_control) - mod-16-h (set_control)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 125,000-1,000,000	— / —	— / —
desktop-windows	— / 500,000	— / —	— / —
esp32	— / 2,874-4,673	— / 82KB-116KB	— / 38KB-92KB
esp32p4rev1-eth	— / 6,494	— / 33224KB	— / 376KB
esp32s3-n16r8	— / 6,803	— / 8328KB	— / 84KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-07-08
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-06-25
• esp32s3-n16r8: observed 2026-07-24

measure-mod-32 (measure) 📏

Setup (preceding non-measured steps): - mod-32-w (set_control) - mod-32-h (set_control)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 52,632-250,000	— / —	— / —
desktop-windows	— / 111,111	— / —	— / —
esp32	— / 1,227-1,558	— / 77KB-101KB	— / 38KB-92KB
esp32p4rev1-eth	— / 1,876	— / 33218KB	— / 376KB
esp32s3-n16r8	— / 2,179	— / 8325KB	— / 84KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-07-08
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-06-25
• esp32s3-n16r8: observed 2026-07-24

measure-mod-64 (measure) 📏

Setup (preceding non-measured steps): - mod-64-w (set_control) - mod-64-h (set_control)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 13,514-55,556	— / —	— / —
desktop-windows	— / 27,778	— / —	— / —
esp32	— / 332-457	— / 58KB-95KB	— / 25KB-64KB
esp32p4rev1-eth	— / 486	— / 33194KB	— / 376KB
esp32s3-n16r8	— / 404	— / 8297KB	— / 84KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-21
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-06-25
• esp32s3-n16r8: observed 2026-07-24

measure-mod-128 (measure) 📏

Setup (preceding non-measured steps): - mod-128-w (set_control) - mod-128-h (set_control)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 2,703-14,286	— / —	— / —
desktop-windows	— / 6,897	— / —	— / —
esp32	— / 187-238	— / 78KB-80KB	— / 34KB
esp32p4rev1-eth	— / 102	— / 33089KB	— / 376KB
esp32s3-n16r8	— / 67.3	— / 8180KB	— / 76KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-07-08
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-06-25
• esp32s3-n16r8: observed 2026-07-24

scenario_perf_light

test/scenarios/light/scenario_perf_light.json — Fast incremental performance check: start from the bare minimum render pipeline and add one thing at a time, measuring the tick/heap delta each step, so a regression shows up as a per-step jump. The LIGHT companion to scenario_perf_full — it stays small (≤64²) and driver-free so it runs in seconds. Mutate mode + canvas-preparing: the steps clear_children whatever Layouts/Effects/Drivers the device already had (the pre-wired apparatus like PreviewDriver/Board survives — clear_children only drops user-editable children) and rebuild a known tree, so it runs from any starting state and always measures the same minimal pipeline. Order: (1) minimal = Grid(16²)+Layer+a LIGHT effect (Spiral, a light effect), no modifier/driver/audio/discovery; (2) +MultiplyModifier (adds the mapping LUT — the heavy memory path); (3) +PreviewDriver; (4) swap to a HEAVY effect (Noise) to bracket the compute range; (5) grid 16²→32²→64² to show the size scaling. Full 128²/16K sweep, real LED/network drivers, audio+discovery cost: see scenario_perf_full.

Mode: mutate · Also touches: Layouts, GridLayout, Drivers, PreviewDriver, SpiralEffect, NoiseEffect, MultiplyModifier

measure-minimal (measure) 📏

Bare minimum: Grid(16²) + Layer + Spiral (light effect). No modifier, no driver. The render floor everything else is measured against.

Setup (preceding non-measured steps): - disable-audio (set_control) — Quiet I2S sampling so it can't pollute the tick (optional — device only). Targets the mic by its runtime name 'Audio' (displayNameFor strips the 'Service' suffix; the catalog adds it with id 'Audio'). - disable-devices (set_control) — Stop the blocking HTTP discovery sweep (optional — device only). - clear-layers (clear_children) — Drop whatever effects/modifiers the device had — start clean. - clear-layouts (clear_children) - clear-drivers (clear_children) — Drop any output driver; the pre-wired PreviewDriver is non-deletable and survives. - build-grid (add_module) - build-layer (add_module) - build-fx (add_module)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 111,111-500,000	— / —	— / —
desktop-windows	— / 333,333	— / —	— / —
esp32	— / 816-971	— / 82KB-119KB	— / 38KB-92KB
esp32p4rev1-eth	— / 18,519	— / 33228KB	— / 376KB
esp32s3-n16r8	— / 8,850	— / 8316KB	— / 80KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-22
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-06-25
• esp32s3-n16r8: observed 2026-07-24

measure-with-modifier (measure) 📏

Cost of the modifier + LUT over the minimal pipeline. Heap delta vs measure-minimal is the LUT allocation.

Setup (preceding non-measured steps): - add-modifier (add_module) — +MultiplyModifier: allocates the mapping LUT (the heavy memory path vs the 1:1 no-LUT case).

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 250,000-1,000,000	— / —	— / —
desktop-windows	— / 1,000,000	— / —	— / —
esp32	— / 2,188-3,378	— / 79KB-115KB	— / 38KB-92KB
esp32p4rev1-eth	— / 10,309	— / 33226KB	— / 376KB
esp32s3-n16r8	— / 8,333	— / 8330KB	— / 84KB

• desktop-macos: observed 2026-09-03
• desktop-windows: observed 2026-08-23
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-06-25
• esp32s3-n16r8: observed 2026-07-24

measure-with-preview (measure) 📏

PreviewDriver is the pre-wired apparatus — it survives clear_children and is already attached, so the measures above already include it (no add step needed; adding a second Preview is rejected). This is a stable repeat of the effect+modifier config for run-to-run variance.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 500,000-1,000,000	— / —	— / —
desktop-windows	— / 1,000,000	— / —	— / —
esp32	— / 2,809-3,509	— / 82KB-117KB	— / 38KB-92KB
esp32p4rev1-eth	— / 10,753	— / 33226KB	— / 376KB
esp32s3-n16r8	— / 8,621	— / 8328KB	— / 84KB

• desktop-macos: observed 2026-09-05
• desktop-windows: observed 2026-08-22
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-06-25
• esp32s3-n16r8: observed 2026-07-24

measure-heavy-16 (measure) 📏

Setup (preceding non-measured steps): - swap-heavy-fx (replace_module) — Swap the light effect for a HEAVY one (Noise — simplex per pixel) to bracket the compute range at the same 16².

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 250,000-1,000,000	— / —	— / —
desktop-windows	— / 500,000	— / —	— / —
esp32	— / 3,759-4,484	— / 83KB-117KB	— / 38KB-92KB
esp32p4rev1-eth	— / 6,494	— / 33224KB	— / 376KB
esp32s3-n16r8	— / 6,803	— / 8332KB	— / 84KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-22
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-06-25
• esp32s3-n16r8: observed 2026-07-24

measure-heavy-32 (measure) 📏

Setup (preceding non-measured steps): - grid-32-w (set_control) - grid-32-h (set_control)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 71,429-250,000	— / —	— / —
desktop-windows	— / 111,111	— / —	— / —
esp32	— / 1,266-1,553	— / 78KB-112KB	— / 38KB-92KB
esp32p4rev1-eth	— / 1,880	— / 33221KB	— / 376KB
esp32s3-n16r8	— / 2,183	— / 8319KB	— / 84KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-21
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-06-25
• esp32s3-n16r8: observed 2026-07-24

measure-heavy-64 (measure) 📏

Setup (preceding non-measured steps): - grid-64-w (set_control) - grid-64-h (set_control)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 16,393-58,824	— / —	— / —
desktop-windows	— / 28,571	— / —	— / —
esp32	— / 272-458	— / 57KB-94KB	— / 38KB-72KB
esp32p4rev1-eth	— / 491	— / 33195KB	— / 376KB
esp32s3-n16r8	— / 402	— / 8277KB	— / 64KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-23
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-06-25
• esp32s3-n16r8: observed 2026-07-24

Layouts

scenario_Layouts_mutation

test/scenarios/light/scenario_Layouts_mutation.json — Tree mutation on the Layouts container while the pipeline runs: add a second layout (multiple layouts under one Layouts), replace a layout with a different type, and remove a layout. The check is that each mutation leaves the pipeline RENDERING — Layer + Drivers re-wire via prepareTree and the buffer stays non-null and non-zero. Mirrors the HTTP add/replace/delete handlers; exercises the runner's add_module / replace_module / remove_module ops. NOTE: the Layer renders a dense bounding-box buffer sized by the layouts' coordinate EXTENT, not the summed light count — layouts that overlap in coordinate space share voxels (two 64x64 grids both occupy x,y in 0..63). There are no per-layout coordinate offsets, so multiple layouts share the same coordinate box; these steps assert liveness, not buffer-size arithmetic. Grids are 64x64 so the tick stays above the host's microsecond clock at every step.

Mode: mutate · Also touches: GridLayout, SphereLayout, Layer, RainbowEffect, Drivers, NetworkSendDriver

measure-one-layout (measure) 📏

Baseline: a single 64x64 grid layout drives the pipeline.

Bounds: - FPS ≥ 1 (absolute)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 20,000-58,824	— / —	— / —
desktop-windows	— / 37,037	— / —	— / —
esp32	— / 76.7-89.8	— / 42KB-95KB	— / 26KB-92KB
esp32-eth	— / 41,667	— / 224KB	— / 108KB
esp32s3-n16r8	— / 29,412	— / 7390KB	— / 72KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-22
• esp32: observed 2026-09-01
• esp32-eth: observed 2026-06-08
• esp32s3-n16r8: observed 2026-07-24

measure-two-layouts (measure) 📏

Pipeline still renders with two layouts wired (buffer non-null, fps measurable).

Setup (preceding non-measured steps): - add-second-layout (add_module) — Add a SECOND layout (a 64x64 grid) under Layouts — two layouts now live under one container. prepareTree re-runs; the pipeline must still render. (Both grids share the 0..63 coordinate box, so the Layer buffer stays 64x64 — see the scenario NOTE.)

Bounds: - FPS ≥ 1 (absolute)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 7,937-20,408	— / —	— / —
desktop-windows	— / 23,810	— / —	— / —
esp32	— / 61.3-73.0	— / 33KB-77KB	— / 26KB-60KB
esp32-eth	— / 37,037	— / 223KB	— / 108KB
esp32s3-n16r8	— / 22,222	— / 7453KB	— / 72KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-07-08
• esp32: observed 2026-09-01
• esp32-eth: observed 2026-06-08
• esp32s3-n16r8: observed 2026-07-24

measure-after-replace (measure) 📏

Pipeline still renders after replacing a grid with a sphere (different layout type, same slot) — buffer re-wires without crashing.

Setup (preceding non-measured steps): - replace-second-layout (replace_module) — Replace the second grid with a SphereLayout (different type, same slot). The first grid is untouched; the pipeline re-wires to the new layout's light count.

Bounds: - FPS ≥ 1 (absolute)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 4,032-10,417	— / —	— / —
desktop-windows	— / 9,009	— / —	— / —
esp32	— / 71.1-73.9	— / 29KB-95KB	— / 16KB-80KB
esp32-eth	— / 38,462	— / 223KB	— / 108KB
esp32s3-n16r8	— / 27,027	— / 7108KB	— / 72KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-07-08
• esp32: observed 2026-09-01
• esp32-eth: observed 2026-06-08
• esp32s3-n16r8: observed 2026-07-24

measure-after-remove (measure) 📏

Pipeline renders with the single remaining grid, same as the baseline.

Setup (preceding non-measured steps): - remove-second-layout (remove_module) — Remove the sphere — back to a single grid layout. Layer/Drivers shrink their buffers via prepareTree.

Bounds: - FPS ≥ 1 (absolute)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 21,277-50,000	— / —	— / —
desktop-windows	— / 38,462	— / —	— / —
esp32	— / 72.2-84.2	— / 36KB-96KB	— / 26KB-92KB
esp32-eth	— / 41,667	— / 224KB	— / 108KB
esp32s3-n16r8	— / 29,412	— / 7401KB	— / 84KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-07-08
• esp32: observed 2026-09-01
• esp32-eth: observed 2026-06-08
• esp32s3-n16r8: observed 2026-07-24

MoonLiveEffect

scenario_MoonLiveEffect_controls

test/scenarios/light/scenario_MoonLiveEffect_controls.json — Exercise MoonLive Stage-1 CONTROLS end-to-end as a wired module. A script declares a member and surfaces it (addControl("speed", speed, 0, 15) in defineControls) and uses it (setRGB(speed, ...)); the engine surfaces the control, the binding creates a real MoonModule control of the widget its member's TYPE calls for, bound to the member's 4-byte slot in the live control-values arena. The scenario: add the effect with a control script (the control appears, renders), change the CONTROL value live (a slider move — must NOT recompile; the arena byte updates and the next tick reads it), edit the SOURCE to add a second control (recompile re-derives the set, existing slider value preserved by the stable-address grow-only arena), edit the source to remove a control (the orphaned value drops), push a broken script (compile fails, renders dark, status shows the diagnostic, no crash), recover, and remove + re-add (resource teardown + re-acquire). A crash in the LoadCtrl codegen, a dangling arena pointer across a recompile, or a value change that wrongly triggers a recompile all show up as a failed measure or a tick spike. The codegen + live-read contract is pinned by unit_moonlive_ir / unit_moonlive_compiler; this is the wired-module gate.

Mode: mutate · Also touches: Layouts, GridLayout, Effects, Layer, Drivers, NetworkSendDriver

add-control-script (add_module) 📏

Add a MoonLiveEffect whose source declares a speed control and uses it. The control appears bound to the arena slot (seeded to its default 7); the wired effect renders one pixel.

Setup (preceding non-measured steps): - stage-initial-script (write_file) — Stage a script before the card points at it.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 90,909	— / —	— / —
esp32	— / 58.7-85.3	— / 34KB-95KB	— / 26KB-92KB
esp32s3-n16r8	— / 216	— / 7376KB	— / 60KB

• desktop-macos: observed 2026-08-28
• esp32: observed 2026-09-01
• esp32s3-n16r8: observed 2026-07-24

set-source-with-control (set_control) 📏

Edit the source to the control script. A source edit recompiles (affectsPrepare gates on script); the engine derives the speed control and the binding surfaces it.

Setup (preceding non-measured steps): - select-initial-script (set_control) — Point the card at its script file, so the controls it declares appear. - set-source-with-control-save (write_file) — Save the script file: editing a script in place is what re-derives its controls.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 1,000,000	— / —	— / —
esp32	— / 74.4-83.0	— / 34KB-95KB	— / 26KB-92KB
esp32s3-n16r8	— / 262	— / 7453KB	— / 72KB

• desktop-macos: observed 2026-08-31
• esp32: observed 2026-09-01
• esp32s3-n16r8: observed 2026-07-24

change-control-live (set_control) 📏

Change the speed control value (a slider move). This must NOT recompile — affectsPrepare returns false for a scripted control; the arena byte updates and the next render tick reads it. Tick stays cheap (a recompile would spike it).

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 1,000,000	— / —	— / —
esp32	— / 879	— / 95KB	— / 92KB
esp32s3-n16r8	— / 262	— / 7376KB	— / 60KB

• desktop-macos: observed 2026-08-31
• esp32: observed 2026-07-24
• esp32s3-n16r8: observed 2026-07-24

edit-source-two-controls (set_control) 📏

Edit the source to add a second control. The recompile re-derives the control set; the stable-address grow-only arena keeps speed's live value while seeding the new slot.

Setup (preceding non-measured steps): - edit-source-two-controls-save (write_file) — Save the script file: editing a script in place is what re-derives its controls.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 100,000-1,000,000	— / —	— / —
esp32	— / 66.8-85.6	— / 34KB-95KB	— / 26KB-92KB
esp32s3-n16r8	— / 230	— / 7399KB	— / 84KB

• desktop-macos: observed 2026-08-31
• esp32: observed 2026-09-01
• esp32s3-n16r8: observed 2026-07-24

edit-source-shrink-to-one-control (set_control) 📏

Edit the source back to a single control. The control set shrinks 2 -> 1: speed stays bound (its live value kept), the removed hue's value is dropped, and the value change path is exercised without an unexpected recompile crash.

Setup (preceding non-measured steps): - edit-source-shrink-to-one-control-save (write_file) — Save the script file: editing a script in place is what re-derives its controls.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 333,333-1,000,000	— / —	— / —
esp32	— / 73.8-78.2	— / 34KB-95KB	— / 26KB-92KB
esp32s3-n16r8	— / 262	— / 7382KB	— / 60KB

• desktop-macos: observed 2026-08-31
• esp32: observed 2026-09-01
• esp32s3-n16r8: observed 2026-07-24

edit-source-broken (set_control) 📏

Push a broken script. Compile fails, the previous code is freed, the effect renders dark and the parse error surfaces in status — no crash.

Setup (preceding non-measured steps): - edit-source-broken-save (write_file) — Save the script file: editing a script in place is what re-derives its controls.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 500,000-1,000,000	— / —	— / —
esp32	— / 66.7-86.5	— / 34KB-95KB	— / 26KB-92KB
esp32s3-n16r8	— / 262	— / 7400KB	— / 72KB

• desktop-macos: observed 2026-08-29
• esp32: observed 2026-09-01
• esp32s3-n16r8: observed 2026-07-24

edit-source-recover (set_control) 📏

Recover with a valid control script — the effect compiles and renders again.

Setup (preceding non-measured steps): - edit-source-recover-save (write_file) — Save the script file: editing a script in place is what re-derives its controls.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 100,000-1,000,000	— / —	— / —
esp32	— / 74.2-77.5	— / 34KB-95KB	— / 26KB-92KB
esp32s3-n16r8	— / 234	— / 7386KB	— / 64KB

• desktop-macos: observed 2026-09-03
• esp32: observed 2026-09-01
• esp32s3-n16r8: observed 2026-07-24

re-add-control-effect (add_module) 📏

Re-add a fresh effect after the remove — exec memory + control arena re-acquired clean (it renders its default fill on add). Control re-acquisition itself is proven by the add-control-script step at the top: a freshly-added effect compiling a control source surfaces + seeds its control; construct-mode set_control can't apply a dynamically-added scripted control as the final asserted render, so the gate here is the bare re-add's liveness.

Setup (preceding non-measured steps): - remove-control-effect (remove_module) — Remove the effect — the engine releases its exec block AND its control arena (release).

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 100,000-1,000,000	— / —	— / —
esp32	— / 66.2-86.1	— / 34KB-95KB	— / 26KB-92KB
esp32s3-n16r8	— / 262	— / 7440KB	— / 60KB

• desktop-macos: observed 2026-08-30
• esp32: observed 2026-09-01
• esp32s3-n16r8: observed 2026-07-24

re-select-script (set_control) 📏

Point the re-added card at the same script file, then TICK. Without a render after the select the buffer still holds what the removed card left, so this is what proves the re-added one draws.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 142,857-1,000,000	— / —	— / —
esp32	— / 73.6-77.9	— / 34KB-43KB	— / 26KB-38KB

• desktop-macos: observed 2026-09-03
• esp32: observed 2026-09-01

scenario_MoonLiveEffect_livescript

test/scenarios/light/scenario_MoonLiveEffect_livescript.json — Exercise a scripted MoonLiveEffect as a wired MoonModule end-to-end — the integration layer the unit tests can't reach. The effect compiles its source text to native code on-device and renders it into the Layer buffer each tick. Prepares its own canvas: Layout(Grid 16x16) + Layer + MoonLiveEffect, measures the default compile, then edits source live (a new fill color recompiles and keeps rendering), pushes a BROKEN script (compile fails, the previous code is freed, the effect renders dark and the parse error surfaces in status, no crash), recovers with a valid script, and finally removes + re-adds the effect (add/remove robustness in any order). A crash in the JIT/emit path, a failed recompile that wedges the tick, or a buffer overrun on an odd grid all show up as a failed measure. The compiler + emit golden bytes are pinned by unit_moonlive_compiler / unit_moonlive_fill; this is the live wired-module gate.

Mode: mutate · Also touches: Layouts, GridLayout, Effects, Layer, Drivers, NetworkSendDriver

add-moonlive (add_module) 📏

Add a MoonLiveEffect to the Layer. Its default source (random pixels) compiles on-device to native code; measure that the wired effect renders.

Setup (preceding non-measured steps): - stage-initial-script (write_file) — Stage the script the effect starts on, before it is added.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 45,455-166,667	— / —	— / —
esp32	— / 71.5-75.1	— / 34KB-95KB	— / 26KB-92KB
esp32p4rev1-eth	— / 88.6	— / 33211KB	— / 376KB
esp32s3-n16r8	— / 249	— / 7448KB	— / 62KB

• desktop-macos: observed 2026-09-06
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-06-27
• esp32s3-n16r8: observed 2026-07-24

edit-source-red (set_control) 📏

Live-edit the script source to a new color. A script edit triggers a recompile (affectsPrepare gates on script); the new native code swaps in and keeps rendering.

Setup (preceding non-measured steps): - select-initial-script (set_control) — Point the card at its script file. - edit-source-red-save (write_file) — Save the script file, the way the card editor writes it.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 41,667-200,000	— / —	— / —
esp32	— / 73.2-86.1	— / 34KB-95KB	— / 26KB-92KB
esp32p4rev1-eth	— / 98.4	— / 33213KB	— / 376KB
esp32s3-n16r8	— / 225	— / 7465KB	— / 84KB

• desktop-macos: observed 2026-09-06
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-06-27
• esp32s3-n16r8: observed 2026-07-24

edit-source-broken (set_control) 📏

Push a script that fails to parse. The compile fails, the engine reports the diagnostic in the module status and renders dark, but the device keeps running (robust, no reboot) — the script-editor failure path. The measure passes because the pipeline still ticks.

Setup (preceding non-measured steps): - edit-source-broken-save (write_file) — Save the script file, the way the card editor writes it.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 52,632-200,000	— / —	— / —
esp32	— / 65.5-85.9	— / 34KB-95KB	— / 26KB-92KB
esp32p4rev1-eth	— / 94.6	— / 33209KB	— / 376KB
esp32s3-n16r8	— / 229	— / 7467KB	— / 84KB

• desktop-macos: observed 2026-09-06
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-06-27
• esp32s3-n16r8: observed 2026-07-24

edit-source-recover (set_control) 📏

Push a valid script again. The engine recompiles cleanly and rendering resumes — a broken edit is fully recoverable.

Setup (preceding non-measured steps): - edit-source-recover-save (write_file) — Save the script file, the way the card editor writes it.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 47,619-200,000	— / —	— / —
esp32	— / 73.5-77.1	— / 34KB-95KB	— / 26KB-92KB
esp32p4rev1-eth	— / 93.4	— / 33212KB	— / 376KB
esp32s3-n16r8	— / 248	— / 7465KB	— / 84KB

• desktop-macos: observed 2026-09-06
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-06-27
• esp32s3-n16r8: observed 2026-07-24

shrink-grid-1x1 (set_control) 📏

Resize the canvas to 1x1 while the scripted effect renders — the smallest non-empty grid. The native fill loops over a single light; the run guards (non-null buffer, cpl>=3) keep it in-bounds. Pins the 'runs at every grid size' hard rule for the JIT'd routine.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 50,000-200,000	— / —	— / —
esp32	— / 405-707	— / 35KB-113KB	— / 26KB-92KB
esp32p4rev1-eth	— / 862	— / 33215KB	— / 376KB
esp32s3-n16r8	— / 868	— / 7535KB	— / 84KB

• desktop-macos: observed 2026-09-06
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-06-27
• esp32s3-n16r8: observed 2026-07-24

grow-grid-back (set_control) 📏

Resize back to a wider grid; the effect keeps rendering across the live dimension change (the no-reboot reconfiguration contract applied to scripted code).

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 41,667-200,000	— / —	— / —
esp32	— / 74.3-85.1	— / 34KB-113KB	— / 26KB-92KB
esp32p4rev1-eth	— / 97.0	— / 33209KB	— / 376KB
esp32s3-n16r8	— / 136	— / 7515KB	— / 80KB

• desktop-macos: observed 2026-09-06
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-06-27
• esp32s3-n16r8: observed 2026-07-24

transpose-grid-h (set_control) 📏

Make it 16x8, then 8x16 below: the SAME sample count in a different shape. resize() keeps the buffer and its contents, which are laid out for the old geometry, so a scripted trail must clear both of its planes or the previous picture smears across the new one. The compiled effects each carry this guard; the binding does it on the script's behalf.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 125,000-200,000	— / —	— / —

• desktop-macos: observed 2026-09-06

transpose-grid-w (set_control) 📏

And the transpose: 8 wide by 16 high, the same count again. The pair proves the clear fires on a reshape rather than only on a size change, in both directions.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 166,667-200,000	— / —	— / —

• desktop-macos: observed 2026-09-06

transpose-restore (set_control) 📏

Back to the square the rest of the scenario assumes.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 166,667-200,000	— / —	— / —

• desktop-macos: observed 2026-09-06

remove-moonlive (remove_module) 📏

Remove the scripted effect. release frees the exec block; the Layer keeps rendering (now empty). Measures add/remove robustness.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 47,619-200,000	— / —	— / —
esp32	— / 73.6-75.6	— / 36KB-114KB	— / 26KB-92KB
esp32p4rev1-eth	— / 88.2	— / 33209KB	— / 376KB
esp32s3-n16r8	— / 135	— / 7516KB	— / 80KB

• desktop-macos: observed 2026-09-06
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-06-27
• esp32s3-n16r8: observed 2026-07-24

re-add-moonlive (add_module) 📏

Re-add a MoonLiveEffect after removal — the exec memory is re-acquired fresh, no leak, no stale pointer. The scripted effect renders again.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 34,483-200,000	— / —	— / —
esp32	— / 62.0-85.7	— / 34KB-113KB	— / 26KB-92KB
esp32p4rev1-eth	— / 90.9	— / 33209KB	— / 376KB
esp32s3-n16r8	— / 121	— / 7521KB	— / 84KB

• desktop-macos: observed 2026-09-06
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-06-27
• esp32s3-n16r8: observed 2026-07-24

re-select-script (set_control) 📏

Point the re-added card at the same script file, then TICK. Without a render after the select the buffer still holds what the removed card left, so this is what proves the re-added one draws.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 32,258-200,000	— / —	— / —
esp32	— / 74.2-74.4	— / 34KB-47KB	— / 26KB-38KB

• desktop-macos: observed 2026-09-06
• esp32: observed 2026-09-01

MoonLiveLayout

scenario_MoonLive_pipeline

test/scenarios/light/scenario_MoonLive_pipeline.json — Drive a WHOLE pipeline whose layout, effect and modifier are all live scripts, and verify it keeps rendering across every edit. This is the end-to-end proof the unit tests cannot give: they exercise each binding against a stub, while here a scripted layout decides where the lights are, a scripted effect colours them, and a scripted modifier folds the mapping, composed in one Layer feeding a real driver. The steps walk the live-authoring loop a user performs: start on the default 16x16 script, add a scripted effect and see it colour the fixture, then replace the layout script with a 24-light row and watch the buffer resize under a running effect; add a scripted modifier and edit it live; break the layout script and confirm the device degrades to zero lights rather than dying; recover it and confirm the fixture comes back. A scripted layout is the demanding case because the pipeline asks it for a light COUNT before asking where any light is, and both answers come from running the same script, so a mismatch shows up here as a wrong buffer size or a wedged tick rather than a compile error. The compile + emit path is pinned by unit_moonlive_compiler / unit_MoonLiveLayout; this is the wired-pipeline gate.

Mode: mutate · Also touches: MoonLiveEffect, MoonLiveModifier, MoonLive, Layouts, Layer

Trailing setup (no measurement after)

• add-scripted-layout (add_module) — Add the scripted layout. A step, not fixture: on a live device only the containers are guaranteed to exist, so the instance has to be created here.
• select-default-layout (set_control) — Point the scripted layout at the SHIPPED grid.mll — the fixture a user starts from. A shipped file, not a staged one: the live runner skips the fixture, so anything written there is absent on a real device.
• baseline-default-script (measure)
• add-scripted-effect (add_module)
• effect-gradient-write (write_file) — Write the script file the card points at, the way the editor saves it.
• effect-gradient (set_control)
• measure-scripted-effect (measure)
• layout-a-row-write (write_file) — Write the script file the card points at, the way the editor saves it.
• layout-a-row (set_control)
• measure-scripted-row (measure)
• add-scripted-modifier (add_module)
• modifier-mirror-write (write_file) — Write the script file the card points at, the way the editor saves it.
• modifier-mirror (set_control)
• measure-all-three-scripted (measure)
• modifier-transpose-write (write_file) — Write the script file the card points at, the way the editor saves it.
• modifier-transpose-resync (set_control) — Re-assert the same filename: editing a file in place must recompile it.
• measure-modifier-edited (measure)
• break-the-layout-write (write_file) — Write the script file the card points at, the way the editor saves it.
• break-the-layout-resync (set_control) — Re-assert the same filename: editing a file in place must recompile it.
• measure-broken-layout (measure)
• recover-the-layout-write (write_file) — Write the script file the card points at, the way the editor saves it.
• recover-the-layout-resync (set_control) — Re-assert the same filename: editing a file in place must recompile it.
• measure-recovered (measure)
• remove-modifier (remove_module)
• measure-after-removal (measure) — The scripted effect still colours the scripted layout after the modifier goes.

MoonModule

scenario_MoonModule_control_change

test/scenarios/core/scenario_MoonModule_control_change.json — Measure the cost of control changes on a running pipeline. Toggles MultiplyModifier's mirrorX/Y at different points and verifies each change is applied without freezing the render loop. Companion to the MoonModule control-change gate unit tests (unit_MoonModule_control_change_gate.cpp) — this is the live equivalent.

Mode: mutate · Also touches: MultiplyModifier, NoiseEffect

baseline (set_control) 📏

Set NoiseEffect.scale=4 and measure baseline FPS (mirror on). Effect controls don't rebuild the pipeline — slider stutter check.

Setup (preceding non-measured steps): - canvas-clear-layers (clear_children) — Self-canvas: clear+rebuild the pipeline this scenario assumes, so it runs from any device state (order-independent in a chained live run). Pre-wired apparatus survives clear_children; replaces the old fixture+reset model. - canvas-clear-layouts (clear_children) - canvas-clear-drivers (clear_children) - canvas-grid (add_module) - canvas-layer (add_module) - canvas-noise (add_module) - canvas-mirror (add_module) - canvas-artnet (add_module)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	≥ 8,333 / 4,032-6,944	unlimited / —	— / —
desktop-windows	— / 4,405	— / —	— / —
esp32	— / 4,717	— / 88KB	— / 48KB
esp32-eth	— / 10.6	— / 133KB	— / 48KB
esp32-eth-wifi	≥ 10.0 / 12.2	≥ 103KB / 94KB	— / 48KB
esp32p4rev1-eth	— / 6,250	— / 33238KB	— / 376KB
esp32s3-n16r8	— / 6,024	— / 8318KB	— / 84KB

• desktop-macos: contract set 2026-06-02 "initial contract" · observed 2026-09-06
• desktop-windows: observed 2026-08-21
• esp32: observed 2026-07-24
• esp32-eth: observed 2026-06-02
• esp32-eth-wifi: contract set 2026-06-02 "initial contract" · observed 2026-06-02
• esp32p4rev1-eth: observed 2026-06-17
• esp32s3-n16r8: observed 2026-07-24

disable-mirrorX (set_control) 📏

Disable mirrorX. Modifier control triggers a pipeline rebuild — measures the rebuilt path.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	≥ 5,000 / 4,049-7,463	unlimited / —	— / —
desktop-windows	— / 3,817	— / —	— / —
esp32	— / 4,717	— / 88KB	— / 48KB
esp32-eth	— / 10.4	— / 132KB	— / 48KB
esp32-eth-wifi	≥ 10.0 / 12.0	≥ 103KB / 94KB	— / 48KB
esp32p4rev1-eth	— / 6,135	— / 33238KB	— / 376KB
esp32s3-n16r8	— / 6,536	— / 8321KB	— / 84KB

• desktop-macos: contract set 2026-06-02 "initial contract" · observed 2026-09-06
• desktop-windows: observed 2026-08-21
• esp32: observed 2026-07-24
• esp32-eth: observed 2026-06-02
• esp32-eth-wifi: contract set 2026-06-02 "initial contract" · observed 2026-06-02
• esp32p4rev1-eth: observed 2026-06-17
• esp32s3-n16r8: observed 2026-07-24

disable-mirrorY (set_control) 📏

Disable mirrorY. Mirror is now fully off — should land on the no-LUT path.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	≥ 2,500 / 4,184-7,937	unlimited / —	— / —
desktop-windows	— / 3,861	— / —	— / —
esp32	— / 5,464	— / 88KB	— / 48KB
esp32-eth	— / 9.0	— / 132KB	— / 48KB
esp32-eth-wifi	≥ 10.0 / 11.1	≥ 103KB / 94KB	— / 48KB
esp32p4rev1-eth	— / 6,061	— / 33238KB	— / 376KB
esp32s3-n16r8	— / 6,494	— / 8317KB	— / 80KB

• desktop-macos: contract set 2026-06-02 "initial contract" · observed 2026-09-06
• desktop-windows: observed 2026-08-21
• esp32: observed 2026-07-24
• esp32-eth: observed 2026-06-02
• esp32-eth-wifi: contract set 2026-06-02 "initial contract" · observed 2026-06-02
• esp32p4rev1-eth: observed 2026-06-17
• esp32s3-n16r8: observed 2026-07-24

re-enable-mirrorY (set_control) 📏

Re-enable mirrorY and measure — the heavy LUT path must recover (FPS within 50% of baseline) without staying degraded.

Setup (preceding non-measured steps): - re-enable-mirrors (set_control) — Re-enable mirrorX (rebuild back to LUT path).

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	≥ 8,333 / 4,049-7,874	unlimited / —	— / —
desktop-windows	— / 4,854	— / —	— / —
esp32	— / 5,376	— / 88KB	— / 48KB
esp32-eth	— / 10.6	— / 132KB	— / 48KB
esp32-eth-wifi	≥ 10.0 / 12.1	≥ 103KB / 94KB	— / 48KB
esp32p4rev1-eth	— / 6,098	— / 33238KB	— / 376KB
esp32s3-n16r8	— / 6,803	— / 8322KB	— / 84KB

• desktop-macos: contract set 2026-06-02 "initial contract" · observed 2026-09-06
• desktop-windows: observed 2026-07-08
• esp32: observed 2026-07-24
• esp32-eth: observed 2026-06-02
• esp32-eth-wifi: contract set 2026-06-02 "initial contract" · observed 2026-06-02
• esp32p4rev1-eth: observed 2026-06-17
• esp32s3-n16r8: observed 2026-07-24

MqttModule

scenario_MqttModule_haDiscovery_toggle

test/scenarios/core/scenario_MqttModule_haDiscovery_toggle.json — Toggle the Home-Assistant MQTT-discovery announce on and off and confirm the render loop survives every change. Pins the robustness + No-reboot-to-apply guarantees for the new haDiscovery control: turning it on publishes a retained homeassistant/light//config (and subscribes ha/set); turning it off retracts the config (empty retained payload) — both live over the already-connected socket on tick1s(), never a reconnect and never on the render task. No toggle, in any order, may crash, wedge the tick, or leak heap. Runs live only — discovery needs a real broker to publish to and MqttModule only exists on a board whose catalog entry includes it (the Shelly model does), so the in-process desktop runner SKIPs it; on a device it flips the control over HTTP. The bound checks FPS + heap stay within range across the on/off/on cycle (a discovery publish is a transient cost, not a permanent degradation), proving the toggle never leaves the network task or render loop degraded. (Background: the announce/retract are on the 1 Hz tick, off the hot path — see the MqttModule /// § Home Assistant MQTT Discovery.)

Mode: mutate · live-only (skipped in-process)

baseline-discovery-on (set_control) 📏

haDiscovery on (default) — captures the baseline FPS/heap for the next two steps.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 333,333	— / —	— / —
esp32	— / 29,412	— / 117KB	— / 108KB
esp32-eth-wifi	≥ 10.0 / —	≥ 88KB / —	— / —
esp32s3-n16r8	— / 29,412	— / 7468KB	— / 84KB

• desktop-macos: observed 2026-08-08
• esp32: observed 2026-07-24
• esp32-eth-wifi: contract set 2026-07-06 "initial contract — pending first hardware capture"
• esp32s3-n16r8: observed 2026-07-24

discovery-off (set_control) 📏

haDiscovery off — the retract publish (empty retained config) goes out; FPS/heap must match or exceed the baseline.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 333,333	— / —	— / —
esp32	— / 27,778	— / 117KB	— / 108KB
esp32-eth-wifi	≥ 10.0 / —	≥ 88KB / —	— / —
esp32s3-n16r8	— / 27,778	— / 7401KB	— / 84KB

• desktop-macos: observed 2026-08-08
• esp32: observed 2026-07-24
• esp32-eth-wifi: contract set 2026-07-06 "initial contract — pending first hardware capture"
• esp32s3-n16r8: observed 2026-07-24

discovery-on-again (set_control) 📏

haDiscovery on again — re-announce + re-subscribe live. Bound: FPS must stay within 20% of the baseline (proves toggling doesn't leave the network task in a degraded state).

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 333,333	— / —	— / —
esp32	— / 28,571	— / 118KB	— / 108KB
esp32-eth-wifi	≥ 10.0 / —	≥ 88KB / —	— / —
esp32s3-n16r8	— / 28,571	— / 7467KB	— / 84KB

• desktop-macos: observed 2026-08-08
• esp32: observed 2026-07-24
• esp32-eth-wifi: contract set 2026-07-06 "initial contract — pending first hardware capture"
• esp32s3-n16r8: observed 2026-07-24

MultiplyModifier

scenario_MultiplyModifier_memory_lut

test/scenarios/light/scenario_MultiplyModifier_memory_lut.json — Verify that adding a MultiplyModifier allocates both the mapping LUT and the driver buffer (the heavy memory path). Companion to scenario_Layer_memory_1to1, which verifies the no-LUT path.

Mode: construct · Also touches: Layer, MappingLUT, BlendMap

add-artnet (add_module) 📏

Add NetworkSendDriver and run the bounded FPS measurement on the LUT path.

Setup (preceding non-measured steps): - add-layout-group (add_module) — Create the top-level Layouts container. - add-grid (add_module) — Add a 16x16 GridLayout. - add-layer (add_module) — Add a Layer wired to Layouts (RGB). - add-noise (add_module) — Add NoiseEffect as the Layer's effect. - add-mirror (add_module) — Add MultiplyModifier — triggers LUT and driver-buffer allocation. - add-driver-group (add_module) — Add a Drivers container wired to the Layer.

Bounds: - FPS ≥ 80% of baseline

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	≥ 8,333 / 47,619-333,333	unlimited / —	— / —
desktop-windows	— / 333,333	— / —	— / —

• desktop-macos: contract set 2026-06-02 "initial contract" · observed 2026-09-06
• desktop-windows: observed 2026-08-23

scenario_MultiplyModifier_pipeline

test/scenarios/light/scenario_MultiplyModifier_pipeline.json — Pipeline with a mirror modifier: NoiseEffect renders one quadrant, MultiplyModifier reflects across X and Y to produce a kaleidoscope. Used to verify the MultiplyModifier wires into Layer cleanly and that the full pipeline still meets its FPS bound.

Mode: construct · Also touches: Layer, NoiseEffect, NetworkSendDriver

add-artnet (add_module) 📏

Add NetworkSendDriver and run the bounded FPS measurement (mirror + LUT path must stay at >=80% of the rated FPS).

Setup (preceding non-measured steps): - add-layout-group (add_module) — Create the top-level Layouts container. - add-grid (add_module) — Add a 128x128 GridLayout child to Layouts. Set explicitly (the module default is 16x16x1) so the tick is measurable above the host's microsecond clock. - add-layer (add_module) — Add a Layer wired to Layouts (RGB). - add-noise (add_module) — Add NoiseEffect as the Layer's effect. - add-mirror (add_module) — Add MultiplyModifier so logical pixels reflect across X and Y in the physical grid. - add-driver-group (add_module) — Add a Drivers container wired to the Layer's output buffer.

Bounds: - FPS ≥ 80% of baseline

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	≥ 8,333 / 3,534-7,937	unlimited / —	— / —
desktop-windows	— / 4,444	— / —	— / —

• desktop-macos: contract set 2026-06-02 "initial contract" · observed 2026-09-06
• desktop-windows: observed 2026-07-08

NetworkModule

scenario_NetworkModule_eth_reconfigure

test/scenarios/core/scenario_NetworkModule_eth_reconfigure.json — Cycle the Ethernet PHY type (ethType: None/LAN8720/IP101/W5500) live on a running device and confirm the render loop survives every transition. Pins the robustness principle for the runtime Ethernet config: changing ethType reshapes the platform eth config (NetworkModule.syncEthLive → setEthConfig, with a live ethStop+ethInit on W5500), and no value or transition order may crash or wedge the tick. Runs live only — the eth controls exist only on hasEthernet ESP32 builds, so the in-process desktop runner SKIPs it; on a device it drives the controls over HTTP. On RMII boards (Olimex) the change saves + asks for restart (no hot re-init), so the live HTTP connection is undisturbed; the W5500 path hot-reinits but the SPI bus teardown keeps the netif alive enough to keep serving.

Mode: mutate · live-only (skipped in-process)

ethType-lan8720 (set_control) 📏

LAN8720 (RMII) — the classic-ESP32 default. Baseline: device renders with Ethernet RMII selected.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
esp32	— / 1,022	— / 100KB	— / 48KB
esp32s3-n16r8	— / 11.4	— / 7464KB	— / 80KB

• esp32: observed 2026-07-24
• esp32s3-n16r8: observed 2026-07-24

ethType-none (set_control) 📏

Switch to None (no Ethernet) live. The eth pin rows hide; the device must keep rendering and stay reachable.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
esp32	— / 1,021	— / 100KB	— / 48KB
esp32s3-n16r8	— / 10.5	— / 7467KB	— / 84KB

• esp32: observed 2026-07-24
• esp32s3-n16r8: observed 2026-07-24

ethType-w5500 (set_control) 📏

Switch to W5500 (SPI) live. On an S3 this hot-reinits eth (ethStop + ethInit); on RMII boards it saves + flags restart. Either way the render loop must survive.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
esp32	— / 1,020	— / 100KB	— / 48KB
esp32s3-n16r8	— / 10.2	— / 7467KB	— / 84KB

• esp32: observed 2026-07-24
• esp32s3-n16r8: observed 2026-07-24

ethType-ip101 (set_control) 📏

Switch to IP101 (RMII) live — the P4 PHY. Exercises the last dropdown value; render loop must survive.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
esp32	— / 1,007	— / 100KB	— / 48KB
esp32s3-n16r8	— / 10.8	— / 7442KB	— / 60KB

• esp32: observed 2026-07-24
• esp32s3-n16r8: observed 2026-07-24

ethType-back-to-lan8720 (set_control) 📏

Return to LAN8720 — confirms the cycle is reversible and leaves the device in a sane state.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
esp32	— / 855	— / 100KB	— / 48KB
esp32s3-n16r8	— / 11.1	— / 7465KB	— / 84KB

• esp32: observed 2026-07-24
• esp32s3-n16r8: observed 2026-07-24

scenario_NetworkModule_mdns_toggle

test/scenarios/core/scenario_NetworkModule_mdns_toggle.json — Toggle the mDNS responder on and off and measure render-FPS impact. Validates that mDNS announcement traffic doesn't degrade the render loop more than 20% on the busiest tick.

Mode: mutate · live-only (skipped in-process)

baseline-mdns-on (set_control) 📏

mDNS on (default) — captures the baseline FPS for the next two steps.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 76,923	— / —	— / —
esp32	— / 28,571	— / 88KB	— / 48KB
esp32-eth	— / 10.6	— / 132KB	— / 48KB
esp32-eth-wifi	≥ 10.0 / 12.2	≥ 103KB / 93KB	— / 48KB
esp32p4rev1-eth	— / 47,619	— / 33245KB	— / 376KB
esp32s3-n16r8	— / 27,778	— / 7400KB	— / 80KB

• desktop-macos: observed 2026-08-08
• esp32: observed 2026-07-22
• esp32-eth: observed 2026-06-02
• esp32-eth-wifi: contract set 2026-06-02 "initial contract" · observed 2026-06-02
• esp32p4rev1-eth: observed 2026-06-17
• esp32s3-n16r8: observed 2026-07-24

mdns-off (set_control) 📏

mDNS off — measured. Expected to match or exceed the baseline.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 76,923	— / —	— / —
esp32	— / 27,778	— / 88KB	— / 48KB
esp32-eth	— / 10.5	— / 137KB	— / 48KB
esp32-eth-wifi	≥ 10.0 / 12.0	≥ 93KB / 98KB	— / 48KB
esp32p4rev1-eth	— / 47,619	— / 33245KB	— / 376KB
esp32s3-n16r8	— / 27,778	— / 7469KB	— / 84KB

• desktop-macos: observed 2026-08-08
• esp32: observed 2026-07-22
• esp32-eth: observed 2026-06-02
• esp32-eth-wifi: contract set 2026-06-02 "shared heap budget; cumulative sweep state reduces standalone-mDNS-off heap by ~15KB" · observed 2026-06-02
• esp32p4rev1-eth: observed 2026-06-17
• esp32s3-n16r8: observed 2026-07-24

mdns-on-again (set_control) 📏

mDNS on again — measured with a bound: FPS must stay within 20% of the baseline (proves toggling doesn't leave the network task in a degraded state).

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 76,923	— / —	— / —
esp32	— / 28,571	— / 83KB	— / 48KB
esp32-eth	— / 9.1	— / 132KB	— / 48KB
esp32-eth-wifi	≥ 10.0 / 10.6	≥ 103KB / 93KB	— / 48KB
esp32p4rev1-eth	— / 50,000	— / 33245KB	— / 376KB
esp32s3-n16r8	— / 28,571	— / 7441KB	— / 60KB

• desktop-macos: observed 2026-08-08
• esp32: observed 2026-07-22
• esp32-eth: observed 2026-06-02
• esp32-eth-wifi: contract set 2026-06-02 "initial contract" · observed 2026-06-02
• esp32p4rev1-eth: observed 2026-06-17
• esp32s3-n16r8: observed 2026-07-24

NetworkSendDriver

scenario_Driver_mutation

test/scenarios/light/scenario_Driver_mutation.json — Add / remove output drivers under the Drivers container while the render pipeline runs, proving the robustness rule for driver deletion (the LED-driver delete path the product owner asked to cover; on the host RmtLed/I80Led/Parlio are inert via platform constants, so the portable NetworkSendDriver + PreviewDriver exercise the SAME generic add/remove lifecycle through the Scheduler that the hardware drivers use). Drivers are consumers of the Layer's output buffer, added/removed at runtime in any order. The checks assert the pipeline keeps RENDERING (buffer non-null, fps measurable) through each mutation: adding a second driver, removing it, and crucially removing a driver while the pipeline is still live (a driver teardown must release its resources without stranding the buffer or the other drivers — the same end-to-end Scheduler path the Audio producer/consumer scenario proves for peripherals, here for the output stage). Grid is 64x64 so the tick stays above the host microsecond clock at every step.

Mode: mutate · Also touches: GridLayout, Layer, RainbowEffect, Drivers, PreviewDriver

measure-one-driver (measure) 📏

Baseline: the pipeline renders with one driver (Preview) wired.

Bounds: - FPS ≥ 1 (absolute)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 10,101-50,000	— / —	— / —
desktop-windows	— / 27,778	— / —	— / —
esp32	— / 77.3-89.8	— / 40KB-97KB	— / 26KB-92KB
esp32s3-n16r8	— / 29,412	— / 7468KB	— / 84KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-23
• esp32: observed 2026-09-01
• esp32s3-n16r8: observed 2026-07-24

measure-two-drivers (measure) 📏

Pipeline renders with both drivers wired.

Setup (preceding non-measured steps): - add-second-driver (add_module) — Add a NetworkSendDriver beside the Preview driver — two consumers of the same Layer output buffer. The add must not disturb the running pipeline.

Bounds: - FPS ≥ 1 (absolute)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 14,706-50,000	— / —	— / —
desktop-windows	— / 28,571	— / —	— / —
esp32	— / 69.9-81.5	— / 38KB-83KB	— / 26KB-80KB
esp32s3-n16r8	— / 26,316	— / 7453KB	— / 60KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-23
• esp32: observed 2026-09-01
• esp32s3-n16r8: observed 2026-07-24

measure-three-drivers (measure) 📏

Pipeline renders with three drivers wired.

Setup (preceding non-measured steps): - add-third-driver (add_module) — Add a second NetworkSendDriver — three drivers now share the Layer output buffer (Preview + two ArtNet). Stacking editable drivers before tearing them down in sequence.

Bounds: - FPS ≥ 1 (absolute)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 15,625-47,619	— / —	— / —
desktop-windows	— / 23,810	— / —	— / —
esp32	— / 70.0-81.7	— / 37KB-69KB	— / 26KB-64KB
esp32s3-n16r8	— / 25,641	— / 7442KB	— / 72KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-23
• esp32: observed 2026-09-01
• esp32s3-n16r8: observed 2026-07-24

measure-after-first-remove (measure) 📏

One ArtNet gone, Preview + ArtNet2 remain: pipeline keeps rendering (buffer non-null, fps measurable). No crash from the mid-list teardown.

Setup (preceding non-measured steps): - remove-first-added-driver (remove_module) — Remove the FIRST-added NetworkSendDriver while the others (Preview + ArtNet2) are still live — delete a middle consumer, not the last. Its teardown must release its resources without stranding the buffer or the surviving drivers.

Bounds: - FPS ≥ 1 (absolute)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 12,048-50,000	— / —	— / —
desktop-windows	— / 23,810	— / —	— / —
esp32	— / 59.6-78.1	— / 39KB-83KB	— / 26KB-68KB
esp32s3-n16r8	— / 27,778	— / 7455KB	— / 84KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-07-08
• esp32: observed 2026-09-01
• esp32s3-n16r8: observed 2026-07-24

measure-back-to-one-driver (measure) 📏

Both added drivers gone, back to the single Preview baseline, still rendering — the add/remove cycle leaves the pipeline coherent.

Setup (preceding non-measured steps): - remove-second-added-driver (remove_module) — Remove the remaining editable driver (ArtNet2) too — back to just the boot-wired Preview. Repeated driver teardown leaves no residue; the pipeline still renders. (PreviewDriver is userEditable=false, so it stays — drivers always have at least the wired output consumer; this mirrors the live API, which forbids deleting code-wired modules.)

Bounds: - FPS ≥ 1 (absolute)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 15,152-50,000	— / —	— / —
desktop-windows	— / 27,778	— / —	— / —
esp32	— / 70.1-83.5	— / 41KB-96KB	— / 26KB-92KB
esp32s3-n16r8	— / 27,778	— / 7469KB	— / 84KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-23
• esp32: observed 2026-09-01
• esp32s3-n16r8: observed 2026-07-24

ParallelLedDriver

scenario_peripheral_grid_sweep

test/scenarios/light/scenario_peripheral_grid_sweep.json — Cross-product benchmark: for EACH output peripheral (RMT, i80, MoonI80, Parlio), sweep the grid 16x16 -> 32x32 -> 64x64 -> 128x128 and measure the tick/heap at each size, driving the FULL grid out that peripheral (16 lanes so 128x128=16384 lights distribute ~1024/lane). This is the apples-to-apples per-board number set: run it identically on any board and the per-peripheral, per-size ticks compare directly (an S31 vs a P4, say). Each peripheral block is optional:true, so a board that lacks one (a classic ESP32 has no MoonI80/Parlio; a P4 has all three) skips it without failing, and the observed blocks record only where the peripheral is real. A NoiseEffect fills every cell so the render cost is non-trivial at every size. Pins are the S3/P4/S31 clean 16-lane set; a board whose pins differ records a driver that failed to init (a small bailout tick, not an encode) for that peripheral. NOTE the driver drives the full grid, so at 128x128 (16384 lights) a whole-frame path may exceed its DMA budget and idle with a status (a clean degrade, captured as a fast bail tick) while the streaming ring / PSRAM path keeps driving; that contrast IS the measurement.

Mode: mutate · Also touches: MultiPinLedDriver, MoonLedDriver, ParlioLedDriver, RmtLedDriver, Layouts, GridLayout, Effects, Layer, NoiseEffect, Drivers, PreviewDriver

measure-rmt-16 (measure) 📏

Setup (preceding non-measured steps): - clear-layers (clear_children) - clear-drivers (clear_children) - build-grid (add_module) — One GridLayout, resized live per sweep step below. - build-layer (add_module) - build-fx (add_module) — A NoiseEffect fills every cell, so render is non-trivial at every grid size. - add-rmt (add_module) — RMT output (every ESP32). One pin; RMT drives per-channel, so this is the single-strand output baseline. - rmt-16-w (set_control) - rmt-16-h (set_control)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 71,429-250,000	— / —	— / —
desktop-windows	— / 111,111	— / —	— / —
esp32	— / 2,273-2,309	— / 56KB	— / 38KB
esp32p4rev1-eth	— / 9,709	— / 33143KB	— / 344KB
esp32s31	— / 5,376	— / 16573KB	— / 164KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-22
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-07-25
• esp32s31: observed 2026-07-25

measure-rmt-32 (measure) 📏

Setup (preceding non-measured steps): - rmt-32-w (set_control) - rmt-32-h (set_control)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 11,905-55,556	— / —	— / —
desktop-windows	— / 27,027	— / —	— / —
esp32	— / 670-692	— / 74KB-76KB	— / 38KB
esp32p4rev1-eth	— / 2,037	— / 33067KB	— / 344KB
esp32s31	— / 1,473	— / 16500KB	— / 164KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-22
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-07-25
• esp32s31: observed 2026-07-25

measure-rmt-64 (measure) 📏

Setup (preceding non-measured steps): - rmt-64-w (set_control) - rmt-64-h (set_control)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 4,149-14,085	— / —	— / —
desktop-windows	— / 6,250	— / —	— / —
esp32	— / 179	— / 59KB	— / 26KB-38KB
esp32p4rev1-eth	— / 453	— / 32761KB	— / 344KB
esp32s31	— / 346	— / 16194KB	— / 164KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-23
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-07-25
• esp32s31: observed 2026-07-25

measure-rmt-128 (measure) 📏

Setup (preceding non-measured steps): - rmt-128-w (set_control) - rmt-128-h (set_control)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 1,066-3,484	— / —	— / —
desktop-windows	— / 1,541	— / —	— / —
esp32	— / 719-858	— / 88KB	— / 38KB
esp32p4rev1-eth	— / 87.0	— / 31537KB	— / 344KB
esp32s31	— / 162	— / 14966KB	— / 164KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-23
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-07-25
• esp32s31: observed 2026-07-25

measure-i80-16 (measure) 📏

Setup (preceding non-measured steps): - remove-rmt (remove_module) - add-i80 (add_module) — i80 (esp_lcd): LCD_CAM on S3/P4/S31, I2S on classic. 16 lanes so 128x128=16384 distributes ~1024/lane. - i80-16-w (set_control) - i80-16-h (set_control)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 62,500-250,000	— / —	— / —
desktop-windows	— / 111,111	— / —	— / —
esp32	— / 2,347	— / 79KB-80KB	— / 34KB-38KB
esp32p4rev1-eth	— / 4,808	— / 33166KB	— / 344KB
esp32s31	— / 2,469	— / 16599KB	— / 164KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-23
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-07-25
• esp32s31: observed 2026-07-25

measure-i80-32 (measure) 📏

Setup (preceding non-measured steps): - i80-32-w (set_control) - i80-32-h (set_control)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 16,393-55,556	— / —	— / —
desktop-windows	— / 27,027	— / —	— / —
esp32	— / 659-691	— / 75KB	— / 34KB-38KB
esp32p4rev1-eth	— / 2,242	— / 33161KB	— / 344KB
esp32s31	— / 1,835	— / 16594KB	— / 164KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-22
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-07-25
• esp32s31: observed 2026-07-25

measure-i80-64 (measure) 📏

Setup (preceding non-measured steps): - i80-64-w (set_control) - i80-64-h (set_control)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 4,386-14,085	— / —	— / —
desktop-windows	— / 6,579	— / —	— / —
esp32	— / 136-143	— / 57KB-58KB	— / 22KB-38KB
esp32p4rev1-eth	— / 536	— / 33143KB	— / 344KB
esp32s31	— / 439	— / 16576KB	— / 164KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-23
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-07-25
• esp32s31: observed 2026-07-25

measure-i80-128 (measure) 📏

Setup (preceding non-measured steps): - i80-128-w (set_control) - i80-128-h (set_control)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 1,135-3,247	— / —	— / —
desktop-windows	— / 1,553	— / —	— / —
esp32	— / 180-189	— / 77KB-89KB	— / 34KB-38KB
esp32p4rev1-eth	— / 111	— / 33071KB	— / 344KB
esp32s31	— / 151	— / 16504KB	— / 164KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-22
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-07-25
• esp32s31: observed 2026-07-25

measure-moon-16 (measure) 📏

Setup (preceding non-measured steps): - remove-i80 (remove_module) - add-moonI80 (add_module) — MoonI80 (own-GDMA below esp_lcd, LCD_CAM only): the streaming ring, so length is not a memory question. Same 16-lane pin set. - moon-16-w (set_control) - moon-16-h (set_control)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 71,429-250,000	— / —	— / —
desktop-windows	— / 111,111	— / —	— / —
esp32	— / 2,364-2,381	— / 79KB-80KB	— / 34KB-38KB
esp32p4rev1-eth	— / 4,167	— / 33166KB	— / 344KB
esp32s31	— / 4,167	— / 16599KB	— / 164KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-22
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-07-25
• esp32s31: observed 2026-07-25

measure-moon-32 (measure) 📏

Setup (preceding non-measured steps): - moon-32-w (set_control) - moon-32-h (set_control)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 18,868-58,824	— / —	— / —
desktop-windows	— / 27,027	— / —	— / —
esp32	— / 645-655	— / 75KB	— / 34KB-38KB
esp32p4rev1-eth	— / 1,992	— / 33161KB	— / 344KB
esp32s31	— / 1,477	— / 16595KB	— / 164KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-22
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-07-25
• esp32s31: observed 2026-07-25

measure-moon-64 (measure) 📏

Setup (preceding non-measured steps): - moon-64-w (set_control) - moon-64-h (set_control)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 3,401-14,085	— / —	— / —
desktop-windows	— / 6,452	— / —	— / —
esp32	— / 148-160	— / 57KB-58KB	— / 34KB-38KB
esp32p4rev1-eth	— / 434	— / 33143KB	— / 344KB
esp32s31	— / 653	— / 16577KB	— / 164KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-22
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-07-25
• esp32s31: observed 2026-07-25

measure-moon-128 (measure) 📏

Setup (preceding non-measured steps): - moon-128-w (set_control) - moon-128-h (set_control)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 1,089-3,497	— / —	— / —
desktop-windows	— / 1,560	— / —	— / —
esp32	— / 180-859	— / 86KB-87KB	— / 38KB
esp32p4rev1-eth	— / 150	— / 33071KB	— / 344KB
esp32s31	— / 165	— / 16499KB	— / 164KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-23
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-07-25
• esp32s31: observed 2026-07-25

measure-parlio-16 (measure) 📏

Setup (preceding non-measured steps): - remove-moonI80 (remove_module) - add-parlio (add_module) — Parlio (P4 / S31): the Parallel-IO peripheral, 16 lanes. - parlio-16-w (set_control) - parlio-16-h (set_control)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 76,923-250,000	— / —	— / —
desktop-windows	— / 111,111	— / —	— / —
esp32	— / 2,342-2,817	— / 79KB-80KB	— / 34KB-38KB
esp32p4rev1-eth	— / 2,584	— / 33166KB	— / 344KB
esp32s31	— / 2,703	— / 16595KB	— / 164KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-22
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-07-25
• esp32s31: observed 2026-07-25

measure-parlio-32 (measure) 📏

Setup (preceding non-measured steps): - parlio-32-w (set_control) - parlio-32-h (set_control)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 19,231-55,556	— / —	— / —
desktop-windows	— / 27,027	— / —	— / —
esp32	— / 540-552	— / 73KB-76KB	— / 34KB-38KB
esp32p4rev1-eth	— / 1,961	— / 33161KB	— / 344KB
esp32s31	— / 1,745	— / 16595KB	— / 164KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-23
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-07-25
• esp32s31: observed 2026-07-25

measure-parlio-64 (measure) 📏

Setup (preceding non-measured steps): - parlio-64-w (set_control) - parlio-64-h (set_control)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 4,808-14,493	— / —	— / —
desktop-windows	— / 6,289	— / —	— / —
esp32	— / 167-171	— / 54KB-58KB	— / 22KB-38KB
esp32p4rev1-eth	— / 432	— / 33143KB	— / 344KB
esp32s31	— / 393	— / 16577KB	— / 164KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-23
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-07-25
• esp32s31: observed 2026-07-25

measure-parlio-128 (measure) 📏

Setup (preceding non-measured steps): - parlio-128-w (set_control) - parlio-128-h (set_control)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 1,144-3,559	— / —	— / —
desktop-windows	— / 1,560	— / —	— / —
esp32	— / 201-230	— / 77KB-89KB	— / 34KB-38KB
esp32p4rev1-eth	— / 216	— / 33071KB	— / 344KB
esp32s31	— / 81.5	— / 16504KB	— / 164KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-23
• esp32: observed 2026-09-01
• esp32p4rev1-eth: observed 2026-07-25
• esp32s31: observed 2026-07-25

Trailing setup (no measurement after)

• remove-parlio (remove_module)
• cleanup-fx (remove_module)
• cleanup-layer (remove_module)
• cleanup-grid (remove_module)

scenario_peripheral_switch

test/scenarios/light/scenario_peripheral_switch.json — Switch a live ParallelLedDriver between its DMA peripherals (i80 / MoonI80 / Parlio) and verify the device keeps running clean across every swap, and that the peripheral-dependent controls (doubleBuffer, pinExpander) behave per backend. Builds one Layout(Grid 16x16) + one Layer + one NoiseEffect + one ParallelLedDriver on lane-0 (64 LEDs), then set_control cycles peripheral and toggles doubleBuffer/pinExpander, measuring after each. The peripheral steps are optional so a board that lacks a given peripheral (a classic ESP32 offers only i80/I2S; a P4 adds Parlio; an S3 offers i80+MoonI80) skips them without failing. Guards the runtime-peripheral-strategy consolidation (ADR-0016): a swap that crashes, wedges, or leaves the driver in a bad state shows up here. Specifically pins the MoonI80 double-buffer fix: with doubleBuffer ON, MoonI80 must run single-buffer and NOT freeze (its own-GDMA whole-frame two-buffer handshake races); the measure after switching to MoonI80 with doubleBuffer ON is the regression guard (a freeze shows as a ~200 ms tick).

Mode: mutate · Also touches: MultiPinLedDriver, MoonLedDriver, ParlioLedDriver, Layouts, GridLayout, Effects, Layer, NoiseEffect, Drivers, PreviewDriver

measure-i80-single (measure) 📏

i80 single-buffer baseline. Only meaningful where the pins are valid (S3/desktop path); a classic/P4 records its own i80 backend.

Setup (preceding non-measured steps): - shrink-w (set_control) - shrink-h (set_control) - clear-layers (clear_children) — Start clean: drop whatever effects/modifiers the device had. - clear-drivers (clear_children) — Drop existing drivers (the pre-wired Preview survives on a device). - rebuild-layer (add_module) - rebuild-fx (add_module) - add-parallel-driver (add_module) — One ParallelLedDriver on lane 0, 64 LEDs (i80 rounds the bus up to 8 pins and parks the spare lanes; the 8-pin set is the S3's clean range). The peripheral is set per switch step below. - switch-i80 (set_control) — Select the i80 peripheral (esp_lcd: LCD_CAM on S3/P4/S31, I2S on classic).

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 62,500-250,000	— / —	— / —
desktop-windows	— / 111,111	— / —	— / —
esp32	— / 90.7-2,331	— / 75KB-118KB	— / 38KB-92KB
esp32p4rev1-eth	— / 4,808	— / 33166KB	— / 344KB
esp32s3-n16r8	— / 23,810	— / 8292KB	— / 80KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-22
• esp32: observed 2026-09-02
• esp32p4rev1-eth: observed 2026-07-24
• esp32s3-n16r8: observed 2026-07-24

measure-i80-double (measure) 📏

i80 with double-buffer: the encode overlaps the wire, so the tick should be at or below the single-buffer baseline. No freeze.

Setup (preceding non-measured steps): - i80-doublebuffer-on (set_control) — i80 supports the async double-buffer (esp_lcd has a real transaction queue) — turn it on.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 62,500-250,000	— / —	— / —
desktop-windows	— / 111,111	— / —	— / —
esp32	— / 90.4-2,288	— / 77KB-117KB	— / 38KB-92KB
esp32p4rev1-eth	— / 4,651	— / 33166KB	— / 344KB
esp32s3-n16r8	— / 21,739	— / 8216KB	— / 80KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-22
• esp32: observed 2026-09-02
• esp32p4rev1-eth: observed 2026-07-24
• esp32s3-n16r8: observed 2026-07-24

measure-moonI80-nofreeze (measure) 📏

MoonI80 whole-frame, doubleBuffer requested but forced single. A ~200 ms tick here is the double-buffer freeze regressing; a normal tick is the fix holding.

Setup (preceding non-measured steps): - switch-moonI80-dbstill-on (set_control) — Switch to MoonI80 with doubleBuffer STILL ON. This is the regression guard: MoonI80 must ignore the async request and run single-buffer (its whole-frame own-GDMA two-buffer handshake races and wedges). The measure below must be a normal tick, NOT ~200 ms.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 71,429-250,000	— / —	— / —
desktop-windows	— / 111,111	— / —	— / —
esp32	— / 90.5-2,353	— / 80KB-119KB	— / 38KB-92KB
esp32p4rev1-eth	— / 4,630	— / 33174KB	— / 352KB
esp32s3-n16r8	— / 23,810	— / 8299KB	— / 80KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-22
• esp32: observed 2026-09-02
• esp32p4rev1-eth: observed 2026-07-24
• esp32s3-n16r8: observed 2026-07-24

measure-moonI80-single (measure) 📏

Setup (preceding non-measured steps): - moonI80-doublebuffer-off (set_control) — Explicitly turn doubleBuffer off on MoonI80 (a no-op behaviorally — it was already forced single — but exercises the control write on the hidden control).

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 71,429-250,000	— / —	— / —
desktop-windows	— / 111,111	— / —	— / —
esp32	— / 90.3-2,342	— / 78KB-119KB	— / 38KB-92KB
esp32p4rev1-eth	— / 4,785	— / 33166KB	— / 344KB
esp32s3-n16r8	— / 22,727	— / 8292KB	— / 80KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-22
• esp32: observed 2026-09-02
• esp32p4rev1-eth: observed 2026-07-24
• esp32s3-n16r8: observed 2026-07-24

measure-moonI80-ring (measure) 📏

MoonI80 ring path live. A crash/wedge on the expander engage shows here.

Setup (preceding non-measured steps): - moonI80-expander-on (set_control) — Turn on the 74HCT595 pin expander: MoonI80 switches to the streaming RING path (wantsRing()). At 64 LOGICAL lights the ring still initializes; this exercises the ring engage on a live switch without needing a 48x256 rig.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 66,667-250,000	— / —	— / —
desktop-windows	— / 111,111	— / —	— / —
esp32	— / 90.1-2,299	— / 74KB-119KB	— / 38KB-92KB
esp32p4rev1-eth	— / 4,608	— / 33166KB	— / 344KB
esp32s3-n16r8	— / 22,727	— / 8290KB	— / 80KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-23
• esp32: observed 2026-09-02
• esp32p4rev1-eth: observed 2026-07-24
• esp32s3-n16r8: observed 2026-07-24

measure-back-i80 (measure) 📏

Setup (preceding non-measured steps): - moonI80-expander-off (set_control) - switch-parlio (set_control) — Select Parlio (P4 only). On a board that doesn't offer it (S3/classic) the Select value is out of range → the device returns 400 and this optional step is SKIPPED, leaving the peripheral where it was. No standalone measure follows it (that would record the wrong peripheral on a skip); the round-trip measure below covers the post-switch state. On a P4 the switch succeeds and the round-trip back to i80 exercises the Parlio→i80 swap. - switch-back-i80 (set_control) — Round-trip back to i80 — the driver must return to a clean, running state after the whole cycle.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	— / 62,500-250,000	— / —	— / —
desktop-windows	— / 111,111	— / —	— / —
esp32	— / 90.5-2,326	— / 76KB-119KB	— / 38KB-92KB
esp32p4rev1-eth	— / 4,854	— / 33174KB	— / 352KB
esp32s3-n16r8	— / 23,810	— / 8279KB	— / 80KB

• desktop-macos: observed 2026-09-06
• desktop-windows: observed 2026-08-22
• esp32: observed 2026-09-02
• esp32p4rev1-eth: observed 2026-07-24
• esp32s3-n16r8: observed 2026-07-24

Trailing setup (no measurement after)

• cleanup-driver (remove_module)
• cleanup-fx (remove_module)
• cleanup-layer (remove_module)

PolarLut

scenario_Fields_polar_lut

test/scenarios/light/scenario_Fields_polar_lut.json — The polar address table through a running pipeline: it is built for the grid a radial effect draws on, rebuilt when that grid resizes, dropped when the effect switches it off, and doubled when full precision is asked for. What the steps pin is that every one of those transitions happens live, under a rendering pipeline, without a reboot and without a stale table addressing pixels that no longer exist. The frame times are recorded per target and read as a TREND rather than as a pass mark: on a desktop the table and the computed address measure the same, because an out-of-order core with a large cache computes atan16 and dist16 about as fast as it loads two arrays. The 34% the table is worth was measured on an ESP32-S3, and it is an in-order-core property, so the contracts that matter here are the device ones. Aurora is measured last because it samples the field several times per pixel, which is what sets the fps a composition of this shape can promise.

Mode: mutate · Also touches: PolarNoiseEffect, AuroraEffect, GridLayout, Layer

add-polarnoise (add_module) 📏

A radial effect on the layer. It builds the table in prepare(), so the allocation happens here rather than on the first rendered frame.

Setup (preceding non-measured steps): - canvas-clear-layers (clear_children) — Self-canvas: clear and rebuild the pipeline this scenario assumes, so it runs from any device state. - canvas-clear-layouts (clear_children) - canvas-grid (add_module) — A 64x64 panel: large enough that the address table is real memory (8 KB narrow) and small enough to run on every target. - canvas-layer (add_module)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	≥ 250 / 2,604-3,448	unlimited / —	— / —

• desktop-macos: contract set 2026-09-04 "initial contract: PolarNoise at 64x64 through the address table" · observed 2026-09-06

table-off (set_control) 📏

Switch the table off under a running effect: the effect computes each pixel's angle and radius instead, which is the path a device short of memory takes. The picture is unchanged, which unit_PolarLut_equivalence pins bit-for-bit at full precision; what this step proves is that the switch takes effect live.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	≥ 167 / 3,125-3,509	unlimited / —	— / —

• desktop-macos: contract set 2026-09-04 "initial contract: the computed-address fallback, slower than the table above" · observed 2026-09-06

table-on (set_control) 📏

Back to the table, which prepare() rebuilds. Confirms the switch is live in both directions rather than one-way.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	≥ 250 / 3,155-3,521	unlimited / —	— / —

• desktop-macos: contract set 2026-09-04 "initial contract: back to the table cost" · observed 2026-09-06

table-wide (set_control) 📏

Full 16-bit precision: 4 bytes per pixel instead of 2, so the table doubles at this grid. Frame time barely moves on any target, which is what makes precision a memory decision rather than a speed one.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	≥ 238 / 2,950-3,521	unlimited / —	— / —

• desktop-macos: contract set 2026-09-04 "initial contract: the wide table, near the narrow one in time" · observed 2026-09-06

resize-down (set_control) 📏

Shrink the grid under a running effect. The table is rebuilt for the new geometry in prepare(), not carried over: a stale table would address pixels that no longer exist.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	≥ 417 / 6,452-7,092	unlimited / —	— / —

• desktop-macos: contract set 2026-09-04 "initial contract: half the pixels, half the table" · observed 2026-09-06

resize-up (set_control) 📏

Grow it again, the direction that has to allocate rather than free. On a device without PSRAM this is where prepare() weighs the table against free heap minus the reserve that protects stacks, WiFi and HTTP, and declines it rather than taking the last of the heap; the effect keeps rendering through the computed address.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	≥ 143 / 1,988-2,370	unlimited / —	— / —

• desktop-macos: contract set 2026-09-04 "initial contract: 64x96 with the wide table" · observed 2026-09-06

swap-to-aurora (add_module) 📏

Aurora alone on the layer: three layers of warped noise over the same address, each on its own oscillator. Several field samples per pixel, so this is the frame time that decides what the fps contract can promise.

Setup (preceding non-measured steps): - remove-polarnoise (remove_module) — Take PolarNoise off the layer before Aurora goes on it. Adding a second effect to a layer does not replace the first: both render, so the step below would have measured the pair and reported it as Aurora's cost.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	≥ 25.0 / 713-810	unlimited / —	— / —

• desktop-macos: contract set 2026-09-04 "initial contract: Aurora at 64x96, 3 layers, 2 octaves" · observed 2026-09-06

aurora-one-layer (set_control) 📏

Drop to a single layer, the cost knob at its cheapest. The ratio against the step above is what an effect author reads to choose a layer count for their fixture.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	≥ 62.5 / 1,695-2,083	unlimited / —	— / —

• desktop-macos: contract set 2026-09-04 "initial contract: roughly a third of the three-layer cost" · observed 2026-09-06

TrailsEffect

scenario_Trails_ladder

test/scenarios/light/scenario_Trails_ladder.json — What a flow costs as a fixture grows, and what it costs to become a volume. Trails runs three passes over its own plane every frame (advect it along the flow, decay it by a half-life, write the emitters), so its cost is per light and the ladder is what proves that: 16x16, 32x32, 64x64 and then a 20x20x20 cube, which has roughly twice the lights of the 64x64 panel and must cost roughly twice as much rather than something worse. The last two steps hold the geometry still and move the controls instead, because a control that changes the cost would be the thing an author has to know about: persistence must not (the decay is a multiply per sample whatever the half-life) and dots must barely (an emitter is one write). The plane is 16-bit and there are two of them, so the memory each step reports is 6 bytes per light, which is the honest price of a tail that fades smoothly.

Mode: mutate · Also touches: draw, OscillatorBank, GridLayout, Layer

trails-16 (add_module) 📏

Trails as it ships, on 16x16. The tick is one advect plus one decay over the whole plane, plus a noise sample per light for the flow, so the per-light cost here is what every step below multiplies.

Setup (preceding non-measured steps): - canvas-clear-layers (clear_children) — Self-canvas: clear and rebuild the pipeline this scenario assumes, so it runs from any device state. - canvas-clear-layouts (clear_children) - canvas-grid (add_module) — A 16x16 panel to start the ladder: the smallest size a trail reads on, and the one every larger step is compared against per light. - canvas-layer (add_module)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	≥ 25,000 / 76,923-90,909	unlimited / —	— / —

• desktop-macos: contract set 2026-09-04 "measured 2026-09-04, budget ~3x p50: Trails at 16x16, 3 dots, curl off" · observed 2026-09-06

grid-32-h (set_control) 📏

Setup (preceding non-measured steps): - grid-32 (set_control) — Four times the lights. Transport and decay are both per light, so this step and the next are what show the cost is linear rather than hiding a per-frame constant.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	≥ 5,556 / 17,544-22,222	unlimited / —	— / —

• desktop-macos: contract set 2026-09-04 "measured 2026-09-04, budget ~3x p50: 32x32, four times 16x16" · observed 2026-09-06

grid-64-h (set_control) 📏

64x64: the size a panel user actually runs, and the one the catalog card's fps claim is read from.

Setup (preceding non-measured steps): - grid-64 (set_control)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	≥ 1,538 / 4,808-5,556	unlimited / —	— / —

• desktop-macos: contract set 2026-09-04 "measured 2026-09-04, budget ~3x p50: 64x64, the panel size the card quotes" · observed 2026-09-06

cube-20-d (set_control) 📏

Setup (preceding non-measured steps): - cube-20 (set_control) — The volumetric case, and the bench fixture: a 20x20x20 cube is 8000 lights against the panel's 4096, and every slice is carried by the same flow. What this pins is that 3D is the same cost per light, not a different algorithm. - cube-20-h (set_control)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	≥ 1,000 / 2,525-2,865	unlimited / —	— / —

• desktop-macos: contract set 2026-09-04 "measured 2026-09-04, budget ~3x p50: the 20-cube, 8000 lights" · observed 2026-09-06

long-tail (set_control) 📏

Persistence at its top. The decay is a multiply per sample whatever the half-life is, so a long tail must cost the same as a short one: a step that moved here would mean the decay had become conditional on its own result.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	≥ 1,000 / 1,645-2,817	unlimited / —	— / —

• desktop-macos: contract set 2026-09-04 "measured 2026-09-04, budget ~3x p50: a long tail costs what a short one costs" · observed 2026-09-06

more-dots (set_control) 📏

Eight emitters rather than three. A dot is one write, so this is the cheapest control on the effect and the step proves it: the emitters are not what a large fixture pays for.

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	≥ 1,000 / 2,217-2,849	unlimited / —	— / —

• desktop-macos: contract set 2026-09-04 "measured 2026-09-04, budget ~3x p50: emitters are nearly free next to the per-light passes" · observed 2026-09-06

back-to-panel-h (set_control) 📏

Setup (preceding non-measured steps): - back-to-panel (set_control) — Back to a flat 64x64, which frees the cube's planes. Returning near the earlier 64x64 number is what shows the effect carries no state that accumulates across a resize: the planes are rebuilt for the new geometry rather than reused. - back-to-panel-w (set_control)

Performance (contract / observed) — tick stored, FPS shown:

Board	FPS	heap	block
desktop-macos	≥ 1,923 / 4,000-5,556	unlimited / —	— / —

• desktop-macos: contract set 2026-09-04 "measured 2026-09-04, budget ~3x p50: back to the 64x64 number above" · observed 2026-09-06