Signed values in MoonLive, and the Mandelbrot it could not write

.github/workflows/release.yml

@@ -234,12 +234,40 @@ jobs:
       - uses: actions/checkout@v4
         with:
           persist-credentials: false
+          # Full history: compute_version.py counts commits since the last v* tag.
+          fetch-depth: 0
       # CMakeLists.txt calls find_program(UV_EXECUTABLE … REQUIRED) so the
       # build-host Python (gzip / build_info.h) is reached through uv. The
       # runners don't ship uv by default — install it before package_desktop.
       - uses: astral-sh/setup-uv@v3
+      # Same tag + version resolution as build-esp32 (see the comments there): the computed
+      # semver must reach the DESKTOP binary too, or a desktop build reports library.json's bare
+      # core and the update badge can never see a `latest` (-dev.N) build as newer. shell: bash
+      # keeps the three jobs' copies of this block identical; without it the Windows copy would
+      # run under PowerShell and fail on the bash syntax.
+      - name: Resolve release tag
+        id: tag
+        shell: bash
+        env:
+          INPUT_TAG: ${{ inputs.tag }}
+          REF_NAME: ${{ github.ref_name }}
+          IS_MAIN: ${{ github.ref == 'refs/heads/main' }}
+        run: |
+          set -euo pipefail
+          if [ -n "$INPUT_TAG" ]; then echo "tag=$INPUT_TAG" >> "$GITHUB_OUTPUT"
+          elif [ "$IS_MAIN" = "true" ]; then echo "tag=latest" >> "$GITHUB_OUTPUT"
+          else echo "tag=$REF_NAME" >> "$GITHUB_OUTPUT"; fi
+      - name: Compute version
+        id: ver
+        shell: bash
+        env:
+          TAG: ${{ steps.tag.outputs.tag }}
+        run: |
+          set -euo pipefail
+          V=$(uv run python moondeck/build/compute_version.py --tag "$TAG")
+          echo "version=$V" >> "$GITHUB_OUTPUT"
       - name: Build + package macOS arm64
-        run: uv run moondeck/ci/package_desktop.py
+        run: uv run moondeck/ci/package_desktop.py --version "${{ steps.ver.outputs.version }}"
       - uses: actions/upload-artifact@v4
         with:
           name: desktop-macos
@@ -252,10 +280,37 @@ jobs:
       - uses: actions/checkout@v4
         with:
           persist-credentials: false
+          fetch-depth: 0
       # Same uv prerequisite as build-macos, see the comment there.
       - uses: astral-sh/setup-uv@v3
+      # Same tag + version resolution as build-esp32 (see the comments there): the computed
+      # semver must reach the DESKTOP binary too, or a desktop build reports library.json's bare
+      # core and the update badge can never see a `latest` (-dev.N) build as newer. shell: bash
+      # keeps the three jobs' copies of this block identical; without it the Windows copy would
+      # run under PowerShell and fail on the bash syntax.
+      - name: Resolve release tag
+        id: tag
+        shell: bash
+        env:
+          INPUT_TAG: ${{ inputs.tag }}
+          REF_NAME: ${{ github.ref_name }}
+          IS_MAIN: ${{ github.ref == 'refs/heads/main' }}
+        run: |
+          set -euo pipefail
+          if [ -n "$INPUT_TAG" ]; then echo "tag=$INPUT_TAG" >> "$GITHUB_OUTPUT"
+          elif [ "$IS_MAIN" = "true" ]; then echo "tag=latest" >> "$GITHUB_OUTPUT"
+          else echo "tag=$REF_NAME" >> "$GITHUB_OUTPUT"; fi
+      - name: Compute version
+        id: ver
+        shell: bash
+        env:
+          TAG: ${{ steps.tag.outputs.tag }}
+        run: |
+          set -euo pipefail
+          V=$(uv run python moondeck/build/compute_version.py --tag "$TAG")
+          echo "version=$V" >> "$GITHUB_OUTPUT"
       - name: Build + package Windows x64
-        run: uv run moondeck/ci/package_desktop.py
+        run: uv run moondeck/ci/package_desktop.py --version "${{ steps.ver.outputs.version }}"
       - uses: actions/upload-artifact@v4
         with:
           name: desktop-windows
@@ -268,14 +323,41 @@ jobs:
       - uses: actions/checkout@v4
         with:
           persist-credentials: false
