Semver firmware versioning + update-available badge (stable + dev channels)

[ewowi]

Summary

Makes the firmware version industry-standard semver, gives every build a precise identity, and surfaces available updates in the UI — for both stable releases and the moving latest channel. Also slims the web installer page.

1. Semver-clean version. The Firmware card's version was 2.0.0 (v2.0.0) — a semver concatenated with a redundant, non-semver channel tag. It's now pure semver: 2.0.0 on a stable release; the channel is derivable from the prerelease suffix, no longer mixed in. library.json moves to 2.1.0-dev (develop-on-a-prerelease), and verify_version.py accepts the release ritual (a vX.Y.Z tag releases what was X.Y.Z-dev).

2. Per-build latest version. A moving latest build had no distinct identity — every one reported the same version, and its manifest/assets were stamped with the old stable version. Now each latest build carries a monotonic 2.1.0-dev.<N> (N = commits since the last v* tag, via compute_version.py), threaded consistently through the binary (MM_VERSION), asset names, and manifest. semver.org §11 orders these numerically.

3. Update-available badge (two channels). A status-bar badge, modelled on ESP32-sveltekit's UpdateIndicator (our own code, no npm dep):

• Stable: every device compares against the newest stable GitHub release (releases/latest, prereleases excluded).
• Dev: a device already on a -dev build also checks the moving latest release's manifest version, so a stale latest build is nudged to the newest latest.
  Cached in localStorage (1 h TTL) so it doesn't slow page load, forced fresh when the Firmware card opens, in-flight de-duplicated. Click pre-selects the release in the install picker and opens the Firmware card — one click from installing. Best-effort: any failure hides the badge.

4. Installer CSS/JS extraction. docs/install/index.html (2080 → 402 lines): inline <style> → install.css, inline module <script> → install.js (consistent with the sibling modules it already imports).

A new dependency-free src/ui/semver.js (parse + §11-correct compare + isNewer) is the one home for version comparison.

Testing

• Pre-commit gates pass on both commits: spec, desktop build (-Werror), ctest, scenarios, platform boundary, ESP32 build, KPI, firmware-list, host JS (15) + Python (15).
• Bench-verified on ESP32-S3: version reports clean semver and injected 2.1.0-dev.<N> (proves the -DMM_VERSION CMake wiring); stable badge appears + opens Firmware pre-selected; /semver.js served from the device.
• Installer extraction verified live via preview_installer (index.html + install.css + install.js + imported modules all serve 200).

Release note