+          fetch-depth: 0
       # Same uv prerequisite as build-macos, see the comment there.
       - uses: astral-sh/setup-uv@v3
       # Builds with the runner's default GCC (13 on ubuntu-24.04). Its four false-positive
       # warnings are handled in CMakeLists.txt, which demotes them to non-fatal on GCC below
       # 16 rather than pinning a compiler here: a from-source build on Debian or Raspberry Pi
       # OS meets the same GCC and deserves the same fix.
+      # Same tag + version resolution as build-esp32 (see the comments there): the computed
+      # semver must reach the DESKTOP binary too, or a desktop build reports library.json's bare
+      # core and the update badge can never see a `latest` (-dev.N) build as newer. shell: bash
+      # keeps the three jobs' copies of this block identical; without it the Windows copy would
+      # run under PowerShell and fail on the bash syntax.
+      - name: Resolve release tag
+        id: tag
+        shell: bash
+        env:
+          INPUT_TAG: ${{ inputs.tag }}
+          REF_NAME: ${{ github.ref_name }}
+          IS_MAIN: ${{ github.ref == 'refs/heads/main' }}
+        run: |
+          set -euo pipefail
+          if [ -n "$INPUT_TAG" ]; then echo "tag=$INPUT_TAG" >> "$GITHUB_OUTPUT"
+          elif [ "$IS_MAIN" = "true" ]; then echo "tag=latest" >> "$GITHUB_OUTPUT"
+          else echo "tag=$REF_NAME" >> "$GITHUB_OUTPUT"; fi
+      - name: Compute version
+        id: ver
+        shell: bash
+        env:
+          TAG: ${{ steps.tag.outputs.tag }}
+        run: |
+          set -euo pipefail
+          V=$(uv run python moondeck/build/compute_version.py --tag "$TAG")
+          echo "version=$V" >> "$GITHUB_OUTPUT"
       - name: Build + package Linux x64
-        run: uv run moondeck/ci/package_desktop.py
+        run: uv run moondeck/ci/package_desktop.py --version "${{ steps.ver.outputs.version }}"
       - uses: actions/upload-artifact@v4
         with:
           name: desktop-linux

CMakeLists.txt

@@ -137,6 +137,16 @@ target_include_directories(mm_core PUBLIC src/)
 target_link_libraries(mm_core PUBLIC mm_platform)
 # `add_dependencies(mm_core ui_embed)` is below, after the ui_embed target is defined.
 
+# The computed semver (compute_version.py): the core for a stable tag, <core>-dev.<N> for a
+# moving latest build. Only the release pipeline sets it (package_desktop.py --version); a local
+# build falls through to build_info.h's #ifndef default (library.json). The same override the
+# ESP32 build has (esp32/main/CMakeLists.txt), so a desktop binary reports the same precise
+# version its release assets are named with, which is what lets the UI's update badge compare
+# a running desktop against the `latest` channel at all.
+if(MM_VERSION)
+    add_compile_definitions(MM_VERSION=${MM_VERSION})
+endif()
+
 # Platform library (desktop). moonlive_emit.cpp is the desktop MoonLive backend (host-ISA
 # codegen) — it lives here because emitted machine code is platform/ISA-specific.
 add_library(mm_platform

README.md

@@ -98,7 +98,7 @@ The numbers above are observations. The **contracts** projectMM commits to, what
 
 **Desktop: download and run.** Grab the build for your OS from the [releases page](https://github.com/MoonModules/projectMM/releases):
 
-- **macOS arm64:** `projectMM-macos-arm64-vX.Y.Z.dmg`: open it and drag projectMM to Applications, then launch it like any app. A Terminal window opens showing what it is doing, your browser opens the UI, and closing that window stops it. (`projectMM-macos-arm64-vX.Y.Z.tar.gz` is the same binary without the wrapper, for scripting.) x86-64 macOS is supported and tested, but only the arm64 build is packaged: build from source for an Intel Mac. The binary is ad-hoc signed rather than notarized, so Gatekeeper says it cannot verify the developer; right-click → Open and confirm, or clear the flag with `xattr -dr com.apple.quarantine ./projectMM`.
+- **macOS arm64:** `projectMM-macos-arm64-vX.Y.Z.dmg`: open it and drag projectMM to Applications, then launch it like any app. A Terminal window opens showing what it is doing, your browser opens the UI, and closing that window stops it. (`projectMM-macos-arm64-vX.Y.Z.tar.gz` is the same binary without the wrapper, for scripting.) x86-64 macOS is supported and tested, but only the arm64 build is packaged: build from source for an Intel Mac. The app is ad-hoc signed rather than notarized, so the first launch is refused with "Apple could not verify projectMM is free of malware". On macOS 15 and later that dialog offers no way through, so clear the download flag once in Terminal and open it again: `xattr -dr com.apple.quarantine /Applications/projectMM.app` (or `./projectMM` for the tarball).
 - **Windows x64:** `projectMM-windows-x64-vX.Y.Z.zip`: unzip, double-click `projectMM.exe`. SmartScreen may warn on first run because the binary is unsigned (More info → Run anyway).
 - **Linux x64:** `projectMM-linux-x64-vX.Y.Z.tar.gz`, or `projectmm_X.Y.Z_amd64.deb` on Debian, Ubuntu and Raspberry Pi OS (`sudo apt install ./projectmm_X.Y.Z_amd64.deb` puts it on your PATH).
 

docs/backlog/backlog-core.md

@@ -16,7 +16,6 @@ Forward-looking to-build items for the **core / infrastructure** domain (`src/co
 - **macOS code-signing (Developer ID)** — the release `.dmg` is now ad-hoc signed, which turns Gatekeeper's outright refusal into the "unidentified developer" prompt a user can accept via right-click Open. A paid Developer ID certificate plus notarization would drop that prompt too.
 - **Windows code-signing** — drops the SmartScreen warning on first run of `projectMM.exe`. Same shape as macOS signing; needs an EV / OV code-signing certificate (Microsoft Trusted Signing is the cheapest current option). Until then, the README notes the SmartScreen prompt.
 - **Live RMII Ethernet reconfigure** — runtime PHY/pin config shipped (`ethType` + pin controls in NetworkModule, per-board defaults in `deviceModels.json`, `platform::setEthConfig`/`ethInit` dispatch). W5500 (SPI) on S3 applies **live** — `ethStop()` tears down the SPI bus and `ethInit()` re-runs on the next `loop1s()` with no reboot. RMII (classic/P4 internal EMAC) still saves config and asks for a restart to apply, because the EMAC bring-up is fiddlier to hot-cycle cleanly. Make RMII live too: a hot `esp_eth_stop` + EMAC/netif teardown + re-init on config change, matching the W5500 path, so every interface honours the no-reboot principle.
-- **Desktop builds report a bare version, so the dev-channel badge cannot fire** — `package_desktop.py` never passes `-DMM_VERSION`, so a desktop binary reports `library.json`'s `3.0.0` while the `latest` release is named `3.0.0-dev.N`. Semver ranks a prerelease *below* its release, so `isNewer("3.0.0-dev.N", "3.0.0")` is false and the desktop dev badge never lights; the `onPrerelease` gate is false for a bare `3.0.0` for the same reason. The stable badge works, so a desktop user is told about real releases and only misses `latest` builds. Fix at the root by stamping the computed `-dev.N` version into the desktop build the way the ESP32 job does, not by special-casing the comparison.
 - **GCC below 16 needs four warnings demoted, and nothing exercises those versions** - `-Wnull-dereference`, `-Wrestrict`, `-Wstringop-overflow` and `-Wformat-truncation` fire on provably correct code from GCC 12 through 15 (five of the twelve inside libstdc++ and glibc headers, unreachable from our source), so CMakeLists demotes them to non-fatal there and keeps them fatal on 16+. That unblocks CI and from-source builds on Debian and Raspberry Pi OS alike, but it is a suppression, not an understanding: nobody routinely compiles with 12-15, so a REAL instance of one of these on those versions is now a warning nobody reads. Revisit when the runner's default GCC reaches 16, at which point the whole block can be deleted.
 - **Installer UX polish** — clear "Pre-release (beta)" warning on RC/latest picks, yank-by-asset-tag instead of yank-by-release-deletion.
 - **Offer projectMM/MoonLight as a library** — a downstream sketch where another firmware/app consumes the light pipeline (or a subset) as an embeddable dependency rather than running the whole binary. `library.json` is already a PlatformIO *library* manifest, so the seed exists. When this is designed, give it a small public **identity surface**: one runtime constant the consumer reads (a `kProjectName`, likely a `ProjectInfo` bundle of name + version + url) that the network wire-strings (ArtNet/E1.31 source-name + CID), the UI banner, and any "About" string all *derive from* — the one place a consumer queries "what am I embedding." This is the genuine home for the name-centralisation that the rename ([rename-to-moonlight.md § Phase 1.3](rename-to-moonlight.md)) deliberately *didn't* do: the rename is a one-time sweep (a constant would just split it), but a library consumer references the identity ongoing and widely, which is the test a constant must pass. Build it *then*, against the real library API, not speculatively now.

docs/backlog/moonlive-language-roadmap.md

@@ -35,7 +35,7 @@ Five hard limits, all found by hitting them:
 | script state | **64 bytes** shared by all members | `kCtrlBytes`, `MoonLiveBuiltins.h:132` |
 | distinct members | **8** | `kMaxCtrls`, same file |
 | branch labels | **16** (an `if` or `for` takes up to 2) | `kIrLabels`, `MoonLiveIr.h:201` |
-| numeric types | `uint8_t`, `uint16_t` | no float, no signed |
+| numeric types | `uint8_t`, `uint16_t`, `int16_t` | no float |
 | ~~builtin table~~ | ~~16, and 16 used~~ → **64** ✅ | `BuiltinTable::kMax` — raised, with an overflow assert |
 
 The branch budget was binary-searched with generated scripts: **6 `if`/`else` + 2 `for` compiles,
@@ -50,7 +50,6 @@ Each row is a compromise the balls effect makes, and the language feature that w
 |---|---|---|
 | 4 objects, not 25 | 64-byte arena, 8 members | a bigger arena, or a pool handle (shipped for particles) |
 | whole-pixel motion | no fractional type | fixed-point or float |
-| a direction bit per axis | unsigned only | signed values |
 | one flat colour | no `hsv()` builtin | `hsv()` |
 | one array per field | no structs | structs |
 | the helper reads a member for its index | functions take no arguments | arguments |
@@ -129,6 +128,15 @@ Doing #1 and #2 together is what actually opens the library; either alone leaves
 
 64 bytes across 8 members is why an effect holds four objects rather than twenty-five.
 
+**The two limits bind at very different points, and it is the COUNT that bites first.**
+`fractal.mle` wanted 4 controls plus 4 scratch members plus a loop counter: 9 members costing
+**12 of the 64 arena bytes**. It compiled once the counter was dropped (a `for` counter does not
+have to be a member), so the script lost nothing, but the ceiling it hit was `kMaxCtrls` with 81%
+of the arena still free. Any script with a handful of controls and a handful of intermediates
+meets the same wall. If only one of the two moves, the count is the one worth moving: the four
+tables it sizes are `DeclaredControl[8]` at 24 B each, so 8 -> 12 costs 96 B per engine and
+roughly 600 B per device across three engines, against `sizeof(MoonLive)` at 864 B today.
+
 **But check the handle route first.** The power-functions spec's item 5 — a particle pool as an
 arena-allocated HANDLE — means a simulation effect stops storing its own particle state entirely,
 which removes the pressure without touching these constants. Widen the arena for the scripts that
@@ -279,12 +287,35 @@ does not foreclose float.
 caller and callee agree by convention and nothing checks it, so a helper called from two places
 with different state silently does the wrong thing. It is also what makes helpers composable.
 
-### 7. Signed values — *moderate, and it removes a whole class of workaround*
-
-Unsigned-only forces a sign bit alongside every value that can go negative — a velocity, a delta,
-an offset from a centre. It also makes ordinary expressions dangerous: `a - b` wraps instead of
-going negative, so scripts guard every subtraction. Comes naturally with fixed-point (#3) if that
-type is signed, which argues for doing them together.
+### 7. Signed values: ✅ *shipped*
+
+`int16_t` members, signed comparison, signed `/` and `%`, and `uvX`/`uvY` returning a signed
+coordinate with no bias to subtract.
+
+**The framing this item had was wrong about the cause, which is worth recording.** It described the
+problem as `a - b` wrapping, and prescribed signed comparison. Writing a Mandelbrot effect produced
+four bugs in one session and **not one of them was a comparison bug**: no `<` or `>` ever produced a
+wrong picture. Three were the *biased-unsigned* convention, where a builtin returned a value centered
+on 32768 and the author had to subtract that bias, which is exactly the subtraction unsigned
+arithmetic breaks. The fourth was a byte argument truncating instead of saturating. Every one
+presented as "the effect renders nothing", never as an error.
+
+So what shipped is smaller than "make the language signed" and removes more than it adds:
+
+- `signedArg`'s undocumented **16-bit window** is gone. It was the inverse of `uint16_t` member
+  truncation, written down in neither place, and it is what made `d = 60000` read as -5536.
+- The **bias on `uvX`/`uvY`** is gone: a coordinate has an origin, so the center is 0.
+- `sin`/`cos` **keep** their bias, deliberately. A wave has no origin, and `scale(sin(a), n)`
+  sweeping a full axis is the idiom 14 shipped call sites use. A script wanting a signed wave
+  writes `sin(a) - 32768`, which works now.
+- **Comparison** is a separate `BranchGeS` op, not a change to `BranchGe`: the array-index clamp
+  and the loop guards need unsigned, and a negative index arriving as a huge value is what lets one
+  branch catch both ends of a range.
+- **`int8_t` is deliberately absent.** Xtensa has no signed byte load, so it would need a
+  sign-extend sequence the other three ISAs do not, for a width no script has asked for.
+
+`escape()` stays a builtin regardless: its Q13 squaring needs 64-bit intermediates, which a 32-bit
+script value cannot express however signed it is.
 
 ### 8. More branch labels — *probably a constant, worth measuring first*
 

docs/metrics/repo-health.json

@@ -1,78 +1,78 @@
 {
-  "commit": "9eea71d6",
+  "commit": "ab508402",
   "flash": {
     "esp32": 1764416,
     "esp32p4rev1-eth": 1653696,
     "esp32p4rev1-eth-wifi": 1933472,
-    "esp32s3-n16r8": 1801632,
+    "esp32s3-n16r8": 1813456,
     "esp32s3-n8r8": 1753232,
     "esp32s31": 2079904,
     "esp32-16mb": 1714608,
     "esp32-eth": 1324816,
     "esp32-wrover": 1765504,
     "qemu": 1318160,
     "esp32p4rev3-eth": 1643760,
-    "desktop": 1105920
+    "desktop": 1230168
   },
   "perf": {
     "desktop": {
-      "tick_us": 437,
-      "fps": 2288
+      "tick_us": 182,
+      "fps": 5494
     },
     "esp32": {
       "tick_us": 2151,
       "fps": 464
     }
   },
   "loc": {
-    "core": 19591,
-    "light": 25712,
-    "platform": 14786,
-    "ui": 6859,
-    "test": 45620,
-    "moondeck": 21359
+    "core": 19684,
+    "light": 25824,
+    "platform": 14891,
+    "ui": 7028,
+    "test": 45902,
+    "moondeck": 21626
   },
   "comments": {
     "core": {
-      "lines": 7689,
-      "ratio": 0.425
+      "lines": 7746,
+      "ratio": 0.426
     },
     "light": {
-      "lines": 10161,
-      "ratio": 0.436
+      "lines": 10237,
+      "ratio": 0.438
     },
     "platform": {
-      "lines": 5263,
+      "lines": 5303,
       "ratio": 0.391
     },
     "ui": {
-      "lines": 1803,
-      "ratio": 0.279
+      "lines": 1861,
+      "ratio": 0.281
     },
     "test": {
-      "lines": 8355,
-      "ratio": 0.21
+      "lines": 8438,
+      "ratio": 0.211
     },
     "moondeck": {
-      "lines": 3479,
-      "ratio": 0.186
+      "lines": 3504,
+      "ratio": 0.185
     }
   },
   "tests": {
-    "cases": 1489,
+    "cases": 1511,
     "scenarios": 23
   },
   "docs": {
     "md_files": 189,
-    "md_lines": 27471,
+    "md_lines": 27631,
     "plans_files": 96,
-    "backlog_lines": 4310,
+    "backlog_lines": 4341,
     "lessons_lines": 576,
     "claude_md_lines": 136
   },
   "complexity": {
-    "functions": 2690,
-    "over_threshold": 164,
+    "functions": 2716,
+    "over_threshold": 165,
     "worst_ccn": 108
   }
 }