The next stable release must bump library.json 2.1.0-dev → 2.1.0 before tagging (drop the -dev suffix). The dev-channel badge becomes fully testable once a latest build republishes with the new 2.1.0-dev.<N> manifest (today's latest still carries the pre-change 2.0.0).

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added a firmware update badge in the app status bar that can surface available updates and jump directly to the Firmware screen.
  • Added a standalone web installer experience with refreshed styling and improved board selection, progress, and install flow.

• Bug Fixes

  • Firmware versions are now shown as clean semantic versions, improving update checks and release matching.
  • Release assets and manifests now use consistent versioned names for better update discovery.

[coderabbitai]

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: f67e2e1d-2f73-4271-9002-415d882bc5f2

📥 Commits

Reviewing files that changed from the base of the PR and between 12e2ddc and 6e61885.

⛔ Files ignored due to path filters (1)

• scripts/build/compute_version.py is excluded by !**/build/**

📒 Files selected for processing (29)

• .github/workflows/release.yml
• docs/architecture.md
• docs/backlog/README.md
• docs/backlog/backlog-core.md
• docs/backlog/livescripts-analysis-top-down.md
• docs/history/plans/Plan-20260625 - Multi-layer composition.md
• docs/moonmodules/light/BlendMap.md
• docs/moonmodules/light/Drivers.md
• docs/moonmodules/light/Layer.md
• docs/moonmodules/light/Layers.md
• docs/tests/scenario-tests.md
• docs/tests/unit-tests.md
• src/light/drivers/Drivers.h
• src/light/layers/BlendMap.h
• src/light/layers/Layer.h
• src/light/layers/Layers.h
• src/ui/app.js
• test/python/test_compute_version.py
• test/scenarios/core/scenario_MoonModule_control_change.json
• test/scenarios/light/scenario_Audio_mutation.json
• test/scenarios/light/scenario_Driver_mutation.json
• test/scenarios/light/scenario_Layers_composition.json
• test/scenarios/light/scenario_Layouts_mutation.json
• test/scenarios/light/scenario_MultiplyModifier_pipeline.json
• test/scenarios/light/scenario_modifier_swap.json
• test/scenarios/light/scenario_perf_full.json
• test/scenarios/light/scenario_perf_light.json
• test/unit/light/unit_BlendMap.cpp
• test/unit/light/unit_Layers_container.cpp

 ___________________________________________________
< This is not a microservice. This is a macro-mess. >
 ---------------------------------------------------
  \
   \   (\__/)
       (•ㅅ•)
       / 　 づ

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch next-iteration

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/history/plans/Plan-20260624` - Semver version + update-available
badge.md:
- Around line 1-56: This plan note should not live under docs/history because
that area is meant for backward-looking, pruned history only. Move the content
to the appropriate active planning/docs location outside docs/history, and leave
docs/history for archived lessons only; update any references in the plan
document if needed so the new location is easy to find.

In `@src/ui/app.js`:
- Around line 2167-2170: The firmware update check is spawning duplicate
concurrent GitHub requests because updateStatusBar() repeatedly calls
checkFirmwareUpdate(false) before the cache is refreshed. Add in-flight
de-duplication inside checkFirmwareUpdate() and/or getLatestStableRelease() so
that when a fetch is already pending, subsequent callers reuse the same promise
instead of starting another releases/latest request. Make sure the shared
promise is cleared after it settles, and keep the cache-first behavior intact
for the updateStatusBar() refresh path.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: f3bf160c-9161-4a26-adcb-7553626cf46c

📥 Commits

Reviewing files that changed from the base of the PR and between 42f5ec1 and 84343f8.

⛔ Files ignored due to path filters (1)

• scripts/build/verify_version.py is excluded by !**/build/**

📒 Files selected for processing (13)

• .github/workflows/release.yml
• docs/history/plans/Plan-20260624 - Semver version + update-available badge.md
• docs/moonmodules/core/FirmwareUpdateModule.md
• library.json
• src/core/FirmwareUpdateModule.h
• src/core/HttpServerModule.cpp
• src/ui/app.js
• src/ui/embed_ui.cmake
• src/ui/index.html
• src/ui/semver.js
• src/ui/style.css
• test/js/semver.test.mjs
• test/python/test_verify_version.py

[coderabbitai]

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Move this plan out of docs/history.

This is active planning, but docs/history/**/*.md is meant to stay backward-looking and be pruned once the lesson is absorbed. Keeping PR plans here will make history notes grow indefinitely.

As per path instructions, docs/history/**/*.md: Keep history pages backward-looking and prune them when lessons have been absorbed; the permanent record is in git commits, not in indefinitely growing history notes.

🧰 Tools

🪛 LanguageTool

[style] ~6-~6: ‘On top of that’ might be wordy. Consider a shorter alternative.
Context: ...has a prerelease suffix → not stable." On top of that clean version, add a status-bar **"firm...

(EN_WORDINESS_PREMIUM_ON_TOP_OF_THAT)

---

[uncategorized] ~24-~24: Do not mix variants of the same word (‘pre-release’ and ‘prerelease’) within a single text.
Context: ...-dev/prerelease suffix marks a moving/pre-release build." ### 2. Reusable semver module ...

(EN_WORD_COHERENCY)

🪛 markdownlint-cli2 (0.22.1)

[warning] 9-9: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

---

[warning] 12-12: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

---

[warning] 20-20: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

---

[warning] 26-26: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

---

[warning] 30-30: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

---

[warning] 40-40: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

---

[warning] 45-45: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

---

[warning] 49-49: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

---

[warning] 52-52: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/history/plans/Plan-20260624` - Semver version + update-available
badge.md around lines 1 - 56, This plan note should not live under docs/history
because that area is meant for backward-looking, pruned history only. Move the
content to the appropriate active planning/docs location outside docs/history,
and leave docs/history for archived lessons only; update any references in the
plan document if needed so the new location is easy to find.

Source: Path instructions

[coderabbitai]

Actionable comments posted: 9

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/history/plans/Plan-20260624 - Dev-channel update badge.md (1)

1-49: 📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

Move this active plan out of docs/history/.

This page is a forward-looking implementation plan, but docs/history/** is reserved for backward-looking notes that get pruned once the lessons are absorbed. Keeping live planning docs here pushes the history tree against the documented convention.

As per coding guidelines, "Keep history pages backward-looking and prune them when lessons have been absorbed; the permanent record is in git commits, not in indefinitely growing history notes."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/history/plans/Plan-20260624` - Dev-channel update badge.md around lines
1 - 49, The plan document is forward-looking but lives under the history docs,
which should only contain backward-looking notes. Move this plan out of
docs/history/ and into the appropriate active planning/docs location, preserving
the content and using the same document title if needed; update any references
so the active plan is discoverable, and keep docs/history reserved for prunable
retrospective notes.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/release.yml:
- Around line 150-152: The release workflow currently maps every non-latest tag
to stable, so RC tags like v2.1.0-rc1 get the plain core version instead of an
RC-aware version. Update the version computation logic in the release job’s
compute-version step to branch explicitly for prerelease/RC tags the same way as
the other version step, and ensure it passes the correct channel into
scripts/build/compute_version.py or the uv run equivalent. Also add a test
alongside test/python/test_compute_version.py that asserts RC tags produce a
prerelease version rather than collapsing to stable X.Y.Z.

In `@docs/install/install.css`:
- Line 233: Replace the deprecated long-token wrapping rule in the stylesheet by
updating the .bd-val declaration to use overflow-wrap: anywhere instead of
word-break: break-word, and apply the same change in the other matching .bd-val
rule referenced by the review; keep the existing flex/min-width behavior intact
while adjusting the wrapping property.

In `@docs/install/install.js`:
- Around line 510-518: The success modal in install.js assigns clickable URLs in
the done-url and done-url-mdns elements before validating them, so a non-http(s)
result can still become an unsafe link. Update the success-link handling around
the code that sets a.href and aMdns.href to only assign href after the same
http(s)-only validation used by myDevices.addProvisionedDevice(), and skip or
neutralize rendering for invalid values.
- Around line 489-501: The success flow in install.js shows the “Device is
online!” header even when no device URL is available, so update the post-flash
handling around the no-URL branch to avoid setting that online state in the
first place. Adjust the logic in the success path and the no-url handling so
that when `url` is missing, the done section uses a neutral/offline message and
only shows the online header when a real device address exists; keep the
behavior localized to the `showSection("done")` / `done-url` / `done-defaults`
flow.
- Around line 876-883: The erase-only success handler is leaving the page in a
stale “done” state, so update the `onSuccess` flow to explicitly reset the
unload guard and clear any previous `done-status` content before showing the
erase completion message. Use the existing `onSuccess` callback in
`docs/install/install.js` and the `showSection("done")` / `done-url` /
`done-url-mdns` / `done-defaults` logic to locate the right spot, and make sure
the erase path does not inherit install-only status or tab-close warnings.

In `@src/ui/app.js`:
- Around line 2274-2275: The dev manifest cache key is shared across firmware
variants even though the URL in the manifest fetch is firmware-specific, so
update the cachedJson call in the dev update path to include dev.firmware in the
cache slot key. Use the existing manifest-loading logic around the url/manifest
assignment in app.js to make the cache entry unique per firmware so one variant
cannot reuse another variant’s latest manifest state.
- Around line 2264-2266: The release asset lookup in the update matching logic
only checks the tagged version form, so stable binaries named with the cleaned
semver are missed. Update the asset-name check in the matching flow around the
version comparison to also consider the pure version derived from rel.tag_name
(without the leading v) when evaluating hasBinary, using the existing release
selection logic and identifiers like isNewer, rel.tag_name, dev.version, and
assetNames.
- Around line 2225-2229: The stale-cache fallback in update should also refresh
the cache metadata so it does not keep retrying on every status tick. In the
catch block that serves data from safeLocalGet(key), update the stored
timestamp/expiry for that key before returning the parsed cached payload, using
the same cache entry logic already used by the successful fetch path in update
so the fallback remains valid until the next intended refresh.

In `@test/python/test_compute_version.py`:
- Around line 28-48: The version computation tests do not cover the no-tag
fallback path promised by the docstring. Add a test in test_compute_version.py
that exercises compute() or the underlying helper when no v* tag exists,
verifying it falls back to rev-list --count HEAD behavior for the first-release
case; use monkeypatch on the relevant helper(s) like commits_since_last_stable
and the version source via LIBRARY_JSON to keep the test deterministic.

---

Outside diff comments:
In `@docs/history/plans/Plan-20260624` - Dev-channel update badge.md:
- Around line 1-49: The plan document is forward-looking but lives under the
history docs, which should only contain backward-looking notes. Move this plan
out of docs/history/ and into the appropriate active planning/docs location,
preserving the content and using the same document title if needed; update any
references so the active plan is discoverable, and keep docs/history reserved
for prunable retrospective notes.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 4cd67847-7e82-47c2-a78f-d5f8921ecfb5

📥 Commits

Reviewing files that changed from the base of the PR and between 84343f8 and aec2e20.

⛔ Files ignored due to path filters (3)

• scripts/build/build_esp32.py is excluded by !**/build/**
• scripts/build/compute_version.py is excluded by !**/build/**
• scripts/build/generate_build_info.py is excluded by !**/build/**

📒 Files selected for processing (11)

• .github/workflows/release.yml
• docs/history/plans/Plan-20260624 - Dev-channel update badge.md
• docs/install/index.html
• docs/install/install.css
• docs/install/install.js
• docs/moonmodules/core/FirmwareUpdateModule.md
• esp32/main/CMakeLists.txt
• src/ui/app.js
• test/js/semver.test.mjs
• test/python/test_compute_version.py
• test/scenarios/light/scenario_Audio_mutation.json

[coderabbitai]

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Match stable binaries by clean semver, not only the v tag.

If release assets are named with the computed pure version, firmware-${dev.firmware}-${rel.tag_name}.bin looks for ...-v2.1.0.bin while the asset is ...-2.1.0.bin, so compatible updates never show.

Proposed fix

     const assetNames = (rel.assets || []).map(a => a.name);
+    const releaseVersion = rel.tag_name.replace(/^v/, "");
     const hasBinary = !dev.firmware ||
-        assetNames.some(n => n === `firmware-${dev.firmware}-${rel.tag_name}.bin`);
+        assetNames.some(n =>
+            n === `firmware-${dev.firmware}-${releaseVersion}.bin` ||
+            n === `firmware-${dev.firmware}-${rel.tag_name}.bin`
+        );

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	const hasBinary = !dev.firmware ||
	assetNames.some(n => n === `firmware-${dev.firmware}-${rel.tag_name}.bin`);
	return (isNewer(rel.tag_name, dev.version) && hasBinary) ? rel.tag_name : null;
	const assetNames = (rel.assets || []).map(a => a.name);
	const releaseVersion = rel.tag_name.replace(/^v/, "");
	const hasBinary = !dev.firmware ||
	assetNames.some(n =>
	n === `firmware-${dev.firmware}-${releaseVersion}.bin` ||
	n === `firmware-${dev.firmware}-${rel.tag_name}.bin`
	);
	return (isNewer(rel.tag_name, dev.version) && hasBinary) ? rel.tag_name : null;

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/ui/app.js` around lines 2264 - 2266, The release asset lookup in the
update matching logic only checks the tagged version form, so stable binaries
named with the cleaned semver are missed. Update the asset-name check in the
matching flow around the version comparison to also consider the pure version
derived from rel.tag_name (without the leading v) when evaluating hasBinary,
using the existing release selection logic and identifiers like isNewer,
rel.tag_name, dev.version, and assetNames.

[coderabbitai]

Actionable comments posted: 4

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

.github/workflows/release.yml (2)

146-153: 🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift

Centralize the tag→version resolution.

These two jobs still duplicate the same release-tag/channel/version mapping. The next semver-rule edit can land in one copy and silently desync the binary MM_VERSION, asset filenames, and manifest --version. Move this logic behind one checked-in helper and call it from both places.

Based on learnings, "Do not duplicate logic or facts across code or documentation; shared behavior belongs in shared functions, and repeated facts in docs should be consolidated and linked instead of restated."

Also applies to: 304-311

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/release.yml around lines 146 - 153, The release-tag to
version mapping is duplicated in the workflow, which can desync version-related
outputs; centralize this logic in one checked-in helper and reuse it from the
Compute version step and the other matching job so binary MM_VERSION, asset
filenames, and manifest --version all come from the same source. Keep the shared
behavior behind a single helper script/function (for example the existing
compute_version.py path or a new wrapper) and update both workflow spots to call
it instead of re-implementing the channel/tag branching inline.

Source: Learnings

---

146-152: 📐 Maintainability & Code Quality | 🔵 Trivial

Replace raw python with uv run in the compute version step.

The "Compute version" step at line 152 invokes python directly, whereas line 310 in the same workflow correctly uses uv run python for the same script. Unify these execution paths to align with repository standards and ensure consistent runtime environments.

Suggested change

          set -euo pipefail
          if [ "${{ steps.tag.outputs.tag }}" = "latest" ]; then CH=latest; else CH=stable; fi
          # Pass the tag so an -rc tag yields its own prerelease semver (not the core).
-          V=$(python scripts/build/compute_version.py --channel "$CH" --tag "${{ steps.tag.outputs.tag }}")
+          V=$(uv run python scripts/build/compute_version.py --channel "$CH" --tag "${{ steps.tag.outputs.tag }}")

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/release.yml around lines 146 - 152, The Compute version
step still calls the compute_version.py script with raw python, which should be
aligned with the rest of the workflow. Update the run block in the ver step to
use uv run python for scripts/build/compute_version.py, matching the existing
execution pattern used elsewhere in this workflow and keeping the environment
consistent.

Source: Learnings

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/architecture.md`:
- Around line 354-356: Update the modifier wording in the architecture docs so
it does not imply chained modifier execution is implemented today: in the
section describing Layer and Layer::rebuildLUT, keep the contract that only the
first enabled modifier is applied, and either remove the sequencing examples or
clearly label them as future/backlog behavior. Use the existing symbols
Layer::rebuildLUT, modifiers, and backlog/README.md to keep the text aligned
with current behavior.

In `@docs/backlog/livescripts-analysis-top-down.md`:
- Around line 372-373: Update the Stage 0.5 acceptance text in the backlog doc
so it validates seam correctness by observable behavior rather than requiring
front-end and IR files to be byte-identical. Keep the existing references to the
same input, same front-end/IR path, and same rendered output, but replace the
file-identity requirement with a behavior-based proof that both backends (RISC-V
P4 and desktop x86-64) produce equivalent results.
- Line 427: The current wording conflates the tutorial hello-world spike with
the fix-warnings crash repro; revise the sentence in the
livescripts-analysis-top-down doc to keep them clearly separate. Update the text
around the Ripples comparison and the `setRGB(random16, blue)` reference so it
says the hello-world script is the tutorial spike, while the `fix-warnings` fork
is the distinct regression case. Use the existing terms `Ripples`,
`setRGB(random16, blue)`, and `fix-warnings` to anchor the distinction.
- Around line 216-219: The safety-tier section conflates runtime protections
with the parser crash from `fix-warnings`; update the discussion around the
nested-arg null-deref to separate AST/parsing validation from runtime bounds
checks and the watchdog. In the `livescripts-analysis-top-down` content, call
out that missing AST children must be handled by parser/analysis validation and
backed by a regression test, while keeping the runtime tier limited to `setRGB`,
indexed access, and watchdog-style protections.

---

Outside diff comments:
In @.github/workflows/release.yml:
- Around line 146-153: The release-tag to version mapping is duplicated in the
workflow, which can desync version-related outputs; centralize this logic in one
checked-in helper and reuse it from the Compute version step and the other
matching job so binary MM_VERSION, asset filenames, and manifest --version all
come from the same source. Keep the shared behavior behind a single helper
script/function (for example the existing compute_version.py path or a new
wrapper) and update both workflow spots to call it instead of re-implementing
the channel/tag branching inline.
- Around line 146-152: The Compute version step still calls the
compute_version.py script with raw python, which should be aligned with the rest
of the workflow. Update the run block in the ver step to use uv run python for
scripts/build/compute_version.py, matching the existing execution pattern used
elsewhere in this workflow and keeping the environment consistent.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 08dea03e-dd73-42d9-af57-84122ab14a98

📥 Commits

Reviewing files that changed from the base of the PR and between aec2e20 and 12e2ddc.

⛔ Files ignored due to path filters (3)

• scripts/build/build_esp32.py is excluded by !**/build/**
• scripts/build/compute_version.py is excluded by !**/build/**
• scripts/build/setup_esp_idf.py is excluded by !**/build/**

📒 Files selected for processing (26)

• .github/workflows/release.yml
• CLAUDE.md
• docs/architecture.md
• docs/backlog/README.md
• docs/backlog/backlog-core.md
• docs/backlog/backlog-light.md
• docs/backlog/backlog-mixed.md
• docs/backlog/leddriver-deferred.md
• docs/backlog/livescripts-analysis-bottom-up.md
• docs/backlog/livescripts-analysis-top-down.md
• docs/backlog/ui-deferred.md
• docs/building.md
• docs/history/README.md
• docs/history/v1-inventory.md
• docs/install/install.css
• docs/install/install.js
• docs/moonmodules/core/AudioModule.md
• docs/moonmodules/light/BlendMap.md
• docs/moonmodules/light/Drivers.md
• docs/moonmodules/light/Layers.md
• docs/moonmodules/light/drivers/LcdLedDriver.md
• docs/moonmodules/light/drivers/NetworkSendDriver.md
• docs/performance.md
• src/ui/app.js
• test/python/test_compute_version.py
• test/scenarios/light/scenario_Audio_mutation.json

💤 Files with no reviewable changes (2)

• docs/backlog/leddriver-deferred.md
• docs/backlog/ui-deferred.md

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Clarify that modifier chaining is still backlog-only.

The new example reads like multiply-then-checkerboard vs checkerboard-then-multiply already changes behavior, but the current contract still applies only the first enabled modifier during Layer::rebuildLUT. Please remove the sequencing example or mark it explicitly as future behavior.

♻️ Suggested rewording

-A layer applies its **first enabled modifier** during LUT build (`Layer::rebuildLUT`). Modifiers are **reorderable** in the UI, and order is meaningful (a multiply-then-checkerboard mask differs from checkerboard-then-multiply, just as mirror-then-rotate differs from rotate-then-mirror). Applying several modifiers in sequence (chaining) is on the [backlog](backlog/README.md).
+A layer applies its **first enabled modifier** during LUT build (`Layer::rebuildLUT`). Modifiers are **reorderable** in the UI so users can choose which one is active first. Applying several modifiers in sequence (chaining) is on the [backlog](backlog/README.md).

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	A layer can have **multiple effects**. Each effect writes to the buffer sequentially in its listed order, overwriting or adding to the previous — so the effects stack (a base-colour effect followed by a sparkle effect).
	A layer applies its **first enabled modifier** during LUT build (`Layer::rebuildLUT`). Modifier *chaining* (applying several in sequence) is not implemented: only the first enabled modifier takes effect. Order matters for a chain (a multiply-then-checkerboard mask differs from checkerboard-then-multiply, just as mirror-then-rotate differs from rotate-then-mirror), which is why modifiers are reorderable in the UI even though only the first is applied today. Chaining is on the [backlog](backlog/backlog.md): static modifiers chain during LUT build, dynamic modifiers during rendering.
	A layer applies its **first enabled modifier** during LUT build (`Layer::rebuildLUT`). Modifiers are **reorderable** in the UI, and order is meaningful (a multiply-then-checkerboard mask differs from checkerboard-then-multiply, just as mirror-then-rotate differs from rotate-then-mirror). Applying several modifiers in sequence (chaining) is on the [backlog](backlog/README.md).
	A layer can have **multiple effects**. Each effect writes to the buffer sequentially in its listed order, overwriting or adding to the previous — so the effects stack (a base-colour effect followed by a sparkle effect).
	A layer applies its **first enabled modifier** during LUT build (`Layer::rebuildLUT`). Modifiers are **reorderable** in the UI so users can choose which one is active first. Applying several modifiers in sequence (chaining) is on the [backlog](backlog/README.md).

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/architecture.md` around lines 354 - 356, Update the modifier wording in
the architecture docs so it does not imply chained modifier execution is
implemented today: in the section describing Layer and Layer::rebuildLUT, keep
the contract that only the first enabled modifier is applied, and either remove
the sequencing examples or clearly label them as future/backlog behavior. Use
the existing symbols Layer::rebuildLUT, modifiers, and backlog/README.md to keep
the text aligned with current behavior.

[coderabbitai]

Note

Unit test generation is a public access feature. Expect some limitations and changes as we gather feedback and continue to improve it.

---

Generating unit tests... This may take up to 20 minutes.

[coderabbitai]

✅ Created PR with unit tests: #28